企业官网建设流程全解析

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

FluentRead 是一款开源的浏览器双语翻译插件，其翻译服务层采用"多引擎 + 自动降级"的架构，不绑定单一翻译提供商：用户可以先用免密钥的免费服务立即开始，再按需接入 OpenAI 兼容 API、Azure、DeepL 等云端引擎，或使用 Ollama 本地模型，并根据阅读场景随时切换。本文以 docs/maintainers/product-reference/translation-engines-20260906.md 为骨架，结合仓库源码（src/services/translation/freeFallback.ts、src/core/config/freeTranslation.ts、src/core/translation/apiKeyPool.ts 等）深入讲解服务选择、免密钥自动降级、AI 精翻、云端与本地模型接入，以及多 Key 轮询机制，读完即可独立完成从"首次配置"到"生产级多引擎混用"的完整搭建。

服务页会显示可用服务、模型和当前连接状态。

怎么选：按需求匹配翻译服务

FluentRead 的翻译服务目录覆盖三类来源：免费翻译服务（免密钥）、云端引擎与 AI 服务（需 API Key）、本地模型（Ollama）。官方文档给出的选择建议如下：

需要留意的是，免费服务的速度和可用性会随时间变化，不能视为稳定 SLA；云端服务的价格、额度和数据政策由服务提供方决定，使用前应确认服务商的隐私政策和额度规则。

从源码看，服务目录被集中定义在 src/core/config/freeTranslation.ts 的FREE_TRANSLATION_PROVIDERS中，每个条目包含id、label、description、official（是否为官方公开 API）和defaultWeight（默认权重）。其中仅myMemory（MyMemory 官方 API）与apertiumFree（Apertium 开放翻译服务）标记为official: true，其余如微软 Edge 网页接口、谷歌网页接口、DeepLX 公共接口等均为official: false——这与文档中"前三项属于网页接口或非官方服务，不能视作有公开 API 保障的官方接口"的提示完全一致。

第一次配置：三步连接一个服务

在"完整设置 → 翻译服务"中完成首次连接：

1. 打开完整设置，进入"翻译服务"。
2. 从列表中选择服务；如果是 AI 服务，再选择模型。
3. 免费翻译服务和 MyMemory 无需填写密钥，可以直接检查连接；标题旁提供"使用说明"。其他已有服务按自身要求显示连接字段和官网入口。
4. 点击"检查连接"，确认服务可以正常返回结果。

两个细节值得注意：

• 切换左侧服务只切换正在配置的项目，网站入口随之更新，但不会改变默认翻译服务；MiniMax 的网站入口会跟随已选择的中国版或全球版区域。
• 连接测试会发送一条很短的请求，可能产生少量服务用量，确认成功后，再翻译长页面。

免费翻译与自动降级：四路免密钥链

"完整设置 → 翻译服务 → 免费翻译服务"是 FluentRead 的核心能力之一：用户可以在其中启用、停用或上下移动后备服务，默认顺序为微软 → DeepLX → 谷歌 → MyMemory，四路均无需密钥，至少保留一路。

各路服务的关键限制

• MyMemory：无需注册或密钥，邮箱可留空，匿名每天 5,000 字符；自愿填写有效联系邮箱后每天 50,000 字符（邮箱会随请求发送给 MyMemory）。每次最多 500 UTF-8 字节，FluentRead 自动分段。自动源语言使用本地检测；短文本无法可靠识别时，手动指定源语言。
• DeepLX：免费降级固定使用默认公共匿名地址，不继承单独 DeepLX 服务中的自建地址、代理和 Token。

Azure Translator、DeepL API Free 等服务虽然有免费额度，但仍需 API Key，不加入免密钥降级；原有独立 DeepL、AI 等服务的配置保持原有用途，免费链不会使用这些密钥。

降级策略的源码实现

免费链的运行时调度由 src/services/translation/freeFallback.ts 中的createFreeFallbackRunner承担，它协调总预算、单次超时、服务并发与间隔、错误退避和恢复单探测。关键参数定义在 src/core/config/freeTranslation.ts：

运行时行为与文档描述一一对应：

• 超时、网络故障、限流或配额错误后切换下一路：freeFallback.ts中每次尝试通过runAttempt设置独立setTimeout，超时抛出AttemptTimeoutError；classifyFreeFailure（src/services/translation/freeRoutingPolicy.ts）将错误归类为rate-limit、quota、blocked、unavailable、request五类，例如 429 →rate-limit、402/456 →quota、401/403/404/410 →blocked。
• 暂时跳过失败服务 60 秒：失败后写入冷却状态state.retryAt = Date.now() + durationMs，冷却期内候选不可用；冷却结束后会重新探测。
• 所有后备均不可用时显示失败，不无限重试：候选全部尝试后抛出"免费翻译服务均不可用"错误并附带各失败原因。
• 用户取消会中止整条链：调用方传入的AbortSignal会同步中止当前尝试并中断排队。
• 冷却状态仅存在当前后台运行期：健康快照通过freeTranslationHealthStorage持久化到存储（见 src/platform/storage/freeTranslationHealthStorage.ts），后台重启后重新加载并重新探测，不代表额度已经恢复。

