LunaTranslator 大模型翻译接口实战指南：通用接口参数、多密钥轮询与 SakuraLLM 离线翻译模型

LunaTranslator 大模型翻译接口实战指南：通用接口参数、多密钥轮询与 SakuraLLM 离线翻译模型

【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator

大模型翻译接口是 LunaTranslator 中最灵活、最强大的翻译引擎之一：它既能以通用接口的形式接入 OpenAI、Gemini、Claude、DeepSeek、通义千问等几十家云端大模型平台，也能以专用接口的形式驱动 SakuraLLM、GalTransl、Hy-MT2 等针对视觉小说/轻小说场景微调的离线翻译模型。本文以官方文档为主线，结合仓库源码，完整讲解通用接口的每个配置参数、常见平台的接入要点、多密钥与多接口的管理技巧，以及专用离线模型内部的 prompt 构造机制，帮助你在视觉小说汉化场景中把大模型翻译调出最佳效果。

一、大模型通用接口：把任意 LLM 变成翻译引擎

LunaTranslator 的“大模型通用接口”（对应源码中的gptcommon基类与 chatgpt-3rd-party.py 中的TS实现）面向绝大多数“对话式”大模型平台。它统一处理请求构造、流式解析、上下文拼接、多密钥轮询和结果缓存，你只需要填好 API 地址、密钥与模型名即可开箱即用，无需关心各家 API 的协议差异。

在翻译设置中选择“大模型通用接口”后，主要工作集中在几个配置项上，下文逐一展开。

二、多密钥与多接口管理

2.1 多 Key 轮询：一个输入框搞定多个密钥

如果你有多个不同的密钥只想做“轮询”使用，只需要用|（竖线）分隔填入API Key输入框即可，例如：

sk-aaaa|sk-bbbb|sk-cccc

源码中模型列表拉取、请求鉴权等环节都按|切分密钥（参见 gptcommon.py 中list_models对SECRET_KEY.split("|")[0]的处理），运行时引擎会自动轮询使用，并根据接口返回的错误反馈动态调整各 Key 的权重——某个 Key 频繁报错会被降低使用优先级，从而提升整体可用性。

2.2 多接口并存：复制一套配置做效果对比

当你不只想轮询密钥，而是想同时用不同的 API 地址 / prompt / model / 采样参数跑同一段文本做翻译效果对比时，可以：

1. 点击大模型通用接口上方的“+”按钮，选择“大模型通用接口”；
2. 在弹出的窗口中为该副本命名，系统会复制一份当前接口的全部设置与 API 配置；
3. 激活复制出的接口，对它单独修改 prompt、模型、参数等；副本与原接口可同时运行、同时出结果。

借助这一机制，你可以把同一句日文同时发给 GPT 系、Gemini 系和 Sakura 离线模型，直观对比各家译文风格，再决定正式使用哪个配置。

三、通用接口参数详解（含源码级原理）

3.1 API 接口地址

大部分常见大模型平台的接口地址可直接从下拉列表选取。对于未列出的平台，请自行查阅其官方文档填写 Base URL。

LunaTranslator 会根据你填写的地址自动识别协议类型，从而采用不同的鉴权与请求/响应解析逻辑。从 utils.py 的APIType实现可以看到识别规则：

以 Azure 为例，官方文档给出的标准地址格式为：

https://{endpoint}.openai.azure.com/openai/deployments/{deployName}/chat/completions?api-version=2023-12-01-preview

其中{endpoint}替换为你的 Azure 资源名，{deployName}替换为模型部署名。

3.2 API Key

API Key在对应平台的控制台获取。要点如下：

• 多 Key 用|分隔即可轮询（见 2.1 节）；
• 百度千帆有特殊要求：请使用百度智能云 IAM 的 Access Key、Secret Key，要么先自行换取 Bearer Token 填入，要么按Access Key:Secret Key的格式直接填入；注意它不是千帆 ModelBuilder 旧版 v1 接口的 API Key/Secret Key，两者不能通用。源码 gptcommon.py 中的qianfanIAM会在检测到Access Key:Secret Key格式时自动签名调用 IAM 换取临时 Token，并缓存复用；
• 讯飞星火比较特殊，需要按APIKey:APISecret的格式填入（见 4.2 节）。

3.3 model

大多数平台填好地址和密钥后，点击model旁边的刷新按钮即可通过平台的模型列表接口拉取可用模型（源码见 gptcommon.py 的list_models）。

如果平台不支持拉取模型列表、且默认列表里没有你想要的模型，就参照该平台官方文档手动填写模型名。手动填写后同样可以正常翻译。

3.4 流式输出

开启后，模型输出内容将以流式增量显示在翻译面板中（逐字/逐段出现），等待时间体感更短；关闭后则等模型完整生成完毕一次性显示全部内容。

