企业官网建设流程全解析

• 前端
• AI 应用
• 本地部署

本文是 FluentRead（开源浏览器双语翻译插件）翻译服务配置的技术指南，围绕 docs/en/config/translation-engines.md 展开。读完本文，你将掌握如何从服务目录中选择并配置机器翻译、云厂商、AI 服务与本地模型，理解多 API Key 轮换、免费翻译自动均衡、DeepLX 端点模板、本地模型资源占用等底层机制，并能独立完成「配置 → 检查连接 → 设为默认服务」的完整接入流程。

先弄清一个关键概念：配置服务 ≠ 切换默认服务

FluentRead 的翻译服务目录按分类排列并支持搜索。点击某个服务条目只会打开它的配置页，不会立刻改变网页翻译所用的服务；真正决定网页翻译去向的是「常规设置」或扩展菜单中的默认服务选择。文档（translation-engines.md）对此有专门提示：文档、字幕和翻译卡片还有各自独立的服务选择，配置时不要混淆。

服务详情中的高级设置默认折叠，展开后按四个分组组织：

• Keys and authentication（密钥与认证）：管理多 Key 轮换；
• Translation preferences（翻译偏好）：调整模型思考与提示词；
• Request settings（请求设置）：调整等待时间与请求频率、代理地址；
• Custom requests（自定义请求）：补充自定义请求头与 JSON 参数。

云服务在详情中会默认展示免费额度、开通步骤以及控制台/接口文档链接；免费额度是否可用、超额如何处理，取决于服务商与当前套餐。

五步完成一次服务接入

文档给出的标准流程如下：

1. 进入「设置 → 翻译服务」，在目录中选中要配置的服务；
2. 按服务商提供的信息填写密钥与地址；AI 服务还需选择模型。即使 API Key 留空也可以先点检查连接——需要凭据的服务会在检查结果中提示缺少凭据或认证失败（源码 connectionTest.ts 即负责这类探测）；
3. 点击服务详情标题栏右侧的检查连接，确认能返回译文。检查会发送一条短请求，可能产生少量用量；
4. 回到常规设置或扩展菜单，将该项选为默认服务；
5. 翻译一句话验证效果。

内置服务无需额外添加即可配置；已有配置与自定义接口会保留。需要接入不在目录中的 OpenAI 兼容接口时，点击目录顶部的自定义服务。

免费翻译服务：零密钥起步与自动均衡

免费翻译服务通过多个免密钥端点生成译文，是「安装后直接翻译」的默认路径。

参与服务的端点

默认启用且无需密钥的有：Microsoft、腾讯交互翻译（Tencent TranSmart）、火山翻译、Google、有道网页翻译、金山词霸（ICIBA）、Yandex、DeepLX、MyMemory；可选启用 Sogou、Reverso、Lingva（三者仍为实验候选）以及 Apertium（暂无中文语言对）。这一目录与源码 freeTranslation.ts 中的FREE_TRANSLATION_PROVIDERS定义一一对应，其中 MyMemory 与 Apertium 标记为官方接口（official: true），其余为网页接口（official: false），默认权重各不相同（微软 5、腾讯交互/火山/谷歌/有道/金山词霸 3、Yandex 2、DeepLX/MyMemory 1）。

自动均衡与优先顺序两种模式

默认模式为自动均衡（balanced）：微软排在首位并优先尝试。后台调度器依据成功率、响应耗时与近期错误动态分配请求；某一路失败时自动切换。调度所需信号全部由后台自动维护（可见 freeRoutingPolicy.ts 中observeFreeProviderPerformance用指数移动平均维护可靠性reliability与延迟latencyMs，并随时间衰减旧观测，避免一次历史故障永久压低服务），用户只需配置启用状态与模式。

你可以停用某些端点，或切换为**优先顺序（sequential）**模式按列表顺序依次尝试；至少要保留一个启用项。

限流与恢复节奏

免费端点的暂停策略在 freeRoutingPolicy.ts 的getFreeFailureCooldown中可查到精确实现：额度耗尽（quota）暂停约 1 天，访问受阻（blocked）从 6 小时起退避、上限 1 天，限流（rate-limit）从 5 分钟起退避、上限 6 小时；如果服务端给出了retryAfter等待时间则优先遵循。恢复记录保存在本地，后台重启后继续生效。每路默认最多等待 5 秒（DEFAULT_FREE_TRANSLATION_TIMEOUT_MS = 5_000），超时即换路。

