基于大语言模型的本地化AI翻译部署实战：从Ollama到Gradio

1. 项目概述：当AI翻译遇上本地化部署

最近在折腾一个挺有意思的项目，叫AITranslate。这名字听起来就挺直白，就是用AI来做翻译。但如果你以为它只是又一个调用在线API的翻译工具，那就错了。这个项目的核心魅力在于它的“本地化”和“可定制性”。简单来说，它让你能在自己的电脑或服务器上，部署一个完全由你掌控的AI翻译引擎，无论是翻译文档、字幕，还是实时翻译网页内容，你都可以自己说了算，不用担心API调用次数、费用，或者数据隐私问题。

我自己最初接触它，是因为需要批量处理一批技术文档的翻译。市面上的通用翻译工具，在专业术语上总是差强人意，而定制化服务又价格不菲。AITranslate的出现，让我看到了一个折中且高效的解决方案：利用开源的大语言模型（LLM），在本地搭建一个专属于我的翻译专家。它不仅仅是一个工具，更像是一个可以不断“调教”和“进化”的翻译伙伴。无论是程序员需要翻译代码注释和文档，字幕组需要高效处理海量视频字幕，还是内容创作者需要本地化自己的作品，这个项目都提供了一个极具潜力的起点。

2. 核心架构与技术选型解析

2.1 为什么选择本地化部署的LLM？

在深入代码之前，我们先聊聊为什么这个项目选择了本地部署大语言模型这条路，而不是更简单的调用云端API（如Google Translate, DeepL, OpenAI等）。这背后有几个核心考量：

首先是数据隐私与控制权。对于企业用户、科研机构或个人开发者而言，待翻译的文档可能包含敏感的源代码、未公开的商业计划、内部技术资料或个人隐私信息。将这些数据发送到第三方云端服务，存在潜在的数据泄露风险。本地化部署确保了数据从始至终都在你自己的硬件环境中流转，从根本上杜绝了隐私顾虑。

其次是成本可控与无使用限制。云端API通常按字符数或请求次数收费，对于大规模的、持续的翻译需求，长期成本可能非常可观。而本地部署是一次性投入硬件（或利用现有算力），后续除了电费几乎没有额外成本。更重要的是，没有了API的调用频率、并发数或月度限额的束缚，你可以随心所欲地进行大批量、高并发的翻译任务。

最后也是最重要的，是模型的可定制性与专业性。通用的翻译API为了兼顾广泛性，在特定垂直领域（如医学、法律、编程）的术语翻译上往往不够精准。AITranslate允许你自由选择底层模型。你可以选择一个在通用语料上表现良好的基础模型，也可以微调（Fine-tune）一个专精于你所在领域的模型。这意味着，你可以打造一个精通你行业“黑话”的专属翻译官，翻译质量远超通用服务。

2.2 项目技术栈拆解

AITranslate项目通常构建在几个关键的技术组件之上，理解它们各自的作用，是后续部署和调优的基础。

1. 大语言模型（LLM）后端这是翻译的“大脑”。项目本身不包含模型，而是作为一个调度和交互框架。常见的后端选择包括：

• Ollama: 目前最流行的本地LLM运行工具之一。它简化了模型的下载、加载和运行，提供了统一的API接口。AITranslate很可能通过调用Ollama的API来与模型通信。它的优势是开箱即用，社区模型库丰富。
• LM Studio: 另一个功能强大的本地GUI工具，同样提供了本地服务器功能，方便测试和调用模型。
• vLLM / Text Generation Inference: 如果你追求极致的推理速度和高并发，可以考虑这类专为生产环境优化的推理服务器。它们通常需要更多的配置，但性能也更强劲。
• 直接使用Transformers库: 对于开发者而言，也可以直接使用Hugging Face的transformers库在代码中加载模型，实现最高程度的控制，但需要自行处理并发、内存管理等复杂问题。