从源码看，流式开关同时影响请求参数与响应解析两条链路：开启时请求体带stream=True，并走 gptcommon.py 的parsestreamresp，按协议差异分发到 Gemini/Claude/qwen-mt/通用 SSE 四种解析器；关闭时走普通 JSON 响应解析。流式模式下还会识别并隐藏思考内容（thinking ...计数），避免大段思维链刷屏。

3.5 附带上下文个数

该参数表示向大模型附带多少条历史的原文与译文作为上下文，用于让模型理解前文语境、保持人称与专有名词一致。设置为0即禁用上下文优化。

从 basetranslator.py 的_gpt_common_parse_context实现看，引擎从最近的会话历史中取出最新 N 组“用户原文 + 助手译文”，按时间正序拼回消息列表；sakura_base.py 中则通过use_context/append_context_num两个配置控制启用与条数。上下文越多对语感连续性越有利，但会消耗更多 token 并拉长首字延迟，建议在 0~8 之间按需调节。

3.6 自定义 system prompt / 自定义 user message / prefill

这是控制模型输出质量的三个“手术刀”：

• 自定义 system prompt：设定模型扮演的角色与总任务，默认值为英文的“你是一个翻译器，请把 {srclang} 翻译成 {tgtlang}，只输出译文不加解释”；
• 自定义 user message：设定每次请求的用户消息模板，默认会把{DictWithPrompt[...]}引导词和{sentence}拼进去；
• prefill：在请求末尾追加一段“助手已经输出的内容”，引导模型顺着 prefill 继续写——常用做法是填一个翻译结果的开头或直接写“译文：”，能显著约束模型只输出译文、不废话（源码见 basetranslator.py 的消息组装逻辑）。

三者都有开关，可以按喜好自定义，也可以全部保持默认。

占位符字段（在 system prompt 和 user message 中均可使用）：

从源码看，上下文占位符由 gptcommon.py 的正则{contextOriginal[(N|\d+)]}等依次替换实现；词条占位符则由__if_has_dwp处理，支持->分隔与TabSplit制表符两种词条格式，未命中词条时返回空串并吞掉后续换行（源码 gptcommon.py）。

一个典型的自定义 user message 示例：

请根据以下术语表，将 {srclang} 文本翻译成 {tgtlang}，只输出译文： {DictWithPrompt[翻译时请将以下专有名词翻译为我指定的译文：]} {sentence}

一个典型的 system prompt 示例：

你是一名视觉小说日译中专家。请结合前文语境（如有）翻译最新一句，保持人称一致： {contextBoth[4]}

3.7 Temperature / max tokens / top p / frequency penalty

这四个是常见的生成采样参数：

• Temperature：温度，越高随机性越强、越低越保守；
• max tokens：单次生成的最大 token 数上限；
• top p：核采样阈值；
• frequency penalty：频率惩罚，抑制重复用词。

针对不同平台，官方文档特别提醒了两种兼容性问题：

1. 部分参数不被接口接受：例如某些平台的模型不接受top p或frequency penalty，此时只需关闭对应参数的开关，请求体中就不会携带该字段（源码 utils.py 中按frequency_penalty_use、top_p_use等开关决定是否写入）；
2. max tokens被弃用：部分新模型改用max completion tokens。此时打开“使用 max completion tokens”开关，引擎就会把请求字段从max_tokens切换为max_completion_tokens（源码 utils.py）。

3.8 reasoning effort（思考强度）

部分平台（如 OpenAI o 系列、Gemini 2.5 系列）支持思考强度控制。LunaTranslator 将其抽象为none / minimal / low / medium / high / xhigh几个档位。

Gemini 平台会自动映射为thinkingBudget，映射规则与源码 utils.py 完全一致：

3.9 thinking.type

部分平台（主要是 DeepSeek）通过thinking.type字段控制思考模式开关。开启后，请求体会带上thinking: {"type": ...}（源码 utils.py），可配合“隐藏思考内容”选项在翻译面板中只展示最终译文。

3.10 其他参数：自定义键值对

以上只是常见参数。如果你的平台提供了额外有用的参数，可以在“其他参数”区域自行添加键值对，它们会被合并进请求体（body）或请求头（header）。从 customparams.py 的实现看，每条自定义参数支持以下类型：

例如某些平台需要传入user_id、metadata或自定义stop参数，都可以通过这里的键值对实现，无需改代码。

四、常见大模型平台接入速查

4.1 欧美平台

4.2 中国平台

4.3 API 聚合管理器

除了直接接入各家平台，也可以使用 new-api 等 API 中继/聚合工具，把多家平台的模型与多个密钥统一托管，再通过一个聚合地址接入 LunaTranslator。这样既便于团队共享额度、统一计费，也省去在多个平台控制台之间来回切换的麻烦；聚合地址在“大模型通用接口”中按普通 OpenAI 兼容地址填入即可。

五、特定离线翻译模型：SakuraLLM / GalTransl / Hy-MT2