免费服务可用性与额度会变化，公共接口和第三方中转有各自的数据政策。若只希望请求流向某一家，就只保留那一个端点，或直接选用对应的独立服务。

MyMemory：匿名翻译的官方选项

选择MyMemory后可直接点击检查连接，联系邮箱可留空。连接检查会翻译一句固定的英文到中文短句，因此不需要先修改源语言或目标语言；已保存的语言与邮箱设置会保留。源码 freeTranslation.ts 标注 MyMemory 为官方 API，匿名每天约 5,000 字符额度。

日常翻译仍使用你选择的语言；自动检测无法确定短文本的源语言时，请手动选择源语言后重试。

DeepL 与 DeepLX：从官方 API 到自建端点

DeepL选择 API Free 或 API Pro 套餐，填入对应密钥即可。注意 DeepL 网页翻译器的订阅与 API 套餐是不同产品，不能直接互换。

DeepLX的配置重点是端点地址：

• 服务地址需填写完整翻译接口路径，例如https://deeplx.example.com/translate；只填域名不会自动补全/translate；留空则使用默认公共匿名端点（源码 deeplx.ts 中默认端点由DEFAULT_DEEPLX_ENDPOINT决定，且自由服务内的 DeepLX 也固定使用公共匿名端点，用户单独配置的地址不会带入免费链）；
• 无需鉴权的端点可以留空 API Key 直接检查连接；需要鉴权时，API Key 只填站点提供的Token 值本身，不加Bearer前缀——请求默认通过请求头发送 Token；
• 若站点要求在 URL 中携带 Token，使用{{apiKey}}占位符模板：

查询参数：https://deeplx.example.com/translate?token={{apiKey}} URL 路径：https://deeplx.example.com/{{apiKey}}/translate

保留{{apiKey}}原样，发送时会被替换为已保存的 API Key。若配置了代理地址，代理优先，也需要在其中填写完整路径和站点要求的 Token 格式。配置了多个端点时，留空的 Key 会跳过含{{apiKey}}/{{token}}的地址，只用有效的匿名地址；如果所有地址都需要 Token，需先填写 Key——未解析的占位地址不会悄悄回落到默认公共端点。

从源码看，DeepLX 适配器（deeplx.ts）会把语言码规范化为 DeepL 协议格式（auto → AUTO、zh-hans/zh-cn → ZH、zh-hant → ZH-HANT），对每个候选端点设置 8 秒单次超时、20 秒总预算，并在端点间做有序故障转移；HTTP 4xx/5xx 状态会被保留，供外层免费链判断是否熔断。

云服务厂商：稳定免费额度与区域一致性

云服务厂商分组收录六大云平台的官方机器翻译 API，与「机器翻译」分组里的免费网页端点相互独立：免费端点无需密钥但可能限流，云厂商接口需要控制台签发密钥，换来稳定服务和明确的免费额度。

在设置页选中任一云厂商后，服务详情默认展开免费额度、三步开通指引以及控制台/接口文档链接；按指引拿到密钥填入表单，点击检查连接即可。免费额度、开通条件与超额处理以厂商控制台与当前套餐为准。

区域一致性是关键：Azure、阿里云与火山引擎的区域会参与请求签名或决定请求域名（源码 aliyun-translation.ts、azure-translator.ts、volc-translation.ts 各自的签名实现均依赖区域参数）。选错区域通常表现为 401/403 或签名不匹配，请保持与控制台中资源所在区域一致。

两段式密钥（AccessKey Secret、SecretKey 等）与 API Key 一样只保存在当前设备；公开分享的配置与配置历史不包含它们，完整备份才会保留。

本地模型翻译：完全离线的浏览器内翻译

在「设置 → 翻译服务 → 本地模型翻译」选择模型并下载，显示可离线使用后即可试译并切换为默认服务。整个过程无需 API Key，也不需要单独启动本地服务器，翻译文字始终在当前设备处理。