2. 模型本身模型的选择直接决定了翻译质量、速度和硬件需求。有几个主流方向：

• 多语言通用模型: 如Qwen2.5-7B-Instruct、Llama-3.1-8B-Instruct、DeepSeek-V2等。这些模型在指令跟随和多语言任务上表现均衡，是很好的起点。
• 翻译专用模型: 有些开源社区专门针对翻译任务微调了模型，例如基于Mistral或Llama微调的翻译版本。它们在翻译任务上的指令遵循能力和格式输出上可能更稳定。
• 小巧的量化模型: 为了在消费级硬件（如只有8GB或16GB内存的电脑）上运行，我们通常需要使用量化模型（如GGUF格式）。量化会轻微损失精度，但能大幅降低内存占用，让7B、8B参数的模型在普通电脑上流畅运行成为可能。

3. 应用框架与界面AITranslate需要提供一个用户交互的界面。这可能是：

• 命令行界面（CLI）: 通过命令行参数指定输入文件、输出目录、模型等，适合自动化脚本集成。
• 图形用户界面（GUI）: 使用Gradio、Streamlit或Tauri等框架构建的本地桌面或Web界面，方便普通用户拖拽文件、选择选项。
• API服务: 将核心功能封装成RESTful API或WebSocket服务，方便其他应用程序（如视频剪辑软件、文档处理工具）调用。

4. 文件处理与格式解析这是项目的“手”和“眼”。它需要能够：

• 读取多种格式的输入：纯文本（.txt）、字幕文件（.srt,.ass）、文档（.md,.docx,.pdf需解析库）。
• 智能拆分文本：将长文档拆分成适合模型上下文长度（如4096 tokens）的片段，并尽量保证段落或句子的完整性。
• 保持格式与元数据：对于字幕文件，需要精确提取时间轴，只翻译文本部分，并在输出时完美还原时间轴格式。对于文档，可能需要保持基本的Markdown结构或样式。

注意：模型的选择是一场速度、质量与资源的三角博弈。在个人电脑上，一个7B参数的4位或5位量化模型往往是平衡点。如果追求质量且有强大显卡（如24GB显存），可以考虑非量化的14B甚至更大模型。

3. 从零开始部署与配置实战

假设我们在一台拥有16GB内存、支持CUDA的NVIDIA显卡（例如RTX 4060 8G）的电脑上，从零开始部署一个基于Ollama和Gradio的AITranslate服务。以下是详细步骤。

3.1 基础环境搭建

首先，我们需要准备好模型运行环境。

步骤1：安装Ollama访问Ollama官网，根据你的操作系统下载并安装。安装完成后，打开终端（Windows为PowerShell或CMD，Mac/Linux为Terminal），运行ollama --version确认安装成功。

步骤2：拉取并运行翻译模型Ollama内置了一个模型库，我们可以直接拉取社区推荐的模型。对于中英翻译，qwen2.5:7b是一个不错的起点，它支持多语言且指令遵循能力强。

# 拉取7B参数的Qwen2.5模型（约4.7GB） ollama pull qwen2.5:7b # 如果你想尝试更小巧的版本，可以拉取3B或1.5B的模型 # ollama pull qwen2.5:3b # ollama pull qwen2.5:1.5b

拉取完成后，你可以先测试一下模型是否能正常工作：

ollama run qwen2.5:7b >>> 翻译以下句子为英文：今天天气真好。 >>> The weather is really nice today.

按Ctrl+D退出交互模式。Ollama默认会在后台启动一个API服务（通常位于http://localhost:11434），供其他程序调用。

3.2 获取与配置AITranslate项目

步骤3：克隆项目代码假设项目托管在GitHub上（例如pmacro/AITranslate），我们将其克隆到本地。

git clone https://github.com/pmacro/AITranslate.git cd AITranslate

步骤4：安装Python依赖项目根目录下通常会有一个requirements.txt文件。创建一个Python虚拟环境是个好习惯，可以避免包冲突。

