Hugging Face's logo

solvrays
/
mdf-form-reader-phi35-vision

Image-to-Text
Transformers
Safetensors
English
qwen2_vl
image-text-to-text
vision-language-model
document-understanding
handwritten-text
insurance-forms
vqa
phi-3.5-vision
lora
qlora
unsloth
medical-forms
ocr-free
Eval Results (legacy)
text-generation-inference
Model card Files
xet
 Community
singtan commited on
Commit
eb867a2
·
verified ·
1 Parent(s): 3dfce27

Upload MDF form reader: Phi-3.5-Vision + QLoRA fine-tune

Browse files
Files changed (9) hide show
  1. .gitattributes +1 -0
  2. README.md +193 -0
  3. chat_template.jinja +7 -0
  4. config.json +97 -0
  5. generation_config.json +14 -0
  6. model.safetensors +3 -0
  7. processor_config.json +59 -0
  8. tokenizer.json +3 -0
  9. tokenizer_config.json +130 -0
.gitattributes CHANGED
@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
33
  *.zip filter=lfs diff=lfs merge=lfs -text
34
  *.zst filter=lfs diff=lfs merge=lfs -text
35
  *tfevents* filter=lfs diff=lfs merge=lfs -text
 
 
33
  *.zip filter=lfs diff=lfs merge=lfs -text
34
  *.zst filter=lfs diff=lfs merge=lfs -text
35
  *tfevents* filter=lfs diff=lfs merge=lfs -text
