Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,118 @@
+---
+license: apache-2.0
+base_model: Qwen/Qwen3-VL-4B-Instruct
+language:
+- en
+- fr
+tags:
+- vidore
+- colpali
+- colqwen3
+- late-interaction
+- visual-document-retrieval
+- multimodal
+- retrieval
+datasets:
+- manu/colpali-queries
+- manu/colpali-corpus
+pipeline_tag: visual-document-retrieval
+library_name: colpali
+---
+
+# ColTurk-VDR-Qwen3VL-4B v1.0
+
+ColBERT-style **late-interaction visual document retriever** built on [Qwen/Qwen3-VL-4B-Instruct](https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct) with the [colpali-engine](https://github.com/illuin-tech/colpali) `ColQwen3` architecture (transformers v5 native). Pages are embedded as multi-vector 128-dim patch/token embeddings; queries and documents are scored with MaxSim.
+
+This repository contains the **merged full model** (LoRA weights baked into the base) — it loads directly with `ColQwen3.from_pretrained`, with no PEFT step and no adapter key-prefix fragility across transformers versions. The original LoRA adapter is preserved under [`adapter/`](./tree/main/adapter) for reproducibility.
+
+- **Developed by:** [Mert Karatay](https://github.com/Verm1lion) (merttkaratayy@gmail.com)
+- **Model type:** multi-vector late-interaction visual retriever (ColBERT/MaxSim)
+- **Languages:** English + French (training data); query side inherits Qwen3-VL multilinguality
+- **License:** Apache-2.0 (inherited from the base model; training code MIT)
+- **Repository / eval code:** https://github.com/Verm1lion/ColTurk-VDR
+
+## Results — ViDoRe V3 (8 public subtasks)
+
+Evaluated on the **full corpus with all queries** per subtask (no sampling), MaxSim scoring, processor-default visual tokens, seeded bootstrap 95% CI. Raw JSONs: [`eval/results/`](https://github.com/Verm1lion/ColTurk-VDR/tree/main/eval/results).
+
+**Mean NDCG@10 = 0.5584 · NDCG@5 = 0.5287 · recall@10 = 0.6110**
+
+| Subtask | NDCG@10 | 95% CI | n_queries | n_corpus |
+|---|---|---|---|---|
+| Vidore3ComputerScienceRetrieval | 0.7306 | [0.718, 0.743] | 1290 | 1360 |
+| Vidore3EnergyRetrieval | 0.6238 | [0.608, 0.638] | 1848 | 2225 |
+| Vidore3PharmaceuticalsRetrieval | 0.6156 | [0.602, 0.629] | 2184 | 2313 |
+| Vidore3FinanceEnRetrieval | 0.5851 | [0.571, 0.601] | 1854 | 2942 |
+| Vidore3HrRetrieval | 0.5463 | [0.532, 0.560] | 1908 | 1110 |
+| Vidore3IndustrialRetrieval | 0.4624 | [0.445, 0.482] | 1698 | 5244 |
+| Vidore3PhysicsRetrieval | 0.4564 | [0.443, 0.471] | 1812 | 1674 |
+| Vidore3FinanceFrRetrieval | 0.4467 | [0.430, 0.463] | 1920 | 2384 |
+
+## Usage
+
+```python
+import torch
+from colpali_engine.models import ColQwen3, ColQwen3Processor
+
+model_id = "Verm1ion/ColTurk-VDR-Qwen3VL-4B-v1.0"
+model = ColQwen3.from_pretrained(
+    model_id, torch_dtype=torch.bfloat16, device_map="cuda:0",
+    attn_implementation="sdpa",
+).eval()
+processor = ColQwen3Processor.from_pretrained(model_id)
+
+# documents: list[PIL.Image] of page images; queries: list[str]
+doc_batch = processor.process_images(documents).to(model.device)
+qry_batch = processor.process_queries(queries).to(model.device)
+with torch.no_grad():
+    doc_emb = model(**doc_batch)
+    qry_emb = model(**qry_batch)
+scores = processor.score_multi_vector(qry_emb, doc_emb)   # (n_queries, n_docs)
+```
+
+Requirements: `colpali-engine>=0.3.16`, `transformers>=5.0`, `torch>=2.5`.
+
+## Training
+
+| | |
+|---|---|
+| Base | Qwen/Qwen3-VL-4B-Instruct (raw, no warm start) |
+| Method | LoRA r=32, α=32, dropout 0.1 on language-model proj layers; `custom_text_proj` head fully trained |
+| Data | [manu/colpali](https://huggingface.co/datasets/manu/colpali-queries) EN+FR, 108K query–page pairs, 2 mined hard negatives per query (K=2) |
+| Loss | ColBERT pairwise negative CE (in-batch + explicit negatives) |
+| Schedule | LR 5e-5, linear decay, warmup 10, effective batch 32, bf16, gradient checkpointing, `max_num_visual_tokens=768` (training) |
+| Hardware | single A100 80GB |
+| Selection | eval-gated checkpoint curve on the full benchmark: step 500 → 0.5441, **step 1000 → 0.5584 (peak, released)**, step 1500 → 0.5518 (overfit onset) |
+
+### Measured negative results (transparency)
+
+Each candidate improvement was evaluated on the full benchmark and dropped on evidence: more negatives (K=4: −0.016, worse on 8/8 subtasks), two-run weight averaging (−0.006, zero synergy across LoRA inits), train-matched visual-token cap at eval (−0.017; uncapped inference is better). Full validity report (causal control, leakage tripwires, pHash contamination scan, bootstrap CIs): [STAGE1_VALIDITY_REPORT.md](https://github.com/Verm1lion/ColTurk-VDR/blob/main/STAGE1_VALIDITY_REPORT.md).
+
+## Evaluation protocol & reproduction
+
+```bash
+git clone https://github.com/Verm1lion/ColTurk-VDR
+cd ColTurk-VDR
+python scripts/eval/eval_colturk_checkpoint.py \
+    --adapter Verm1ion/ColTurk-VDR-Qwen3VL-4B-v1.0 \
+    --bootstrap 1000 --output eval/results/repro.json
+```
+
+Environment pins and seeds: [REPRODUCIBILITY.md](https://github.com/Verm1lion/ColTurk-VDR/blob/main/REPRODUCIBILITY.md). Training data ↔ benchmark contamination was checked empirically (perceptual-hash scan over train images × V3 corpora: 0 exact duplicates, 0.025% at the document true-duplicate bar, visually inspected) — details in the validity report.
+
+## Limitations
+
+- Trained on 108K EN+FR pairs (single-GPU budget) — well below the multi-million-pair data scale of the top ViDoRe V3 entries; scores reflect that gap honestly.
+- English and French document domains only in v1.0; Turkish document support is the next planned stage.
+- Retrieval-only model: no reranking, no generation.
+
+## Citation
+
+```bibtex
+@misc{karatay2026colturkvdr,
+  author = {Karatay, Mert},
+  title  = {ColTurk-VDR: A Late-Interaction Visual Document Retriever on Qwen3-VL-4B},
+  year   = {2026},
+  url    = {https://github.com/Verm1lion/ColTurk-VDR}
+}
+```

chat_template.jinja

@@ -0,0 +1,120 @@
+{%- if tools %}
+    {{- '<|im_start|>system\n' }}
+    {%- if messages[0].role == 'system' %}
+        {%- if messages[0].content is string %}
+            {{- messages[0].content }}
+        {%- else %}
+            {%- for content in messages[0].content %}
+                {%- if 'text' in content %}
+                    {{- content.text }}
+                {%- endif %}
+            {%- endfor %}
+        {%- endif %}
+        {{- '\n\n' }}
+    {%- endif %}
+    {{- "# Tools\n\nYou may call one or more functions to assist with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>" }}
+    {%- for tool in tools %}
+        {{- "\n" }}
+        {{- tool | tojson }}
+    {%- endfor %}
+    {{- "\n</tools>\n\nFor each function call, return a json object with function name and arguments within <tool_call></tool_call> XML tags:\n<tool_call>\n{\"name\": <function-name>, \"arguments\": <args-json-object>}\n</tool_call><|im_end|>\n" }}
+{%- else %}
+    {%- if messages[0].role == 'system' %}
+        {{- '<|im_start|>system\n' }}
+        {%- if messages[0].content is string %}
+            {{- messages[0].content }}
+        {%- else %}
+            {%- for content in messages[0].content %}
+                {%- if 'text' in content %}
+                    {{- content.text }}
+                {%- endif %}
+            {%- endfor %}
+        {%- endif %}
+        {{- '<|im_end|>\n' }}
+    {%- endif %}
+{%- endif %}
+{%- set image_count = namespace(value=0) %}
+{%- set video_count = namespace(value=0) %}
+{%- for message in messages %}
+    {%- if message.role == "user" %}
+        {{- '<|im_start|>' + message.role + '\n' }}
+        {%- if message.content is string %}
+            {{- message.content }}
+        {%- else %}
+            {%- for content in message.content %}
+                {%- if content.type == 'image' or 'image' in content or 'image_url' in content %}
+                    {%- set image_count.value = image_count.value + 1 %}
+                    {%- if add_vision_id %}Picture {{ image_count.value }}: {% endif -%}
+                    <|vision_start|><|image_pad|><|vision_end|>
+                {%- elif content.type == 'video' or 'video' in content %}
+                    {%- set video_count.value = video_count.value + 1 %}
+                    {%- if add_vision_id %}Video {{ video_count.value }}: {% endif -%}
+                    <|vision_start|><|video_pad|><|vision_end|>
+                {%- elif 'text' in content %}
+                    {{- content.text }}
+                {%- endif %}
+            {%- endfor %}
+        {%- endif %}
+        {{- '<|im_end|>\n' }}
+    {%- elif message.role == "assistant" %}
+        {{- '<|im_start|>' + message.role + '\n' }}
+        {%- if message.content is string %}
+            {{- message.content }}
+        {%- else %}
+            {%- for content_item in message.content %}
+                {%- if 'text' in content_item %}
+                    {{- content_item.text }}
+                {%- endif %}
+            {%- endfor %}
+        {%- endif %}
+        {%- if message.tool_calls %}
+            {%- for tool_call in message.tool_calls %}
+                {%- if (loop.first and message.content) or (not loop.first) %}
+                    {{- '\n' }}
+                {%- endif %}
+                {%- if tool_call.function %}
+                    {%- set tool_call = tool_call.function %}
+                {%- endif %}
+                {{- '<tool_call>\n{"name": "' }}
+                {{- tool_call.name }}
+                {{- '", "arguments": ' }}
+                {%- if tool_call.arguments is string %}
+                    {{- tool_call.arguments }}
+                {%- else %}
+                    {{- tool_call.arguments | tojson }}
+                {%- endif %}
+                {{- '}\n</tool_call>' }}
+            {%- endfor %}
+        {%- endif %}
+        {{- '<|im_end|>\n' }}
+    {%- elif message.role == "tool" %}
+        {%- if loop.first or (messages[loop.index0 - 1].role != "tool") %}
+            {{- '<|im_start|>user' }}
+        {%- endif %}
+        {{- '\n<tool_response>\n' }}
+        {%- if message.content is string %}
+            {{- message.content }}
+        {%- else %}
+            {%- for content in message.content %}
+                {%- if content.type == 'image' or 'image' in content or 'image_url' in content %}
+                    {%- set image_count.value = image_count.value + 1 %}
+                    {%- if add_vision_id %}Picture {{ image_count.value }}: {% endif -%}
+                    <|vision_start|><|image_pad|><|vision_end|>
+                {%- elif content.type == 'video' or 'video' in content %}
+                    {%- set video_count.value = video_count.value + 1 %}
+                    {%- if add_vision_id %}Video {{ video_count.value }}: {% endif -%}
+                    <|vision_start|><|video_pad|><|vision_end|>
+                {%- elif 'text' in content %}
+                    {{- content.text }}
+                {%- endif %}
+            {%- endfor %}
+        {%- endif %}
+        {{- '\n</tool_response>' }}
+        {%- if loop.last or (messages[loop.index0 + 1].role != "tool") %}
+            {{- '<|im_end|>\n' }}
+        {%- endif %}
+    {%- endif %}
+{%- endfor %}
+{%- if add_generation_prompt %}
+    {{- '<|im_start|>assistant\n' }}
+{%- endif %}

config.json

@@ -0,0 +1,66 @@
+{
+  "architectures": [
+    "ColQwen3"
+  ],
+  "dtype": "bfloat16",
+  "image_token_id": 151655,
+  "model_type": "qwen3_vl",
+  "text_config": {
+    "attention_bias": false,
+    "attention_dropout": 0.0,
+    "bos_token_id": 151643,
+    "dtype": "bfloat16",
+    "eos_token_id": 151645,
+    "head_dim": 128,
+    "hidden_act": "silu",
+    "hidden_size": 2560,
+    "initializer_range": 0.02,
+    "intermediate_size": 9728,
+    "max_position_embeddings": 262144,
+    "model_type": "qwen3_vl_text",
+    "num_attention_heads": 32,
+    "num_hidden_layers": 36,
+    "num_key_value_heads": 8,
+    "pad_token_id": null,
+    "rms_norm_eps": 1e-06,
+    "rope_parameters": {
+      "mrope_interleaved": true,
+      "mrope_section": [
+        24,
+        20,
+        20
+      ],
+      "rope_theta": 5000000,
+      "rope_type": "default"
+    },
+    "tie_word_embeddings": true,
+    "use_cache": true,
+    "vocab_size": 151936
+  },
+  "tie_word_embeddings": true,
+  "transformers_version": "5.11.0",
+  "video_token_id": 151656,
+  "vision_config": {
+    "deepstack_visual_indexes": [
+      5,
+      11,
+      17
+    ],
+    "depth": 24,
+    "dtype": "bfloat16",
+    "hidden_act": "gelu_pytorch_tanh",
+    "hidden_size": 1024,
+    "in_channels": 3,
+    "initializer_range": 0.02,
+    "intermediate_size": 4096,
+    "model_type": "qwen3_vl_vision",
+    "num_heads": 16,
+    "num_position_embeddings": 2304,
+    "out_hidden_size": 2560,
+    "patch_size": 16,
+    "spatial_merge_size": 2,
+    "temporal_patch_size": 2
+  },
+  "vision_end_token_id": 151653,
+  "vision_start_token_id": 151652
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0609d7d696429e54afacd0a7ba84374762519a201b008a39627c56ae6a89a52d
+size 8877358624

processor_config.json

@@ -0,0 +1,60 @@
+{
+  "image_processor": {
+    "do_convert_rgb": true,
+    "do_normalize": true,
+    "do_rescale": true,
+    "do_resize": true,
+    "image_mean": [
+      0.5,
+      0.5,
+      0.5
+    ],
+    "image_processor_type": "Qwen2VLImageProcessor",
+    "image_std": [
+      0.5,
+      0.5,
+      0.5
+    ],
+    "merge_size": 2,
+    "patch_size": 16,
+    "resample": 3,
+    "rescale_factor": 0.00392156862745098,
+    "size": {
+      "longest_edge": 16777216,
+      "shortest_edge": 65536
+    },
+    "temporal_patch_size": 2
+  },
+  "processor_class": "ColQwen3Processor",
+  "video_processor": {
+    "do_convert_rgb": true,
+    "do_normalize": true,
+    "do_rescale": true,
+    "do_resize": true,
+    "do_sample_frames": true,
+    "fps": 2,
+    "image_mean": [
+      0.5,
+      0.5,
+      0.5
+    ],
+    "image_std": [
+      0.5,
+      0.5,
+      0.5
+    ],
+    "max_frames": 768,
+    "merge_size": 2,
+    "min_frames": 4,
+    "patch_size": 16,
+    "resample": 3,
+    "rescale_factor": 0.00392156862745098,
+    "return_metadata": false,
+    "size": {
+      "longest_edge": 25165824,
+      "shortest_edge": 4096
+    },
+    "temporal_patch_size": 2,
+    "video_processor_type": "Qwen3VLVideoProcessor"
+  }
+}

tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:be75606093db2094d7cd20f3c2f385c212750648bd6ea4fb2bf507a6a4c55506
+size 11422650

tokenizer_config.json

@@ -0,0 +1,31 @@
+{
+  "add_prefix_space": false,
+  "backend": "tokenizers",
+  "bos_token": null,
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "<|im_end|>",
+  "errors": "replace",
+  "extra_special_tokens": [
+    "<|im_start|>",
+    "<|im_end|>",
+    "<|object_ref_start|>",
+    "<|object_ref_end|>",
+    "<|box_start|>",
+    "<|box_end|>",
+    "<|quad_start|>",
+    "<|quad_end|>",
+    "<|vision_start|>",
+    "<|vision_end|>",
+    "<|vision_pad|>",
+    "<|image_pad|>",
+    "<|video_pad|>"
+  ],
+  "is_local": false,
+  "local_files_only": false,
+  "model_max_length": 262144,
+  "pad_token": "<|endoftext|>",
+  "processor_class": "ColQwen3Processor",
+  "split_special_tokens": false,
+  "tokenizer_class": "Qwen2Tokenizer",
+  "unk_token": null
+}