# 创建虚拟环境（以venv为例） python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # Mac/Linux: source venv/bin/activate # 安装依赖 pip install -r requirements.txt

关键的依赖通常包括：requests（调用Ollama API）、gradio（构建Web界面）、pysrt或ass（处理字幕文件）、python-docx（处理Word文档）、pypdf2或pdfplumber（处理PDF）等。

步骤5：配置文件解析仔细查看项目根目录下的配置文件，可能是config.yaml、config.json或settings.py。你需要关注并修改以下几个核心配置项：

# 示例 config.yaml model: name: "qwen2.5:7b" # 与Ollama中拉取的模型名一致 base_url: "http://localhost:11434" # Ollama API地址 api_key: "" # Ollama无需API Key，留空。如果是OpenAI等云端服务则需填写。 translation: system_prompt: "你是一个专业的翻译助手。请将用户输入的内容准确、流畅地翻译成目标语言，保持原文风格和专业术语的正确性。只输出翻译结果，不要添加任何解释。" max_tokens: 2048 # 单次请求最大token数 temperature: 0.1 # 温度参数，越低输出越确定，翻译任务通常设低值（0.1-0.3） batch_size: 5 # 对于批量任务，每次发送多少句/段进行翻译 file_processing: chunk_size: 1500 # 将长文本拆分成多少字符的片段（需小于模型上下文长度） subtitle_max_chars: 80 # 单行字幕最大字符数，超出可能自动折行

步骤6：编写核心翻译函数项目核心是一个与Ollama API交互的函数。下面是一个简化的示例：

import requests import json def translate_with_ollama(text, target_lang="英文", model_name="qwen2.5:7b", base_url="http://localhost:11434"): """ 调用Ollama API进行翻译 """ # 构造提示词。清晰的指令是获得好结果的关键。 prompt = f"请将以下内容翻译成{target_lang}：\n\n{text}" payload = { "model": model_name, "prompt": prompt, "stream": False, # 非流式响应，一次性获取结果 "options": { "temperature": 0.1, "num_predict": 2048, } } try: response = requests.post(f"{base_url}/api/generate", json=payload, timeout=60) response.raise_for_status() result = response.json() translated_text = result.get("response", "").strip() # 清理可能的额外说明文字 if "翻译如下" in translated_text or "Translation:" in translated_text: translated_text = translated_text.split("\n")[-1].strip() return translated_text except requests.exceptions.RequestException as e: print(f"API请求失败: {e}") return f"翻译出错: {e}" except json.JSONDecodeError as e: print(f"响应解析失败: {e}") return "翻译出错：响应格式异常"

3.3 构建用户交互界面

使用Gradio可以快速构建一个美观的Web界面。创建一个app.py文件：

