# docs-model-dataset

**Repository Path**: openeuler/docs-model-dataset

## Basic Information

- **Project Name**: docs-model-dataset
- **Description**: To develop dataset for openEuler documentation.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-07-23
- **Last Updated**: 2025-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Doc

## README

# docs-model-dataset

## 介绍

本项目基于 Gitee openEuler 社区 `docs-centralized` 仓库的 PR 数据构建工具，用于获取和处理文档修改数据，生成可用于文档编辑优化模型训练的数据集。  具备灵活可配置的过滤系统，支持快速扩展新规则。

## 核心特性

- **多规则过滤**：策略模式设计，可通过配置文件启用/禁用
- **详细追踪**：记录被过滤数据的原因
- **易扩展**：可快速添加自定义过滤器
- **AI智能评估**：基于大模型的文档编辑评估与标签分类
- **动态Few-shot**：智能示例选择，探索利用数据集优化大模型评估效果的方法
- **BERT训练支持**：提供完整的文本分类模型训练流程
- **异步处理**：支持高并发评估，提升处理效率

## 项目架构

```
docs-model-dataset/
├── 📁 crawler/                 # PR数据爬取模块
├── 📁 filters/                 # 数据过滤规则引擎
├── 📁 processors/              # 数据处理器
├── 📁 llm_label/              # LLM评估与标签分类
├── 📁 llm_few_shot/           # Few-shot验证流水线--数据集使用场景探索
├── 📁 bert_train/              # BERT模型训练--基于Bert的数据标签验证
├── 📁 utils/                   # 工具函数
├── 📁 tests/                   # 测试用例
├── 📁 data/                    # 数据存储目录
├── 📁 logs/                    # 日志文件
├── main.py                     # 主入口程序
├── config.py                   # 全局配置
└── requirements.txt            # 依赖列表
```

### 核心模块功能

| 模块 | 功能描述 | 主要用途 |
|------|----------|----------|
| **crawler** | PR数据获取 | 从Gitee API获取PR、commits、files等数据 |
| **filters** | 数据过滤 | 基于规则过滤无效或低质量变更 |
| **processors** | 数据处理 | 变更单元分割、格式化处理 |
| **llm_label** | 智能标签 | 大模型评估文档编辑质量并分类 |
| **llm_few_shot** | 验证流水线 | 向量化+智能Few-shot验证 |
| **bert_train** | 模型训练 | BERT文本分类器训练和评估 |

## 内置过滤规则

| 规则名称                  | 功能描述       | 过滤条件                                  |
| ------------------------- | -------------- | ----------------------------------------- |
| `file_extension`          | 文件类型过滤   | 只保留.md文件，过滤其他类型文件           |
| `type_base`               | 修改类型过滤   | 只保留指定类型（modify/add/delete）       |
| `trivial_whitespace`      | 格式过滤       | 过滤仅空格、换行的格式改动                |
| `code_block_language_tag` | 代码块标记过滤 | 过滤代码块语言标记的修改                  |
| `url_change`              | URL修改过滤    | 过滤URL的小幅修改（如扩展名）             |
| `markdown_heading_level`  | 标题级别过滤   | 过滤仅改变Markdown标题级别的修改          |
| `punctuation_change`      | 标点符号过滤   | 过滤中英文标点或末尾句号的小幅改动        |
| `list_style_change`       | 列表样式过滤   | 过滤列表符号变化（如 `-` ↔ `*`）          |
| `content_length`          | 内容长度过滤   | 过滤少于N个字符的短内容修改               |
| `trailing_symbol_change`  | 尾部装饰符过滤 | 过滤语句尾部装饰符变动（如末尾添加标点）  |


⚠️ **注意**：部分规则与标签是相互影响的，因此请根据需要启用或关闭过滤器

## 使用方法

### 安装

```bash
pip install -r requirements.txt
```

### 下载 PR 数据

```bash
python main.py download --state open --per_page 50 --max_pages 2
```

### 处理数据（应用过滤规则）

```bash
python main.py process \
  --input data/raw/prs_open.json \
  --output data/processed/prs_open_filtered.json \
  --rejected data/processed/prs_open_filtered_rejected.json
```

### 一步执行下载 + 处理

```bash
python main.py deal --state open --per_page 100 --max_pages 0
```

### 🧠 LLM智能评估验证

项目提供了一套完整的动态 few-shot 验证管线，使用数据集样本作为 few-shot 提示，辅助大模型对 pull request 修改质量进行判断。

