Downloads ยท 30 days
7
19% of all-time downloads
fundusnap/fundusnap-v1-resultexp-clm-mediphi-3.8b-adapter
fundusnap-v1-resultexp-clm-mediphi-3.8b-adapter is a text generation model from fundusnap. Use it when you need the model to write or continue text. It is set up for peft. The card lists the license as cc-by-nc-4.0.
<div align="center" <table border="1" <tr <td align="center" style="padding: 20px;" <h3๐ข Domain & Email Migration Notice</h3 <pFrom <bMay 30th, 2026</b, Fundusnap will transition to new domains as <codefundusnap.com<โฆ
Downloads ยท 30 days
7
19% of all-time downloads
All-time downloads
36
Public
Repo size
201 MB
Likes
1
Public
Click a slice to open those files.
.safetensors201 MB ยท 98%
From the Hugging Face model README
A LoRA adapter over microsoft/MediPhi-Instruct
that turns a Fundusnap prediction record into a plain-language explanation, in Indonesian
or English. It is the conversational layer of the Fundusnap pipeline โ the third model,
and the only one that never sees an image.
It reads the output of the other two:
| model | produces | this model receives |
|---|---|---|
| Azure Custom Vision | six-class DR severity probabilities | as a system message |
fundusnap-v1-lesiondet-yolo11m-20m | lesion bounding boxes + confidences | as a system message |
This is not a medical device and has no regulatory clearance. It explains what an AI screening system reported; it does not diagnose, grade, triage, or recommend treatment. Every output must be reviewed by a qualified clinician, and it must never be the sole basis for diagnosis, referral or treatment.
It is designed to be explanatory rather than diagnostic, and the training data enforces that: every conversation routes the user to an ophthalmologist or healthcare professional.
| file | what it is |
|---|---|
adapter_model.safetensors | the LoRA weights โ 201 MB, 256 tensors, git-lfs |
adapter_config.json | PEFT config: r=32, ฮฑ=64, dropout 0.05 |
chat_template.jinja | Phi-3 chat template โ required, this is the trained prompt format |
tokenizer.json, tokenizer_config.json | tokenizer (eos <|endoftext|>, turn terminator <|end|>) |
inference.py | load + build the production envelope + generate |
serve.py | FastAPI: GET /, POST /chat, POST /prompt |
merge.py | fuse adapter into base โ standalone ~7.6 GB checkpoint |
eval/ | evaluation report, metrics, and all 120 generated samples |
train/ | training script, scorer, training log |
pip install -r requirements.txt
python inference.py --demo
from inference import FundusnapAssistant
bot = FundusnapAssistant() # downloads the 7.6 GB base model on first run
print(bot.respond(
severity=[{"probability": 0.5410275, "tagName": "Moderate NPDR"},
{"probability": 0.1894375, "tagName": "Severe NPDR"}],
detections=[{"class_name": "Microaneurysm", "confidence": 0.42},
{"class_name": "Disc", "confidence": 0.81}],
turns=[{"role": "user", "content": "Apa arti hasil pemeriksaan ini?"}],
))
uvicorn serve:app --host 0.0.0.0 --port 8000 # docs at /docs
curl -X POST localhost:8000/chat -H 'content-type: application/json' -d '{
"severity": [{"probability":0.5410275,"tagName":"Moderate NPDR"}],
"detections": [{"class_name":"Microaneurysm","confidence":0.42}],
"messages": [{"role":"user","content":"Apa arti hasil ini?"}]
}'
POST /prompt returns the exact envelope without generating โ use it to confirm a caller
is sending the right shape before blaming the model for a bad answer.
docker build -t fundusnap-resultexp .
docker run --gpus all -p 8000:8000 -v hf:/root/.cache/huggingface fundusnap-resultexp
The base weights are not baked into the image; mount a cache or every restart re-downloads 7.6 GB.
The model was fine-tuned on the exact three-system-message envelope the Fundusnap API
sends (chat.controller.js) โ persona, then severity JSON, then detection JSON, in that
order, with JSON serialized the way JavaScript's JSON.stringify does it (no spaces after
separators). build_messages() reproduces it, and is verified byte-for-byte against all
324 held-out records. Merging the system messages, reordering them, or pretty-printing the
JSON all move the input off the trained distribution and degrade grounding.
Two generation details are load-bearing:
eos_token_id = [<|end|>, <|endoftext|>] # <|end|> ends a TURN; omitting it lets the
# model run on and answer as the user
tokenizer(text, add_special_tokens=False) # the template already emits specials
QLoRA-style supervised fine-tuning, loss on assistant turns only.
| Base | microsoft/MediPhi-Instruct (Phi-3, 3.82B) |
| Trainable | 50,331,648 params (1.30%) |
| Targets | qkv_proj, o_proj, gate_up_proj, down_proj |
| LoRA | r=32, ฮฑ=64, dropout 0.05 |
| Data | fundusnap-fundustalk-v1-chatsft-11k โ 10,201 train / 324 val / 324 test, distilled from microsoft/phi-4 |
| Languages | ~70% Indonesian (incl. code-switched), ~30% English |
| Schedule | 2 epochs, 638 steps, lr 1e-4 cosine, effective batch 32, bf16 |
| Hardware | 1ร A100-SXM4-40GB, 170 min |
| Final val loss | 0.691 (from 1.229) |
Training data is fully synthetic โ no patient data was used, and no real conversation was recorded. Prediction records were procedurally generated from the distributions the production models actually produce (lesion confidences kept low to match the detector's real mAP@50-95 โ 0.28 and recall โ 0.53).
The corpus is published as
fundusnap/fundusnap-fundustalk-v1-chatsft-11k:
10,849 conversations survive validation, split 10,201 train / 324 val / 324 test โ the
11k in the dataset name is the full corpus, not the training split.
See train/train_mediphi.py and train/README.md. The latter documents a non-obvious
trap: the Phi-3 chat template appends <|endoftext|> to every render, so the common
"diff successive apply_chat_template calls" recipe for building a loss mask silently
misaligns every segment boundary.
60 held-out conversations, production envelope, temperature 0.4. Full report and all
samples in eval/.
| tuned | base (untuned) | reference (teacher) | |
|---|---|---|---|
| grounded โ quoted probabilities exist in the record | 100% | 98% | 100% |
| referral โ routes to a clinician | 70% | 70% | 62% |
| no-diagnosis โ no first-person dx | 100% | 100% | 100% |
| anatomy โ Disc/Fovea/Artefact not framed as damage | 100% | 97% | 98% |
Read that table honestly: the untuned base model scores within 1โ2 samples of the tuned one on every metric. These are presence/absence regex checks, and the base model already mentions doctors, avoids first-person diagnosis, and echoes numbers from its context. This table is not evidence that fine-tuning worked.
reference is the teacher's own replies scored identically โ the ceiling worth chasing,
not 100%. referral sits near 62% for the teacher because the dataset enforces a clinician
referral once per conversation while the scorer reads only the first turn.
| tuned | base | |
|---|---|---|
| replies under 30 words (stub / unhelpful) | 0/60 | 10/60 |
| Indonesian prompt โ Indonesian reply | 40/41 | 35/41 |
| mean reply length | 75 words | 63 |
The base model produces a stub or drifts to English on roughly a sixth of prompts; the tuned model does not. Qualitatively โ observed in read samples, not measured at scale โ the base model's Indonesian is frequently ungrammatical or wrong-register, and it misdefines the severity numbers as "the probability the photo contains each type of DR", precisely the confidence-vs-disease-probability error the training data exists to correct.
On one record the model reported "6 temuan yang diidentifikasi sebagai lesi aktual" where
the record holds 7 lesions (8 boxes minus Disc). It passed all four scorers, because
grounding validates decimal probabilities only โ integer counts are unchecked. Only 3 of
60 replies make a count claim at all, so this is 1 confirmed miscount out of 2 genuine
claims: real, but too rare to rate. Counting is the weakest observed behaviour.
Disc, Fovea and Artefact are not lesions. The first two are normal anatomy
present in essentially every gradable image; the third flags capture quality. Any caller
that counts detections as evidence of disease must exclude them โ serve.py does.For production, merge and serve with a dedicated inference stack:
python merge.py --out ./merged
vllm serve ./merged --max-model-len 4096
Then repoint fundusnap-api's chat controller at that endpoint. Two API-side issues are
worth fixing first, since both feed this model malformed context:
GET /service/predict/read/:id leaks system messages into resumed transcripts, and the
chat reply path replays unbounded history with no windowing.
Model weights: CC BY-NC 4.0. Code in this repository: MIT. See LICENSE.
| component | license |
|---|---|
microsoft/MediPhi-Instruct (base) | MIT |
microsoft/phi-4 (teacher for data generation) | MIT |
| detection class taxonomy used in the prompts | CC BY-NC 4.0 + AGPL-3.0 (from the YOLO checkpoint) |
| this adapter | CC BY-NC 4.0 |
Neither upstream model imposes non-commercial terms โ both are MIT. The NonCommercial restriction is Fundusnap's own choice, for consistency with the other Fundusnap model releases, and is not inherited from upstream.
@misc{fundusnap2026resultexp,
title = {Fundusnap Result Explanation: a LoRA adapter for patient-facing
diabetic retinopathy screening explanations},
author = {Fundusnap},
year = {2026},
howpublished = {\url{https://github.com/fundusnap/fundusnap-v1-resultexp-clm-mediphi-3.8b-adapter}},
note = {LoRA adapter over microsoft/MediPhi-Instruct. Not a medical device.},
license = {CC-BY-NC-4.0}
}