5.1 设计初衷与适用场景

有一部分大模型是专为离线翻译设计、或针对特定场景微调的，例如面向日文轻小说/Galgame 汉化的 SakuraLLM 系模型、腾讯的 Hy-MT2 多语言翻译模型。它们大多部署好后可以直接用“大模型通用接口”调用，但部分模型需要专用 prompt 格式才能发挥最佳效果（例如 Sakura 需要携带术语表、历史翻译等结构化信息）。

为此，LunaTranslator 提供了“特定离线翻译模型”专用接口：它不开放用户自定义 prompt，而是由程序按模型发布者提供的 prompt 格式自动构造消息，用户只需要选择模型版本、填好本地部署地址即可。

目前该接口支持的模型如下：

5.2 模型自动识别与版本探测

即使你在“大模型通用接口”中选用了 SakuraLLM 等模型，LunaTranslator 也能根据模型名自动切换 prompt 模板。从 sakura_base.py 的maybedetectprompttype可以看到识别规则：

专用接口中也可直接选择具体的 prompt 版本（SakuraLLM v0.9 / v0.10 / v1.0 / v1.5 / GalTransl / Hy-MT2）。

5.3 各版本 prompt 差异（源码级）

不同版本的 prompt 构造逻辑集中在 sakura_base.py 的sakura_make_messages与hymt2_make_messages中，核心差异如下：

• SakuraLLM v0.9：最简形式。system prompt 为“轻小说翻译模型”人设，要求以日本轻小说风格将日文译成简体中文、联系上下文正确使用人称、不擅自添加原文没有的代词；用户消息为“将下面的日文文本翻译成中文：{sentence}”。
• SakuraLLM v0.10：引入术语表。system prompt 强调“使用给定的术语表”、注意使役态与被动态的主语宾语区分；用户消息先给“根据以下术语表（可以为空）……”再给待译文本。
• SakuraLLM v1.0：术语表 + 上下文组合。会将历史翻译对按“user 原文 / assistant 译文”格式拼接，同时支持术语表（格式src->dst #备注）。
• GalTransl / SakuraLLM v1.5：面向视觉小说的增强格式。system prompt 强调“视觉小说翻译模型”“日本二次元领域翻译模型”；用户消息按历史翻译 + 术语表 + 待译文本三段式拼接，并显式要求“结合历史剧情和上下文”。
• Hy-MT2：多语言翻译模型。不强制使用术语表，消息模板为“将以下文本翻译成{目标语言}，注意只需要输出翻译后的结果，不要额外解释”；若检测到词典则改为“参考下面的翻译……”引导格式（中文目标时用翻译成连接、英文目标时用translates to），并把最近 N 轮历史消息前置（sakura_base.py）。

5.4 部署与调用提示

• SakuraLLM 系模型通常需要本地/局域网部署 llama.cpp 类推理服务（如支持 llama.cpp 接口的 Sakura 分支服务端），部署完成后把服务地址填入“API 接口地址”即可；详细的 Sakura 部署步骤可参考仓库内 docs/zh/sakurallmcolab.md；
• 连接失败时，专用接口的报错提示为“无法连接，可能未正确部署 Sakura 模型”（sakura_base.py），排查时优先确认服务端口、模型是否加载完成以及地址协议是否匹配；
• Hy-MT2 面向通用多语言翻译，更适合非日文语向；日文→中文场景建议优先 SakuraLLM/GalTransl 以获得更贴合 galgame 语境的译文。

六、小结与调优建议

大模型翻译接口的参数体系可以归纳为三层：连通性参数（API 地址、Key、model）、生成参数（流式、temperature、top p、max tokens、reasoning effort 等）与内容控制参数（system/user prompt、上下文条数、术语表占位符）。实操中建议按以下顺序调优：

1. 先用刷新按钮拉模型列表，确认连通性；
2. 保持默认 prompt 跑通第一版翻译，再逐项调整“附带上下文个数”（4~8 条）与 system prompt；
3. 打开“专有名词翻译 +{DictWithPrompt[...]}”占位符，统一人名/地名/专有名词，注意未命中词条时占位符会自动清除，不会污染译文；
4. 多平台对比时用“+”复制接口，同时挂载不同配置逐句对比；
5. 离线场景直接选用专用接口加载 SakuraLLM/GalTransl，并确认模型名可被自动识别到对应 prompt 版本。

源码中与本主题相关的关键文件包括：translator/gptcommon.py（通用接口核心与流式解析）、translator/sakura_base.py（离线模型 prompt 构造）、translator/basetranslator.py（prompt 模板与上下文拼接）、myutils/utils.py（APIType 识别与 Gemini thinkingBudget 映射）、gui/customparams.py（自定义参数类型）。深入阅读这些实现，可帮助你针对特定平台写出更精准的自定义 prompt 与扩展参数。

【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator