TransBench

Appearance

需求文档 ​

大模型中英翻译能力基准测试工具 — 需求文档 ​

1. 背景与目标 ​

为评估不同大模型在中英互译任务上的表现，需要一个可复用、可配置、可批量运行的基准测试工具。该工具读取指定格式的试题文件 exam.txt，调用大模型进行翻译，并将结果以 CSV 形式输出，便于后续统计与对比分析。

1.1 项目目标 ​

  • 支持读取当前目录下 exam.txt 作为输入
  • 支持两种翻译主体（task）：
    • <en_zh>：英译中
    • <zh_en>：中译英（注意：原描述里写了“英译中”，但从命名看应为“中译英”；实现按标签语义处理）
  • 支持注释行（以 # 开头）跳过不翻译
  • 支持批量翻译并输出结果 CSV：列为 原文、翻译
  • 可配置模型 API（key、base_url 等）通过 .env 管理
  • 提供进度条、日志、错误处理与可复现运行

2. 范围说明 ​

2.1 In Scope（本期范围） ​

  • 解析 exam.txt 中 <exam> 容器下的 <zh_en> / <en_zh> 区块
  • 逐行读取区块内容（每行一段文本）
  • 跳过：
    • 空行
    • 以 # 开头的注释行
  • 对有效文本调用大模型翻译
  • 输出 CSV 到当前目录（支持按 task 分文件输出）
  • Python + uv 包管理
  • tqdm 显示进度
  • loguru 记录日志
  • 通过 LangChain 统一调用大模型（统一 API）

2.2 Out of Scope（暂不做） ​

  • 自动评分、BLEU/COMET 等指标计算
  • 多文件批处理/目录扫描（可作为后续扩展）
  • UI/网页界面
  • 自动语言检测（由 task 标签确定翻译方向）
  • 复杂格式（多行段落合并、Markdown/HTML 保留）——本期以“每行一段”为准

3. 用户与使用场景 ​

3.1 目标用户 ​

  • 研发/评测人员：需要快速对同一套试题在不同模型上跑翻译结果并对比。

3.2 典型流程 ​

  1. 用户在项目根目录准备 exam.txt
  2. 在 .env 配置模型访问参数
  3. 执行命令运行评测
  4. 得到输出 CSV（按方向/task 输出）
  5. 进一步用 Excel/脚本做对比分析

4. 输入文件规范（exam.txt） ​

4.1 文件位置 ​

  • 程序默认读取当前工作目录下 exam.txt

4.2 格式要求 ​

  • 外层容器：<exam> ... </exam>
  • 内含一个或多个 task 区块：
    • <zh_en> ... </zh_en>
    • <en_zh> ... </en_zh>
  • 每行一段文本：一行对应一次翻译请求的源文本
  • 以 # 开头的行是注释，不翻译
  • 空行不翻译

示例（与需求一致）：

xml
<exam>
<zh_en>
名词翻译
高质量发展
数字经济
科技创新
长难句翻译
经济增长带来了更多就业机会。
</zh_en>
<en_zh>
名词翻译
长难句翻译
</en_zh>
</exam>

4.3 解析规则（关键） ​

  • 只处理 <exam>...</exam> 内的内容
  • 识别 <zh_en> 与 <en_zh> 标签包裹的区间
  • 区间内逐行读取：
    • trim 后为空：跳过
    • trim 后以 # 开头：跳过
    • 否则作为“待翻译原文”
  • 允许某个 task 区块为空（输出空 CSV 或仅表头，视实现选择）

5. 功能需求 ​

5.1 核心功能：试题解析 ​

  • 输入：当前目录 exam.txt
  • 输出：结构化试题列表，例如：
    • task: zh_en / en_zh
    • items: [{"source": "...", "line_no": n}, ...]

验收点：

  • 能正确识别两类 task
  • 注释与空行不进入待翻译列表
  • 保留原始行文本（不额外合并）

5.2 核心功能：调用大模型翻译 ​

对每条 source 文本：

  • 根据 task 设置翻译方向提示词/系统指令
  • 调用 LangChain 的统一 LLM 接口（chat model）
  • 产出译文字符串（target）

