DeepSeek API 实现葡语字幕自动翻译：SRT 解析与 Python 脚本实战

做字幕翻译这件事，很多人第一反应是“直接用机翻不就行了”，但真拿一部老动画的葡萄牙语字幕去试，就会发现机器翻译出来的句子要么丢人名，要么把固定称谓翻得乱七八糟，更别说还有时间轴、断句、文本长度这些实际问题。最近在整理 1990 年那部《丽佳娃娃不可思议的奇幻故事》OVA 的葡语字幕时，我用 DeepSeek 搭了一套“字幕解析 -> 分批翻译 -> 写回 SRT”的工作流，整个过程比预想中顺很多。这篇文章就把这套方案完整拆开，从 DeepSeek API 的基础调用讲到具体脚本实现，再配合常见报错和工程化建议，给需要做外文字幕汉化、视频翻译的读者一条可以直接复用的路径。

1. 为什么要用 DeepSeek 做字幕翻译

1.1 字幕翻译的常规痛点

不管是字幕组还是个人爱好者，拿到一集外文动画的字幕文件时，第一个感觉通常是“量太大”。一部 20 多分钟的 OVA，字幕通常有 300 到 500 条，逐句复制到在线翻译网站再粘贴回来，不仅耗时，而且格式非常容易乱。更麻烦的是，翻译工具通常不理解上下文：同一句话里出现的角色名，前一秒翻译成“丽佳”，后一秒可能变成“莉卡”；同一个语气词，每个句子翻译得都不一样。遇到葡萄牙语这种本身存在不少缩合词和变位规则的语言，普通机翻的翻车率更高，人物关系、敬语和夸张语气经常被翻译得平淡无奇。

字幕翻译不是单纯的“把 A 语言换成 B 语言”，它还要考虑：

• 阅读时长：中文台词不能太长，否则观众来不及读完；
• 上下文一致性：同一角色名、专有名词全片统一；
• 口语化：动画台词偏口语，不能翻成书面语腔调；
• 格式安全：SRT 文件里的序号和时间轴不能破坏。

这些需求叠加在一起，传统机翻难以胜任，纯人工又太慢，于是基于大模型的翻译方案就成了一个很自然的选择。

1.2 DeepSeek 在字幕翻译中的优势

DeepSeek 目前提供兼容 OpenAI 接口的 API，可以直接复用openaiPython SDK，对开发者非常友好。在字幕翻译这个场景下，它的几个特点很实用：

第一个是上下文理解能力。DeepSeek 的对话模型可以接收较大的上下文窗口，翻译时把前面几条字幕作为参考一并发给模型，就能保证角色名和语气的前后一致。

第二个是可控的返回格式。可以在system提示词里要求模型“只返回翻译后的字幕文本，不要解释，不要输出序号”，这样就很容易从返回结果中直接提取翻译内容，不需要额外清洗。

第三个是成本与效率平衡。相比逐句人工翻译，批量调用 API 可以在几分钟内完成整集字幕的初译，虽然还需要人工校对，但整体效率提升明显。

1.3 本文的完整方案

本文的实操部分围绕一条主线展开：把一份葡萄牙语 SRT 字幕文件，通过 Python 脚本解析成结构化数据，然后分批调用 DeepSeek API 翻译成中文，最后重新写回 SRT 文件。整个过程包含：

• DeepSeek API Key 的准备与基础调用方法；
• SRT 文件的解析和写入；
• 批量翻译时的上下文拼接策略；
• 一个可以直接改来用的完整 Python 脚本；
• 常见报错与排查清单；
• 工程化落地的建议。

以《丽佳娃娃不可思议的奇幻故事》1990 OVA 的葡语字幕为例，我会演示整个翻译流程，但所有代码都是通用的，换成其他动画的字幕也完全适用。

2. 环境准备与账号配置

2.1 环境说明

本文示例代码以 Python 3.10+ 为主要运行环境，操作系统为 Windows / macOS / Linux 均可。核心依赖只有一个openaiPython 包，用于调用 DeepSeek 的兼容接口。

