为什么必须使用Qwen3-Embedding-0.6B？UltraData-Code-L2-Classifier输入要求与常见报错速查
UltraData-Code-L2-Classifier是 OpenBMB UltraData 系列中的代码筛选分类器，它为 Python、Java、C++ 等 11 种语言的文件提供算法相关性打分，用于从海量代码语料中筛选出高质量算法实现（L2 语料）。而使用它的第一道门槛，就是输入 Embedding 必须来自 Qwen3-Embedding-0.6B——这篇文章帮你讲清楚"为什么"，并附一份输入要求清单和常见报错速查表，帮你快速定位问题。
为什么必须使用 Qwen3-Embedding-0.6B？
这不是一个可有可无的约定，而是模型训练时的硬性设定。UltraData-Code-L2-Classifier 内部包含三个打分模型：
| 模型 | 作用 | 输入 |
|---|---|---|
| C（文件角色分类器） | 判断文件属于ALGO、WEB、TEST等哪一类 | 1024 维 Embedding |
| A（算法相关性模型） | 输出algo_rel_score，衡量文件是否"算法密集" | 1024 维 Embedding + 256 维路径哈希 |
| Q（代码质量模型） | 输出 0~10 分的quality_score | 1024 维 Embedding |
三个模型在训练时统一消费 Qwen3-Embedding-0.6B 生成的 1024 维向量，这一点在 config.json 中有明确声明：
"embedding_model": { "repo_id": "Qwen/Qwen3-Embedding-0.6B", "dim": 1024, "training_max_tokens": 8192 }关键细节是：加载器会校验维度，但无法识别"错误的编码器"（见 scripts/scorers.py 的注释）。也就是说，如果你换了另一个 1024 维的 Embedding 模型，程序不会报错，只会静默地输出错误的分数——这是新手最容易踩的坑。
输入要求完整清单：Embedding、路径与语言目录
在跑分之前，请对照以下清单逐项检查：
- Embedding 列：每行一个文件的向量，
float32、形状为[N, 1024]，必须与行一一对齐； - 仓库相对路径：相关性模型 A 会消费路径特征（256 维哈希向量，权重 0.4），输入需包含
relative_path列，或meta结构体内的file_path字段，见 scripts/path_features.py； - 语言目录要对：
classifiers/下每种语言一套独立权重（C_file_role.bin、A_relevance.bin、Q_quality.bin、Q_scaler.npz、C_file_role.json五个文件缺一不可），给 Java 文件打分就必须用 classifiers/java/，不能混用； - Parquet 格式：批量打分要求输入 Parquet 文件中存在
embedding列。
快速上手：两条命令跑通 L2 分类器打分
先安装运行时依赖：
pip install numpy torch pyarrow方式一：Python API
import sys sys.path.insert(0, "scripts") from scorers import LanguageScorers scorers = LanguageScorers.load("classifiers/python") out = scorers.score(embeddings, paths) # embeddings: [N, 1024]，paths 为仓库相对路径方式二：scripts/score_parquet.py 批量打分
python scripts/score_parquet.py \ --scorers classifiers/python \ --input data/input \ --output-root data/output \ --batch-size 1024 \ --device cpu \ --apply-policy加上--apply-policy后，输出会多一列布尔值selected，表示该文件是否通过筛选策略（默认阈值来自 config.json：algo_rel_score >= 0.8且quality_score >= 3.0且角色不为EXCLUDE）。
常见报错速查表：Embedding 维度、路径缺失与配置问题
| 报错信息 | 原因 | 解决方法 |
|---|---|---|
expected embeddings of shape [N, 1024], got ... | Embedding 维度不是 1024，或没有压成二维数组 | 用 Qwen3-Embedding-0.6B 重新编码，并保证形状为[N, 1024] |
these scorers use path features but no 'relative_path' column (or meta.file_path) was found in the input | 输入缺少路径列，模型 A 无法构造路径特征 | 在 Parquet 中补充relative_path列，或确保meta.file_path存在 |
no parquet files under <path> | --input指向的目录里没有任何 Parquet 文件 | 检查输入路径拼写与目录结构 |
could not read selection_policy from .../config.json | config.json缺失或字段被改坏 | 恢复配置文件，或显式传--algo-rel-min、--quality-min、--exclude-categories覆盖默认值 |
A expects ...-d input but the configured featurization produces ...-d | 检查点声明的结构与实际特征不一致 | 重新完整获取对应语言的classifiers/目录，不要手工改动权重文件 |
C_file_role.json maps ... categories but the checkpoint has ... output units | 类别映射文件与权重文件不匹配 | 同上，保持classifiers/<语言>/下五个文件成套使用 |
| 不报错，但分数明显异常 | 用了另一个 1024 维的 Embedding 模型 | 换回 Qwen3-Embedding-0.6B——维度校验通过 ≠ 编码器正确 |
💡 排查技巧：先用python scripts/score_parquet.py --scorers classifiers/python --describe打印当前打分器的完整配置（Embedding 维度、路径哈希维度、类别列表），再与自己的输入逐项比对，通常一分钟就能定位问题。
小结：记住三句话
- Embedding 只认 Qwen3-Embedding-0.6B 的 1024 维输出，换模型要么维度报错，要么静默出错分；
- 路径列是刚需，
relative_path（或meta.file_path）必须与 Embedding 行对齐； - 一套语言、一套权重，
classifiers/<语言>/目录内的文件不可拆分混用。
按这份清单核对一遍，UltraData-Code-L2-Classifier 的打分流程基本不会再卡在输入环节。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