值得一提的实现细节是免费链的匿名身份：providerIdentity（src/providers/translation/free-translation.ts）只用公共端点、MyMemory 可选邮箱做 SHA-256 哈希生成身份，已保存的 Key、代理和独立 DeepLX 地址均不能改变免费链的连接或冷却身份——这与文档中"DeepLX 免费降级固定使用默认公共匿名地址"的说明互为印证。

免费链的批量并发

免费翻译还支持批量文本，translateFreeBatch使用FREE_TRANSLATION_BATCH_CONCURRENCY = 3的并发度（src/providers/translation/free-translation.ts），同一批次共享截止时间，任一失败会中止整个批次并向外传播错误。修改后备顺序后，新请求使用对应的新缓存身份；新的等待策略只影响后续请求；已显示的译文可恢复原文后重新翻译。

关于官方来源与更多候选比较，可查阅仓库中的免密钥接口核验与接入限制。

Azure：Chat Completions 接入与部署名称

选择"Azure"，填写 Azure API Key，并在"Azure 端点"中填入资源地址，例如https://YOUR-RESOURCE-NAME.openai.azure.com，也支持https://YOUR-RESOURCE-NAME.services.ai.azure.com。

FluentRead 使用 Chat Completions 接口。地址处理规则如下：

• 填写资源地址或/openai/v1/基础地址时，会自动补齐为/openai/v1/chat/completions；
• 也可以直接填写完整接口地址；
• v1 无需日期型api-version参数；
• 已有的/openai/deployments/部署名称/chat/completions?api-version=版本完整地址可以继续使用，原有部署路径和版本参数会保留。

"模型"应填写 Azure 中的实际部署名称，不一定等于模型的通用名称；可通过"自定义模型"输入。配置会自动保存，填写后点击"检查连接"。

从源码看，Azure 地址兼容逻辑位于 src/core/config/azure.ts，注释明确"保留旧版 deployments 路径与自定义网关前缀，不替换显式 api-version"，证实了旧地址格式的向后兼容设计。

DeepL：API Free 与 API Pro 套餐

选择"DeepL"，先在"DeepL API 套餐"中选择套餐，再填写对应的 API Key：

套餐选择会自动保存，"当前 API 地址"会显示实际使用的地址。已有配置默认沿用 API Free；切换官方套餐后，需要重新填写对应的 API Key。如果设置了自定义接口地址，会优先使用该地址，切换套餐不会覆盖它。DeepL 翻译器订阅与 DeepL API 套餐相互独立，请使用 API 套餐提供的密钥。

AI 上下文与多段翻译：两个独立开关

这两个选项独立生效，默认都关闭：

• AI 精翻（AI 智能上下文）：点击弹窗翻译服务卡片右侧的紧凑入口，在展开面板中开启，也可在"完整设置 → 通用设置"调整。翻译时参考网页标题、描述和部分正文，帮助理解术语和指代。相关网页内容会发送给当前 AI 服务，并可能用于生成摘要，可能增加用量和等待时间。
• AI 多段翻译：在"完整设置 → 翻译设置 → 全文翻译"开启，把同批到达的相邻短段合并为一次 AI 请求，通常每批不超过 4 个文本槽、2000 字符。一个段落中的多个可翻译文本节点也会占用槽位，因此不等同于固定 4 个段落。它不要求开启 AI 智能上下文。

AI 精翻的状态机

AI 精翻与翻译服务共用一行，入口只显示名称及状态：已关闭、已开启、待配置、当前不适用、当前不可用或已暂停。悬停可查看简短提示，点击可展开开关、功能、用量与隐私，以及生效方式。需要配置服务时，可直接前往翻译服务设置。

其展示状态由 src/ui/view-model/aiContext.ts 的resolveAIContextPresentation计算：依次检查插件暂停、站点停用、当前不可用、服务不支持、缺少凭据，最终落到off/ready/needs-setup/unsupported/unavailable/paused。开关偏好会自动保存，切换到不支持的服务或模型不会清除偏好，也不会立即开始翻译——开启只代表保存的偏好，供后续新翻译使用。开启后用于后续新翻译；网页已有译文时，可恢复原文后重新翻译以应用新设置。

回显检测与降级重译

若译文出现上下文标签、明显夹带参考材料，或大部分内容复制了原文中没有的长上下文片段，会去掉页面上下文和摘要重译一次。普通术语重合只作为重试线索；重试后仍明确回显参考内容的结果不会展示或写入缓存。多段结果按槽位还原：批次格式完整时，只有夹带上下文的段落会单独进行无上下文重译，其余正确译文继续复用；无法解析批次格式时才降级为逐段翻译。

