From 6f464eb6dd9b5e72c8cbe28e5fd94b7a40495e80 Mon Sep 17 00:00:00 2001 From: phamnazage-jpg Date: Fri, 22 May 2026 07:43:42 +0800 Subject: [PATCH] docs: add provider validation matrix --- README.md | 1 + docs/PROVIDER_ONBOARDING_PLAYBOOK.md | 2 + docs/PROVIDER_VALIDATION_MATRIX.md | 249 +++++++++++++++++++++++++++ docs/SOURCE_OF_TRUTH.md | 18 +- 4 files changed, 266 insertions(+), 4 deletions(-) create mode 100644 docs/PROVIDER_VALIDATION_MATRIX.md diff --git a/README.md b/README.md index aa7916bb..0a55a94f 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,7 @@ sub2api-cn-relay-manager/ - [docs/EXECUTION_BOARD.md](./docs/EXECUTION_BOARD.md) —— 当前执行状态、最新 gate、剩余阻断 - [docs/PRODUCTION_CLOSURE_BOARD.md](./docs/PRODUCTION_CLOSURE_BOARD.md) —— 当前是否可按 PRD 首版范围放行 - [docs/PROVIDER_ONBOARDING_PLAYBOOK.md](./docs/PROVIDER_ONBOARDING_PLAYBOOK.md) —— 新增 provider、宿主版本变更后重验、稳定导入与快速诊断的完整作业手册 +- [docs/PROVIDER_VALIDATION_MATRIX.md](./docs/PROVIDER_VALIDATION_MATRIX.md) —— 官方 provider 模板覆盖度、key 覆盖度、live 验收进度矩阵 - [docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md](./docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md) —— 真实宿主验收标准步骤 - [docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md](./docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md) —— 已调通细节、典型误判点、诊断顺序 diff --git a/docs/PROVIDER_ONBOARDING_PLAYBOOK.md b/docs/PROVIDER_ONBOARDING_PLAYBOOK.md index 3017d6fd..9e9a6923 100644 --- a/docs/PROVIDER_ONBOARDING_PLAYBOOK.md +++ b/docs/PROVIDER_ONBOARDING_PLAYBOOK.md @@ -15,6 +15,8 @@ - `docs/SOURCE_OF_TRUTH.md` - 回答“当前最新真相是什么” +- `docs/PROVIDER_VALIDATION_MATRIX.md` + - 回答“哪些 provider 已有模板、哪些已有官方 key、哪些已经完成 live 验收” - `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md` - 回答“标准真实宿主验收怎么跑” - `docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md` diff --git a/docs/PROVIDER_VALIDATION_MATRIX.md b/docs/PROVIDER_VALIDATION_MATRIX.md new file mode 100644 index 00000000..626a8826 --- /dev/null +++ b/docs/PROVIDER_VALIDATION_MATRIX.md @@ -0,0 +1,249 @@ +# Provider Validation Matrix + +日期：2026-05-22 + +## 目的 + +这份文档用于回答 4 个问题： + +1. 当前仓库已经内置了哪些官方 provider 模板 +2. 哪些 provider 已经具备本机可用的官方 key +3. 哪些 provider 已经完成了真实 fresh-host live 验收 +4. 哪些 provider 仍然卡在缺 key、缺模板或上游 quota / rate-limit + +它不是 gate 文档，也不替代 `REAL_HOST_ACCEPTANCE_RUNBOOK.md`。 + +分工如下： + +- `docs/SOURCE_OF_TRUTH.md` + - 回答当前项目整体 gate +- 本文 + - 回答 provider 维度的模板覆盖度、凭据覆盖度、live 验收覆盖度 +- `docs/PROVIDER_ONBOARDING_PLAYBOOK.md` + - 回答后续如何继续补模板和验收 + +## 阅读结论 + +先说结论： + +1. **首批 10 个官方 provider 模板已经落库** + - 当前 `openai-cn-pack` 已内置 Qwen、DeepSeek、GLM、Kimi、MiniMax、Step 的 10 个官方模板 + +2. **还不能宣称“国内 10 大模型都已逐个真实验证通过”** + - 当前最大的阻断不是控制面代码，而是 **官方 key 不齐** + - 其次是部分官方 key 即便存在，也会在真实 completion 阶段命中 `429 quota/rate-limit` + +3. **当前真正已跑过 official live 验收的只有 MiniMax 官方模板** + - 结果不是控制面错误，而是 upstream `429` + - 这证明模板、models 暴露、导入链路都已接通，但当前 key 不具备稳定 completion 验收能力 + +4. **Qwen / GLM / Step / Kimi 官方路线当前没有本机可用官方 key 证据** + - 所以它们目前只能算“模板已就绪，未完成 live 验收” + +## 统计口径 + +### 状态定义 + +- `模板已就绪` + - `packs/openai-cn-pack/providers/*.json` 已存在 + - `checksums.txt` 已更新 + - `internal/pack` 回归已通过 + +- `官方 key 已就绪` + - 本机可确认存在该厂商官方环境变量或等价安全存储引用 + - 不等于 key 一定有足够额度 + +- `live 验收已完成` + - 已在真实 fresh-host 上跑过 provider 级 artifact + +- `PASS` + - host `/v1/models` 与 `/v1/chat/completions` 均通过 + - upstream `/chat/completions` 也通过 + +- `BLOCKED_BY_KEY` + - 没有官方 key，无法开始 live 验收 + +- `BLOCKED_BY_QUOTA` + - 有 key，但 upstream 或 host completion 命中 `429/403` 等额度问题 + +## A. 已内置的 10 个官方 provider 模板 + +| 分类 | provider_id | 官方 base_url | smoke_test_model | 模板状态 | 本机官方 key | live 验收状态 | 当前结论 | +|---|---|---|---|---|---|---|---| +| 通义千问 | `qwen-official` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-plus` | 已就绪 | 未发现 `DASHSCOPE_API_KEY` | 未开始 | `BLOCKED_BY_KEY` | +| 通义千问 Coder | `qwen-coder-official` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen3-coder-plus` | 已就绪 | 未发现 `DASHSCOPE_API_KEY` | 未开始 | `BLOCKED_BY_KEY` | +| DeepSeek Chat | `deepseek-chat-official` | `https://api.deepseek.com/v1` | `deepseek-chat` | 已就绪 | 未发现官方 DeepSeek key；仅有中转 key | 未开始 | `BLOCKED_BY_KEY` | +| DeepSeek Reasoner | `deepseek-reasoner-official` | `https://api.deepseek.com/v1` | `deepseek-reasoner` | 已就绪 | 未发现官方 DeepSeek key；仅有中转 key | 未开始 | `BLOCKED_BY_KEY` | +| 智谱 GLM 5.1 | `glm-5-1-official` | `https://open.bigmodel.cn/api/paas/v4` | `glm-5.1` | 已就绪 | 未发现 `ZHIPU_API_KEY`/`BIGMODEL_API_KEY` | 未开始 | `BLOCKED_BY_KEY` | +| 智谱 GLM 4.7 | `glm-4-7-official` | `https://open.bigmodel.cn/api/paas/v4` | `glm-4.7` | 已就绪 | 未发现 `ZHIPU_API_KEY`/`BIGMODEL_API_KEY` | 未开始 | `BLOCKED_BY_KEY` | +| Kimi K2.5 | `kimi-k2-5-official` | `https://api.moonshot.cn/v1` | `kimi-k2.5` | 已就绪 | 未发现 `MOONSHOT_API_KEY`；仅有中转 `XUANSUAN_KIMI_API_KEY` | 未开始 | `BLOCKED_BY_KEY` | +| Kimi K2 Thinking | `kimi-k2-thinking-official` | `https://api.moonshot.cn/v1` | `kimi-k2-thinking` | 已就绪 | 未发现 `MOONSHOT_API_KEY`；仅有中转 `XUANSUAN_KIMI_API_KEY` | 未开始 | `BLOCKED_BY_KEY` | +| MiniMax M2.7 | `minimax-m2-7-official` | `https://api.minimaxi.com/v1` | `MiniMax-M2.7-highspeed` | 已就绪 | 已发现 `MINIMAX_CN_API_KEY` | 已完成 | `BLOCKED_BY_QUOTA` | +| Step 3.5 Flash | `step-3-5-flash-official` | `https://api.stepfun.com/v1` | `step-3.5-flash` | 已就绪 | 未发现 `STEP_API_KEY` | 未开始 | `BLOCKED_BY_KEY` | + +## B. 官方模板外的优先扩展厂商 + +这些更接近你说的“六小龙 + BAT + 小米等”的完整矩阵，但当前仓库里还没有正式 provider 模板，或者没有本机 key： + +| 厂商/路线 | 当前模板状态 | 当前 key 状态 | 建议动作 | +|---|---|---|---| +| 腾讯混元官方 | 未落模板 | 未发现官方 key | 先补模板，再补 `HUNYUAN` / 腾讯云对应 key | +| 豆包 / 火山方舟官方 | 未落模板 | 未发现官方 key | 先补模板，再补 `ARK` / `VOLCENGINE_API_KEY` | +| 百川官方 | 未落模板 | 未发现官方 key | 先补模板，再补官方 key | +| 零一万物 Yi 官方 | 未落模板 | 未发现官方 key | 先补模板，再补官方 key | +| 小米 MiMo 官方 | 未落模板 | 未发现 `XIAOMI_API_KEY` | 先补模板，再补官方 key | + +说明： + +- 当前这批未落模板厂商，不代表项目不支持 +- 只代表这轮仓库里还没有为它们建立正式 provider manifest +- 一旦补模板，后续导入路径仍然可以复用当前 pack 驱动模式 + +## C. 当前已确认的本机凭据盘点 + +### 已确认存在的厂商环境变量 + +从当前本机配置里能确认到这些变量名： + +- `MINIMAX_CN_API_KEY` +- `MINIMAX_API_KEY` +- `MINIMAX_ZHONGZHUAN_API_KEY` +- `MINIMAX_53HK_API_KEY` +- `XUANSUAN_KIMI_API_KEY` +- `DEEPSEEK_API_KEY` +- `DEEPSEEK_2166_API_KEY` + +### 只能说明什么 + +它们只能说明： + +1. 本机至少存在 MiniMax / Kimi 中转 / DeepSeek 中转路线 +2. 不代表对应**官方** provider 已有可跑 live 的 key + +### 当前缺失的官方 key 信号 + +当前没有在本机配置中确认到这些官方变量名： + +- `DASHSCOPE_API_KEY` +- `MOONSHOT_API_KEY` +- `ZHIPU_API_KEY` +- `BIGMODEL_API_KEY` +- `STEP_API_KEY` +- `XIAOMI_API_KEY` +- `VOLCENGINE_API_KEY` + +这也是为什么这轮不能把“Qwen/GLM/Step/Kimi 官方路线”都逐个跑完。 + +## D. 已完成的 official live 验收 + +### MiniMax 官方 + +本轮已实际执行： + +- provider：`minimax-m2-7-official` +- artifact： + - `artifacts/real-host-acceptance/20260521_222212_remote43_minimax-m2-7-official_key_import` + +关键结论： + +1. host `/v1/models` 已通过，且命中预期模型 +2. upstream `/models` 也能返回预期官方模型集合 +3. host `/v1/chat/completions` 返回 `429` +4. upstream `/chat/completions` 同样返回 `429` + +所以根因不是控制面导入失败，而是： + +- 当前官方 MiniMax key 命中 upstream 真实限流/额度问题 + +证据： + +- [21-summary.json](/home/long/project/sub2api-cn-relay-manager/artifacts/real-host-acceptance/20260521_222212_remote43_minimax-m2-7-official_key_import/21-summary.json:1) +- [11-chat.headers.txt](/home/long/project/sub2api-cn-relay-manager/artifacts/real-host-acceptance/20260521_222212_remote43_minimax-m2-7-official_key_import/11-chat.headers.txt:1) +- [19-upstream-chat.headers.txt](/home/long/project/sub2api-cn-relay-manager/artifacts/real-host-acceptance/20260521_222212_remote43_minimax-m2-7-official_key_import/19-upstream-chat.headers.txt:1) + +补充说明： + +- 同一批次中还暴露了 fresh-host 环境补前置时的历史噪音： + - `api_keys.group_id_fkey` 触发失效 group 外键 + - 但最终 summary 已经足够说明真正的 provider-level 主阻断是 `429` +- 因此这轮应归类为： + - 模板就绪 + - official key 存在 + - live 验收已开始并已拿到真实结论 + - 当前状态：`BLOCKED_BY_QUOTA` + +## E. 为什么 Qwen 还没法“直接宣称已验证通过” + +`qwen-official` 模板已经存在，后续导入命令也已经标准化；但当前仍缺一条关键前提： + +- 本机没有确认到可用的 `DASHSCOPE_API_KEY` + +因此 Qwen 当前状态只能写成： + +- 模板：已就绪 +- 一键导入入口：已就绪 +- 官方 live 验收：未开始 +- 阻断：`BLOCKED_BY_KEY` + +这和“控制面不支持 Qwen”不是一回事。 + +## F. 推荐执行顺序 + +如果目标是把“六小龙 + BAT + 小米等”逐个真实收口，建议按下面顺序继续： + +1. 先补官方 key + - `DASHSCOPE_API_KEY` + - `MOONSHOT_API_KEY` + - `ZHIPU_API_KEY` 或 `BIGMODEL_API_KEY` + - `STEP_API_KEY` + - `VOLCENGINE_API_KEY` + - `XIAOMI_API_KEY` + +2. 先跑已经有模板的 10 个 provider + - 先补齐模板内的 official 路线 + - 再扩厂商模板 + +3. 优先顺序建议 + - Qwen 官方 + - Kimi 官方 + - GLM 官方 + - Step 官方 + - DeepSeek 官方 + - MiniMax 官方复验（换一把非限流 key） + +4. 第二梯队扩模板 + - 腾讯混元 + - 豆包 / 火山方舟 + - 百川 + - Yi + - 小米 MiMo + +## G. 当前最短闭环 + +如果你要最快把这份矩阵往前推进一格，最有效的不是继续改代码，而是： + +1. 给我 `DASHSCOPE_API_KEY` + - 我先把 `qwen-official` 跑成第一条 Qwen 官方 live artifact + +2. 再给我 `MOONSHOT_API_KEY` 与 `ZHIPU_API_KEY` + - 我可以继续把 Kimi / GLM 官方路线逐个跑出来 + +3. 对 MiniMax 官方 + - 当前不需要改模板 + - 只需要换一把有真实 completion 配额的 key 再复验 + +## H. 一句话结论 + +当前仓库已经进入： + +- **“官方 provider 模板成批就绪”** 阶段 + +但还没有进入： + +- **“国内主流官方模型已逐个 live 验收通过”** 阶段 + +剩余主阻断是： + +1. 官方 key 不齐 +2. 个别官方 key 有真实 quota / rate-limit 限制 +3. 第二梯队厂商模板尚未补齐 diff --git a/docs/SOURCE_OF_TRUTH.md b/docs/SOURCE_OF_TRUTH.md index b73c678b..346d0a0e 100644 --- a/docs/SOURCE_OF_TRUTH.md +++ b/docs/SOURCE_OF_TRUTH.md @@ -68,7 +68,16 @@ - 它定义“后续怎么稳定地继续加 provider / 复验宿主” - 不直接决定当前 gate，但决定后续变更能否低风险复用 -### 5. `docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md` +### 5. `docs/PROVIDER_VALIDATION_MATRIX.md` +用途： +- 按 provider 维度跟踪“模板是否已就绪 / 官方 key 是否存在 / live 验收是否已完成” +- 给后续“六小龙 + BAT + 小米等”模型矩阵扩展提供同一口径 + +解释规则： +- 它不直接改变项目整体 gate +- 但它是当前 provider 覆盖度和验证进度的第一来源 + +### 6. `docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md` 用途： - 已调通的细节 - 高频误判点 @@ -179,9 +188,10 @@ ### 想继续做真实宿主验收 1. `docs/SOURCE_OF_TRUTH.md` 2. `docs/PROVIDER_ONBOARDING_PLAYBOOK.md` -3. `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md` -4. `docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md` -5. 再看最新 artifact +3. `docs/PROVIDER_VALIDATION_MATRIX.md` +4. `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md` +5. `docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md` +6. 再看最新 artifact ### 想回顾为什么会演化成现在这样 1. `docs/SOURCE_OF_TRUTH.md`