在拿到一份英文 SRT 字幕、希望快速转成中文字幕时很多人第一个直觉是打开网页翻译工具逐段粘贴。这样做的最大问题是丢上下文同一句话单独翻译和结合前后对白翻译结果经常完全不同。尤其遇到口语化台词、角色称呼、双关语和长对白时逐句复制粘贴的效率和质量都不理想。用 DeepSeek 来做英转中文字幕本质上是把字幕格式解析、API 批量调用、上下文管理和人工校审串成一条可重复执行的流水线。这篇文章会从零搭一个最小可用的字幕翻译脚本覆盖 SRT 解析、请求构造、批量翻译、质量校验和常见错误排查最终产出的工具可以直接用于个人学习或拥有合法授权的字幕翻译场景。DeepSeek API 的调用方式和 OpenAI Chat Completion 兼容核心思路并不复杂把字幕分块发给模型要求模型保留序号、时间轴结构只翻译文本内容然后把返回结果重新拼成 SRT 文件。难点集中在三处第一SRT 文件的解析和还原必须足够稳定第二模型输出必须严格遵循约定的格式否则无法自动化第三长字幕、多角色、多话题语境下翻译一致性需要额外设计。下面按完整流程展开。1. 先理解字幕翻译的链路为什么不能直接把整个文件丢给模型字幕翻译不是简单的文本翻译因为字幕文件有自己的结构。一个典型 SRT 文件长这样1 00:00:01,000 -- 00:00:04,500 Good evening, everyone. Thank you for coming. 2 00:00:05,200 -- 00:00:08,000 Tonight, we have a special guest.这个结构包含三层信息序号、时间轴、字幕文本。翻译时时间轴必须原样保留序号必须连续文本可以合理调整换行但每一段对应的起止时间不能变。如果不做解析直接把整个字幕文件内容塞给大模型会出现几类问题模型可能把时间轴也“翻译”掉把00:00:01,000理解成无意义符号并改写。模型可能合并或拆分条目导致条数变化最终字幕对不上原视频时间。文件超过模型上下文窗口时请求直接失败。多条字幕放在一个请求里模型可能漏掉某一条导致输出条数少于输入条数。所以正确做法是先写程序解析字幕把每条字幕变成结构化对象再按批次发送给模型最后把翻译结果还原成标准 SRT。这样模型只负责“翻译文本”这一件事格式和时序由代码保证。这条流水线的关键取舍在于把工程问题格式解析、批处理、重试、断点续传全部放在代码层把语言问题翻译、语境、术语交给大模型。字幕翻译工具要稳定的核心不在于提示词写得有多漂亮而在于前后处理逻辑足够严谨。2. 准备环境与字幕材料在写代码之前先把运行环境和输入材料准备好。2.1 运行环境要求建议使用 Python 3.9 或更高版本。脚本本身只依赖标准库和requests依赖非常少适合在没有复杂环境的机器上直接运行。需要准备的内容如下表项目说明Python 版本3.9用于运行脚本requests 库发送 HTTP 请求到 DeepSeek APIDeepSeek API Key从 DeepSeek 开放平台创建用于鉴权英文字幕文件SRT 格式文本编码建议为 UTF-8可选工具ffmpeg用于从视频中提取或封装字幕流安装依赖pip install requests注意字幕文件如果是从网络下载、从视频流提取或由其他工具转换而来编码可能不是 UTF-8。旧字幕常见 UTF-16 LE 或 GBK 编码。处理时先统一转成 UTF-8避免解析乱码。2.2 准备一份可用的英文字幕假设手头有一份 1995 年 OVA 的英文字幕文件文件名是episode01.srt内容是英文对白。使用前先确认来源合法最好是本人翻译自己制作的内容或者已经获得字幕作者的授权。用大模型翻译字幕属于复制和转换行为只应在合法范围内使用不要在未授权的情况下分发翻译结果。打开终端先确认文件编码file episode01.srt如果输出包含UTF-8可以直接处理。如果输出ISO-8859或UTF-16需要先转换iconv -f UTF-16 -t UTF-8 episode01.srt episode01_utf8.srt统一的脚本环境会省掉后面大量编码问题。这里建议在项目目录下建立清晰的目录结构subtitle_translator/ ├── input/ │ └── episode01.srt ├── output/ │ └── episode01.zh.srt ├── cache/ │ └── translated_batch.jsonl └── translate_srt.pyinput放原始字幕output放最终翻译结果cache存放中间结果方便断点续传。2.3 获取并配置 DeepSeek API Key在 DeepSeek 开放平台完成注册后进入 API Key 管理页面创建密钥。创建后只显示一次需要立即复制保存。在脚本中不建议把 Key 硬编码进源码更稳妥的方式是通过环境变量传入。export DEEPSEEK_API_KEYsk-你的密钥读取方式import os DEEPSEEK_API_KEY os.getenv(DEEPSEEK_API_KEY) if not DEEPSEEK_API_KEY: raise RuntimeError(请先设置环境变量 DEEPSEEK_API_KEY)之所以用环境变量是为了防止误提交到 Git 仓库导致密钥泄露。实际项目中还可以结合.env文件和管理工具读取但不建议把.env提交进版本库。3. SRT 字幕解析与还原把翻译问题变成结构化数据处理问题SRT 解析是整个流程里最基础也最容易出错的部分。解析逻辑的目标只有一个在翻译前把字幕完整拆成条目在翻译后把条目还原成合法 SRT 文件。为了做到这一点需要定义清晰的数据结构。3.1 字幕条目的数据结构每个条目包含三个字段dataclass class SubtitleEntry: index: int start: str end: str text: str这里start和end直接保存原始时间轴字符串不转成毫秒。原因是翻译过程不需要修改时间轴保留原文最稳妥。3.2 解析函数解析函数按块拆分字幕文本。块与块之间用空行分隔块内部第一行是序号第二行是时间轴后续行是字幕文本。import re from dataclasses import dataclass dataclass class SubtitleEntry: index: int start: str end: str text: str def parse_srt(content: str) - list[SubtitleEntry]: blocks re.split(r\r?\n\r?\n, content.strip()) entries [] for block in blocks: lines block.splitlines() if len(lines) 2: continue try: index int(lines[0].strip()) except ValueError: continue time_match re.match( r(\d{2}:\d{2}:\d{2}[,.]\d{3})\s*--\s*(\d{2}:\d{2}:\d{2}[,.]\d{3}), lines[1], ) if not time_match: continue text \n.join(lines[2:]).strip() entries.append( SubtitleEntry( indexindex, starttime_match.group(1), endtime_match.group(2), texttext, ) ) return entries这里三处细节要注意。第一分隔正则\r?\n\r?\n兼容 Windows 和 Unix 换行。直接按\n\n分割在 Windows 生成的 SRT 上可能失效因为行尾是\r\n。第二时间轴正则[,.]同时接受逗号和点作为毫秒分隔符。标准 SRT 用逗号但有些字幕工具会导出点号格式。统一接受可以避免解析失败。第三text保留内部换行。SRT 中一句话可能跨两行显示直接用\n.join(lines[2:])保留原始换行翻译时再让模型决定是否合并。3.3 还原函数还原时需要把条目按原始顺序输出块之间保留空行。def format_srt(entries: list[SubtitleEntry]) - str: blocks [] for entry in entries: block f{entry.index}\n{entry.start} -- {entry.end}\n{entry.text} blocks.append(block) return \n\n.join(blocks) \n翻译完成的条目index、start、end都应该保持原样只有text被替换。3.4 解析后的自检解析完成后不要急着调用 API先做一次自检def validate_entries(entries: list[SubtitleEntry]) - None: indices [entry.index for entry in entries] if len(indices) ! len(set(indices)): raise ValueError(解析出的字幕序号存在重复) for i, entry in enumerate(entries, start1): if entry.index ! i: print(f提示: 第 {i} 个条目的序号为 {entry.index}, 将在还原时处理)字幕序号重复会导致还原后的 SRT 无法被播放器正确读取这一步能提前发现问题。4. 调用 DeepSeek API 翻译字幕块环境准备好、解析函数写完后接下来是核心环节调用 DeepSeek API 完成翻译。4.1 请求接口与参数DeepSeek API 兼容 OpenAI 的 Chat Completion 请求格式。调用时使用POST请求请求体包含model、messages、temperature等参数。参数选择如下参数建议值说明model按 DeepSeek 当前可用模型填写deepseek-chat 适合通用对话和翻译任务具体以开放平台列表为准temperature0.3 到 0.7越低越稳定越高越有创造性。字幕翻译建议先用低温保证术语稳定max_tokens1000 到 2000每个请求的输出上限需要根据批次大小调整top_p默认即可采样方式相关也可以固定为 1.0streamfalse字幕翻译不需要流式输出关闭减少处理复杂度第一次做字幕翻译最容易犯的错误是temperature设置过高。翻译任务追求准确不是追求文采temperature1.5会让同一个词在不同上下文里产生完全不同的译法。推荐从0.3开始观察效果后再微调。4.2 单次翻译请求实现使用requests库直接构造请求import json import os import requests API_URL https://api.deepseek.com/chat/completions API_KEY os.getenv(DEEPSEEK_API_KEY) def translate_batch(entries: list[SubtitleEntry], glossary: str ) - list[dict]: system_prompt ( 你是一名专业字幕翻译。你会收到一组带序号的字幕文本。 你的任务是翻译成简体中文。\n 要求\n 1. 保留口语化和自然语气\n 2. 不要翻译角色名、地名、专有名词除非有约定俗成译法\n 3. 如果文本中有 HTML 标签保留标签不动\n 4. 输出必须是 JSON 数组数组长度与输入条目数一致\n 5. 每个元素格式为 {\id\: 原始序号, \translation\: \翻译结果\}\n 6. 不要输出多余解释。 ) if glossary: system_prompt f\n\n术语对照表\n{glossary} user_payload [] for entry in entries: user_payload.append({id: entry.index, text: entry.text}) messages [ {role: system, content: system_prompt}, {role: user, content: json.dumps(user_payload, ensure_asciiFalse)}, ] payload { model: deepseek-chat, messages: messages, temperature: 0.3, max_tokens: 2000, stream: False, } headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } resp requests.post(API_URL, jsonpayload, headersheaders, timeout120) resp.raise_for_status() data resp.json() content data[choices][0][message][content] return parse_model_translation(content)这里有两个关键点。第一系统提示词要求模型输出 JSON 数组。字幕翻译脚本需要把模型输出反序列化回程序数据如果模型输出里夹带解释文字程序会解析失败。输出格式约束越明确自动化越稳定。第二用户请求内容用 JSON 传入每条字幕带id这样即使模型乱序输出程序也能按id映射回原始条目。4.3 模型返回内容的解析模型返回内容可能是干净 JSON也可能被 Markdown 代码块包裹。写一个兼容两种情况的解析函数def parse_model_translation(content: str) - list[dict]: text content.strip() if text.startswith(): text re.sub(r^(?:json)?, , text, flagsre.IGNORECASE).strip() text re.sub(r$, , text).strip() try: return json.loads(text) except json.JSONDecodeError: pass # 尝试提取数组部分 match re.search(r\[.*\], text, re.DOTALL) if match: return json.loads(match.group(0)) raise ValueError(f无法解析模型输出: {content[:200]})这个函数先处理代码块包裹问题再尝试完整解析最后用正则提取 JSON 数组。如果三种方式都失败直接抛出异常让外层调用决定是重试还是跳过。4.4 将翻译结果合并回字幕条目拿到翻译 JSON 后按id映射回原条目def apply_translation(entries: list[SubtitleEntry], translated: list[dict]) - list[SubtitleEntry]: translation_map {item[id]: item[translation] for item in translated} new_entries [] for entry in entries: new_text translation_map.get(entry.index, entry.text) new_entry SubtitleEntry( indexentry.index, startentry.start, endentry.end, textnew_text, ) new_entries.append(new_entry) return new_entries如果某条字幕在模型输出中缺失这里采用降级策略保留原文。这样虽然会产生一条未翻译字幕但至少不会破坏整个文件结构。5. 批量翻译的工程化处理一个完整字幕文件通常有几百条字幕。把所有条目放在一个请求里既可能超过上下文限制也会让模型在输出长 JSON 时更容易出错。所以必须分批发给模型。5.1 批次大小怎么定批次划分参考两个指标条目数量和字符总数。按条目数划分def split_entries(entries, batch_size): for i in range(0, len(entries), batch_size): yield entries[i : i batch_size]按字符数划分def split_entries_by_chars(entries, max_chars3000): batch [] total_chars 0 for entry in entries: if total_chars len(entry.text) max_chars and batch: yield batch batch [] total_chars 0 batch.append(entry) total_chars len(entry.text) if batch: yield batch建议第一版从batch_size30或max_chars2500开始。批次越大单次请求的 token 越高模型输出更长 JSON 时越容易出错批次太小请求次数多限流风险增加。实际项目里可以先跑一两个批次观察效果再调大或调小。5.2 增加重试与退避字幕翻译是批量任务网络抖动或服务端临时错误都可能让某个批次失败。重试逻辑不能只是简单重复请求要带上指数退避import time def translate_with_retry(entries, max_retries3, base_delay2.0): for attempt in range(max_retries): try: return translate_batch(entries) except requests.exceptions.HTTPError as exc: status_code exc.response.status_code if status_code in (401, 403): raise if status_code 429: delay base_delay * (2**attempt) print(f触发限流, 等待 {delay} 秒后重试) time.sleep(delay) continue if status_code 500: delay base_delay * (2**attempt) print(f服务端错误, 等待 {delay} 秒后重试) time.sleep(delay) continue raise except requests.exceptions.Timeout: delay base_delay * (2**attempt) print(f请求超时, 等待 {delay} 秒后重试) time.sleep(delay) raise RuntimeError(重试多次仍然失败)重试策略要分状态码处理状态码含义处理方式401鉴权失败不重试检查 API Key403无权限不重试检查账号权限429请求过多退避重试必要时降低并发5xx服务端错误退避重试网络超时请求未完成退避重试但要注意幂等5.3 断点续传不要每次从头跑几百条字幕翻译到一半可能因为限流、网络断开或程序异常中断。如果中间结果没有保存重跑一次会重复消耗 token。在第 2 节的目录中已经预留了cache/translated_batch.jsonl翻译过程中就把每个成功批次的输出追加写入def save_cache(cache_path, entry_id, translated_text): with open(cache_path, a, encodingutf-8) as f: f.write( json.dumps( {id: entry_id, translation: translated_text}, ensure_asciiFalse, ) \n )主流程启动时先加载缓存def load_cache(cache_path) - dict: result {} if not os.path.exists(cache_path): return result with open(cache_path, r, encodingutf-8) as f: for line in f: line line.strip() if not line: continue try: item json.loads(line) result[item[id]] item[translation] except json.JSONDecodeError: continue return result翻译时检查缓存def translate_with_cache(entries, cache_path): cache load_cache(cache_path) pending [] result_entries [] for entry in entries: if entry.index in cache: result_entries.append( SubtitleEntry( indexentry.index, startentry.start, endentry.end, textcache[entry.index], ) ) else: pending.append(entry) print(f缓存命中 {len(result_entries)} 条, 待翻译 {len(pending)} 条) return pending, result_entries缓存文件是可读的 JSONL即使是翻译到一半中断也能从日志里检查哪些条目已经完成。5.4 避免并发过高如果为了加速加入多线程必须控制并发。DeepSeek API 有速率限制并发请求过高会触发大量 429。稳妥的做法是先用单线程跑通流程确认稳定后再考虑并发。并发版本可以使用ThreadPoolExecutor同时设置最大工作线程数from concurrent.futures import ThreadPoolExecutor, as_completed def translate_all_batches(batches, max_workers3): results {} with ThreadPoolExecutor(max_workersmax_workers) as executor: future_map { executor.submit(translate_with_retry, batch): batch for batch in batches } for future in as_completed(future_map): batch future_map[future] translated future.result() for item in translated: results[item[id]] item[translation] print(f完成 {len(batch)} 条, 当前累计 {len(results)} 条) return results并发数建议从2或3起步不要一开始就开 10 个线程。限流导致的错误重试反而会让总耗时变长。5.5 术语一致性字幕中往往有人名、地名、招式名、物品名等专有词汇。每个批次独立请求时模型没有全局记忆同一个名字在不同批次可能被译为不同写法。解决办法是在系统提示词中注入术语表glossary Kaito - 海人 Mira - 未来 Neo City - 新城市 for batch in split_entries(entries, batch_size30): translated translate_batch(batch, glossaryglossary)术语表需要人工维护或从剧本中提取。对于第一次翻译可以先让模型翻译一部分再从中整理高频专有名词形成术语表后重新跑一遍效果会明显改善。5.6 提供上下文避免单句失准字幕翻译的最大难点不是词汇而是语境。模型单独翻译一条字幕时不知道这段对白是在夸人、吵架还是开玩笑。如果模型支持上下文窗口可以在每次请求时把前几个条目的原文和译文也放进 prompt帮助模型理解语境。在批次请求中给每个待翻译条目附带“前文信息”def build_contextual_payload(entries, previous_texts): payload [] for entry in entries: payload.append( { id: entry.index, text: entry.text, previous_context: previous_texts[-3:], } ) return payload但要注意上下文会显著增加 token 消耗。项目初期可以先不加遇到明显语境问题再引入。6. 完整流程串联从 SRT 文件到翻译结果分段逻辑都完成后写一个主函数把它们串起来。def main(): input_path input/episode01.srt output_path output/episode01.zh.srt cache_path cache/translated_batch.jsonl with open(input_path, r, encodingutf-8) as f: content f.read() entries parse_srt(content) validate_entries(entries) print(f共解析到 {len(entries)} 条字幕) pending, completed_entries translate_with_cache(entries, cache_path) if pending: batches list(split_entries(pending, batch_size30)) translated_map translate_all_batches(batches, max_workers3) for entry in pending: if entry.index in translated_map: completed_entries.append( SubtitleEntry( indexentry.index, startentry.start, endentry.end, texttranslated_map[entry.index], ) ) else: completed_entries.append(entry) completed_entries.sort(keylambda e: e.index) output_srt format_srt(completed_entries) with open(output_path, w, encodingutf-8) as f: f.write(output_srt) print(f翻译完成, 输出文件: {output_path}) if __name__ __main__: main()这个流程包含四个阶段解析 SRT 并做序号校验。加载缓存跳过已完成条目。对未翻译条目分批调用 API。合并结果、排序并输出新 SRT。运行方式export DEEPSEEK_API_KEYsk-你的密钥 python translate_srt.py输出文件output/episode01.zh.srt可以直接用字幕播放器加载预览。7. 翻译结果验证与质量检查脚本能跑通不等于翻译结果可用。字幕翻译是给观众看的内容质量检查至少要覆盖以下几个维度。7.1 结构完整性检查翻译后的 SRT 必须满足三个基本条件检查项预期结果条目数量与原文一致序号从 1 连续递增时间轴与原文完全一致可以用脚本自动检查def verify_srt(original_entries, translated_entries): assert len(original_entries) len(translated_entries), 条目数量不一致 for orig, trans in zip(original_entries, translated_entries): assert orig.index trans.index, 序号不一致 assert orig.start trans.start, 开始时间不一致 assert orig.end trans.end, 结束时间不一致 print(结构检查通过)7.2 常见翻译质量问题问题现象可能原因处理建议角色名前后不一致没有术语表或批次太多提取术语表后重新翻译口语对白被翻译成书面语temperature 过高或提示词未强调口语化降低 temperature系统提示词明确要求口语化双关语、俚语翻译错误缺少上下文引入上下文窗口或人工修正HTML 标签被翻译提示词没说明保留标签提示词加上“保留 HTML 标签不动”字幕过长超出屏幕模型合并了多行文本提示词要求保持原文分段按换行翻译专有名词音译奇怪没有术语表手动维护音译对照表7.3 人工校审建议机器翻译的初稿可以大幅提高效率但不能替代人工校审。对于字幕翻译建议按这个顺序过一遍先用播放器加载翻译字幕完整看一遍标记时间轴和显示时长不舒服的位置。对照原文检查角色名、地名和特殊称谓是否统一。重点检查口语短句字幕中最难译的往往是 “Well...”“You know”“Come on” 这类语气词。检查中文断句是否适合阅读每行字幕最好控制在 15 个汉字以内。对长句做削减把书面语改成更适合口头表达的短句。注意字幕翻译的质量上限由人工校审决定而不是由模型决定。模型负责把初稿做到 70 分剩下 30 分要靠校审补齐。8. 常见问题排查实际运行时脚本报错的场景集中在 API 调用和字幕解析两类。下面按现象、原因、检查方式、解决方案整理。8.1 API 调用类问题问题现象可能原因检查方式解决方案返回 401API Key 错误或未正确传入检查环境变量是否设置重新导出环境变量确认 Key 没有空格返回 403账号权限或余额问题查看 DeepSeek 控制台账号状态检查账号是否欠费或是否有接口权限返回 429请求触发限流查看请求频率增加退避时间降低并发数返回 500服务端临时错误查看重试日志等待后重试超过 3 次则暂停任务请求超时网络波动或响应时间过长检查timeout设置增大超时时间到 120 秒以上输出 JSON 解析失败模型返回了多余文字或格式错误打印原始返回内容增强parse_model_translation的正则兜底或降低批次大小8.2 字幕解析类问题问题现象可能原因检查方式解决方案解析出的条目数为 0换行符或文件编码问题查看文件前几行是否正常先转成 UTF-8确认空行分隔存在时间轴解析失败使用了非标准 SRT 格式打开原文件检查时间轴行手工调整正则兼容点号毫秒分隔序号混乱原 SRT 文件本身不规范打印前 20 个条目索引解析后做排序和重新编号文本中出现\rWindows 换行残留检查解析后文本解析时间轴后用replace(\r, )清理8.3 翻译结果类问题问题现象可能原因检查方式解决方案某条字幕保持原文模型输出缺少该条降级保留原文查看缓存文件是否包含该 id对有问题的条目单独重试翻译同一术语译法多样缺乏全局术语表搜索输出文件中的角色名添加术语表重新翻译中文行太长模型合并了换行对比原文换行结构提示词要求保留换行还原时按\n拆回批量翻译顺序错乱并发返回顺序不确定检查按 id 映射逻辑确认合并时按 index 排序8.4 排查顺序建议遇到问题不要先怀疑模型能力按以下顺序排查文件编码是否正确。解析出的条目数量和数据是否符合预期。请求参数是否完整API Key 是否有效。模型返回内容是否能被程序解析。网络重试逻辑是否生效。合并输出后结构是否完整。大多数问题出在前两层也就是数据准备阶段而不是模型阶段。9. 生产环境建议与扩展方向脚本在本地跑通只是第一步。如果要把它做成日常可用的工具还要考虑稳定性和成本。9.1 从学习脚本到可用工具改进项学习环境做法生产环境建议API Key 管理环境变量密钥管理系统或受控的配置文件日志print 输出使用 logging记录每次请求的批次、耗时、失败原因缓存JSONL 本地文件同步到对象存储或数据库防止本地丢失并发控制固定线程数根据限流配额动态调整异常处理抛出异常记录失败批次支持手工重跑字幕质量人工检查建立术语库、错误库、前后对照校审流程token 成本不关注统计每个文件的输入输出 token估算成本生产环境还需要额外考虑固定模型版本避免模型更新后翻译风格变化。保留每次翻译的源文件、脚本版本、模型参数和输出日志保证可追溯。对翻译结果做完整备份防止缓存文件损坏导致全部重跑。对耗时较长的任务加入进度上报和中断恢复机制。9.2 token 成本控制单条字幕 token 消耗可以估算英文字幕大约每 4 个字符算 1 个 token中文字幕大约每 1 到 2 个汉字算 1 个 token。一批 30 条字幕假设每条 10 个英文单词输入约 500 token输出约 300 token。一个 500 条字幕的文件总 token 消耗在 1 万到 2 万之间。节省成本的方式缓存已翻译条目避免重复翻译。先在小样本上调整提示词确认效果后再全量跑。如果字幕文件很大先分离纯噪声内容比如歌词、重复的拟声词。把系统提示词写精简减少固定 token 消耗。9.3 从字幕翻译到视频本地化字幕翻译只是视频本地化的第一步。后续常见工作包括把翻译后的 SRT 封装进视频文件用ffmpeg生成内嵌软字幕ffmpeg -i input.mp4 -i episode01.zh.srt -c copy -c:s mov_text output.mp4生成双语字幕左右或上下对照方便学习语言# 伪代码: 将中英文本合并为一个 SRT 条目的两行 merged_text f{english_text}\n{chinese_text}根据视频实际情况调整字幕时长比如长句需要多读 500 毫秒。9.4 常见坑位总结最后把实践中最容易踩的坑汇总一下。坑 1直接翻译整个 SRT 文件内容。后果是时间轴被改动、条数被合并。正确做法是先解析再把条目分批交给模型最后还原。坑 2把 API Key 写死在代码里。一旦代码被提交到公开仓库Key 会立刻泄露。正确做法是环境变量或密钥管理。坑 3翻译结果不按 id 映射而是按顺序拼接。并发请求的返回顺序不是固定的按顺序拼接会导致字幕错位。正确做法是每条字幕带 id返回后通过 id 映射回原条目。坑 4温度参数调太高。字幕翻译不是创意写作温度越高前后术语一致性越差。先用 0.3质量不够再往上调整。坑 5批次太大。一次请求塞 200 条字幕模型输出的 JSON 又长又容易出错而且超过上下文窗口时直接失败。批次大小从 20 到 30 条起步。坑 6没有断点续传。几百条字幕翻译中途报错只能从头再来浪费时间和 token。中间结果一定要落盘。9.5 进一步学习路径如果之前没有做过 API 集成的开发可以按下面的顺序继续练习先跑通本文的最小脚本替换成自己的字幕文件。加入术语表和上下文窗口观察翻译质量变化。加入多种输出格式比如 ASS、VTT。做一个简单的命令行参数解析支持输入输出路径、批次大小、并发数配置。尝试把脚本封装成 Web 服务上传字幕后返回翻译结果。如果目的是提高翻译质量重点放在提示词设计和术语表维护上如果目的是做工具重点放在健壮性、缓存和可观测性上。两条路线都值得深入但不要一开始就追求全部功能。字幕翻译工具的价值在于把重复劳动自动化模型提供初稿代码保证格式人工负责质量。这个分工清晰之后后续无论换模型、加语言还是接视频处理流程都是在同一套工程骨架上加功能。