```bash
# 构建向量数据库
python llm_few_shot/build_embedding_database.py \
  --input-file data/label_data/auto_pass.jsonl \
  --output-dir llm_few_shot/data/label_embedding

# 运行验证流水线（一键启动）
cd llm_few_shot && ./run.sh

# 或手动运行
python llm_few_shot/pipeline.py \
  --units-data-file ../data/processed/units_prs_closed.jsonl \
  --sample-count 10 \
  --model-name "Qwen/Qwen3-8B"
```

### 🤖 BERT模型训练

支持基于 BERT 的完整文本分类训练，用于验证数据集标签是否具有可分类性。

```bash
# 一键训练评估
cd bert_train && ./run_train_eval.sh

# 数据处理
python bert_train/prepare_core_dataset.py \
  --input ../data/label_data/auto_pass_*.jsonl \
  --output_dir data \
  --text_format bert_pair

# 模型训练
python bert_train/train_classifier.py \
  --data_dir data \
  --output_dir models \
  --epochs 3
```

## 配置说明

### 过滤器配置结构

在 `config.py` 中配置过滤器：

```python
FILTER_CONFIG = {
    'file_extension': {
        'allowed_extensions': ['.md']  # 只允许.md文件
    },
    'type_base': {
        'allowed_types': ['modify']   # 只允许修改类型
    },
    'markdown_heading_level': {},         # Markdown标题级别过滤
    'list_style_change': {},             # 列表样式过滤
    'content_length': {
        'min_length': 6                  # 最小字符数
    },

    # 以下规则由于与标签有冲突，默认禁用，可按需启用：
    # 'trivial_whitespace': {},
    # 'code_block_language_tag': {},
    # 'punctuation_change': {},
    # 'url_change': {},
    # 'trailing_symbol_change': {
    #     'trailing_symbols': [
    #         '。', '，', '；', '：', '！', '？', '"', "'",
    #         '.', ',', ';', ':', '!', '?', '"', "'",
    #         ' ', '\t', '\n', '、', '…', '~', '-', '_'
    #     ]
    # }
}
```

### 可配置参数说明

- **file_extension**: `allowed_extensions` - 允许的文件扩展名列表
- **type_base**: `allowed_types` - 允许的修改类型列表（modify/add/delete）
- **content_length**: `min_length` - 内容最小字符数
- **trailing_symbol_change**: `trailing_symbols` - 尾部符号列表


### AI评估配置

在 `llm_label/llm_eval.py` 中配置大模型参数：

```python
# 模型配置
model_name = "Qwen/Qwen3-8B"  # 使用的模型名称
max_concurrency = 10           # 最大并发数
api_key = "your_api_key"       # API密钥
base_url = "http://localhost:8000"  # API基础地址
```

## 输出格式

### 基础过滤后的数据格式

```json
{
  "pr_number": 123,
  "file_path": "docs/example.md",
  "hunk_header": "@@ -10,7 +10,7 @@",
  "add_content": "新的内容",
  "remove_content": "旧的内容",
  "unit_id": "PR123_docs_example_md_unit_0",
  "context_before": "上下文内容",
  "context_after": "上下文内容",
  "change_type": "modify"
}
```

### AI评估后的数据格式

```json
{
  "pr_number": 123,
  "file_path": "docs/example.md",
  "hunk_header": "@@ -10,7 +10,7 @@",
  "add_content": "新的内容",
  "remove_content": "旧的内容",
  "unit_id": "PR123_docs_example_md_unit_0",
  "context_before": "上下文内容",
  "context_after": "上下文内容",
  "change_type": "modify",
  "evaluation": {
    "is_valid": true,
    "valid_reason": "该修改修复了专业术语的拼写错误，具有教学价值",
    "label_id": "1",
    "label_name": "错别字-英文错别字",
    "label_reason": "属于专业名词的拼写错误修正，符合标签1的定义",
    "error": null
  }
}
```

### 字段说明

- `pr_number`: PR编号
- `file_path`: 文件路径
- `hunk_header`: Git diff的hunk头部信息
- `add_content`: 新增内容
- `remove_content`: 删除内容
- `unit_id`: 唯一标识符（格式：PR{编号}_{文件路径}_unit_{序号}）
- `context_before`: 修改前的上下文
- `context_after`: 修改后的上下文
- `change_type`: 修改类型（modify/add/delete）
- `evaluation`: AI评估结果
  - `is_valid`: 是否具备训练价值
  - `valid_reason`: 有效性判断理由
  - `label_id`: 标签编号（1-23）
  - `label_name`: 标签名称
  - `label_reason`: 标签选择理由
  - `error`: 评估过程中的错误信息

## 文档编辑标签体系

系统定义了 **22** 个文档编辑优化标签，涵盖多个类别的文档质量问题。每个标签包含问题类型、适用范围（unit）等详细信息。

