# UltraData-Code-L2-Classifier

<p align="center">
<a href="https://huggingface.co/collections/openbmb/ultradata">📦 UltraData 合集</a> |
<a href="https://ultradata.openbmb.cn/">🌐 UltraData</a> |
<a href="https://huggingface.co/collections/openbmb/minicpm5">🤗 MiniCPM5 系列</a> |
📖 技术报告（即将发布）|
<a href="https://huggingface.co/datasets/openbmb/UltraData-Code">🤗 UltraData-Code 数据集</a>
</p>

<p align="center"><a href="https://huggingface.co/openbmb/UltraData-Code-L2-Classifier/blob/main/README.md">English</a> | 中文</p>

## 📚 简介

***UltraData-Code-L2-Classifier*** 是一组编程语言特定的文件级打分器，针对 [UltraData-Code-L1](https://huggingface.co/datasets/openbmb/UltraData-Code) 中的 11 种编程语言分别设计。

我们针对每种语言训练并应用对应的 L2 打分器，对 UltraData-Code-L1 中相应语言的文件进行筛选。筛选后的文件共同构成 [UltraData-Code-L2](https://huggingface.co/datasets/openbmb/UltraData-Code)，其目标是集中可解释的计算与问题求解逻辑。最终 L2 数据约包含 **400B tokens**，总体保留 L1 约 **12.23% 的文件**。

## 💡 亮点

> **摘要：** 代码生成已成为大语言模型（LLMs）的核心能力，而代码数据则是形成这一能力的预训练过程中的关键要素。随着获取高质量公开代码数据的难度日益增加，仅依赖语料规模扩张已难以推动模型能力持续提升。为此，分层数据管理通过对规模逐级缩减的数据池实施针对性不断增强的处理，构建适配不同训练目标的数据形态。基于这一理念，本文提出 **UltraData-Code**，其包含四个相互衔接的数据层级：L0 层的代码仓库归档、L1 层的标准化自然代码、L2 层的算法导向筛选，以及 L3 层的任务导向合成。其中，L0 层完整保留代码仓库数据及其来源信息，以支持后续再处理；L1 层通过可扩展的过滤、规范化与近重复数据消除，为通用预训练提供标准化代码数据；L2 层利用语言自适应的相关性信号与质量约束，筛选具有较高质量和算法相关性的代码文件，最终构建覆盖 11 种编程语言、规模约为 400B tokens 的 **UltraData-Code-L2**，用于面向特定能力的持续预训练；L3 层则将筛选后的代码实现转化为结构化编程练习，形成覆盖相同 11 种编程语言、规模约为 150B tokens 的 **UltraData-Code-L3**，适用于任务导向的中期训练或监督微调（SFT）。在受控实验中，我们使用 10B tokens 的数据对一个 1B 模型进行持续预训练。结果表明，与 L1 相比，L2 使模型在 EvalPlus 和 MultiPL-E 基准上的 pass@1 分别提升 **7.80** 和 **5.13** 个百分点。进一步以 L3 数据替换一半的 L2 训练 tokens 后，模型在上述两个基准上的性能分别再提升 **8.42** 和 **8.07** 个百分点。当训练预算扩展至 100B tokens 时，这两类性能增益均进一步扩大。为推动大语言模型相关研究，我们已公开所构建的数据集与分类器。

- **完整的代码数据构建流水线：** 将仓库归档和规范化自然代码与细粒度精筛、结构化合成连接起来，在 11 种编程语言上分别形成约 400B tokens 的 L2 和约 150B tokens 的 L3。相关数据集现已公开发布，旨在推动大语言模型的研发与能力提升。
- **细粒度算法相关代码精筛：** 我们提出一种语言自适应筛选框架，将文件角色监督与语言特定启发式线索结合，学习代码文件的算法相关性。该框架在文件角色、算法相关性和代码质量模型之间复用预计算语义表征，最终结合角色与质量约束完成筛选。
- **任务导向合成：** 我们提出一种结构化合成方案，将 L2 筛选出的每个算法相关实现转化为一道编程练习，并基于同一源实现联合生成独立完整的任务、分析、解答与候选测试用例。该转换既保留了源代码的计算意图，又为代码生成引入了显式的任务监督与解答监督。

<div align="center">
  <img src="assets/ultradata-code-l0-l3-overview.png" width="760" alt="UltraData-Code L0-L3 构建流程"/>
</div>

## 🔎 L2 筛选流程

L2 流程分别应用于 UltraData-Code-L1 中的 11 种语言：

1. **编码文件：** 使用 [Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B) 为每个文件生成 1024 维 embedding。
2. **预测文件角色：** 将文件分为 `ALGO`、`WEB`、`TOOL`、`DATA`、`TEST`、`CONFIG` 或 `EXCLUDE`。
3. **构造双线索监督：** 将 ALGO 角色标注与语言特定启发式证据结合，覆盖 ALGO 之外的算法相关文件。
4. **预测相关性和质量：** 相关性模型输出 `algo_rel_score`，质量模型输出 `quality_score`。
5. **校准并筛选：** 在留出数据上为每种语言校准相关性阈值。文件需通过相关性阈值和质量阈值且不被预测为 `EXCLUDE`，才会保留。

<div align="center">
  <img src="assets/ultradata-code-l2.png" width="760" alt="UltraData-Code L2 筛选流程"/>
</div>

## 📈 评测结果

10B-token 对比均使用相同的 1B 基座模型、训练设置、去污流程和评测协议。

**Python 结果：算法相关性精筛带来最强的自然代码结果。** UltraData-Code-L2-py 的 EvalPlus 平均 pass@1 比 UltraData-Code-L1-py 提升 **17.91 个百分点**，比 Stack-Edu-py 提升 **8.46 个百分点**。

<div align="center">
  <img src="assets/python-training-dynamics.png" alt="Python 训练动态" width="760"/>
</div>

<div align="center">
  <img src="assets/python_results.png" alt="Python 主结果表" width="900"/>
</div>

**多语言结果：L2 精筛优于自然代码基线。** UltraData-Code-L2 相比 UltraData-Code-L1 在 EvalPlus 和 MultiPL-E 上分别提升 **7.80** 和 **5.13 个百分点**，相比 Stack-Edu 分别提升 **4.37** 和 **3.05 个百分点**。

<div align="center">
  <img src="assets/multilingual-training-dynamics.png" alt="多语言训练动态" width="760"/>
</div>

<div align="center">
  <img src="assets/multilingual_results.png" alt="多语言主结果表" width="900"/>
</div>

## 🚀 UltraData-Code-L2 打分器使用方法

安装依赖：

```bash
pip install numpy torch pyarrow
```

### 在 Python 中对 embedding 打分

```python
import sys
sys.path.insert(0, "scripts")
from scorers import LanguageScorers

scorers = LanguageScorers.load("classifiers/cpp")

# float32 [N, 1024]；paths 与 embeddings 顺序一致，使用仓库相对路径
out = scorers.score(embeddings, paths)
```

请为每种输入语言使用对应的语言目录。相关性模型需要真实的仓库相对路径。

### Parquet 文件打分

[`scripts/score_parquet.py`](scripts/score_parquet.py) 可处理单个 Parquet 文件或递归处理目录。输入必须包含 `embedding` 列，以及 `relative_path` 列或包含 `file_path` 的 `meta` 结构。

```bash
SCORERS=classifiers/cpp
DATA_PATH=data/input
SAVE_PATH=data/output

python scripts/score_parquet.py \
  --scorers ${SCORERS} \
  --input ${DATA_PATH} \
  --output-root ${SAVE_PATH} \
  --batch-size 1024 \
  --device cpu \
  --apply-policy
```

输出会镜像输入目录结构，并保留所有原有列。使用 `--describe` 查看打分器配置，使用 `--limit N` 限制处理的 Parquet 文件数，或使用 `--algo-rel-min`、`--quality-min` 和 `--exclude-categories` 覆盖策略值。

### 输出字段

打分器会在输入文件中追加以下结果：

```text
category: {预测的文件角色}
cls_confidence: {文件角色置信度}
algo_rel_score: {算法相关性分数}
quality_score: {代码质量分数}
selected: {是否通过筛选策略}
```

- `category` 为 `ALGO`、`WEB`、`TOOL`、`DATA`、`TEST`、`CONFIG` 或 `EXCLUDE` 之一。
- `cls_confidence` 和 `algo_rel_score` 的范围为 `0` 到 `1`，`quality_score` 的范围为 `0` 到 `10`。
- 只有启用 `--apply-policy` 时才会添加 `selected`。该字段标记同时通过相关性阈值、`EXCLUDE` veto 和质量阈值的行，不会删除未通过的行。

### 注意事项

- 输入必须使用 [Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B) 生成的 1024 维 embedding。
- 算法相关性打分器还会使用仓库相对路径，请传入与 embedding 顺序一致的真实路径。
- [`config.json`](config.json) 提供通用默认值。命令行参数可以覆盖这些默认值。
- 当前打分脚本为单进程实现。大规模语料推理时，建议在外部按数据分片或子目录进行调度。

## ❤️ 致谢

本项目基于 [Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B)、[PyTorch](https://pytorch.org/)、[PyArrow](https://arrow.apache.org/docs/python/) 。感谢这些优秀开源工作，正是开源社区的贡献让 UltraData-Code 成为可能！🙌

## 💳 许可证

本项目基于 [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) 许可证发布。

## 📖 引用

如果 **UltraData-Code** 或本 Classifier 对您的研究有帮助，请考虑引用：

```bibtex
@misc{ultradata_code,
  title        = {{UltraData-Code}: From Raw Repositories to Algorithmically Dense and Task-Oriented Code Data},
  author       = {Chengying Tu and Hengyu Zhao and Shuaikang Xue and Zhongming Qu and Jihao Zhou and Xinle Lin and Junshao Guo and Zixuan Fu and Qiang Ma and Jie Zhou and Chaojun Xiao and Hongfei Yan and Yudong Wang and Xu Han and Zhiyuan Liu and Maosong Sun},
  year         = {2026},
  publisher    = {Hugging Face},
  howpublished = {\url{https://huggingface.co/datasets/openbmb/UltraData-Code}}
}
```