36
+ tokenizer.json filter=lfs diff=lfs merge=lfs -text
README.md ADDED
@@ -0,0 +1,193 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ language:
3
+ - en
4
+ license: apache-2.0
5
+ library_name: transformers
6
+ tags:
7
+ - vision-language-model
8
+ - document-understanding
9
+ - handwritten-text
10
+ - insurance-forms
11
+ - vqa
12
+ - phi-3.5-vision
13
+ - lora
14
+ - qlora
15
+ - unsloth
16
+ - medical-forms
17
+ - ocr-free
18
+ pipeline_tag: image-to-text
19
+ base_model: microsoft/Phi-3.5-vision-instruct
20
+ datasets:
21
+ - custom-mdf-forms
22
+ metrics:
23
+ - exact_match
24
+ model-index:
25
+ - name: mdf-form-reader-phi35-vision
26
+ results:
27
+ - task:
28
+ type: visual-question-answering
29
+ name: Visual Question Answering (MDF Forms)
30
+ metrics:
31
+ - type: exact_match
32
+ value: 0
33
+ name: Exact Match (%)
34
+ - type: ood_refusal_rate
35
+ value: 0
36
+ name: OOD Refusal Rate (%)
37
+ ---
38
+
39
+ # MDF Form Reader — Phi-3.5-Vision Fine-tuned
40
+
41
+ **Vision-native handwritten insurance form understanding, fine-tuned from [microsoft/Phi-3.5-vision-instruct](https://huggingface.co/microsoft/Phi-3.5-vision-instruct) using QLoRA.**
42
+
43
+ > **No OCR needed.** This model reads handwriting, checks checkbox states, and extracts structured data directly from scanned MDF (Monthly Disability Verification) form images.
44
+
45
+ ---
46
+
47
+ ## 📋 Model Summary
48
+
49
+ | Property | Value |
50
+ |---|---|
51
+ | **Base Model** | `microsoft/Phi-3.5-vision-instruct` (4.2B) |
52
+ | **Task** | Visual Question Answering on MDF forms |
53
+ | **Fine-tuning Method** | QLoRA (r=16, alpha=32) via Unsloth |
54
+ | **Quantization** | 4-bit NF4 (training) → 16-bit merged |
55
+ | **Annotator** | Vertex AI Gemini 2.5 Flash |
56
+ | **Exact Match** | 0% |
57
+ | **OOD Refusal Rate** | 0% |
58
+ | **License** | Apache 2.0 |
59
+
60
+ ---
61
+
62
+ ## 🚀 Quick Start
63
+
64
+ ```python
65
+ from transformers import AutoModelForCausalLM, AutoProcessor
66
+ from PIL import Image
67
+ import torch
68
+
69
+ model_id = "solvrays/mdf-form-reader-phi35-vision"
70
+
71
+ processor = AutoProcessor.from_pretrained(model_id, trust_remote_code=True)
72
+ model = AutoModelForCausalLM.from_pretrained(
73
+ model_id,
74
+ torch_dtype=torch.bfloat16,
75
+ device_map="cuda",
76
+ trust_remote_code=True,
77
+ )
78
+
79
+ # Load your scanned MDF form image
80
+ image = Image.open("mdf_form.png").convert("RGB")
81
+
82
+ # Ask a question about the form
83
+ question = "What is the name of the physician who signed this form?"
84
+
85
+ messages = [{"role": "user", "content": f"<|image_1|>
86
+ {question}"}]
87
+ text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
88
+
89
+ inputs = processor(text=[text], images=[image], return_tensors="pt").to("cuda")
90
+
91
+ with torch.no_grad():
92
+ out = model.generate(**inputs, max_new_tokens=200, temperature=0.1)
93
+
94
+ answer = processor.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
95
+ print(answer)
96
+ ```
97
+
98
+ ---
99
+
100
+ ## 🏥 What is an MDF Form?
101
+
102
+ A **Monthly Disability Verification Form (Form 441.O.MDF.O)** is issued by TriPlus Services, acting as Third-Party Administrator of Penn Treaty Network America and American Network policies. It requires a licensed physician to certify a patient's ongoing disability status monthly.
103
+
104
+ ### Key Fields Extracted
105
+
106
+ - Physician name, address, phone, fax
107
+ - Submission date range (from / to)
108
+ - Patient disability status (YES checked / NO checked)
109
+ - Disability end date (if applicable)
110
+ - Form completion date
111
+ - Physician signature presence
112
+
113
+ ---
114
+
115
+ ## 🔬 Why Vision-Native vs OCR?
116
+
117
+ | Challenge | OCR Approach | This Model |
118
+ |---|---|---|
119
+ | Cursive physician names | Fails ("Carnazzo", "Kruszka") | Reads directly from image |
120
+ | Checkbox state (YES/NO) | Misses (no text to extract) | Sees the ✓/✗ mark in context |
121
+ | Date grid cells (MM/DD/YYYY) | Digit confusion in small boxes | Layout-aware reading |
122
+ | Signature field | Garbage output | Correctly ignored |
123
+ | Handwritten addresses | High error rate | Contextual correction |
124
+
125
+ ---
126
+
127
+ ## 🛠️ Training Pipeline
128
+
129
+ ```
130
+ Scanned MDF Form (PDF)
131
+ ↓ Image pre-processing (deskew 300 DPI, bilateral denoise, CLAHE)
132
+ ↓ Vertex AI Gemini 2.5 Flash → structured JSON annotation
133
+ ↓ VQA triplet dataset (field extraction + OOD refusal pairs)
134
+ ↓ Phi-3.5-Vision + QLoRA (Unsloth, 2-5× faster, 80% less VRAM)
135
+ ↓ Merge adapters → full 16-bit model
136
+ ↓ HuggingFace Hub (safetensors)
137
+ ```
138
+
139
+ ### Training Configuration
140
+
141
+ ```yaml
142
+ base_model: microsoft/Phi-3.5-vision-instruct
143
+ fine_tuning_method: QLoRA (NF4, double quantization)
144
+ lora_rank: 16
145
+ lora_alpha: 32
146
+ lora_dropout: 0.05
147
+ use_rslora: true
148
+ vision_layers: frozen
149
+ language_layers: adapted
150
+ optimizer: AdamW 8-bit (paged)
151
+ lr_scheduler: cosine
152
+ neftune_noise_alpha: 5
153
+ annotator: Vertex AI Gemini 2.5 Flash
154
+ framework: Unsloth + HuggingFace TRL
155
+ ```
156
+
157
+ ---
158
+
159
+ ## 📊 Evaluation Results
160
+
161
+ | Metric | Value |
162
+ |---|---|
163
+ | Exact Match (field extraction) | 0% |
164
+ | OOD Refusal Rate | 0% |
165
+ | Evaluation Set | Held-out MDF form pages |
166
+
167
+ **OOD Refusal Rate** measures how reliably the model declines to answer questions not answerable from the form (e.g. "What is the diagnosis?", "Has this claim been approved?").
168
+
169
+ ---
170
+
171
+ ## ⚠️ Limitations
172
+
173
+ - **Domain-specific**: Trained exclusively on TriPlus Services MDF forms. Performance on other form types is not guaranteed.
174
+ - **Image quality**: Works best on scans ≥ 300 DPI. Very low-resolution or heavily degraded scans may reduce accuracy.
175
+ - **Language**: English only.
176
+ - **Redacted fields**: Returns `null` for blacked-out fields (insured name/policy number).
177
+ - **Not for medical diagnosis**: This model extracts administrative form data only.
178
+
179
+ ---
180
+
181
+ ## 📄 License
182
+
183
+ This model is released under the **Apache 2.0 License**.
184
+ The base model ([microsoft/Phi-3.5-vision-instruct](https://huggingface.co/microsoft/Phi-3.5-vision-instruct)) is also Apache 2.0.
185
+
186
+ ---
187
+
188
+ ## 🙏 Acknowledgements
189
+
190
+ - [Unsloth](https://github.com/unslothai/unsloth) for 2-5× faster fine-tuning
191
+ - [Microsoft Phi-3.5-Vision](https://huggingface.co/microsoft/Phi-3.5-vision-instruct) for the base vision-language model
192
+ - [Vertex AI Gemini 2.5 Flash](https://cloud.google.com/vertex-ai) for dataset annotation
193
+ - [HuggingFace TRL](https://github.com/huggingface/trl) for SFTTrainer
chat_template.jinja ADDED
@@ -0,0 +1,7 @@
 
 
 
 
 
 
 
 
1
+ {% set image_count = namespace(value=0) %}{% set video_count = namespace(value=0) %}{% for message in messages %}{% if loop.first and message['role'] != 'system' %}<|im_start|>system
2
+ You are a helpful assistant.<|im_end|>
3
+ {% endif %}<|im_start|>{{ message['role'] }}
4
+ {% if message['content'] is string %}{{ message['content'] }}<|im_end|>
5
+ {% 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 %}<|im_end|>
6
+ {% endif %}{% endfor %}{% if add_generation_prompt %}<|im_start|>assistant
7
+ {% endif %}
config.json ADDED
@@ -0,0 +1,97 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "architectures": [
3
+ "Qwen2VLForConditionalGeneration"
4
+ ],
5
+ "dtype": "bfloat16",
6
+ "image_token_id": 151655,
7
+ "model_name": "unsloth/qwen2-vl-7b-instruct",
8
+ "model_type": "qwen2_vl",
9
+ "pad_token_id": 151654,
10
+ "text_config": {
11
+ "attention_dropout": 0.0,
12
+ "bos_token_id": 151643,
13
+ "dtype": "bfloat16",
14
+ "eos_token_id": 151645,
15
+ "hidden_act": "silu",
16
+ "hidden_size": 3584,
17
+ "initializer_range": 0.02,
18
+ "intermediate_size": 18944,
19
+ "layer_types": [
20
+ "full_attention",
21
+ "full_attention",
22
+ "full_attention",
23
+ "full_attention",
24
+ "full_attention",
25
+ "full_attention",
26
+ "full_attention",
27
+ "full_attention",
28
+ "full_attention",
29
+ "full_attention",
30
+ "full_attention",
31
+ "full_attention",
32
+ "full_attention",
33
+ "full_attention",
34
+ "full_attention",
35
+ "full_attention",
36
+ "full_attention",
37
+ "full_attention",
38
+ "full_attention",
39
+ "full_attention",
40
+ "full_attention",
41
+ "full_attention",
42
+ "full_attention",
43
+ "full_attention",
44
+ "full_attention",
45
+ "full_attention",
46
+ "full_attention",
47
+ "full_attention"
48
+ ],
49
+ "max_position_embeddings": 32768,
50
+ "max_window_layers": 28,
51
+ "model_type": "qwen2_vl_text",
52
+ "num_attention_heads": 28,
53
+ "num_hidden_layers": 28,
54
+ "num_key_value_heads": 4,
55
+ "pad_token_id": 151654,
56
+ "rms_norm_eps": 1e-06,
57
+ "rope_parameters": {
58
+ "mrope_section": [
59
+ 16,
60
+ 24,
61
+ 24
62
+ ],
63
+ "rope_theta": 1000000.0,
64
+ "rope_type": "default",
65
+ "type": "default"
66
+ },
67
+ "sliding_window": null,
68
+ "use_cache": true,
69
+ "use_sliding_window": false,
70
+ "vocab_size": 152064
71
+ },
72
+ "tie_word_embeddings": false,
73
+ "transformers_version": "5.5.0",
74
+ "unsloth_fixed": true,
75
+ "unsloth_version": "2026.5.2",
76
+ "video_token_id": 151656,
77
+ "vision_config": {
78
+ "depth": 32,
79
+ "dtype": "bfloat16",
80
+ "embed_dim": 1280,
81
+ "hidden_act": "quick_gelu",
82
+ "hidden_size": 3584,
83
+ "in_channels": 3,
84
+ "in_chans": 3,
85
+ "initializer_range": 0.02,
86
+ "mlp_ratio": 4,
87
+ "model_type": "qwen2_vl",
88
+ "num_heads": 16,
89
+ "patch_size": 14,
90
+ "spatial_merge_size": 2,
91
+ "spatial_patch_size": 14,
92
+ "temporal_patch_size": 2
93
+ },
94
+ "vision_end_token_id": 151653,
95
+ "vision_start_token_id": 151652,
96
+ "vision_token_id": 151654
97
+ }
generation_config.json ADDED
@@ -0,0 +1,14 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "bos_token_id": 151643,
3
+ "do_sample": true,
4
+ "eos_token_id": [
5
+ 151645,
6
+ 151643
7
+ ],
8
+ "max_length": 32768,
9
+ "pad_token_id": 151654,
10
+ "temperature": 0.01,
11
+ "top_k": 1,
12
+ "top_p": 0.001,
13
+ "transformers_version": "5.5.0"
14
+ }
model.safetensors ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:59961635740e113ac4a54c794c96d048a2220410ba4984cbbf7ee5cc66c205fe
3
+ size 16582834600
processor_config.json ADDED
@@ -0,0 +1,59 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "image_processor": {
3
+ "do_convert_rgb": true,
4
+ "do_normalize": true,
5
+ "do_rescale": true,
6
+ "do_resize": true,
7
+ "image_mean": [
8
+ 0.48145466,
9
+ 0.4578275,
10
+ 0.40821073
11
+ ],
12
+ "image_processor_type": "Qwen2VLImageProcessor",
13
+ "image_std": [
14
+ 0.26862954,
15
+ 0.26130258,
16
+ 0.27577711
17
+ ],
18
+ "merge_size": 2,
19
+ "patch_size": 14,
20
+ "resample": 3,
21
+ "rescale_factor": 0.00392156862745098,
22
+ "size": {
23
+ "longest_edge": 12845056,
24
+ "shortest_edge": 3136
25
+ },
26
+ "temporal_patch_size": 2
27
+ },
28
+ "processor_class": "Qwen2VLProcessor",
29
+ "video_processor": {
30
+ "do_convert_rgb": true,
31
+ "do_normalize": true,
32
+ "do_rescale": true,
33
+ "do_resize": true,
34
+ "do_sample_frames": false,
35
+ "image_mean": [
36
+ 0.48145466,
37
+ 0.4578275,
38
+ 0.40821073
39
+ ],
40
+ "image_std": [
41
+ 0.26862954,
42
+ 0.26130258,
43
+ 0.27577711
44
+ ],
45
+ "max_frames": 768,
46
+ "merge_size": 2,
47
+ "min_frames": 4,
48
+ "patch_size": 14,
49
+ "resample": 3,
50
+ "rescale_factor": 0.00392156862745098,
51
+ "return_metadata": false,
52
+ "size": {
53
+ "longest_edge": 12845056,
54
+ "shortest_edge": 3136
55
+ },
56
+ "temporal_patch_size": 2,
57
+ "video_processor_type": "Qwen2VLVideoProcessor"
58
+ }
59
+ }
tokenizer.json ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:ff8cce547abc110590d19c6b5b6e0c6a7b4c8d1012d78b9c42131bae7f494a02
3
+ size 11420367
tokenizer_config.json ADDED
@@ -0,0 +1,130 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "add_prefix_space": false,
3
+ "backend": "tokenizers",
4
+ "bos_token": null,
5
+ "clean_up_tokenization_spaces": false,
6
+ "eos_token": "<|im_end|>",
7
+ "errors": "replace",
8
+ "is_local": false,
9
+ "model_max_length": 32768,
10
+ "pad_token": "<|vision_pad|>",
11
+ "padding_side": "left",
12
+ "processor_class": "Qwen2VLProcessor",
13
+ "split_special_tokens": false,
14
+ "tokenizer_class": "Qwen2Tokenizer",
15
+ "unk_token": null,
16
+ "added_tokens_decoder": {
17
+ "151643": {
18
+ "content": "<|endoftext|>",
19
+ "single_word": false,
20
+ "lstrip": false,
21
+ "rstrip": false,
22
+ "normalized": false,
23
+ "special": true
24
+ },
25
+ "151644": {
26
+ "content": "<|im_start|>",
27
+ "single_word": false,
28
+ "lstrip": false,
29
+ "rstrip": false,
30
+ "normalized": false,
31
+ "special": true
32
+ },
33
+ "151645": {
34
+ "content": "<|im_end|>",
35
+ "single_word": false,
36
+ "lstrip": false,
37
+ "rstrip": false,
38
+ "normalized": false,
39
+ "special": true
40
+ },
41
+ "151646": {
42
+ "content": "<|object_ref_start|>",
43
+ "single_word": false,
44
+ "lstrip": false,
45
+ "rstrip": false,
46
+ "normalized": false,
47
+ "special": true
48
+ },
49
+ "151647": {
50
+ "content": "<|object_ref_end|>",
51
+ "single_word": false,
52
+ "lstrip": false,
53
+ "rstrip": false,
54
+ "normalized": false,
55
+ "special": true
56
+ },
57
+ "151648": {
58
+ "content": "<|box_start|>",
59
+ "single_word": false,
60
+ "lstrip": false,
61
+ "rstrip": false,
62
+ "normalized": false,
63
+ "special": true
64
+ },
65
+ "151649": {
66
+ "content": "<|box_end|>",
67
+ "single_word": false,
68
+ "lstrip": false,
69
+ "rstrip": false,
70
+ "normalized": false,
71
+ "special": true
72
+ },
73
+ "151650": {
74
+ "content": "<|quad_start|>",
75
+ "single_word": false,
76
+ "lstrip": false,
77
+ "rstrip": false,
78
+ "normalized": false,
79
+ "special": true
80
+ },
81
+ "151651": {
82
+ "content": "<|quad_end|>",
83
+ "single_word": false,
84
+ "lstrip": false,
85
+ "rstrip": false,
86
+ "normalized": false,
87
+ "special": true
88
+ },
89
+ "151652": {
90
+ "content": "<|vision_start|>",
91
+ "single_word": false,
92
+ "lstrip": false,
93
+ "rstrip": false,
94
+ "normalized": false,
95
+ "special": true
96
+ },
97
+ "151653": {
98
+ "content": "<|vision_end|>",
99
+ "single_word": false,
100
+ "lstrip": false,
101
+ "rstrip": false,
102
+ "normalized": false,
103
+ "special": true
104
+ },
105
+ "151654": {
106
+ "content": "<|vision_pad|>",
107
+ "single_word": false,
108
+ "lstrip": false,
109
+ "rstrip": false,
110
+ "normalized": false,
111
+ "special": true
112
+ },
113
+ "151655": {
114
+ "content": "<|image_pad|>",
115
+ "single_word": false,
116
+ "lstrip": false,
117
+ "rstrip": false,
118
+ "normalized": false,
119
+ "special": true
120
+ },
121
+ "151656": {
122
+ "content": "<|video_pad|>",
123
+ "single_word": false,
124
+ "lstrip": false,
125
+ "rstrip": false,
126
+ "normalized": false,
127
+ "special": true
128
+ }
129
+ }
130
+ }