展开本页目录
开始前准备什么
- UTF-8 CSV，表头严格为 row_id,text
- Python 与 OpenAI SDK；当前令牌支持文本模型
- 小批量预算、固定术语表与人工抽查规则
- 验证输入
- 逐行请求
- 检查数字与术语
- 恢复失败行
逐行日志、设置哈希、术语及数字校验、明确重试开关。
包含术语、数量、交付天数与前导零订单号。
row_id 保持稳定，CSV 用解析器读取
行号会随排序和删除变化，使用业务稳定 ID 关联结果。下载脚本拒绝重复或空 row_id，使用 csv.DictReader 处理引号、逗号和换行；不通过 split(",") 拆表格。
示例只翻译 text，原 row_id 与源文本原样保留。价格、数量、SKU 等独立业务字段应留在你自己的数据列里，尽量不让模型重写。
developer-translation-sample.csv
row_id,text
qr-001,使用大模型处理 30 条记录，按量计费。
qr-002,预计交付时间为 7 天；订单号 00128 不变。
本站绘制的内容说明图：这些是下载 CSV 的示例内容；翻译时保留行号、数字和订单前导零，不能按输出顺序猜原行。
术语与数字先写验收规则
示例约定“大模型”译为 large language model，“按量计费”译为 pay-as-you-go；数字字符串按出现次数比较，00128 不能变成 128。翻译为空、漏术语或改数字，都标记校验失败。
数字规则只是基础检查，不证明语义完全正确。百分比、单位、日期、占位符和 HTML 标签应按实际表格再扩展校验；有多语言数字格式时，先定业务允许的转换规则。
完整运行流程：预检、翻译、恢复
--validate-only 只读本地 CSV，不访问 API。首次翻译前设置环境 Key 和准确模型。普通再次运行跳过 success、failed 与 unknown；要重试失败行，明确使用对应参数。
bash
python -m pip install -U openai
python developer-csv-translation.py developer-translation-sample.csv --validate-only
# 配置 tokenba_API_KEY 与 tokenba_MODEL 后
python developer-csv-translation.py developer-translation-sample.csv
# 已确认的校验失败行，可明确再次提交
python developer-csv-translation.py developer-translation-sample.csv --retry-failed
# unknown/processing 先查控制台记录；确认可重发后才使用
python developer-csv-translation.py developer-translation-sample.csv --retry-unknown独立可运行的 CSV 预检示例
这个预检不会发送数据；完整下载脚本把请求、逐次 usage、数字与术语检查、持久化日志和输出合并放在一起。
python
import csv
from pathlib import Path
with Path("developer-translation-sample.csv").open(
encoding="utf-8-sig", newline="") as stream:
reader = csv.DictReader(stream)
if reader.fieldnames != ["row_id", "text"]:
raise ValueError("表头必须为 row_id,text")
rows = list(reader)
ids = [row["row_id"] for row in rows]
if any(not value for value in ids) or len(ids) != len(set(ids)):
raise ValueError("row_id 必须非空且唯一")
print(f"已验证 {len(rows)} 行，未调用 API")日志让恢复可解释，但不承诺恰好执行一次
| 状态 | 含义 | 下一步 |
|---|---|---|
| processing | 已落盘准备提交，未写终态 | 中断后当未知，先查记录 |
| success | 完整返回并通过本地校验 | 相同输入与设置下跳过 |
| failed | HTTP、内容或校验失败 | 分析原因，显式 retry-failed |
| unknown | 超时或连接错误，执行结果不确定 | 查控制台，再决定 retry-unknown |
- 状态
- processing
- 含义
- 已落盘准备提交，未写终态
- 下一步
- 中断后当未知，先查记录
- 状态
- success
- 含义
- 完整返回并通过本地校验
- 下一步
- 相同输入与设置下跳过
- 状态
- failed
- 含义
- HTTP、内容或校验失败
- 下一步
- 分析原因，显式 retry-failed
- 状态
- unknown
- 含义
- 超时或连接错误，执行结果不确定
- 下一步
- 查控制台，再决定 retry-unknown
本站绘制的内容说明图：恢复表用于逐行追踪已发请求；不确定结果与确定失败分开，避免重复提交造成额外费用。
输入或设置变化，另开一份日志
每行记录 input_hash 和 settings_hash，后者覆盖模型、目标语言、术语表与提示版本。使用已有日志时若源文本或设置改变，脚本直接停止，避免用旧成功结果覆盖新内容。
同一日志只允许运行一个进程。脚本逐行 fsync 保护落盘，但不保证网络调用恰好一次；尤其 processing 记录后进程中断，仍需要核对上游记录。
保留全部尝试，再评估质量与费用
usage 随每次可用响应保存，包括返回后数字校验失败的尝试。一次人工重试会新增调用费用；不能只汇总最终成功行。超时缺 usage 时标未知，用后台记录补证。
先翻译样本两行，检查术语、00128、7 与30，以及语义。扩大批量前定义并发、限速、字符预算和人工抽样；不要一开始自动重试整张表。
怎样确认已经完成
- 重复 ID、坏表头、畸形 CSV 被预检拒绝
- 30、7、00128 与术语表被保留
- 第二次普通运行不会调用已有成功行
- 失败与未知使用不同重试参数，全部尝试留日志
常见问题
断点恢复是否绝对不会重复计费？
不保证。已完成成功行会跳过，但超时或进程中断可能已被上游处理，未知状态必须先查记录。
改了术语表，可以直接复用日志吗？
不行。示例会检查设置哈希并停止，请使用新日志，避免复用旧译文。