Fold the LoRA adapter in as lora/, one repository for both forms

README.md

@@ -16,6 +16,7 @@ tags:
 - hanja
 - classical-chinese
 - custom_code
+- lora
 metrics:
 - cer
 ---
@@ -27,14 +28,17 @@ metrics:
 Bandit OCR reads a page of a Korean historical document and returns one region per printed column,
 in reading order, with the characters of that column. It is a LoRA fine-tune of
 [dots.mocr](https://huggingface.co/dots-studio/dots.mocr), a 1.7B-parameter document vision-language model,
-trained on 229,356 annotated pages of Joseon-dynasty woodblock prints and manuscripts. The
-adapter is merged into the weights, so it loads and serves exactly like the base.
+trained on 229,356 annotated pages of Joseon-dynasty woodblock prints and manuscripts.
 
 On the held-out test split it reads a page at 0.0195 character error rate with a column
 F1 of 0.9856, against 0.1436 for the AI Hub ResNet pipeline and
 0.2398 for NDLkotenOCR on the same pages.
 
-- LoRA adapter: [dhchoi/bandit-ocr-lora](https://huggingface.co/dhchoi/bandit-ocr-lora)
+The repository holds both forms of the same fine-tune. At the root are the merged weights, the
+adapter already folded in at scale 0.75, which load and serve exactly like the base and need
+no PEFT. Under `lora/` is the LoRA adapter itself, for composing onto the base yourself,
+changing the scale or training further. Take the root unless you know you want the adapter.
+
 - Desktop application and project site: https://bandit.dhchoi.net
 - Paper: JADH 2026, September 2026
 
@@ -45,8 +49,9 @@ F1 of 0.9856, against 0.1436 for the AI Hub ResNet pipeline and
 | Base model | [dots-studio/dots.mocr](https://huggingface.co/dots-studio/dots.mocr) at revision `e539fbb52280393adc081b289ec597430a0f9031` |
 | Parameters | 1.7B (1.2B language decoder + 0.4B vision tower) |
 | Adaptation | LoRA, rank 64, alpha 128, dropout 0.05, on the language projections and the vision tower |
-| Weights | the adapter folded in at scale 0.75; a plain bfloat16 checkpoint, no PEFT needed |
-| Files | 2 safetensors shards, about 6.1 GB |
+| Weights | root: the adapter folded in at scale 0.75, a plain bfloat16 checkpoint, no PEFT needed |
+| Adapter | `lora/`: the same LoRA unmerged, 580 MB, to apply at scale 0.75 yourself |
+| Files | 2 safetensors shards at the root, about 6.1 GB, plus the adapter |
 | Checkpoint | t3_full step 56000 of the full training run |
 | Trained on | 229,356 annotated pages of Korean historical documents |
 | Input | one page image, 3,136 to 11,289,600 pixels after `smart_resize` |
@@ -168,6 +173,40 @@ Send the image as a data URL with the prompt above, `temperature` 0, `max_tokens
 decode settings of the section below: `"stop_token_ids": [151673]` and
 `"logit_bias": {"151643": -100, "151672": -100}`.
 
+### The LoRA adapter
+
+`lora/` holds the same fine-tune unmerged, for composing onto the base yourself, changing
+the scale or training further. The delta is scaled by 0.75 before it is applied: that scale is
+part of the released model, not a training artefact, and every number below was measured with it.
+
+```python
+import torch
+from peft import PeftModel
+from transformers import AutoModelForCausalLM
+
+base = AutoModelForCausalLM.from_pretrained(
+    "dots-studio/dots.mocr", revision="e539fbb52280393adc081b289ec597430a0f9031",
+    trust_remote_code=True, torch_dtype=torch.bfloat16, device_map="auto",
+)
+model = PeftModel.from_pretrained(base, "dhchoi/bandit-ocr", subfolder="lora")
+
+for module in model.modules():                  # every LoRA layer scales its delta by scaling[name]
+    scaling = getattr(module, "scaling", None)
+    if isinstance(scaling, dict):
+        for name in scaling:
+            scaling[name] *= 0.75
+
+model = model.merge_and_unload()
+```
+
+That reproduces the weights at the root of this repository. Prompt, decode and rescale boxes the
+same way, and set the stop id yourself, because the composed model inherits the base's generation
+config.
+
+Applied at its trained scale of 1.0 the adapter is a different, measurably worse model: on the same
+540-page validation set an earlier checkpoint of this run read at 0.0656 page CER at scale 1.0
+against 0.0376 at scale 0.75, both under the stop rule of the day.
+
 ## Decoding: stop on one token, suppress two
 
 This matters more than any other setting here. The training target ends with `<|endofassistant|>`
@@ -175,7 +214,9 @@ This matters more than any other setting here. The training target ends with `<|
 `<|assistant|>` (151672) as stop ids. The fine-tune sometimes emits `<|endoftext|>` in the middle of
 a column at a hard glyph, and a page that stops there is truncated or fails to parse.
 
-- `generation_config.json` in this repository already sets `eos_token_id` to 151673 alone.
+- `generation_config.json` at the root of this repository already sets `eos_token_id` to 151673
+  alone. If you compose the adapter onto the base yourself, set it there: the base's config stops
+  on all three.
 - Suppress 151643 and 151672 during decoding as well (`suppress_tokens` in `generate`, a -100
   `logit_bias` through an OpenAI-compatible server).
 
@@ -314,12 +355,14 @@ back to eager attention, which is quadratic in the number of patches; set
 
 Built with dots.mocr.
 
-This model is a fine-tune of [dots.mocr](https://huggingface.co/dots-studio/dots.mocr) by Xingyin
-Information Technology (Shanghai) Co., Ltd. (rednote / Xiaohongshu), used under the dots.mocr
-LICENSE AGREEMENT. A copy of that agreement and the base `NOTICE` ship in this repository (clauses
-7.1 and 7.2), the notices in them are unchanged, and this card displays the attribution statement
-clause 7.3 requires. Nothing here implies endorsement by the licensor, and no name in this project
-is a licensor trade name (clause 4.4).
+This model is a fine-tune of [dots.mocr](https://huggingface.co/dots-studio/dots.mocr), copyright
+Xingyin Information Technology (Shanghai) Co., Ltd, used under the dots.mocr LICENSE AGREEMENT. A
+copy of that agreement and the base `NOTICE` ship in this repository (clauses 7.1 and 7.2), the
+notices in them are unchanged, and this card displays the attribution statement clause 7.3
+requires. Nothing here implies endorsement by the licensor, and no name in this project is a
+licensor trade name (clause 4.4). The weights are released on the terms the base is released
+under; where the agreement and the metadata tag differ, the agreement is the document that
+ships.
 
 The training data is licensed separately and is not redistributed; see the section above.
 

lora/adapter_config.json

@@ -0,0 +1,47 @@
+{
+  "alpha_pattern": {},
+  "auto_mapping": null,
+  "base_model_name_or_path": "/home/dhchoi/bandit/models/dots_mocr",
+  "bias": "none",
+  "corda_config": null,
+  "eva_config": null,
+  "exclude_modules": null,
+  "fan_in_fan_out": false,
+  "inference_mode": true,
+  "init_lora_weights": true,
+  "layer_replication": null,
+  "layers_pattern": null,
+  "layers_to_transform": null,
+  "loftq_config": {},
+  "lora_alpha": 128,
+  "lora_bias": false,
+  "lora_dropout": 0.05,
+  "megatron_config": null,
+  "megatron_core": "megatron.core",
+  "modules_to_save": null,
+  "peft_type": "LORA",
+  "qalora_group_size": 16,
+  "r": 64,
+  "rank_pattern": {},
+  "revision": null,
+  "target_modules": [
+    "attn.qkv",
+    "mlp.fc1",
+    "attn.proj",
+    "down_proj",
+    "mlp.fc3",
+    "up_proj",
+    "q_proj",
+    "o_proj",
+    "gate_proj",
+    "mlp.fc2",
+    "k_proj",
+    "v_proj"
+  ],
+  "target_parameters": null,
+  "task_type": "CAUSAL_LM",
+  "trainable_token_indices": null,
+  "use_dora": false,
+  "use_qalora": false,
+  "use_rslora": false
+}

lora/adapter_model.safetensors

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