🔑 大模型 API Key 使用说明

字帖生成器 v3.0.7 · AI 组词补齐 / 拼音纠错 / 全量检查（18 家内置引擎 + 自定义引擎 · 自动检测 + 自动优选）

更新日期：2026-10-04 · 适用版本：v3.0.7 及以上

← 返回字帖 📥 导入与修改 →

一、功能概述

v1.1.0v3.0.4v3.0.6字帖的 AI 辅助功能提供组词补齐、拼音纠错与全量检查三项能力，支持 18 家内置大模型引擎，并可在 AI 控制台里添加任意自定义引擎（唯一注册表：src/modules/aiProviders.js）：

v3.0.6 的两个大变化：① 新增「⚙ AI 控制台（模型设置）」——引擎 / 模型 / Key 的统一管理面板，支持自定义引擎（自己的 Base URL + OpenAI/Anthropic 协议 + 请求参数）、批量导入、连通性体检；② Key 默认只存内存、不再明文落盘，旧版明文 Key 会在首次加载时迁入内存并从本地存储删除（会弹一次安全提示）。
提示：AI 辅助为可选功能，不配置 Key 时字帖所有核心功能（生成 / 打印 / 笔顺演示等）完全不受影响。

二、快速开始

  1. 点击右上角「⚙️ 设置中心」→ 找到「🤖 AI 辅助（可选）」区块，先勾上「启用 AI 辅助」开关（默认关闭，不勾则下方配置区不显示）
  2. 添加 Key，两条路都行：
    • 快通道：在「＋ 添加」输入框粘贴 Key（如 DeepSeek 的 sk- 开头、火山引擎豆包的 ark- 开头），点击「＋ 添加」
    • 完整通道（推荐）：点「⚙ AI 控制台（模型设置）」——双栏面板，左侧是引擎列表（内置 18 家 + 你添加的自定义引擎），右侧是该引擎下的 Key / 模型 / 参数。可一次填完 Key + Base URL + 模型 ID + 协议（OpenAI / Anthropic）+ 请求参数，也能「＋ 添加供应商」挂一个注册表里没有的引擎，或用「📂 导入」批量导入
  3. 勾选功能开关：组词补齐（默认）/ 拼音纠错 / 全量检查（级联联动）
  4. 点击「▶ AI 检查与补齐」运行，状态栏显示旋转图标 + 批次进度
说明：v3.0.1 起 Key 采用「添加即生效」机制，无需再点「保存」按钮；v3.0.4 起添加或导入后自动探测（识别引擎 + 判定可用性 + 是否免费）并纳入自动优选，无需任何手动步骤。
🔒 v3.0.6 起 Key 默认只存内存：刷新页面就没了。想让它活着，在 AI 控制台里显式选一种保存方式（见「五、安全与隐私」）——这是刻意的安全默认值，不是 bug。

三、多 Key 管理

3.1 支持的平台（18 家内置引擎）