### 🔤 拼写类（标签 1-4）
- **标签1 - 拼写-英文专业名词大小写**  
  英文专业术语、单位、品牌名等的大小写不规范，需要統一为标准形式  
  适用范围：句子 | 例如：cpu→CPU、api→API、github→GitHub

- **标签2 - 拼写-英文同词大小写一致**  
  同一章节内相同的非专业英文单词大小写不一致，需要統一为同一形式  
  适用范围：章节 | 例如：test/Test/TEST应統一为test

- **标签3 - 拼写-中文相似字错误**  
  中文词汇使用了同音字或形近字，需要替换为正确汉字  
  适用范围：句子 | 例如：区块連→区块链、阀值→阈值

- **标签4 - 拼写-中文误触多余字**  
  因键盘误操作产生的重复字符，需要删除多余字符  
  适用范围：句子 | 例如：安裝包包→安裝包、打开開文档→打開文档

### 🔗 超链接类（标签 5）
- **标签5 - 超链接-描述与格式错误**  
  超链接的文字描述与目标不符、格式不规范或地址错误  
  适用范围：超链接 | 需要更正鏈接描述、补充格式标记或修正地址

### ⚡ 空格类（标签 6）
- **标签6 - 空格-中英文与标点空格错误**  
  空格使用不规范，包括纯中文間的过多空格、中英文混排時英文前后缺少空格、中英文标点前后空格不当等问题  
  适用范围：句子/代码行

### 📝 标点类（标签 7-10）
- **标签7 - 标点-中英文标点使用错误**  
  中英文标点符号混用，需要統一标点类型  
  适用范围：代码行/句子

- **标签8 - 标点-顿号使用错误**  
  顿号使用场景不当，应该仅在句子内并列词语間使用顿号  
  适用范围：句子

- **标签9 - 标点-成对标点缺失**  
  成对标点符号缺少一侧，需要补齐缺失的引号、括号、书名号等  
  适用范围：句子/段落

- **标签10 - 标点-同级内容标点一致**  
  同级内容的标点使用不統一，需要调整标点规则保持段落结尾、列表项等标点一致  
  适用范围：段落/表格/列表

### 📐 格式 & 版式类（标签 11-12）
- **标签11 - 格式-换行不一致**  
  同级内容的换行格式不統一，需要调整为相同的换行逻辑和缩进规范  
  适用范围：段落

- **标签12 - 版式-视觉排版优化**  
  文档中存在影响视觉一致性和阅读体验的排版问题，包括图片位置不当、行间距/段落间距不統一、对齐方式混乱等  
  适用范围：段落/文档

### 🔧 标记与代码类（标签 13-14）
- **标签13 - 标记-文档标记规范化**  
  文档标记语法错误或格式不統一，包括Markdown、HTML、XML标签语法错误，格式风格不統一等  
  适用范围：文档/代码块

- **标签14 - 标记-代码块规范**  
  代码块缺语言标识、命令语法错误、注释符号错误等  
  适用范围：代码块 | 例如：```→```python、//注释→#注释

### 📁 文件与路径类（标签 15-16）
- **标签15 - 文件-命名规范**  
  文件名语义不当或扩展名错误，需要更正文件名含义或修正扩展名类型  
  适用范围：文件

- **标签16 - 文件-路径规范**  
  实际文件路径错误，需要更正为正确的文件系統路径  
  适用范围：文件

### ✍️ 表达类（标签 17-18）
- **标签17 - 表达-语义优化**  
  句子表达不够准确或流畅，需要优化语义表达以提升内容的准确性和可读性  
  适用范围：句子/段落

- **标签18 - 表达-冗余精简**  
  存在语义重复或冗余表达，需要删除重复内容并精简表述  
  适用范围：句子/段落

### 📚 结构类（标签 19）
- **标签19 - 结构-章节顺序优化**  
  章节编号或逻辑顺序不合理，需要调整为正确的章节序号和逻辑结构  
  适用范围：章节/文档

### 🏷️ 标题类（标签 20）
- **标签20 - 标题-语义优化**  
  标题语义不够准确或描述性不强，需要优化标题内容使其更好地概括章节内容  
  适用范围：标题

### 📋 信息类（标签 21）
- **标签21 - 信息-完整性补充**  
  信息不完整或缺失关键内容，需要补充操作步骤、参数说明、技术背景等必要信息  
  适用范围：句子/段落

### 🚪 兜底类（标签 22）
- **标签22 - 其他**  
  不属于以上任何类别的情况  
  适用范围：文档/句子


## 参与贡献

1. Fork 本仓库
2. 新建功能分支（`Feat_xxx`）
3. 提交代码
4. 新建 Pull Request