Update model card with honest metrics and known limitations

README.md

@@ -1,75 +1,85 @@
 ---
-library_name: transformers
+language:
+- zh
 license: apache-2.0
-base_model: hfl/chinese-macbert-base
+library_name: transformers
 tags:
-- generated_from_trainer
-metrics:
-- accuracy
-model-index:
-- name: vulnerability-severity-classification-chinese-macbert-base-test
-  results: []
+- text-classification
+- vulnerability
+- severity
+- cybersecurity
+- cnvd
+datasets:
+- CIRCL/Vulnerability-CNVD
+base_model: hfl/chinese-macbert-base
+pipeline_tag: text-classification
 ---
 
-<!-- This model card has been generated automatically according to the information the Trainer had access to. You
-should probably proofread and complete it, then remove this comment. -->
+# VLAI: Automated Vulnerability Severity Classification (Chinese Text)
+
+A fine-tuned [hfl/chinese-macbert-base](https://huggingface.co/hfl/chinese-macbert-base) model for classifying Chinese vulnerability descriptions from the [China National Vulnerability Database (CNVD)](https://www.cnvd.org.cn/) into three severity levels: **Low**, **Medium**, and **High**.
+
+Trained on the [CIRCL/Vulnerability-CNVD](https://huggingface.co/datasets/CIRCL/Vulnerability-CNVD) dataset as part of the [VulnTrain](https://github.com/vulnerability-lookup/VulnTrain) project.
+
+## Evaluation results
+
+Evaluated on a **deduplicated test set** (25,845 samples) where no description text appears in both train and test splits, preventing data leakage from CNVD's reuse of boilerplate descriptions across different vulnerability IDs.
+
+| Class  | Precision | Recall | F1-score | Support |
+|--------|-----------|--------|----------|---------|
+| Low    | 0.5968    | 0.4099 | 0.4860   | 2,293   |
+| Medium | 0.7867    | 0.8165 | 0.8013   | 14,351  |
+| High   | 0.7662    | 0.7809 | 0.7735   | 9,201   |
+
+- **Overall accuracy**: 76.8%
+- **Macro F1**: 0.6870
+- **Weighted F1**: 0.7634
 
-# vulnerability-severity-classification-chinese-macbert-base-test
+### Class distribution
 
-This model is a fine-tuned version of [hfl/chinese-macbert-base](https://huggingface.co/hfl/chinese-macbert-base) on an unknown dataset.
-It achieves the following results on the evaluation set:
-- Loss: 2.4903
-- Accuracy: 0.7699
-- F1 Macro: 0.6888
-- Low Precision: 0.6247
-- Low Recall: 0.4030
-- Low F1: 0.4899
-- Medium Precision: 0.7837
-- Medium Recall: 0.8259
-- Medium F1: 0.8042
-- High Precision: 0.7706
-- High Recall: 0.7740
-- High F1: 0.7723
+The dataset is imbalanced: Low (8.9%), Medium (55.5%), High (35.6%).
 
-## Model description
+## Usage
 
-More information needed
+```python
+from transformers import pipeline
 
-## Intended uses & limitations
+classifier = pipeline(
+    "text-classification",
+    model="CIRCL/vulnerability-severity-classification-chinese-macbert-base"
+)
 
-More information needed
+description = "TOTOLINK A3600R存在缓冲区溢出漏洞，攻击者可利用该漏洞在系统上执行任意代码或者导致拒绝服务。"
+result = classifier(description)
+print(result)
+# [{'label': 'High', 'score': 0.98}]
+```
 
-## Training and evaluation data
+## Known limitations
 
-More information needed
+- **Low severity recall is ~41%**: approximately 60% of Low-severity entries are misclassified, mostly as Medium. This reflects the vocabulary overlap between Low and Medium descriptions in CNVD data. Class-weighted loss and focal loss were tested but all degraded Medium recall disproportionately without a net benefit.
 
-## Training procedure
+- **Keyword dependency**: the model biases toward a vulnerability type's typical severity. For example, buffer overflow descriptions are predicted as High regardless of the actual assigned severity. On entries where the actual severity deviates from the type's typical severity, accuracy drops from ~89% to ~55%.
 
-### Training hyperparameters
+- **Negation blindness**: the model does not understand negation. Descriptions like "does NOT allow remote code execution" can still produce high-confidence High severity predictions.
 
-The following hyperparameters were used during training:
-- learning_rate: 3e-05
-- train_batch_size: 64
-- eval_batch_size: 64
-- seed: 42
-- optimizer: Use OptimizerNames.ADAMW_TORCH_FUSED with betas=(0.9,0.999) and epsilon=1e-08 and optimizer_args=No additional optimizer arguments
-- lr_scheduler_type: linear
-- num_epochs: 5
+- **CVE overlap**: 81% of CNVD entries have a corresponding CVE. The model primarily adds value for the ~19% of CNVD-only entries (concentrated in Chinese domestic software) where no CVE severity assessment exists.
 
-### Training results
+These limitations were identified through independent analysis in [VulnTrain#19](https://github.com/vulnerability-lookup/VulnTrain/issues/19).
 
-| Training Loss | Epoch | Step | Validation Loss | Accuracy | F1 Macro | Low Precision | Low Recall | Low F1 | Medium Precision | Medium Recall | Medium F1 | High Precision | High Recall | High F1 |
-|:-------------:|:-----:|:----:|:---------------:|:--------:|:--------:|:-------------:|:----------:|:------:|:----------------:|:-------------:|:---------:|:--------------:|:-----------:|:-------:|
-| 2.2603        | 1.0   | 1590 | 2.3939          | 0.7494   | 0.6085   | 0.6964        | 0.1771     | 0.2823 | 0.7452           | 0.8456        | 0.7922    | 0.7604         | 0.7419      | 0.7510  |
-| 2.3054        | 2.0   | 3180 | 2.2652          | 0.7657   | 0.6696   | 0.6445        | 0.3345     | 0.4404 | 0.7669           | 0.8450        | 0.8040    | 0.7799         | 0.7494      | 0.7643  |
-| 1.7666        | 3.0   | 4770 | 2.3074          | 0.7663   | 0.6847   | 0.6148        | 0.3995     | 0.4843 | 0.7821           | 0.8202        | 0.8007    | 0.7649         | 0.7736      | 0.7692  |
-| 1.7766        | 4.0   | 6360 | 2.3694          | 0.7670   | 0.6888   | 0.5959        | 0.4200     | 0.4927 | 0.7901           | 0.8082        | 0.7990    | 0.7604         | 0.7893      | 0.7746  |
-| 1.4851        | 5.0   | 7950 | 2.4903          | 0.7699   | 0.6888   | 0.6247        | 0.4030     | 0.4899 | 0.7837           | 0.8259        | 0.8042    | 0.7706         | 0.7740      | 0.7723  |
+## Training details
 
+- **Base model**: [hfl/chinese-macbert-base](https://huggingface.co/hfl/chinese-macbert-base)
+- **Dataset**: [CIRCL/Vulnerability-CNVD](https://huggingface.co/datasets/CIRCL/Vulnerability-CNVD)
+- **Train/test split**: deduplicated on description text (no leakage), 80/20 split
+- **Loss**: uniform cross-entropy (no class weighting)
+- **Learning rate**: 3e-05
+- **Batch size**: 16
+- **Epochs**: 5
+- **Best model selection**: by accuracy
 
-### Framework versions
+## References
 
-- Transformers 5.4.0
-- Pytorch 2.11.0+cu130
-- Datasets 4.8.4
-- Tokenizers 0.22.2
+- [Vulnerability-Lookup](https://vulnerability.circl.lu) - the vulnerability data source
+- [VulnTrain](https://github.com/vulnerability-lookup/VulnTrain) - training pipeline
+- [ML-Gateway](https://github.com/vulnerability-lookup/ML-Gateway) - inference API