引擎 Key 形状 是否免费 申请地址 备注
DeepSeek sk- 开头 付费但便宜 platform.deepseek.com Key 为 sk- 开头（该前缀被多家共用）
火山引擎豆包 ark- 开头 有免费额度 console.volcengine.com/ark 全量检查自动使用 turbo 强模型
智谱 GLM 形如 <32位十六进制>.<密钥段> GLM-4-Flash 免费 open.bigmodel.cn GLM-4-Flash 免费
月之暗面 Kimi sk- 开头 付费（低价档） platform.moonshot.cn Key 与 DeepSeek 同前缀，需探测消歧
硅基流动 sk- 开头 有免费模型 cloud.siliconflow.cn Key 为 sk- 开头，需探测消歧
阿里云百炼（兼容模式） sk- 开头 新用户 token 额度 bailian.console.aliyun.com Key 为 sk- 开头，需探测消歧
OpenRouter sk-or-v1- 开头 有 :free 免费模型 openrouter.ai/keys 专属前缀；/models 公开，不能用于验 Key
MiniMax JWT 形式（eyJ 开头） 付费（低价档） platform.minimaxi.com 模型 ID 未核实
阶跃星辰 无稳定前缀特征 付费（低价档） platform.stepfun.com Key 形状未核实，无法自动识别，需手动指定引擎
百度千帆 v2 bce-v3/ALTAK-… 有免费额度 console.bce.baidu.com/qianfan Key 形状未核实
腾讯混元 无稳定公开特征（可能为 sk-） hunyuan-lite 免费 console.cloud.tencent.com/hunyuan Key 形状未核实，需手动指定引擎
Google Gemini 未验证 AIzaSy 开头 有免费额度 aistudio.google.com/app/apikey 未验证（浏览器跨域可能受限）：CORS 未实测（沙箱网络受限），不得视为可用
Groq 未验证 gsk_ 开头 有免费额度 console.groq.com/keys 未验证（浏览器跨域可能受限）：CORS 未实测（沙箱网络受限），不得视为可用
Agnes AI 实测可用 sk- 开头 免费（agnes-3.0-flash） agnes-ai.com 已实测：/models 与 /chat/completions 均返回 Access-Control-Allow-Origin: *，浏览器可直连；agnes-3.0-flash 免费且支持 JSON 模式。Key 为 sk- 开头（与 DeepSeek 等共用），需探测消歧
ModelScope 魔搭 实测可用 ms- 开头 免费（每日 2000 次） modelscope.cn 已实测可跨域直连；模型 ID 为「组织/模型」形式（如 Qwen/Qwen3.8-Flash-Next）。注意：现有可用模型均为推理型，真实组词负载明显偏慢（实测 4 字约 100–120 秒），适合作为备用引擎
AMD Radeon Cloud 未实测 无稳定前缀 8 款 Public Free Model API —（Base URL 已内置：developer.amd.com.cn/radeon/api/v1） 免费模型最多的一家（GLM-5.3-Flash / Qwen3.8-27B / DeepSeek-V4-Flash-0731 / MiniCPM5-2B 等）。⚠ CORS 状态为 unverified（本机无 Key，未实测），因此不会进入「形状未知」时的自动扫描候选，需在 AI 控制台里手动指定引擎；官方共享端点按 Key + IP 限流，建议选轻量款
商汤 SenseNova 未实测 无稳定前缀 有低价档（计费未核实） —（Base URL 已内置：token.sensenova.cn/v1） 注册表按命名惯例把 *-flash-lite / *-lite 记为低价档、*-pro 记为付费，宁可低估（避免自动优选把付费模型当免费用）；无 /models 零 token 快路径，探测走 3 token 能力校验，需手动指定引擎
APINEX 实测不可用 sk-apx 开头 — apinex.bond 已实测：浏览器直连不可用——响应缺少 Access-Control-Allow-Origin（预检 204 亦无），真实 Chromium 中 fetch 直接失败；且账户提示余额不足。保留条目仅为让 sk-apx 形状被唯一识别并给出准确诊断，不参与自动优选
说明：「是否免费」依据注册表 tier 字段（free 永久免费 / cheap 免费额度或低价 / paid 付费）。标注「实测」的条目为 2026-09-18 以 curl + 真实 Chromium 跨域 fetch 双重验证的结论；标注「未实测」的两条（AMD Radeon Cloud / 商汤 SenseNova）是 v3.0.6 随注册表一并带入的，本机无 Key、未做过在线核实，其 CORS 状态如实记为 unverified 而不谎报 verified。其余模型 ID 多数未经在线核实，实际可用性以「🔍 检测全部 Key 可用性」的探测结果为准。这 18 家之外，你还可以在 AI 控制台里添加任意自定义引擎（见 3.6）。

讯飞星火未收录：实测其端点 OPTIONS 返回 403、POST 返回 401，且响应不带 Access-Control-Allow-Origin，浏览器直连不可用，故本应用刻意不支持。

为什么有的引擎「不可用」也保留条目：形状唯一的 Key（如 sk-apx）若不入表，会被 sk- 家族的旧前缀语义误判为 DeepSeek，从而发起一串注定 401 的探测。入表后应用能立刻识别归属并给出「可能是浏览器跨域(CORS)限制」的准确诊断。

3.2 多 Key 存储与自动选择

3.3 从文件导入 Key

3.4 自动识别与消歧（v3.0.4）

3.5 「🔍 检测全部 Key 可用性」（v3.0.4）

设置中心新增该按钮，逐个探测已保存的 Key 并显示徽章结果。探测分两阶段：

  1. 阶段 1（零 token）：GET /models 鉴权快路径 —— 仅对「该端点确实校验鉴权且带 CORS 头」的引擎启用，不消耗额度
  2. 阶段 2（3 token）：max_tokens: 3 的 chat 能力探测，校验应用真正要发送的那个模型 ID；若引擎不支持 response_format: json_object，会自动去掉该字段重试一次并降级记录。引擎拒绝 response_format 有两种方式，都会被处理：(1) 规范的 400/422 + 错误文本；(2) 不合规的 200 但响应体退化（如 {"choices":null}，实测 ModelScope 的 Qwen/Qwen3.8-Flash-Next 在 3 token 下即如此）—— 后者若不重试，会把真实可用的引擎误报为「走了代理或 baseUrl 配置错误」
徽章 含义
✓免费 探测成功，且使用的是免费档（tier: free）模型
✓可用 探测成功（付费 / 低价档模型）
⚠限流 HTTP 429，请求过于频繁；Key 仍然可用，不会被标记为失效
⚠不可达 网络或浏览器跨域（CORS）限制导致无法连接；文案会明确提示「可能是跨域限制」
✗Key无效 HTTP 401，Key 无效或已过期
✗额度耗尽 HTTP 402 / 403，额度不足或无该模型权限（歧义状态，不判定为 Key 无效）
✗模型不存在 HTTP 404，模型 ID 不存在或未开通，需在注册表中更换模型
说明：探测串行执行（并发 1），单个约 8 秒超时，裁决缓存 30 分钟；离线时跳过探测并保留上次结果。探测结果仅用于本地选择，不会上传。
自动优选的评分依据：0.30×免费度 + 0.20×速度 + 0.25×JSON稳定性 + 0.25×历史成功率 − 额度风险，并列时按「延迟升序 → 引擎优先级 → 创建时间」决胜。
关于「速度」的诚实说明：探测只有 3 token，对推理型模型毫无代表性——推理模型在 3 token 下秒回，真实组词负载下却会先生成大量 reasoning token。实测同一任务（4 字全量检查）：Agnes 约 13 秒，ModelScope 约 100–120 秒（约 8–9 倍），而两者探测延迟反而是 ModelScope 更快。因此注册表支持 slow 标记（仅对实测过的模型设置），标记后该项不再由失真的探测延迟给分，避免自动优选选中"探测快、实际慢"的引擎。

3.6 自定义引擎与「⚙ AI 控制台」（v3.0.6）

设置中心 AI 区顶部新增「⚙ AI 控制台（模型设置）」入口，旁边一行实时摘要显示「N 个 Key · M 个已配置引擎 · 共 18 个引擎可选」。控制台是双栏 master-detail：左侧引擎导航（已配置在前、内置在后，带状态点），右侧是该引擎的 Key 列表、模型列表与参数表单。

「＋ 添加供应商」可挂一个任意 OpenAI 兼容或 Anthropic 端点——注册表里没有的也能用：

字段 说明
API Key 必填；不得含空格，至少 8 位，否则当场拒绝（不会带着脏数据打到线上端点）
Base URL 必填，例如 https://your-gateway.example.com/v1；应用会拼接协议默认路径（openai → /chat/completions，anthropic → /v1/messages）。别把 chat 路径写进 Base URL——创建入口与体检入口共用同一份识别正则，创建时就会被拦下，避免出现「创建时说合法、体检时说非法」的自相矛盾
模型 ID 必填，至少一个；可加多个，其中标为「全量检查用」的会在深度校验时自动升档
协议 openai（Authorization: Bearer，system 走 messages 数组）或 anthropic（x-api-key + anthropic-version，system 是顶层字段、max_tokens 必填、响应体是 content[]、不接受 response_format）
请求参数 max_tokens / temperature / top_p 以及任意附加 JSON。可设置，也可留空用默认值——留空时按内置默认发（fast 2048 / 全量 4096 token，temperature 0.1），且不会发出非法字段

四、引擎路由与调用流程

  1. 引擎路由：默认「自动选择（推荐）」——系统探测并消歧后确定活跃 Key 所属引擎，优先免费且稳定的引擎；手动选中某个 Key 时按该 Key 固定路由，无需手动切换
  2. 分批处理：待处理汉字按每批 ≤10 字分组，逐批调用大模型 API，支持中断（运行中按钮变为「⏹ 中断」）
  3. 进度提示：状态栏显示蓝色旋转图标 + 批次进度（如「正在补齐 [DeepSeek]… 10/20 字（批次 1/2）」）
  4. 结果解读：完成后显示「✓ DeepSeek：共 X · 默认 X · AI X · 缺失 X（Xms）」；开启拼音纠错还会列出纠错明细（原拼音 → 纠正拼音 + 原因）
  5. 缓存机制：已写入 AI 缓存的字（ai_zuci_cache_v1）自动跳过，避免重复消耗；如需重查可执行 localStorage.removeItem("ai_zuci_cache_v1") 清缓存
  6. 概率属性：AI 回答具有概率性，少数情形一次未必能覆盖全部；多重复点击几次可逐步补齐 / 纠错全部
可靠性：5 分钟硬超时 + 3 次重试；错误码提示——401 无效 Key、403 无模型权限 / 额度耗尽、429 请求过频（等待 30 秒重试）。

五、安全与隐私（v3.0.6 起：默认不落盘）

5.1 四种保存方式，你自己选

在 AI 控制台里选「保存方式」，四档语义明确、互斥：

保存方式 Key 存哪 刷新后 关标签页后 安全性
不保存（默认） 只在内存 丢失 丢失 ★★★ 磁盘上什么都没有
记住到本标签页 镜像到 sessionStorage（ai_keys_session） 存活 丢失 ★★ 不出当前标签页
明文保存在本机 localStorage['ai_api_keys_plain'] 存活 存活 ★ 无口令，任何能在本页执行脚本的东西都能读走
长期记住（口令加密） localStorage['ai_api_keys_enc']，密文 {v,salt,iv,ct} 存活 存活 ★★★ PBKDF2(SHA-256, 200000 次迭代) 派生 AES-GCM-256 密钥，口令本身不落盘

选择「明文保存在本机」时界面会给出等价强度的警告——便利和安全在这里是直接对立的，应用不替你做决定，但会把代价说清楚。

5.2 旧数据的处理

5.3 不变的底线

建议：多用户共用电脑上请保持默认（不保存）；自己长期用的机器可选「长期记住 + 口令」；图省事选明文前，先想清楚这台机器还有谁能开这个浏览器。默认不落盘这条，是把「忘了自己存过 Key」这种最常见的泄露路径直接堵掉。

六、常见问题

Q1：Key 保存后显示「验证失败 / 401」？

先点「🔍 检测全部 Key 可用性」查看具体原因：✗Key无效 表示 Key 过期，✗额度耗尽 表示余额不足，⚠不可达 表示网络不通或浏览器跨域（CORS）受限。同时确认网络可访问对应引擎的 API 域名。

Q2：文件导入找不到 Key？

确保文件内容包含完整的 Key（形状见 3.1 表格，如 sk- / ark- / sk-or-v1- / AIzaSy / gsk_ 开头、前后无截断），支持多行 / 多 Key；docx 需含正文文本（解析 word/document.xml）。

Q3：如何切换当前生效的 Key？

默认使用「自动选择（推荐）」，无需手动切换；如需指定，≥2 个 Key 时在设置面板下拉中选中某个具体 Key 即固定为手动模式，重新选择「自动选择」即回到自动模式。删除活跃 Key 后自动切换到剩余第一个。

Q4：刷新页面后 Key 没了？

这是 v3.0.6 的默认行为（保存方式 = 不保存，只存内存）。想让它活下来：AI 控制台 → 保存方式 → 选「记住到本标签页」/「明文保存在本机」/「长期记住（口令加密）」之一。详见第五节。

Q5：如何删除已保存的 Key？

AI 控制台 → 选中引擎 → 该 Key 行点删除；或打开设置中心 → 点击 Key 展示框右侧 🗑 删除当前 Key。删掉活跃 Key 会自动切到剩下的第一个；删空则一并清空当前保存方式对应的存储键（ai_api_keys_plain / ai_api_keys_enc / ai_keys_session）。也可用浏览器开发者工具 → Application → Local Storage 手工清。

Q6：豆包报 403？

无该模型权限或额度耗尽，请更换模型（见 3.4 逃生门）或充值；全量检查使用的 Turbo 模型可能需单独开通权限。

Q7：怎么确认这把 Key「真的能用」，而不是只存下来了？

用 AI 控制台里的连通性体检（或设置面板的「🔍 检测全部 Key 可用性」）。它发的请求与真实组词调用形状完全一致——同样的端点、同样的鉴权头、同样的 response_format 处理，只是把 max_tokens 压到 3。因此只有真的拿到 chat completion 响应体才判「✓可用」；HTTP 200 但响应体是 HTML（典型是走了代理或 Base URL 配错）会被判为不可用，不会拿 200 糊弄你。