NLP翻译评测

作者：chen_qc

一个只处理外部推理结果的多语种到中文翻译评测系统。它不加载翻译模型、不执行 GPU 推理，负责测试集与模型台账、结果发现/上传、OpenAI 兼容 LLM 打分、阈值指标、历史对比和 Git CSV 导出。

主要能力

• JSONL 测试集版本化和内容指纹
• 逐语言 TXT/JSONL 结果目录及 ZIP 上传
• 定时扫描结果根目录，稳定性检测后加入持久化 Worker 队列
• OpenAI 兼容评价服务，asyncio.Semaphore 控制并发，严格解析 0–10 整数
• 不可变 ModelEvaluationRecord：不同阈值、Prompt、评价模型或结果配置生成不同记录
• 同一 ScoreRun 可派生多个阈值记录，不重复调用 LLM
• 每语言准确率、宏/微平均、得分分布、空输出和失败统计
• 主评价配置、当前记录固定、模型发布与多 Git revision
• 逐条错误分析、人工备注、配对模型对比和确定性 CSV

安装与启动

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
translate-eval init

分别启动 Web 和 Worker：

translate-eval web --host 0.0.0.0 --port 8000
translate-eval worker

打开 http://127.0.0.1:8000。Web 进程不执行长任务；如果 Worker 未启动，任务会安全地保留在队列中。

translate-eval init 为新实例创建当前数据库结构和运行目录；对已经初始化完成的当前结构重复执行是安全的。Web、Worker 和其他操作命令只校验数据库结构版本，不会在启动时改表。若数据库未初始化或结构不匹配，命令会明确失败；请配置新的数据库路径后执行 translate-eval init。

管理中心

/admin 与工作台共用同一个 FastAPI 服务和 SQLite。工作台面向结果导入、评测审阅、模型比较和队列进度；管理中心集中处理评价基准、测试集与语言、模型台账、Worker 和扫描运维。

• 评价基准：Prompt、评价模型、带版本 Profile、唯一主配置、连通性测试和历史重评。
• 测试集与语言：启用/归档、语言别名和停用规则；已注册语料与指纹保持不可变。
• 模型台账：训练与制品元数据、多发布 revision、归档、当前评测记录固定/解除固定。
• 模型目录：集中维护可枚举的模型族与基础模型，台账通过下拉选取并保留名称快照。
• 运维：Worker 在线状态、任务进度、协作式取消、失败终态任务删除、扫描源配置、立即扫描和结果漂移确认。

数据格式

一个测试集目录包含若干以语言代码命名的 JSONL 文件：

dataset-v1/
├── en.jsonl
├── fr.jsonl
└── ...

每行默认字段如下，字段名可以在注册时映射：

{"sample_id":"en-1","source":"Hello","reference_zh":"你好"}

结果根目录约定为：

${RESULTS_ROOT}/<dataset>/<dataset-version>/<model-version>/
├── en.txt
├── fr.txt
├── ...
├── manifest.json
└── .ready                 # 可选

TXT 每个物理行对应测试集同语言文件的一行，空行是空预测。也支持 JSONL：

{"sample_id":"en-1","prediction":"你好","status":"success"}

推荐外部推理程序先写临时目录，完成后原子重命名到结果根目录，并创建 .ready；也可以在 manifest.json 中写入 "complete": true。没有完成标记时，扫描器默认要求文件连续稳定 120 秒。

examples/ 中提供了可直接注册和扫描的最小示例。

评价配置

在管理中心的“评价基准”页面依次创建：

1. Prompt 版本，必须包含 {reference} 和 {candidate}（也可使用 {source}、{language}）。
2. 评价模型版本，包括 API 模型名、配置版本、OpenAI 兼容 base URL 和 API Key 环境变量名。
3. Evaluation Profile，绑定 Prompt、评价模型和默认阈值；可设为唯一主配置。

例如：

export OPENAI_API_KEY='...'

评价接口调用 ${base_url}/chat/completions。响应内容必须是可由 int(response.strip()) 解析的 0–10 整数。

常用环境变量

环境变量	默认值	说明
TRANSLATE_EVAL_DATA_DIR	./var	SQLite 与运行制品根目录
TRANSLATE_EVAL_RESULTS_ROOT	./var/results	自动扫描的默认结果目录
TRANSLATE_EVAL_DATABASE_URL	SQLite	SQLAlchemy 数据库 URL
TRANSLATE_EVAL_SCAN_INTERVAL	60	扫描周期（秒）
TRANSLATE_EVAL_SCAN_STABLE	120	无完成标记时的稳定窗口
TRANSLATE_EVAL_DEFAULT_SCANNER	true	是否自动注册默认扫描路径

CLI

translate-eval import-dataset demo v1 /path/to/dataset
translate-eval import-result 1 /path/to/model-result
translate-eval worker --once
translate-eval export

CSV 默认输出到 var/exports/。应用只生成文件，不执行 git add 或 git commit。

维护文档

后续智能体和维护者应从 doc/README.md 开始阅读。doc/ 包含系统架构、数据模型、部署运维、开发调试、扩展方式和常见故障说明，并以当前代码、页面和数据约束为唯一描述对象。

修改架构、数据不变量、任务状态机或扩展接口时，应在同一次变更中同步更新对应文档。

测试

pip install -e '.[dev]'
pytest