验收点：

  • 能成功调用模型并返回译文
  • 发生错误可记录日志并不中断整个批次（可配置：遇错继续/终止）

5.3 核心功能：结果输出 CSV ​

每个 task 输出一个 CSV（推荐）：

  • 文件名建议：result_zh_en.csv、result_en_zh.csv
  • 编码：UTF-8（建议带 BOM 以兼容 Excel，或提供参数控制）
  • 表头：原文,翻译

验收点：

  • 每条输入对应一条输出记录
  • 原文与译文严格对齐
  • 顺序与输入保持一致

5.4 进度展示（tqdm） ​

  • 按 task 显示整体进度
  • 或显示全局进度（task 合并）——二选一即可

验收点：

  • 运行时可见进度条更新
  • 能显示当前已完成/总数

5.5 日志记录（loguru） ​

记录内容至少包括：

  • 启动信息（时间、版本、参数、输出路径）
  • 解析结果（各 task 条数）
  • 每条翻译失败的错误详情（含行号、原文截断、异常栈）
  • 最终统计（成功数/失败数/耗时）

验收点：

  • 默认输出到控制台
  • 同时落盘到 logs/（建议，如 logs/run_YYYYMMDD_HHMMSS.log）

5.6 配置管理（.env） ​

使用 .env 存储：

  • OPENAI_API_KEY（或统一命名 LLM_API_KEY）
  • OPENAI_BASE_URL（或 LLM_BASE_URL）
  • MODEL_NAME
  • （可选）TEMPERATURE、MAX_TOKENS、TIMEOUT

验收点：

  • 未配置时给出清晰报错并退出
  • 读取 .env 生效，无需改代码

6. 非功能需求 ​

6.1 性能 ​

  • 支持至少 1,000 行文本（串行可运行）
  • 运行耗时主要受 API 影响；工具需具备稳定性与断点能力可作为后续扩展

6.2 稳定性与容错 ​

  • 单条失败不影响整体（默认 continue）
  • 输出 CSV 中失败项可写入空译文或写入错误占位（建议新增列 错误 为后续扩展；本期若严格按两列，则失败写空并在日志记录）

6.3 可复现性 ​

  • 输出中建议记录运行元信息（可写日志或单独 run_meta.json，后续扩展）
  • 同一输入与同一模型配置下尽量保持结果一致（temperature 默认 0）

7. 技术方案与约束 ​

7.1 技术栈 ​

  • Python 3.11+（建议）
  • uv 作为包管理与虚拟环境工具
  • langchain 调用大模型（统一 API）
  • tqdm：进度条
  • loguru：日志
  • python-dotenv：加载 .env
  • csv 标准库：写 CSV

8. 交互与命令行（建议） ​

8.1 启动方式 ​

  • uv run python -m src.main
  • 或 uv run python src/main.py

8.2 可选参数（非必须，但建议） ​

  • --input exam.txt
  • --outdir outputs
  • --tasks zh_en,en_zh
  • --continue_on_error true/false

本期可先只做“零参数运行”，默认读取当前目录 exam.txt，输出到 outputs/。

9. 验收标准（Definition of Done） ​

  1. 在项目根目录放置符合格式的 exam.txt，运行命令后：
    • 能正确解析 <zh_en> 与 <en_zh> 区块
    • 注释行与空行不翻译
  2. 调用大模型完成翻译，并生成：
    • outputs/result_zh_en.csv
    • outputs/result_en_zh.csv
  3. CSV 含两列：原文、翻译，顺序与输入一致
  4. 控制台显示 tqdm 进度条
  5. loguru 输出日志到控制台并落盘（至少落盘其一也可接受，但需明确）

10. 风险与注意事项 ​

  • API 限流/超时：需设置 timeout 与重试策略（可先做简单重试 2~3 次，后续优化）
  • 试题中可能包含引号/逗号：CSV 写入需正确转义（使用 csv 模块）
  • 标签错误/缺失：应输出清晰错误并退出或跳过无效块
  • 需求文本中对 <zh_en> 的描述有歧义：以标签语义为准实现（zh_en=中译英，en_zh=英译中）

MIT Licensed

Copyright © TransBench Contributors