版本方面，openai库建议使用 1.x 版本，因为 1.x 之后的调用方式和 0.x 有明显差异。如果你的项目之前装的是 0.x，需要先升级。可以用下面的命令安装：

pip install -U openai

安装完成后，可以通过 Python 检查版本：

python -c "import openai; print(openai.__version__)"

如果输出1.x.x，说明环境正常。不同小版本之间的 API 参数基本一致，本文代码可以直接运行。

2.2 获取 DeepSeek API Key

要调用 DeepSeek API，首先需要注册 DeepSeek 开放平台账号，然后在控制台创建一个 API Key。创建之后，Key 只显示一次，需要复制保存到本地。

一个容易被忽略的安全点是：API Key 不能硬编码在脚本里。本文所有示例都从环境变量DEEPSEEK_API_KEY中读取。在 Linux / macOS 下可以这样设置：

export DEEPSEEK_API_KEY="sk-你的真实key"

在 Windows PowerShell 下：

$env:DEEPSEEK_API_KEY="sk-你的真实key"

也可以把 Key 放到项目根目录的.env文件中，再用python-dotenv加载。为了保持示例简洁，下文统一用环境变量方式。

2.3 调用地址与模型说明

DeepSeek API 的 Base URL 是https://api.deepseek.com，模型名常用的是deepseek-chat。如果配置了其他模型，比如推理模型deepseek-reasoner，也可以直接在代码里改用对应模型名。需要注意，模型名称在不同平台时期可能调整，实际使用时以 DeepSeek 官方文档为准。

下面这段代码是最小可用的调用示例：

# 文件路径：test_api.py import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com" ) resp = client.chat.completions.create( model="deepseek-chat", messages=[ {"role": "system", "content": "你是一个葡语翻译助手，负责把葡萄牙语翻译成中文。"}, {"role": "user", "content": "Olá, tudo bem?"} ] ) print(resp.choices[0].message.content)

运行脚本：

python test_api.py

如果看到中文输出“你好，一切都好吗？”之类的翻译结果，说明调用链路已经打通。

3. DeepSeek API 基础调用

3.1 对话补全的核心结构

DeepSeek 的接口完全兼容 OpenAI 的 Chat Completions 格式，核心就是给模型传一个messages列表。列表里通常包含两类角色：

• system：系统提示词，用来设定模型的身份和行为规则；
• user：用户的输入内容。

在字幕翻译场景中，system提示词尤其关键。相同的一段葡萄牙语，如果系统提示词写得不清楚，模型可能返回解释、加引号、甚至自己编序号；如果提示词写清楚，模型就会严格遵守“只输出译文”的约束。

下面是一个更贴近字幕翻译的system提示词示例：

system_prompt = ( "你是一名专业字幕翻译。你的任务是把用户提供的葡萄牙语字幕翻译成中文。" "要求：1. 只输出译文文本，不要输出任何解释、序号或时间轴；" "2. 保持口语化，不要翻译成书面语；" "3. 角色名要统一；" "4. 中文台词不要太长，控制在15个汉字以内；" "5. 如果原文是语气词，请翻译成对应的中文语气词。" )

这个提示词基本涵盖了字幕翻译的核心约束，实际使用中可以根据片源风格微调。

3.2 温度参数与翻译稳定性

temperature是控制模型随机性的参数。数值越低，输出越保守、稳定；数值越高，输出越发散。字幕翻译属于强约束任务，建议把temperature设置在 0.3 以下，避免同一个句子多次翻译得到不同结果。