模型目录在源码 localTranslation.ts 中定义，与文档一一对应：中英/日英语言包基于 OPUS-MT（Xenova/opus-mt-en-zh、opus-mt-zh-en、opus-mt-ja-en等），引擎为opus；Hy-MT2 1.8B 来自tencent/Hy-MT2-1.8B-GGUF，引擎为hunyuan，其语言范围在HUNYUAN_LANGUAGE_NAMES（localTranslation.ts）中覆盖中文、英文、日文、韩文、泰文、阿拉伯文等 30 余种。模型下载为 q8 量化格式（LOCAL_TRANSLATION_DTYPE = 'q8'），文件来自 Hugging Face，校验完成前不可用——接近 100% 时请留意状态，不要只看百分比。

关于下载与运行，文档明确了几个重要事实：

• 下载中可暂停，切换设置页不中断；重启浏览器后可继续已保存的进度；
• 删除模型需二次确认，只影响所选模型；模型文件属于当前浏览器，不包含在设置备份中；
• 下载大小不等于运行内存：轻量语言包也可能短暂占用约 1–2 GB 额外内存，载入时 CPU 升高（源码memoryMb: [500, 2000]与混元的[1500, 2500]印证了这一区间）；模型空闲 30 秒后释放；
• 该功能需要支持扩展内本地运行的浏览器，油猴版（userscript）不提供模型下载与运行；不兼容混元时页面会提示更换浏览器或选择轻量包；
• 本地混元与需要账户密钥的混元云端服务是两回事，模型来源与许可可从卡片信息入口查看。

本地翻译的实现路径在 local-translation.ts：请求经 provider 层转换后交给 Offscreen Worker（localTranslationOffscreenAdapter）推理，全程不上传云端；不支持的语言或未下载模型会映射为对应的本地化错误文案。

AI 服务：轻量模型默认与自定义端点

新配置默认使用适合日常翻译的轻量模型：

聚合平台与接口分组还收录了 Mistral AI、Cohere、Cerebras、Together AI、Fireworks AI、DeepInfra、Perplexity 等 OpenAI 兼容平台，配置方式与普通 AI 服务相同：填平台密钥、选模型。目录更新不会覆盖已保存的有效模型或自定义模型。DeepSeek 默认关闭思考（模型思考开关实现见 modelThinking.ts）；无法完全关闭思考的模型使用其支持的最低档。更大的模型仍可手动选择，费用以服务商为准。DeepSeek 新编号见其官方更新记录；旧的deepseek-v4-flash仍是兼容别名；已下线的混元hy3-preview会自动迁移为hy3。

使用 Azure 时，模型栏填写实际的部署名称，地址栏填写资源地址或服务商给出的完整接口地址。

自定义服务的 Base URL 规则

自定义服务使用OpenAI Chat Completions协议，可填完整端点或 Base URL：

• https://opencode.ai/zen/v1→ 请求https://opencode.ai/zen/v1/chat/completions；
• 仅填域名和端口 → 自动补/v1/chat/completions；
• 其他非标准路径 → 按完整端点使用；
• 高级设置中的代理地址优先，且作为完整端点请求、不自动补全路径；查询参数保留。

以 OpenCode Zen / Go 为例：Base URL 分别为https://opencode.ai/zen/v1与https://opencode.ai/zen/go/v1，需选择官方模型表中支持/chat/completions的模型，并填写 API 模型 ID（不带opencode/或opencode-go/前缀）。仅提供/responses、/messages或 Gemini 原生接口的模型无法用于此自定义服务。

如果检查连接返回 HTTP 404 且页面是 HTML，多半是端点或模型协议不符，这类响应不能证明 API Key 无效；JSON 格式的模型错误会显示服务商的具体说明。切勿在公开反馈中包含 API Key。

自定义请求头

在服务列表中选择自定义 OpenAI 兼容服务，展开「高级设置 → 自定义请求 → 自定义请求头」，填写 JSON 对象（名称与值都必须是字符串）：

{"x-opencode-session": "a71a2ad6-1d1f-4e92-a30e-e35c8fd623ab"}

请求头只作用于该自定义服务，同名头会覆盖默认值（名称不区分大小写）；留空恢复默认。需要稳定会话标识时保存同一个值即可，每次请求不会重新生成。可用于额外鉴权、HTTP-Referer、X-Title等参数；使用自定义鉴权且无需默认 Bearer Token 时，可关闭该模型的 API Key 要求。浏览器对请求头的限制仍然适用。请求头按凭据保存：公开导出与配置历史不包含它，完整备份保留；更换端点或代理地址后需重新填写。