import gradio as gr from translation_core import translate_text, translate_subtitle, translate_document # 假设核心函数在这些模块中 import os def process_file(file_obj, target_lang, file_type): """处理上传的文件""" if file_obj is None: return "请先上传文件。" file_path = file_obj.name _, ext = os.path.splitext(file_path) try: if file_type == "字幕文件" and ext.lower() in ['.srt', '.ass']: output_path = translate_subtitle(file_path, target_lang) return f"字幕翻译完成！文件已保存至：{output_path}" elif file_type == "文本文档" and ext.lower() in ['.txt', '.md']: output_path = translate_document(file_path, target_lang) return f"文档翻译完成！文件已保存至：{output_path}" else: return f"暂不支持 {ext} 格式的 {file_type} 翻译。" except Exception as e: return f"处理文件时出错：{str(e)}" # 构建Gradio界面 with gr.Blocks(title="AITranslate 本地AI翻译站", theme=gr.themes.Soft()) as demo: gr.Markdown("# 🌐 AITranslate - 本地化AI翻译工具") gr.Markdown("上传你的文件，选择目标语言，即可获得AI驱动的本地翻译。") with gr.Row(): with gr.Column(scale=1): file_input = gr.File(label="上传文件", file_types=[".txt", ".srt", ".ass", ".md"]) file_type = gr.Radio(["自动检测", "文本文档", "字幕文件"], label="文件类型", value="自动检测") target_lang = gr.Dropdown(["英文", "日文", "韩文", "法文", "德文", "西班牙文"], label="目标语言", value="英文") translate_btn = gr.Button("开始翻译", variant="primary") with gr.Column(scale=2): output_result = gr.Textbox(label="处理结果", lines=10, interactive=False) # 还可以增加一个实时翻译的Tab with gr.Tab("实时文本翻译"): text_input = gr.Textbox(label="输入文本", lines=5, placeholder="在这里输入需要翻译的文本...") text_output = gr.Textbox(label="翻译结果", lines=5, interactive=False) text_translate_btn = gr.Button("翻译文本") # 绑定事件 translate_btn.click(fn=process_file, inputs=[file_input, target_lang, file_type], outputs=output_result) text_translate_btn.click(fn=translate_text, inputs=[text_input, target_lang], outputs=text_output) # 启动应用，设置share=True可生成临时公网链接 if __name__ == "__main__": demo.launch(server_name="0.0.0.0", server_port=7860, share=False)

运行python app.py，打开浏览器访问http://localhost:7860，你就能看到一个功能完整的本地AI翻译工具界面了。

4. 核心功能实现与优化技巧

4.1 长文本拆分与上下文管理

LLM有上下文长度限制（如4096、8192 tokens）。翻译一整本书或长报告时，必须进行拆分。简单的按固定字符数拆分会切断句子，导致翻译质量下降。

优化策略：语义段落拆分不要简单按字符数切割。优先在段落末尾、标题处、或者特定的标点（如句号、问号、换行符）后进行拆分。可以结合nltk或spacy库进行句子边界检测，确保拆分点在一个完整的句子之后。

import re def smart_chunking(text, max_chars=1500): """ 智能分块：尽量在段落或句子末尾切割。 """ chunks = [] # 首先按双换行符（段落）分割 paragraphs = re.split(r'\n\s*\n', text) current_chunk = "" for para in paragraphs: # 如果当前块加上新段落仍然小于限制，就添加 if len(current_chunk) + len(para) + 2 < max_chars: current_chunk += para + "\n\n" else: # 否则，保存当前块，并开始新块 if current_chunk: chunks.append(current_chunk.strip()) # 如果单个段落就超长，则按句子强行分割 if len(para) > max_chars: sentences = re.split(r'(?<=[。！？.?!])\s+', para) temp_chunk = "" for sent in sentences: if len(temp_chunk) + len(sent) < max_chars: temp_chunk += sent else: if temp_chunk: chunks.append(temp_chunk.strip()) temp_chunk = sent if temp_chunk: current_chunk = temp_chunk + "\n\n" else: current_chunk = para + "\n\n" # 添加最后一块 if current_chunk: chunks.append(current_chunk.strip()) return chunks

4.2 字幕文件翻译的特殊处理

字幕翻译是AITranslate的一个典型应用场景，其难点在于保持时间轴同步和文本长度适配。

关键步骤：

1. 解析时间轴：使用pysrt库精确读取.srt文件的每个条目（包括序号、时间轴、文本）。
2. 纯文本提取与拼接：将多条字幕文本（例如一个场景的连续对话）合并成一个段落发送给AI翻译，以获得更好的上下文连贯性。合并时需记录原始条目索引的映射关系。
3. 翻译后重组：将翻译结果按原映射关系拆分回各条字幕。这里需要特别注意，翻译后的文本长度可能变化，如果一行过长，需要根据标点或语义进行智能折行，并确保不超出播放器显示范围（通常单行不超过40个字符为佳）。
4. 时间轴保留：输出时，必须原封不动地写入原始时间轴，任何修改都会导致音画不同步。

