Update model card: usage, evaluation and task prompts

README.md

@@ -1,133 +1,147 @@
 ---
-tasks: []
+language:
+- zh
+license: apache-2.0
+library_name: transformers
+pipeline_tag: text-generation
+tags:
+- qwen3
+- traditional-chinese-medicine
+- lingdan-v2
+- base
 ---
+
+# Lingdan-14B-Base
+
 <p align="center">
   <img width="420" src="https://raw.githubusercontent.com/TCMAI-BJTU/Lingdan-V2/main/assets/logo.png" alt="Lingdan-V2 logo" />
 </p>
 
 <p align="center"><strong>Lingdan-V2: Large Language Models for Clinically Grounded Reasoning in Traditional Chinese Medicine</strong></p>
 
-<p align="center">A multi-scale family of language models for TCM knowledge comprehension, clinical reasoning, and prescription recommendation</p>
+<p align="center">
+  <a href="http://tcmai.chat/">
+    <img src="https://img.shields.io/badge/OPEN_LINGDAN--V2_ONLINE-tcmai.chat-F28C28?style=for-the-badge&logo=googlechrome&logoColor=white" alt="Open the Lingdan-V2 online demo" />
+  </a>
+</p>
 
 <p align="center">
-  <a href="https://modelscope.cn/organization/TCMAIBJTU"><img src="https://img.shields.io/badge/Models-ModelScope-624AFF" alt="ModelScope models" /></a>
-  <a href="http://tcmai.chat/"><img src="https://img.shields.io/badge/Online_Demo-tcmai.chat-F28C28" alt="Lingdan-V2 online demo" /></a>
+  <a href="https://modelscope.cn/collections/TCMAIBJTU/Lingdan-V2"><img src="https://img.shields.io/badge/Models-ModelScope-624AFF" alt="ModelScope models" /></a>
   <a href="https://github.com/TCMAI-BJTU/LingLan"><img src="https://img.shields.io/badge/Benchmark-LingLan-2A8F5B" alt="LingLan benchmark" /></a>
   <img src="https://img.shields.io/badge/Model_scales-4B_%7C_8B_%7C_14B-0B5394" alt="Model scales: 4B, 8B, and 14B" />
   <a href="https://github.com/TCMAI-BJTU/Lingdan-V2/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache--2.0-D22128" alt="Apache License 2.0" /></a>
 </p>
 
-<p align="center">
-  <a href="#overview">Overview</a> ·
-  <a href="#model-zoo">Model Zoo</a> ·
-  <a href="#study-design">Study Design</a> ·
-  <a href="#main-results">Main Results</a> ·
-  <a href="#data-privacy-and-responsible-use">Responsible Use</a> ·
-  <a href="#license">License</a>
-</p>
-
-## Overview
-
-Clinical decision-making in traditional Chinese medicine (TCM) requires the joint integration of domain knowledge, symptom presentations, syndrome differentiation, treatment principle selection, herbal prescription composition, and dosage information. Although general-purpose large language models demonstrate strong language understanding capabilities, they remain limited in their adaptation to specialized TCM knowledge, complex diagnostic-therapeutic reasoning, and structured prescription generation.
-
-Lingdan-V2 is a family of TCM large language models developed from Qwen3 backbone models at three parameter scales: 4B, 8B, and 14B. Through TCM-domain continued pretraining (CPT), reasoning-oriented supervised fine-tuning (SFT), and prescription-centered Group Relative Policy Optimization (GRPO), the models progressively acquire domain knowledge, task execution capabilities, structured reasoning, and prescription decision-making abilities. Lingdan-14B-R1 is the primary model investigated in this study, while the 4B and 8B series provide complementary evidence regarding the effects of model scale and prescription-centered post-training.
-
-| Model family | CPT corpus | SFT corpus | GRPO data | Evaluation scale |
-| --- | ---: | ---: | ---: | ---: |
-| 4B, 8B, and 14B × Base, SFT, and R1 | 16.62B tokens | 7.73M samples / 2.08B tokens | 24,212 Samples | LingLan: 25,624 items / Private clinical set: 4,348 cases |
-
-<p align="center">
-  <img width="100%" src="https://raw.githubusercontent.com/TCMAI-BJTU/Lingdan-V2/main/assets/overview.png" alt="Overview of Lingdan-V2 development and evaluation" />
-</p>
-<p align="center"><sub>Figure 1. Data foundation, staged training pipeline, and evaluation settings of Lingdan-V2.</sub></p>
-
-## Key Contributions
-
-- **A multi-scale family of TCM language models:** We develop Base, SFT, and R1 models at the 4B, 8B, and 14B parameter scales to support domain research, instruction-following tasks, and TCM clinical reasoning.
-- **A staged pathway for capability development:** We integrate large-scale TCM knowledge acquisition, reasoning-oriented supervised learning, and prescription-centered reinforcement post-training within a unified framework.
-- **A systematic evaluation of TCM clinical reasoning:** We evaluate TCM knowledge, information extraction, diagnostic-therapeutic reasoning, decision recognition, prescription composition, and dosage agreement on LingLan, LingLan-Hard, and a private prescription dataset for spleen and stomach disorders.
-
-## Model Zoo
-
-All models are released on ModelScope. Model names follow the unified format `Lingdan-{Scale}-{Stage}`.
+## Contents
 
