Update README.md

README.md

@@ -1,3 +1,159 @@
 ---
 license: apache-2.0
+datasets:
+- openbmb/Ultra-FineWeb
+language:
+- zh
+- en
+tags:
+- text-classification
+- data-quality
+- text-quality
+- pytorch
+- custom-architecture
+pipeline_tag: text-classification
 ---
+# Data Quality Scoring Model
+> 中英文文本质量评分器 | Chinese & English Text Quality Scoring Model
+一个基于自研 Transformer 架构的文本质量评估模型，为预训练/微调数据清洗场景设计。模型对输入文本进行 0-5 分的质量评分，分数越高表示文本质量越好。
+---
+## 模型概述
+
+| 项目 | 说明 |
+|------|------|
+| **任务** | 文本质量评分 (Text Quality Scoring) |
+| **输出** | 0 ~ 5 分的连续质量分数 |
+| **架构** | 自定义 Transformer Decoder (非 Transformers 库) |
+| **参数量** | 4.8M (轻量级) |
+| **支持语言** | 中文、英文 |
+| **最大序列长度** | 4096 tokens |
+| **量化支持** | FP16 / FP32 / BF16 / INT8 (动态量化) |
+---
+## 架构亮点
+本模型采用自研轻量级 Transformer 架构，核心设计包括：
+- **YaRN 旋转位置编码**：支持长度外推，通过因子 16x 扩展上下文窗口
+- **分组查询注意力 (GQA)**：2 个 KV 头共享给 4 个 Query 头，降低推理内存
+- **GEGLU 前馈网络**：Gated GELU 激活，提升表达能力
+- **密集层连接 (Dense Layer Connections)**：跨层残差加权聚合，增强梯度流动
+- **RMSNorm**：替代 LayerNorm，训练更稳定
+### 模型配置
+
+| 参数 | 值 |
+|------|-----|
+| Hidden Size | 128 |
+| 层数 | 4 |
+| 注意力头数 | 4 (Query) / 2 (KV) |
+| 头维度 | 32 |
+| 中间层维度 | 341 (8/3 × hidden_size) |
+| 词表大小 | llama2_tokenizer_32k Tokenizer |
+| Dropout | 0.0 |
+---
+## 快速开始
+### 环境要求
+```bash
+pip install torch tqdm
+```
+### 下载与加载
+```python
+from huggingface_hub import hf_hub_download
+import os
+# 下载模型文件
+model_path = hf_hub_download(
+    repo_id="X-Orange/Data_Quality_Scoring_Model",
+    filename="new_model.pth"
+)
+tokenizer_path = hf_hub_download(
+    repo_id="X-Orange/Data_Quality_Scoring_Model",
+    filename="local_tokenizer",
+    local_dir="./tokenizer_cache"
+)
+```
+### 推理示例
+```python
+from Classifier_Model import ClassifierModel
+# 初始化模型
+model = ClassifierModel(
+    model_path="new_model.pth",        # 模型权重路径
+    tokenizer_path="local_tokenizer",   # Tokenizer 路径
+    device="cuda",                      # cuda / xpu / cpu
+    dtype="fp6"                         # fp16 / fp32 / bf16 / q8 (INT8量化)
+)
+# 单条或批量评分
+texts = [
+    "量子纠缠是量子力学中的一种现象，当两个或多个粒子相互作用后...",
+    "我觉得量子计算机挺厉害的，听说以后算东西会特别快。不过具体怎么快我也不太清楚...",
+    "量子量子量子的子子子计算机算算算机机机比特特特叠加态态态态态态..."
+]
+scores = model.compute(texts, batch_size=400, max_length=1024)
+for text, score in zip(texts, scores):
+    print(f"Score: {score:.2f} | {text[:40]}...")
+```
+**预期输出：**
+```
+Score: 2.62 | 量子纠缠是量子力学中的一种现象...
+Score: 1.41 | 我觉得量子计算机挺厉害的...
+Score: 0.92 | 量子量子量子的子子子计算机...
+```
+---
+## 评分标准
+模型输出 0 ~ 5 分的连续质量分数，大致对应：
+
+| 分数区间 | 质量等级 | 典型特征 |
+|----------|----------|----------|
+| 4.5 ~ 5.0 | 优秀 | 专业、连贯、信息密度高、语法正确 |
+| 3.5 ~ 4.5 | 良好 | 通顺、有意义、少量瑕疵 |
+| 2.5 ~ 3.5 | 一般 | 口语化、信息密度低、部分冗余 |
+| 1.0 ~ 2.5 | 较差 | 大量重复、逻辑混乱、严重口语化 |
+| 0.0 ~ 1.0 | 垃圾 | 无意义字符、恶意内容、严重乱码 |
+---
+## 批量数据过滤
+使用 `data_eval.py` 对 JSONL 数据集进行批量过滤：
+```bash
+python data_eval.py \
+    --jsonl_path ./raw_data \
+    --jsonl_key content \
+    --save_path ./filtered_data \
+    --target_score 3 \
+    --batch_size 400 \
+    --max_length 1024 \
+    --model_path new_model.pth \
+    --tokenizer_path local_tokenizer \
+    --device cuda \
+    --dtype q8
+```
+### 参数说明
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--jsonl_path` | `sample` | 输入 JSONL 文件/文件夹路径 |
+| `--jsonl_key` | `content` | JSON 中待评分的字段名 |
+| `--save_path` | `save` | 输出目录 |
+| `--save_size` | `160000` | 每个输出文件的最大行数 |
+| `--batch_size` | `400` | 推理批次大小 |
+| `--max_length` | `1024` | 最大截断长度 |
+| `--target_score` | `3` | 最低保留分数（≥此分数保留） |
+| `--model_path` | `new_model.pth` | 模型权重路径 |
+| `--tokenizer_path` | `local_tokenizer` | llama2_tokenizer_32k 路径 |
+| `--device` | `cuda` | 计算设备 |
+| `--dtype` | `fp16` | 数据精度 |
+---
+## 文件说明
+
+| 文件 | 说明 |
+|------|------|
+| `new_model.pth` | 模型权重 (PyTorch state_dict) |
+| `local_tokenizer/` | llama2_tokenizer_32k Tokenizer 目录 |
+| `model.py` | 模型架构定义 (Classifier, TransformerDecoder, GQA, YaRN, GEGLU) |
+| `Classifier_Model.py` | 推理封装类 (ClassifierModel) |
+| `data_eval.py` | 批量数据过滤脚本 |
+---
+## 性能参考
+在 Intel Arc GPU (XPU) 上测试，FP16 量化模式：
+- 批量 400 条 (max_length=1024)：~0.95s
+- 显存占用：~14GB
+---
+## 应用场景
+- 预训练语料清洗（去除低质量、重复、乱码文本）
+- 微调数据筛选（保留高质量指令-回复对）
+- 数据去重前的质量分层
+- 多语言混合语料的质量评估