import pysrt def translate_srt_file(srt_path, target_lang): subs = pysrt.open(srt_path) translated_subs = pysrt.SubRipFile() # 策略：每5条字幕合并翻译一次，以保持对话连贯 batch_size = 5 for i in range(0, len(subs), batch_size): batch = subs[i:i+batch_size] original_texts = [sub.text for sub in batch] combined_text = "\n".join(original_texts) # 用换行符连接，提示AI这是独立行 # 调用翻译函数 translated_combined = translate_with_ollama(combined_text, target_lang) translated_lines = translated_combined.strip().split('\n') # 将翻译结果分配回各字幕条目 for j, sub in enumerate(batch): new_sub = pysrt.SubRipItem() new_sub.index = sub.index new_sub.start = sub.start new_sub.end = sub.end # 如果翻译结果行数匹配，则对应分配；否则，将所有翻译结果给第一条，后续留空或重复（需更复杂逻辑处理） if j < len(translated_lines): new_sub.text = translated_lines[j] else: new_sub.text = "" # 或采用其他回退策略 translated_subs.append(new_sub) # 保存新文件 output_path = srt_path.replace('.srt', f'.{target_lang}.srt') translated_subs.save(output_path, encoding='utf-8') return output_path

4.3 提示词工程与翻译质量调优

给AI的“指令”（提示词）至关重要。一个模糊的指令会导致结果不可控。

基础翻译提示词：“请将以下内容翻译成英文，保持技术术语的准确性，并确保语言流畅自然。”

进阶优化技巧：

• 指定风格：“请以科技博客的正式口吻，将以下内容翻译成英文。”
• 术语表：对于专业文档，可以预先提供一个术语对照表，并在提示词中说明：“翻译时请遵循以下术语对照：‘卷积神经网络’ -> ‘Convolutional Neural Network (CNN)’, ‘负载均衡’ -> ‘Load Balancing’。请将以下内容翻译成英文。”
• 上下文示例（Few-shot Learning）：在提示词中给一两个翻译示例，让AI模仿风格。

  请按照以下示例的风格进行翻译： 示例1： 原文：这个函数的性能优化至关重要。 译文：The performance optimization of this function is crucial. 示例2： 原文：用户界面需要简洁直观。 译文：The user interface needs to be concise and intuitive. 现在，请翻译： 原文：[你的文本]

• 输出格式约束：“只输出翻译结果，不要添加任何额外的解释、说明或修饰性词语。”

在代码中，我们可以动态构造更强大的提示词：

def build_translation_prompt(text, target_lang, style="formal", glossary=None): base_prompt = f"请将以下内容翻译成{target_lang}" if style == "formal": base_prompt += "，采用正式、专业的书面语风格。" elif style == "casual": base_prompt += "，采用口语化、轻松的语调。" if glossary: glossary_str = ", ".join([f"'{k}' -> '{v}'" for k, v in glossary.items()]) base_prompt += f" 请严格遵守以下术语翻译：{glossary_str}。" base_prompt += "\n\n原文：\n" + text + "\n\n译文：" return base_prompt

5. 性能优化与生产环境部署

当翻译需求从偶尔使用变为持续服务时，性能和稳定性就成为关键。

5.1 加速推理：量化、硬件利用与批处理

1. 模型量化这是在有限硬件上运行大模型的法宝。Ollama拉取的模型很多已经是量化版本（如qwen2.5:7b默认可能是Q4_K_M量化）。你可以指定更激进的量化等级来进一步降低内存占用，但会损失更多精度。

# 拉取不同量化等级的模型（如果社区有提供） ollama pull qwen2.5:7b-q4_0 # 4位整数量化，体积最小，精度损失相对大 ollama pull qwen2.5:7b-q8_0 # 8位整数量化，较好的精度与体积平衡