-| Model scale | Base | SFT | R1 |
-| --- | --- | --- | --- |
-| 4B | [Lingdan-4B-Base](https://modelscope.cn/models/TCMAIBJTU/Lingdan-4B-Base) | [Lingdan-4B-SFT](https://modelscope.cn/models/TCMAIBJTU/Lingdan-4B-SFT) | [Lingdan-4B-R1](https://modelscope.cn/models/TCMAIBJTU/Lingdan-4B-R1) |
-| 8B | [Lingdan-8B-Base](https://modelscope.cn/models/TCMAIBJTU/Lingdan-8B-Base) | [Lingdan-8B-SFT](https://modelscope.cn/models/TCMAIBJTU/Lingdan-8B-SFT) | [Lingdan-8B-R1](https://modelscope.cn/models/TCMAIBJTU/Lingdan-8B-R1) |
-| 14B | [Lingdan-14B-Base](https://modelscope.cn/models/TCMAIBJTU/Lingdan-14B-Base) | [Lingdan-14B-SFT](https://modelscope.cn/models/TCMAIBJTU/Lingdan-14B-SFT) | [Lingdan-14B-R1](https://modelscope.cn/models/TCMAIBJTU/Lingdan-14B-R1) |
+1. [Model Details](#model-details)
+2. [Quickstart](#quickstart)
+3. [vLLM Deployment](#vllm-deployment)
+4. [Data Privacy and Responsible Use](#data-privacy-and-responsible-use)
+5. [License](#license)
+6. [Citation](#citation)
+7. [Related Links](#related-links)
 
-- **Base:** Continued pretrained models for further fine-tuning and domain-specific research.
-- **SFT:** Models obtained by supervised fine-tuning of the Base checkpoints for TCM question answering, information extraction, and general diagnostic and therapeutic instruction-following tasks.
-- **R1:** Models aligned from the SFT checkpoints through prescription-centered GRPO, with an emphasis on structured clinical reasoning and prescription recommendation.
+## Model Details
 
-## Study Design
+**Lingdan-14B-Base** is a Qwen3-based TCM model in the [Lingdan-V2 family](https://github.com/TCMAI-BJTU/Lingdan-V2). CPT on 16.62B tokens.
 
-### Data Foundation and Staged Training
+| Field | Value |
+| --- | --- |
+| Parameter scale | 14B |
+| Architecture family | Qwen3 causal language model |
+| Training stage | Continued pretraining (CPT) |
+| Starting checkpoint / backbone | Qwen3 14B backbone |
+| Intended use | Text completion, domain research, and further fine-tuning |
+| Platform model ID | `TCMLLM/Lingdan-14B-Base` |
 
-1. **Continued pretraining (CPT):** Lingdan-Base models are trained on 16.62B tokens of TCM and clinically relevant text, including clinical data, classical and modern TCM literature, structured knowledge, public medical data, and general-domain corpora.
-2. **Supervised fine-tuning (SFT):** Lingdan-SFT models are trained on 7,729,982 samples comprising 2.08B tokens. The tasks include TCM question answering, information extraction, diagnostic-therapeutic reasoning, clinical cases, and prescription generation.
-3. **Prescription-centered GRPO:** Lingdan-R1 models are trained on 24,212 Samples, with prescription composition agreement serving as the primary optimization objective.
+## Quickstart
 
-### Evaluation Settings
+Use Transformers ≥4.51.0; see the [Qwen3 quickstart](https://qwen.readthedocs.io/en/stable/getting_started/quickstart.html).
 
-- **LingLan:** 25,624 expert-verified samples spanning five TCM capability domains and 13 subtasks.
-- **LingLan-Hard:** 5,200 challenging samples, with 400 samples selected from each subtask.
-- **Private clinical prescription evaluation:** 4,348 de-identified cases involving spleen and stomach disorders, used to evaluate prescription composition and dosage agreement. The original clinical data are not publicly released.
+```bash
+pip install -U torch transformers accelerate
+```
 
-## Main Results
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_name = "TCMLLM/Lingdan-14B-Base"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForCausalLM.from_pretrained(
+    model_name,
+    torch_dtype="auto",
+    device_map="auto",
+).eval()
+
+# Base checkpoints are intended for completion and further fine-tuning.
+text = "中医辨证论治的基本概念是"
+inputs = tokenizer([text], return_tensors="pt").to(model.device)
+outputs = model.generate(
+    **inputs,
+    max_new_tokens=1024,
+    do_sample=True,
+    temperature=0.6,
+    top_p=0.95,
+    top_k=20,
+)
+new_tokens = outputs[0, inputs.input_ids.shape[1]:]
+print(tokenizer.decode(new_tokens, skip_special_tokens=True))
+```
 
-### Comprehensive Benchmark Performance
+## vLLM Deployment
 
-Lingdan-14B-R1 achieves an Overall Score of **67.1** on the full LingLan benchmark and **45.3** on LingLan-Hard. Among the external models evaluated in this study, DeepSeek-R1 obtains corresponding scores of 64.6 and 38.9. Lingdan-14B-R1 also achieves prescription-generation F1 scores of 37.0 on the full benchmark and 24.9 on the challenging subset.
+Install vLLM in a GPU environment with compatible CUDA/PyTorch; see the [Qwen3 vLLM guide](https://qwen.readthedocs.io/en/stable/deployment/vllm.html).
 
-The Overall Score is computed as the unweighted mean of 16 primary metrics.
+```bash
+pip install -U "vllm>=0.9.0" openai
+```
 
-<p align="center">
-  <img width="760" src="https://raw.githubusercontent.com/TCMAI-BJTU/Lingdan-V2/main/assets/overall_score_comparison.png" alt="Overall Score comparison on LingLan and LingLan-Hard" />
-</p>
-<p align="center"><sub>Figure 2. Overall Score comparison between Lingdan-14B-R1 and external models of different scales on LingLan and LingLan-Hard.</sub></p>
+### Start the Server
 
-### Performance Changes from SFT to R1
+**Hugging Face:**
 
-Within the primary 14B model trajectory, prescription-centered GRPO improves the Overall Score from 65.3 to 67.1 on the full LingLan benchmark and from 41.3 to 45.3 on LingLan-Hard. Prescription-generation F1 increases from 30.9 to 37.0 on the full benchmark and from 17.4 to 24.9 on the challenging subset.
+```bash
+export VLLM_USE_MODELSCOPE=false
+vllm serve TCMLLM/Lingdan-14B-Base \
+  --served-model-name Lingdan-14B-Base \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --max-model-len 16384
+```
 
-Overall Score and prescription-generation F1 improve from SFT to R1 across the 4B, 8B, and 14B model scales on both LingLan and LingLan-Hard. At 8B, Overall Score increases from 63.0 to 63.7 on the full benchmark and from 36.6 to 39.1 on LingLan-Hard, while prescription-generation F1 increases from 29.8 to 34.5 and from 16.1 to 22.6, respectively. The largest gains were observed in prescription generation, the task directly optimized during GRPO..
+Replace the repository ID with a local model directory to reuse downloaded files. For two GPUs, append `--tensor-parallel-size 2`. Adjust the 16,384-token context limit (input + output) to available GPU memory.
 
-<p align="center">
-  <img width="100%" src="https://raw.githubusercontent.com/TCMAI-BJTU/Lingdan-V2/main/assets/training_stage_performance.png" alt="Performance changes from SFT to R1 across Lingdan-V2 model scales" />
-</p>
-<p align="center"><sub>Figure 3. Changes in Overall Score and prescription-generation F1 from SFT to R1 across the 4B, 8B, and 14B models.</sub></p>
+### Completion Client
 
-### Private Clinical Prescription Evaluation
+```python
+from openai import OpenAI
 
-On 4,348 de-identified cases involving spleen and stomach disorders, Lingdan-14B-R1 achieves a herb-level F1 score of **52.8**, a dosage cosine similarity of **50.6**, and a dosage MAE of **4.369**. Under the retrospective, text-based evaluation protocol defined in this study, these results indicate closer agreement with the reference prescriptions in both herbal composition and dosage structure.
+client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="EMPTY")
+response = client.completions.create(
+    model="Lingdan-14B-Base",
+    prompt="中医辨证论治的基本特点是",
+    max_tokens=512,
+    temperature=0.6,
+    top_p=0.95,
+    extra_body={"top_k": 20},
+)
+print(response.choices[0].text)
+```
 
-<p align="center">
-  <img width="100%" src="https://raw.githubusercontent.com/TCMAI-BJTU/Lingdan-V2/main/assets/private_prescription_recommendation.png" alt="Private prescription recommendation results for spleen and stomach disorders" />
-</p>
-<p align="center"><sub>Figure 4. Herbal composition F1, dosage cosine similarity, and dosage MAE in the private clinical prescription evaluation for spleen and stomach disorders.</sub></p>
+`EMPTY` is a placeholder for the local server started without API-key authentication.
 
 ## Data Privacy and Responsible Use
 
-- The training and evaluation of Lingdan-V2 involve both public data and restricted clinical data. The repository does not disclose original private clinical cases, patient identifiers, medical record excerpts, or other information that could enable patient re-identification.
-- The private clinical evaluation is a retrospective, text-based assessment of prescription agreement. It does not constitute prospective clinical validation or evidence of effectiveness in real-world clinical practice.
-- Lingdan-V2 is intended solely for scientific and technical research. It does not provide medical advice and must not replace diagnosis, syndrome differentiation, treatment, or prescription review by qualified healthcare professionals.
-
+Lingdan-V2 is for research and does not replace qualified clinical judgment. Private clinical data are not released. Retrospective prescription agreement is not evidence of clinical safety or effectiveness; use de-identified inputs and professional review for any clinical application.
 
 ## License
 
-The Lingdan-V2 model weights, together with the documentation and images in this repository for which the project authors hold copyright, are released under the [Apache License 2.0](https://github.com/TCMAI-BJTU/Lingdan-V2/blob/main/LICENSE). Lingdan-V2 is developed from Qwen3 open-weight models, which are also released under the Apache License 2.0.
-
-Subject to the terms of the Apache License 2.0, personal, research, and commercial use is permitted, as are copying, modification, and redistribution. Redistributions of the original or derivative versions must retain the license text and all applicable copyright, patent, trademark, and attribution notices; disclose any modifications; and preserve the project's [NOTICE](https://github.com/TCMAI-BJTU/Lingdan-V2/blob/main/NOTICE) file.
-
-The Apache License 2.0 does not relicense third-party training data, external benchmark materials, or private clinical data. These resources remain subject to their original licenses, data-use agreements, and privacy requirements. The medical safety statements above describe the intended use and associated risks of the models; they do not impose additional restrictions under the Apache License 2.0. Users are responsible for deployment decisions, regulatory compliance, and any clinical use.
-
-This section is provided only as a summary. The `LICENSE` and `NOTICE` files in this repository govern the applicable rights and obligations.
+Lingdan-V2 model weights and project-owned documentation and images are released under the [Apache License 2.0](https://github.com/TCMAI-BJTU/Lingdan-V2/blob/main/LICENSE). See [NOTICE](https://github.com/TCMAI-BJTU/Lingdan-V2/blob/main/NOTICE) for attribution notices. Third-party data and materials remain subject to their original terms.
 
 ## Citation
 
-If you use Lingdan-V2 in your research, please cite this project:
+Cite Lingdan-V2 and the earlier Lingdan work:
 
 ```bibtex
 @misc{hua2026lingdanv2,
@@ -136,11 +150,21 @@ If you use Lingdan-V2 in your research, please cite this project:
   year   = {2026},
   url    = {https://github.com/TCMAI-BJTU/Lingdan-V2}
 }
+
+@article{hua2024lingdan,
+  title={Lingdan: enhancing encoding of traditional Chinese medicine knowledge for clinical reasoning tasks with large language models},
+  author={Hua, Rui and Dong, Xin and Wei, Yu and Shu, Zixin and Yang, Pengcheng and Hu, Yunhui and Zhou, Shuiping and Sun, He and Yan, Kaijing and Yan, Xijun and others},
+  journal={Journal of the American Medical Informatics Association},
+  volume={31},
+  number={9},
+  pages={2019--2029},
+  year={2024},
+  publisher={Oxford University Press}
+}
 ```
 
 ## Related Links
 
-- [Lingdan-V2 GitHub](https://github.com/TCMAI-BJTU/Lingdan-V2)
-- [Lingdan-V2 models on ModelScope](https://modelscope.cn/organization/TCMAIBJTU)
-- [LingLan benchmark](https://github.com/TCMAI-BJTU/LingLan)
+[GitHub](https://github.com/TCMAI-BJTU/Lingdan-V2) · [Hugging Face collection](https://huggingface.co/collections/TCMLLM/lingdan-v2) · [ModelScope collection](https://modelscope.cn/collections/TCMAIBJTU/Lingdan-V2) · [LingLan benchmark](https://github.com/TCMAI-BJTU/LingLan)
 
+For task prompts and thinking-mode chat, see the [SFT/R1 guide](https://github.com/TCMAI-BJTU/Lingdan-V2#task-prompts).