需要明确的是，回显检测是保守的文本匹配，无法识别所有改写后的参考材料，也不把专名、代码或原样输出直接判定为翻译失败。多段翻译可以减少常规全文请求数量，但服务返回异常时，重试和降级仍会产生额外请求。悬浮、划词和输入框翻译继续使用各自的请求方式。

云端服务与本地模型：隐私与运行前提

云端服务通常更容易开始，但待翻译内容会发送到对应服务，使用前请确认服务商的隐私政策和额度规则。

Ollama 适合希望在本机处理内容的用户，需要提前在本机安装并运行 Ollama，同时准备一个可用模型。模型越大不一定越适合翻译，速度、质量和电脑性能需要一起考虑。

自定义服务：OpenAI 兼容接口

如果使用的服务提供 OpenAI 兼容接口，可以在"我的服务"中添加它，并单独保存地址、模型和凭据。自定义服务的请求格式、计费方式和数据处理由服务商负责。

自定义服务和 New API 的"访问网站"会打开已配置地址的网站首页（保留端口），不会携带 API 路径、查询参数或账号凭据；地址为空或无效时，入口改为"使用说明"。

连接失败时的排查清单

• 先用短句测试，确认地址、模型和凭据没有填错。
• 检查服务商账号是否还有额度，区域或版本是否匹配。
• AI 服务返回空结果时，尝试换一个模型或减少请求内容。
• 如果使用本地模型，确认 Ollama 正在运行，并允许浏览器扩展访问。

API Key 只应填写在 FluentRead 设置中，不要放进截图、Issue、聊天记录或仓库。

多 Key 轮询：一个服务多个密钥的动态加权

当一个服务配置了多个 API Key 时，FluentRead 会按服务、端点、模型等身份隔离进行动态加权轮询，其算法位于 src/core/translation/apiKeyPool.ts。

凭据模型：apiKeys 与 token 的兼容

服务的完整凭据列表使用apiKeys[service]，旧token[service]是首个非空值的兼容镜像。配置保存、导入、备份、历史恢复和地址绑定同时处理两者；公开导出和历史不包含 Key 列表。旧单 Key 按原值迁移，不按逗号拆分。相关纯函数实现在 src/core/config/apiKeys.ts：getServiceApiKeys优先读取apiKeys，缺失时才回退到旧token的单 Key 来源（src/core/config/apiKeys.ts）。

动态权重的运行规则

• 动态权重只存在于当前运行进程，使用摘要（scope）隔离服务、端点、模型与 Key，不记录明文凭据。
• 各 Key 初始权重相同（API_KEY_POOL_DEFAULT_WEIGHT = 4，src/core/translation/apiKeyPool.ts）。
• 鉴权、配额和限流使其暂停：auth、quota、rate-limit类失败将权重直接置 0（进入冷却）；transient、network、server类失败将权重减半。
• 网络/服务暂时失败逐步降低权重，成功提高权重：成功后权重 +1，直到恢复初始权重。
• 默认恢复窗口为 1 分钟：DEFAULT_API_KEY_RECOVERY_MS = 60_000（src/core/config/scheduling.ts），用户可在高级请求限制中调整为 1–60 分钟（以整分钟保存，见normalizeApiKeyRecoveryMs）。
• 明确的 Retry-After 至少等待 1 秒并优先于默认值：reportFailure传入的retryAfterMs优先于恢复窗口。
• 取消、模型及公共配置错误不惩罚 Key：config、cancelled属于NON_PENALIZING_FAILURES（src/core/translation/apiKeyPool.ts）。
• 每次请求每个唯一 Key 最多尝试一次，各次尝试都受原调度器与共享 deadline 限制。
• 阅读/写作流仅在建立前失败时切换，开始输出后不重放。

连接检测与界面勾选

连接检测按原始行索引执行且绕过自动切换；空行与重复值不参与批量检查。界面中的勾选只代表该次检查结果，编辑或服务配置变化会使结果失效。后台还专门提供了仅对设置页开放的权重快照接口（src/app/background/handlers/freeTranslationWeights.ts），通过isOptionsUrl校验调用来源，快照只包含服务身份摘要和时间/性能数据，不暴露连接身份哈希。

小结

FluentRead 的翻译服务层是一个典型的"多引擎 + 策略调度"系统：免费链通过加权均衡与错误分类实现 5 秒超时、60 秒冷却、整链 20 秒预算的自动降级；云端接入（Azure、DeepL、OpenAI 兼容自定义服务）统一走"地址 + 模型 + 凭据 + 检查连接"的配置范式；AI 精翻与多段翻译以独立开关提供上下文增强；多 Key 轮询则用摘要隔离 + 动态加权保证一个服务多个密钥的稳定分摊。理解这套架构后，你可以按"免费起步 → 按需接云端 → 敏感内容走本地"的思路，为不同阅读场景配置最合适的翻译链路。

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