2. 利用GPU加速确保Ollama使用了GPU。安装正确的CUDA驱动和ollama版本（通常安装包会自动检测）。运行ollama run qwen2.5:7b时，观察终端输出或使用nvidia-smi命令查看GPU是否被调用。你也可以在Ollama的Modelfile中指定GPU层数，但对于已拉取的模型，更简单的方式是设置环境变量：

# Linux/Mac OLLAMA_GPU_LAYERS=100 ollama run qwen2.5:7b # Windows (PowerShell) $env:OLLAMA_GPU_LAYERS=100; ollama run qwen2.5:7b

GPU_LAYERS表示将模型的前多少层放到GPU上，值越大GPU占用越高，速度越快。可以尝试设为20, 50, 100等，直到找到性能和显存的平衡点。

3. 批处理请求对于大量短文本（如字幕条目），逐个请求API的网络延迟会成为瓶颈。如果模型支持，可以修改提示词，让AI一次性翻译多个句子，并用特殊符号分隔。或者，更优雅的方式是使用支持批处理的推理服务器（如vLLM），但这需要更复杂的部署。

5.2 构建健壮的生产服务

1. 错误处理与重试机制网络波动、模型加载失败、上下文过长都可能导致单次翻译失败。必须添加重试逻辑和降级方案。

import time from tenacity import retry, stop_after_attempt, wait_exponential @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10)) def robust_translate(text, target_lang): """带重试机制的翻译函数""" try: return translate_with_ollama(text, target_lang) except Exception as e: print(f"翻译失败，正在重试... 错误: {e}") raise e # 触发重试 # 如果重试后依然失败，可以返回原文或一个错误标记

2. 异步处理与队列对于Web服务，使用异步框架（如FastAPI+asyncio）可以避免一个长翻译任务阻塞整个服务。对于文件翻译任务，可以引入任务队列（如Celery+Redis），实现后台异步处理，用户上传文件后立即返回，通过轮询或WebSocket通知用户处理完成。

3. 日志与监控记录每一次翻译请求的元数据（时间戳、模型、文本长度、耗时、是否成功）。这有助于分析性能瓶颈、统计使用情况，并在出错时快速定位问题。可以使用Python的logging模块，将日志输出到文件或像ELK这样的集中式日志系统。

5.3 模型微调：打造专属翻译专家

如果你的翻译领域非常垂直（例如医学论文、法律合同、游戏本地化），通用模型的表现可能不尽如人意。这时，微调（Fine-tuning）是终极解决方案。

基本流程：

1. 准备数据集：收集一个高质量的“原文-译文”平行语料库。数据量从几百到几千对不等，质量远比数量重要。格式可以是JSONL，每行一个对象：{"input": "原文", "output": "译文"}。
2. 选择基座模型：从一个多语言能力强的模型开始，如Qwen2.5-7B-Instruct。
3. 选择微调方法：
   • 全参数微调：效果最好，但需要大量计算资源（多张高端GPU）和显存。
   • LoRA/LoRA+：目前的主流选择。它只训练模型的一小部分参数（适配器），大大降低了资源需求（一张消费级显卡如RTX 4090即可），效果接近全参数微调。使用peft和transformers库可以轻松实现。
4. 训练与评估：使用像trl（Transformer Reinforcement Learning）这样的库进行监督微调（SFT）。划分训练集和验证集，监控验证集上的损失（loss）和BLEU等翻译质量指标。
5. 合并与部署：训练完成后，将LoRA适配器与原始模型权重合并，导出为一个新的模型文件，然后像使用任何其他模型一样，用Ollama加载它。

实操心得：对于大多数个人或小团队，从LoRA微调开始是性价比最高的。你可以在Google Colab的付费GPU（如A100）或租赁的云服务器上，用几百条高质量数据，在几小时内训练出一个专精于你领域的翻译模型。微调后的模型在特定领域内的翻译准确性和术语一致性会有质的飞跃。

6. 常见问题排查与实战经验

在实际部署和使用过程中，你肯定会遇到各种“坑”。下面是我踩过的一些坑和解决方案。