resp = client.chat.completions.create( model="deepseek-chat", messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": "O que é isso?"} ], temperature=0.3 )

max_tokens参数也可以根据单次翻译的文本量适当设置。字幕条文本较短，一般 200 到 500 足够；如果一次传入多句，可以调到 1000 以上。

3.3 错误处理与重试

网络请求不是百分百可靠的，调用 DeepSeek API 时可能遇到超时、限流、服务端临时错误。最基础的做法是捕获openai的异常类型，并在失败后等待一段时间重试：

import time from openai import OpenAI, APIError, APITimeoutError, RateLimitError client = OpenAI( api_key=os.environ.get("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com", timeout=30 ) def chat_once(messages, max_tokens=500): try: resp = client.chat.completions.create( model="deepseek-chat", messages=messages, temperature=0.3, max_tokens=max_tokens ) return resp.choices[0].message.content except (RateLimitError, APITimeoutError, APIError) as e: print(f"请求失败：{e}") return None

在完整脚本中，我们可以配合time.sleep做有限次重试，避免一次失败直接中断整个字幕翻译任务。

4. 实战：葡语字幕转中文字幕完整流程

现在进入核心部分。假设我们已经拿到一份《丽佳娃娃不可思议的奇幻故事》1990 OVA 的葡萄牙语字幕文件，文件名是licca_1990_pt.srt。接下来要做的就是把里面的葡语文案全部转换成中文，并保留原始时间轴。

4.1 SRT 字幕的文件格式

SRT 字幕是最常见的字幕格式之一，结构简单，用记事本就能打开。一个完整的 SRT 文件由多个字幕块组成，每个块包含四部分：

1 00:00:01,000 --> 00:00:04,000 Olá, eu sou a Licca. 2 00:00:04,500 --> 00:00:07,000 Que história estranha!

其中：

• 第一行是字幕序号；
• 第二行是开始时间 --> 结束时间；
• 第三行开始是字幕文本，可以有多行；
• 字幕块之间用一个空行分隔。

解析 SRT 时要注意：不要去猜测“第三行一定是正文”，因为有些字幕块可能有三行甚至更多文本。稳妥的做法是按空行切分块，再分别提取序号、时间轴和文本。

4.2 编写 SRT 解析与写入函数

下面这段代码完成两个任务：把 SRT 文本解析成 Python 列表，以及把列表写回 SRT 文本。

# 文件路径：srt_utils.py import re def parse_srt(text): """ 将 SRT 字幕文本解析为列表。 返回格式：[{"index": int, "time": str, "text": str}] """ blocks = [] raw_blocks = text.strip().split("\n\n") for block in raw_blocks: lines = block.strip().split("\n") if len(lines) < 2: continue index = int(lines[0].strip()) time_line = lines[1].strip() content = "\n".join(lines[2:]).strip() blocks.append({ "index": index, "time": time_line, "text": content }) return blocks def build_srt(blocks): """ 将字幕列表写回 SRT 文本。 """ parts = [] for item in blocks: parts.append(f"{item['index']}\n{item['time']}\n{item['text']}\n") return "\n".join(parts)

解析函数按空行切分，避免了手动逐行遍历的麻烦。写回函数则把所有字幕块重新拼成 SRT 文本，翻译后只需要替换每个text字段，再调用build_srt即可。

4.3 批量翻译与上下文保持

直接一条一条翻译，效率低且上下文割裂。更合理的做法是：把 5 到 10 条字幕拼接成一个大文本，一起发送给模型，返回后再按行拆分。

这里有一个细节需要处理：拼接时要给每条字幕加编号，防止模型返回后无法对齐原文。例如：

[1] Olá, tudo bem? [2] Quem é você?

翻译后让模型保持同样的编号格式返回，脚本再按编号写回。这样可以避免“模型少翻译了一句”导致后续全部错位。

批量翻译的示例逻辑如下：

def build_batch_prompt(blocks, start, batch_size): lines = [] for i in range(start, min(start + batch_size, len(blocks))): lines.append(f"[{blocks[i]['index']}] {blocks[i]['text']}") return "\n".join(lines)

然后把这段拼接文本作为user消息发送，并且要求模型按编号输出译文。

4.4 完整翻译脚本

综合前面的模块，下面给出一个可以直接运行的完整脚本。脚本会读取指定的 SRT 文件，分批调用 DeepSeek 翻译，最后生成中文 SRT。

# 文件路径：deepseek_subtitle_translator.py import os import re import time from openai import OpenAI from srt_utils import parse_srt, build_srt # 初始化客户端 client = OpenAI( api_key=os.environ.get("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com", timeout=30 ) SYSTEM_PROMPT = ( "你是一名专业字幕翻译。你的任务是把用户提供的葡萄牙语字幕翻译成中文。\n" "要求：\n" "1. 只输出翻译后的中文台词，不要输出原文本；\n" "2. 保持口语化，符合动画角色的说话语气；\n" "3. 中文台词尽量精简，控制在15个汉字左右，方便观众阅读；\n" "4. 角色名保持统一，例如 Licca 统一译为“丽佳”；\n" "5. 用户输入格式为 [序号] 原文，你必须按 [序号] 译文 的格式输出；\n" "6. 不要翻译序号，只需要翻译引号后的部分。" ) def translate_batch(batch_text, retry_times=3): messages = [ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": batch_text} ] for attempt in range(retry_times): try: resp = client.chat.completions.create( model="deepseek-chat", messages=messages, temperature=0.3, max_tokens=1000 ) return resp.choices[0].message.content except Exception as e: print(f"请求异常（第 {attempt + 1} 次）：{e}") time.sleep(2 * (attempt + 1)) return None def main(): input_file = "licca_1990_pt.srt" output_file = "licca_1990_zh.srt" if not os.path.exists(input_file): print(f"找不到字幕文件：{input_file}") return with open(input_file, "r", encoding="utf-8") as f: source_text = f.read() blocks = parse_srt(source_text) print(f"共解析到 {len(blocks)} 条字幕") batch_size = 8 translated_map = {} for start in range(0, len(blocks), batch_size): batch_text = build_batch_prompt(blocks, start, batch_size) print(f"正在翻译第 {start + 1} - {min(start + batch_size, len(blocks))} 条...") result = translate_batch(batch_text) if not result: print("跳过本批，继续下一批") continue # 解析返回结果，例如 [1] 你好\n[2] 你是谁 pattern = re.compile(r"\[(\d+)\]\s*(.*)") for line in result.split("\n"): line = line.strip() m = pattern.match(line) if m: idx = int(m.group(1)) translated_map[idx] = m.group(2) time.sleep(0.5) # 避免请求过快 # 写回翻译结果 for block in blocks: idx = block["index"] if idx in translated_map: block["text"] = translated_map[idx] output_text = build_srt(blocks) with open(output_file, "w", encoding="utf-8") as f: f.write(output_text) print(f"翻译完成，已保存到 {output_file}") def build_batch_prompt(blocks, start, batch_size): lines = [] for i in range(start, min(start + batch_size, len(blocks))): lines.append(f"[{blocks[i]['index']}] {blocks[i]['text']}") return "\n".join(lines) if __name__ == "__main__": main()

在运行脚本之前，确保srt_utils.py和deepseek_subtitle_translator.py在同一个目录，同时已经设置好DEEPSEEK_API_KEY环境变量。

4.5 运行与验证

执行翻译脚本：

python deepseek_subtitle_translator.py

脚本会自动输出解析到的字幕条数，并且分批打印翻译进度。正常情况下的输出类似：

共解析到 412 条字幕 正在翻译第 1 - 8 条... 正在翻译第 9 - 16 条... ... 翻译完成，已保存到 licca_1990_zh.srt

打开licca_1990_zh.srt，可以看到如下内容：

1 00:00:01,000 --> 00:00:04,000 你好，我是丽佳。 2 00:00:04,500 --> 00:00:07,000 真是个奇怪的故事！

如果某些字幕没有翻译成功，脚本会保留原葡语文本，方便后续人工定位。这里要意识到：大模型翻译初稿不等于最终成品，还需要一遍人工校对，尤其要注意角色语气、专有名词和断句。

5. 常见问题与排查思路

在实际使用 DeepSeek 翻译字幕的过程中，下面这些问题是出现频率最高的。

排查顺序建议是：先确认 API Key 能正常调用，再用单条字幕测试提示词效果，最后再跑完整脚本。千万不要第一次就直接翻译整部剧，否则出了格式问题排查起来很费劲。

6. 最佳实践与工程建议

6.1 术语表与角色名管理

动画字幕翻译最怕的就是角色名不统一。建议在项目目录维护一个terms.txt，把全文要统一的人名、招式名、地名列出来，然后在构造system提示词时动态读入。例如：

Licca -> 丽佳 Marina -> 玛丽娜 Takarajima -> 宝岛

把这些映射追加到系统提示词后面，模型就能维持更高的一致性。对于《丽佳娃娃》这类老动画，很多角色和物品在中文社区已有习惯译名，翻译前先做一个简单排查会更稳妥。

6.2 API Key 与限流管理

API Key 的安全不能忽视。除了使用环境变量，还可以在代码里加一层校验，确保环境变量存在再执行：

if not os.environ.get("DEEPSEEK_API_KEY"): raise RuntimeError("请先设置 DEEPSEEK_API_KEY 环境变量")

另外，批量翻译时要控制节奏，不要短时间内疯狂请求。脚本里在每批之间加time.sleep(0.5)，本质上是做一次简单的自我保护。如果翻译几百集字幕，建议把任务做成队列，每批失败后记录日志，后续重试。

6.3 本地部署 DeepSeek 的补充说明

如果数据敏感或需要离线翻译，也可以考虑本地部署 DeepSeek 系列模型。常见的本地推理框架大多兼容 OpenAI 接口，因此上文代码只需要修改base_url为本地服务地址即可，业务代码不用大改。

但本地部署有两个实际代价需要提前评估：一是显存和内存开销，二是推理速度。字幕翻译场景通常要求不高，但处理几百条字幕时，本地小模型的翻译质量和速度不一定比官方 API 更有优势。建议先跑通 API 流程，再根据实际需求决定是否做本地化方案。

6.4 翻译质量人工审核流程

全自动字幕翻译目前还不能完全取代人工，尤其是老动画的台词往往带有特定时代背景和口语特征。建议采用“机器初译 + 人工精校”的双轮流程：

1. 第一轮：用脚本批量翻译，生成中文 SRT；
2. 第二轮：打开字幕文件，重点检查角色名、语气词、长句断句；
3. 第三轮：把字幕加载到播放器里，边看边校对时间轴和阅读节奏。

这样做的好处是，机器处理掉大量机械性翻译工作，人工只需要专注于需要判断力的部分，整体效率比纯人工翻译高很多。

6.5 版权与使用边界

字幕文件的版权情况比较复杂，尤其是老动画的外语字幕，可能涉及字幕组翻译成果、官方字幕、粉丝自制字幕等多种来源。用 DeepSeek 翻译字幕时，建议仅用于个人学习、技术研究和非公开交流场景。不要擅自将翻译后的字幕用于商业分发、二次销售或公开传播，避免产生版权风险。这也是技术人使用这类工具时应该保持的基本边界。

7. 总结与后续拓展

通过这次《丽佳娃娃不可思议的奇幻故事》1990 OVA 的葡转中字幕实践，我们用 DeepSeek 跑通了一条完整链路：读取 SRT、按批拼接上下文、调用对话补全接口翻译、按序号解析回写。整个过程只需要几十行 Python 代码，却能把原本可能要熬夜完成的字幕初译压缩到几分钟。

顺着这个方向，其实还可以做很多拓展：

• 把脚本改造成支持 ass 字幕格式，保留特效标签；
• 增加术语表自动提取功能，从原文中抽取高频人名并预翻译；
• 引入翻译记忆库，让相同台词在整部剧集中保持统一；
• 做成一键批处理工具，批量翻译多集字幕；
• 对接视频压制流程，翻译完成后自动合成内嵌字幕视频。

字幕翻译这个需求量一直不小，过去依赖人工逐句翻译，现在有了 DeepSeek 这类大模型接口之后，个人开发者也完全可以搭建自己的翻译流水线。后续如果再遇到老动画的外语字幕，我会优先把字幕丢进这套脚本里，先跑一版中文初稿，再慢慢校对细节，比起从零开始手动翻译确实高效太多了。如果你也正在处理类似的字幕翻译任务，不妨动手把上面脚本复制过去，跑通一次之后再按自己的片源类型调整提示词和批量大小，相信会打开一个新世界。