腾讯混元连接失败排查

选择腾讯混元并填写混元控制台创建的 API Key，默认使用官方端点；腾讯混元翻译是另一项独立服务，需要 SecretId 与 SecretKey（源码 hunyuan-translation.ts）。旧版本若报Failed to fetch，可在「请求设置 → 代理地址」填入https://api.hunyuan.cloud.tencent.com/v1/chat/completions后重新检查连接；自建代理或 TokenHub 则使用对应平台提供的完整端点与密钥。

AI 精翻与多段翻译

• AI 精翻：允许翻译参考网页标题与部分正文，帮助理解术语与指代；会发送更多上下文，可能增加用量与等待时间；
• AI 多段翻译：把相邻短段一起交给 AI，可能减少请求次数；结果异常时仍可能重试。

两者默认关闭、可独立开启。改变设置后，对已有译文先恢复原文再重新翻译；需要术语一致时可配合术语库。

Ollama 与本地聚合平台

Ollama 需先安装、启动并下载模型，再接入 FluentRead。在聚合平台与接口中选择Ollama（本地）：

• 默认连接http://127.0.0.1:11434，无需 API Key；
• 模型栏填写本机已拉取的模型名，如qwen3:8b；
• Ollama 运行在其他机器或非默认端口时，在服务地址填写完整的/v1/chat/completions地址；
• 浏览器扩展访问 Ollama 需允许来源：启动时设置OLLAMA_ORIGINS=*，否则请求会被 CORS 拒绝。

该分组的 Mistral AI、Cohere、Cerebras、Together AI、Fireworks AI、DeepInfra、Perplexity 按普通 AI 服务方式配置。选择本地模型只决定对应翻译请求的去向；朗读、查词、下载等独立功能仍可能使用网络服务，详见数据与隐私。

多 API Key 轮换与批量检查

支持 API Key 的服务可在「高级设置 → 密钥与认证」中启用 Key 轮换，点击列表底部「添加 Key」每行填写一个（无需分隔符）；原来保存的单个 Key 继续保留。所有 Key 共用该服务的地址、模型、区域与自定义请求头——这些设置不同时，请分别创建自定义服务。

轮换机制在 apiKeyRotation.ts 中实现：开始时各 Key 均衡分担请求（实际按轮询租约挑选）；请求失败自动尝试其他 Key 并降低失败 Key 的使用频率；鉴权失败或额度用尽的 Key 可能暂停。失败 Key 的默认恢复等待为 1 分钟，可在「设置 → 高级 → 请求限制」调整为 1–60 分钟；服务端给出明确限流等待时间时遵循该时间。轮换不绕过已配置的请求频率与总超时限制。健康状态是临时状态，扩展后台进程重启后重置。

「检查全部」按顺序测试每个已填写且不重复的 Key，结果与汇总同区显示；点开失败状态可查看原因，或用行末按钮单独重测，检查期间可停止。一个 Key 失败不会中断其余检查；空白行与重复 Key 不额外发请求。检查会发送短测试文本，可能消耗少量服务额度；通过只代表这次检查，不保证后续始终可用。值得注意的实现细节：redactApiKeyError会把错误信息中的明文密钥替换为[已隐藏的密钥]，确保密钥不会泄漏进运行时错误或日志。

连接失败排查

• 先核对密钥、地址、模型与账号额度；
• 能翻译短句却无法处理长文章时，减少同时请求数或更换服务；
• 有道网页翻译与金山词霸目前支持简体中文和英文方向；Yandex 暂不支持繁体中文目标；不支持的语言方向会交给其他候选处理；
• 免费网页接口可能限流或失效，可在设置中停用；
• 不要把真实密钥放进截图或反馈中。

更完整的排查流程见常见问题。

小结

FluentRead 的翻译服务体系覆盖了从「零密钥即用」到「完全离线」的全部路径：免费翻译靠多端点自动均衡与本地健康记录保证可用性；云厂商接口以区域签名换取稳定免费额度；本地模型在浏览器内完成推理；AI 服务与 OpenAI 兼容自定义端点则提供模型级灵活性。多 Key 轮换、请求头、代理与请求限制共同构成了可精细调校的连接层。无论选择哪条路径，核心流程始终一致：配置服务 → 检查连接 → 从常规设置或扩展菜单设为默认。

• 前端
• AI 应用
• 本地部署