6.1 翻译质量不佳

• 问题：翻译结果生硬、术语错误、或添加了多余的解释。
• 排查：
  1. 检查提示词：是否清晰明确？是否要求了“只输出译文”？尝试在提示词中强调“准确”、“专业”、“流畅”。
  2. 检查模型：当前使用的模型是否在多语言翻译上表现良好？尝试换一个模型，比如从llama3.2:1b换成qwen2.5:7b。
  3. 调整温度参数：将temperature调低（如0.1），让输出更确定，减少“胡言乱语”。
  4. 提供上下文：对于歧义句子，尝试在提示词中提供更多背景信息。

6.2 翻译速度慢

• 问题：翻译一句话需要十几秒甚至更久。
• 排查：
  1. 硬件利用：确认Ollama是否在使用GPU。运行ollama ps查看模型运行状态，或检查任务管理器的GPU使用率。
  2. 模型大小：7B模型比14B模型快。在质量可接受的前提下，换用更小的模型（如3B、1.5B）。
  3. 量化等级：Q4量化模型比Q8量化模型推理更快。
  4. 网络延迟：如果是通过局域网访问另一台机器的Ollama服务，检查网络状况。
  5. 上下文长度：单次请求的文本是否过长？过长的上下文会显著增加计算时间。优化拆分策略。

6.3 Ollama服务无法启动或模型加载失败

• 问题：运行ollama run时报错，或提示模型不存在。
• 排查：
  1. 查看日志：Windows在%USERPROFILE%\.ollama\logs\server.log，Linux/Mac在~/.ollama/logs/server.log。日志里有详细的错误信息。
  2. 磁盘空间：确保有足够的磁盘空间下载和存储模型。
  3. 权限问题：在Linux/Mac下，确保对Ollama的安装目录和模型存储目录（~/.ollama）有读写权限。
  4. 端口占用：Ollama默认使用11434端口。检查是否有其他程序占用：netstat -ano | findstr :11434(Windows) 或lsof -i :11434(Mac/Linux)。
  5. 重新拉取模型：有时模型文件损坏，可以尝试ollama rm <model-name>删除后重新ollama pull。

6.4 字幕文件时间轴错乱或格式丢失

• 问题：翻译后的字幕文件时间轴对不上，或格式（如斜体、颜色）丢失。
• 排查：
  1. 解析库选择：确保使用健壮的库如pysrt，它能更好地处理各种.srt变体。
  2. 仅翻译文本节点：在解析.ass等高级字幕格式时，必须只提取对话文本（Dialogue行）进行翻译，其他样式、特效行必须原样保留。
  3. 编码问题：始终使用utf-8编码读写文件，避免中文乱码。
  4. 行长度控制：翻译后文本可能变长，需在拆分时确保单行不超过播放器限制，否则会导致显示不全。

6.5 内存/显存溢出（OOM）

• 问题：翻译长文档时程序崩溃，提示CUDA out of memory或内存不足。
• 解决方案：
  1. 减小批次大小：在配置中降低batch_size。
  2. 减小文本块大小：降低chunk_size，让每次发送给模型的文本更短。
  3. 使用量化模型：换用更低比特的量化模型（如Q4_0）。
  4. 启用CPU卸载：如果GPU显存不足，可以设置Ollama将部分模型层放在CPU内存中（虽然会变慢）。例如：OLLAMA_GPU_LAYERS=20（只把前20层放GPU）。
  5. 系统层面：关闭不必要的应用程序，释放内存。

最后，一个很重要的经验是：先在小样本上测试。在翻译整个大型文件或部署到生产环境前，先用一个包含各种典型句子（长句、短句、专业术语、口语）的小文件进行测试，调整好提示词、参数和拆分策略，确认效果满意后再进行批量处理。这能节省大量时间和计算资源。本地AI翻译的魅力就在于这种高度的可控性和可优化性，每解决一个问题，你的翻译流水线就变得更强大一分。