niuniu/sub2api-cn-relay-manager
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
af2c77d40be867e930ac76a2e7163fa91223a381
sub2api-cn-relay-manager/docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md

26 KiB
Raw Blame History

真实宿主验收经验与已调通细节

日期：2026-05-21

目的

这份文档不替代 docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md，而是把已经在线下真实打通过、以及多次踩坑后确认的细节沉淀下来，避免后续重复误判。

建议阅读顺序：

  1. docs/EXECUTION_BOARD.md —— 看当前 gate 与最新真相
  2. docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md —— 看标准执行步骤
  3. 本文 —— 看调试经验、误判点、诊断顺序

已经确认打通的事实

  1. account 视角模型暴露可以正确落库

    • CRM 在 account 创建/导入时写入 credentials.model_mapping
    • 宿主 GET /api/v1/admin/accounts/:id/models 已能返回目标 provider 模型，而不是一律回退到 GPT 默认集合
    • DeepSeek / MiniMax 都已在 live 验收中确认

  2. channel 视角模型映射与定价可以正确落库

    • channel 创建时需要同时下发：
      • model_mapping
      • model_pricing
      • restrict_models=true
      • billing_model_source=channel_mapped
    • 对既有 channel，CRM 需要走 UpdateChannel 做纠偏；这一点已在 latest-head fresh rerun 上确认生效
    • 旧现象“MiniMax channel 有 model_mapping 但没有 pricing”已经被 ca1d448 修复并完成 live 验证

  3. subscription 场景的真实 probe key 语义已经确认

    • closure 最终用于宿主 /v1/models 探测的，不是外部传入的原始 access_api_key
    • 真正使用的是 CRM 在宿主侧创建/查找出来的 managed key（sk-relay-* 风格）
    • 因此 subscription 验收如果直接拿调用方原始 probe key 去打 /v1/models，出现 403 not assigned to any group 并不代表 CRM 主链路失败，而是 probe key 用错了

  4. self_service 场景的 gateway probe 认证语义已经确认

    • 真实宿主的普通用户 gateway key 访问 /v1/models / /v1/chat/completions 时，使用的是 Authorization: Bearer <gateway-key>
    • 不能把这条普通用户 gateway key 当成宿主管理 API key 再塞进 x-api-key
    • latest-head 最后一个真实阻断就是这里：CRM 的 CheckGatewayAccess / CheckGatewayCompletion 之前错误地把 self_service 的普通用户 key 放进了 x-api-key
    • 修复后，latest-head self_service 标准 fresh-host 验收 artifacts/real-host-acceptance/20260521_210403 已真实收口到 self_service_ready

  5. group 聚合视角与 account 单体视角必须分开看

    • GET /api/v1/admin/accounts/:id/models 是 account 单体视角
    • GET /v1/models 是普通用户 key + group 聚合视角
    • 二者语义不同，不能互相替代
    • 正确诊断顺序应该是：
      1. 先看 account models 是否正确
      2. 再看 managed key 视角 /v1/models 是否正确
      3. 最后才看 completion smoke 是否通过

宿主源码再次确认的设计逻辑

这部分不是基于 artifact 推断，而是直接对照 sub2api-official-fresh 宿主源码确认：

  1. channel admin handler 的真实入参契约

    • backend/internal/handler/admin/channel_handler.go
    • model_mapping 的真实结构是 map[string]map[string]string
    • model_pricing 是独立数组字段，不会从 model_mapping 自动推导
    • billing_model_source 合法值包括 channel_mapped
    • restrict_models 是独立布尔开关

  2. channel pricing platform 为空时，宿主会回退到 anthropic

    • create/update handler 都会在入参 platform 为空时补默认值
    • repository createModelPricingExec 也会把空 platform 写成 anthropic
    • 这意味着 CRM 若不给 OpenAI-compatible provider 显式写 platform，宿主会按 anthropic 语义处理，不能接受
    • 因此 CRM 当前策略必须是：
      1. 先用 provider platform
      2. 若调用侧仍为空，再回退 openai

  3. gateway /v1/models 与 completion 共享同一套 API key middleware 前置校验

    • backend/internal/server/middleware/api_key_auth.go
    • 它先校验：
      • key 有效
      • user active
      • IP 限制
      • group / subscription / balance 前置
    • 所以 /v1/models 的 403/429 通常首先反映的是 key/group/subscription/balance 约束，而不等同于 account/channel 落库失败

  4. subscription group 的 key 绑定条件与 standard group 不同

    • backend/internal/service/api_key_service.go
    • standard group：走 user.CanBindGroup(...)
    • subscription group：走 GetActiveByUserIDAndGroupID(...)
    • 也就是说，subscription 场景里“group 已存在”或“allowed_groups 已写入”都不够，必须有 active subscription

  5. user 自助创建 key 与 admin 绑定 group 是两步

    • backend/internal/handler/api_key_handler.go + api_key_service.go
    • user 侧 POST /api/v1/api-keys 可创建带 custom_key 的 key
    • CRM managed key 流程里，先以普通用户身份创建 key，再用 admin PUT /api/v1/admin/api-keys/:id 绑定 group
    • 这与我们当前 EnsureSubscriptionAccess 的两阶段实现一致

已调通的宿主侧前置动作

self_service

至少满足：

  1. 普通用户已真实创建
  2. 普通用户 key 已生成且可用
  3. 该 key 已绑定目标标准 group
  4. 用户具备可用余额

经验结论：

  • 若只做了 key/group 绑定但没余额，/v1/models 可能从 403 进入 INSUFFICIENT_BALANCE
  • 这不是 CRM 导入逻辑失败，而是宿主运营前置未完成
  • 若普通用户 key 直打宿主 /v1/models / /v1/chat/completions 已经 200，但 CRM 的 self_service closure 仍显示 401/403 broken，优先检查 CRM 的 gateway probe 是否错误地复用了 x-api-key 语义，而不是先怀疑宿主前置

subscription

至少满足：

  1. 普通用户已真实创建
  2. 普通用户 key 已生成且可用
  3. 目标 group 是 subscription 类型
  4. 普通用户已完成 subscription 分配
  5. 普通用户 key 已绑定该 subscription group

经验结论：

  • 只有管理员主体、只有 group、或者只有 subscription 记录都不够
  • 必须把“普通用户 + key + group + subscription”整条链补齐，/v1/models 才会稳定通过

已确认的高频误判点

  1. 把 /accounts/:id/models 和 /v1/models 混为一谈

    • 前者对，后者错，不代表 account 落库失败；往往是 key/group/subscription 问题

  2. 用错 probe key

    • subscription 场景拿原始 access_api_key 直打宿主 /v1/models，很容易得到 403
    • 这时应先回到 closure 结果或 managed access 证据，而不是先否定产品链路

  3. 旧 CRM 进程误导当前结论

    • live 行为必须先确认运行中的 CRM 进程是否真的包含最新提交
    • 之前 MiniMax existing channel 没自动补 model_pricing，最终确认根因就是在线 CRM 进程早于修复提交 ca1d448
    • 如果看到“有 model_mapping 但 model_pricing=[]”，不要立刻判定 current-code 仍未执行 UpdateChannel；先核对该 artifact 是否本来就是旧进程产物

MiniMax model_pricing=[] 误判的已确认根因时间线

  1. 旧进程先创建了半成品 channel

    • 证据：artifacts/real-host-acceptance/20260520_222713_crm18100_live_model_mapping_validation/summary.json
    • 其中 MiniMax host_channel.data.id=5
    • model_mapping 已有值，但 model_pricing=[]
    • 且 created_at=updated_at=2026-05-20T20:39:23Z
    • 这说明当时只是旧逻辑创建了 channel，没有发生后续 UpdateChannel 纠偏

  2. 新代码已经具备纠偏能力，但必须由新进程实际执行

    • ca1d448 之后，代码路径已改为：
      • 新建 channel 时直接携带完整 model_pricing
      • 命中既有 channel 时执行 UpdateChannel
    • 所以判断“修复是否生效”时，不能只看仓库 HEAD，必须看 18100 监听进程的真实启动时间与实际 DB

  3. 当前 18100 新进程已在 live host 上完成纠偏

    • 18100 新进程启动时间：2026-05-21 01:08
    • 当前真实 DB：/tmp/sub2api-relay-manager-realhost-18100.db
    • 当前 host admin 直查 GET /api/v1/admin/channels/5 可见：
      • model_pricing 非空
      • model_mapping 仍正确
      • updated_at=2026-05-21T06:45:00Z
    • 这证明新进程已经真正执行过 UpdateChannel，MiniMax 既有 channel 已被纠偏

  4. 最终结论

    • “MiniMax channel 有 mapping 但无 pricing”不是 current-code 仍缺失 UpdateChannel
    • 真相是：旧 artifact 反映的是旧 CRM 进程产物；切到新进程并 fresh rerun 后，该问题已被 live 修复

  5. PACK_PATH 使用了 operator 机器的概念路径，而不是 CRM 进程本机可读路径

    • 当 CRM 改在本机运行时，继续传远端 /home/ubuntu/... 会直接触发 stat pack path ... no such file or directory
    • 这个报错属于验收 harness / 环境参数问题，不是 import 业务逻辑问题

  6. remote43/fresh-host 的 Postgres/Redis 容器目标写错

    • 若脚本仍打到旧 relaymgr 宿主，会看到 managed user / key / subscription 状态为空或串台
    • 需要确保脚本明确指向 fresh host 对应的 {postgres,redis} 容器

  7. fresh-host bearer token 过期时，最前面的 host 注册/探测也会伪装成 CRM 侧 502

    • latest-head self_service 收尾时，脚本最前面的 POST /api/hosts 曾直接返回 502
    • 继续往里看，upstream detail 才显示 TOKEN_EXPIRED
    • 这类现象不要先误判成 CRM 新代码挂了；应先刷新 fresh-host 管理员 bearer token，再继续验收

  8. 把 /v1/models 已通误认为 completion 也一定通

    • 这不成立
    • 当前最新真相就是：DeepSeek / MiniMax 的 /v1/models 可以 200，但 /v1/chat/completions 仍可能因为 host 兼容性或上游 quota 问题失败

推荐诊断顺序

一、先确认是不是环境/脚本问题

  1. 确认当前运行 CRM 的提交版本与启动时间
  2. 确认 PACK_PATH 是 CRM 本机可读路径
  3. 确认 CRM_HOST_BASE 是否与实际 CRM 到 host 的可达地址一致
  4. 确认脚本命中的 Postgres/Redis 容器属于目标 fresh host，而不是旧环境

二、再确认导入数据是否正确写入宿主

  1. account
    • GET /api/v1/admin/accounts/:id
    • 看 credentials.model_mapping
  2. account models
    • GET /api/v1/admin/accounts/:id/models
  3. channel
    • GET /api/v1/admin/channels/:id
    • 看：
      • model_mapping
      • model_pricing
      • restrict_models
      • billing_model_source

三、最后再确认普通用户访问链路

  1. self_service：看普通用户 key/group/balance
  2. subscription：看 managed key / allowed_groups / user_subscriptions
  3. 宿主 /v1/models
  4. 宿主 /v1/chat/completions

如何解释常见现象

现象 A：/accounts/:id/models 正确，但 /v1/models 返回 403

优先判断：

  • 普通用户 key 没绑定 group
  • subscription 场景用错了原始 probe key
  • subscription 分配或 allowed_groups 未完成

现象 B：/v1/models 返回 GPT 系模型，而不是目标国产模型

优先判断：

  • account credentials.model_mapping 是否落库
  • channel 是否同时具备 model_mapping + model_pricing + restrict_models + billing_model_source=channel_mapped
  • 是否误打到了旧 CRM 进程

现象 C：/v1/models 已 200，但 /v1/chat/completions 失败

优先判断：

  • host provider 兼容性
  • 上游 key/quota
  • 不要先回退归因为 CRM 导入失败

现象 D：普通用户 key 直打宿主 /v1/models 与 /v1/chat/completions 都是 200，但 CRM 的 self_service access/status 仍是 broken

优先判断：

  • CRM 的 gateway probe 是否错误使用了 x-api-key 而不是 Authorization: Bearer
  • 当前 online CRM 进程是否真的已经切到包含该修复的新二进制

进一步缩圈：DeepSeek chat/completions 当前更像宿主兼容层问题，而不是 key 失效

2026-05-21 新增的直接证据链：

  1. managed key 直打 fresh host 仍稳定失败

    • http://127.0.0.1:18097/v1/models = HTTP 200
    • http://127.0.0.1:18097/v1/chat/completions = HTTP 502
    • 说明普通用户 / subscription / key / group 绑定链路不是这一步的主阻断

  2. 同一台 remote43 主机直打 upstream 反而成功

    • 对 https://aitoken.quanfuli.cn/v1/chat/completions
    • 使用同一 upstream key、同一 deepseek-v4-flash payload
    • 返回 HTTP 200
    • 但响应 Content-Type 是 text/event-stream

  3. fresh-host app 日志显示 host chat 会在一组重复 DeepSeek accounts 间 failover，全部记成 account_upstream_error 500/502

    • 当前 group 5 里有 10 个 active DeepSeek accounts：14,15,16,17,19,20,23,25,26,28
    • 它们 credentials.api_key/base_url/model_mapping 相同
    • 请求并不是命中一个固定坏 account，而是在重复 account 集合中轮流失败

当前最合理的解释：

  • DeepSeek 这条 completion 阻断已经缩到“宿主 chat 上游兼容/解析层”
  • 不是 CRM 没把模型、channel、subscription、managed key 准备好
  • 重复 account 不是唯一根因，但会把一次失败放大成整组 failover 噪音，增加生产不稳定性

进一步缩圈：MiniMax 当前是 quota 阻断，不是 CRM 路由阻断

  1. managed key 视角 /v1/models 已 200
  2. upstream 直探 /chat/completions = 403 insufficient_user_quota
  3. fresh-host group 6 内 6 个 active MiniMax accounts 的 temp_unschedulable_reason 都明确记录了 insufficient_user_quota

因此：

  • MiniMax 当前要解的是“换可用 key / 补额度”
  • 不应继续把它归因为 CRM import/access 逻辑失败

当前建议固化到后续文档/脚本的规则

  1. 所有真实宿主验收结论都要同时记录：

    • account 视角结果
    • managed key 视角 /v1/models 结果
    • completion smoke 结果

  2. 任何“MiniMax/DeepSeek 没生效”的结论前，必须先检查在线 CRM 是否为最新提交

  3. 任何 subscription 验收脚本都不应默认把外部 access_api_key 当最终 probe key

  4. 任何 fresh-host 验收脚本都必须参数化：

    • PACK_PATH
    • CRM_HOST_BASE
    • 目标 Postgres 容器
    • 目标 Redis 容器

  5. latest-head self_service 验收通过后，如果 reconcile 仍是 drifted，应优先把它解释为 shared fresh-host 的历史残留资源噪音，而不是主链路未打通；判断时先看 05-import.json / 07-access-status.json 的 ready 结果，再看 09-reconcile.json 的 summary.access_status

凭据与可用性判断矩阵

先记住：本项目里最容易混淆的不是 API 本身，而是“看起来都像 key，但其实职责完全不同”的几类凭据。

凭据/身份 属于谁 主要用途 正确验证方式 不能直接证明什么 最常见误判
供应链 key / 上游 key 供应商账号 / 中转账号 写入 host account credentials.api_key，供宿主向上游 provider 发请求 1. account 创建成功 2. POST /api/v1/admin/accounts/:id/test 成功 3. GET /api/v1/admin/accounts/:id/models 返回目标模型 不能直接证明普通用户一定能看到模型，也不能直接证明 /v1/chat/completions 一定可用 把 account /test 成功误说成“普通用户已可用”
普通用户 key 宿主普通用户 走宿主网关访问 /v1/models、/v1/chat/completions 1. key/group 绑定正确 2. GET /v1/models 返回目标模型 3. 推荐继续测 /v1/chat/completions 不能直接证明供应链 account 本身健康 把普通用户 403 直接归因为供应链 key 无效
subscription 原始外部 ACCESS_API_KEY 调用方传入的外部 probe key subscription 请求输入，可能只用于触发流程，不一定是最终探测 key 不能单独用它判断最终 gateway closure；必须先确认是否被 managed key 覆盖 不能直接代表最终 subscription 场景的普通用户访问结果 拿它直打 /v1/models 收到 403，就误判 CRM 主链路失败
managed key (sk-relay-*) CRM 在宿主侧创建/查找的托管普通用户 key subscription 场景最终 gateway probe / managed 普通用户访问 1. managed user / key 已创建 2. group/subscription 已绑定 3. GET /v1/models 返回目标模型 4. 推荐继续测 /v1/chat/completions 不能直接证明上游 provider 一定有 quota 或 host completion 一定兼容 把它和外部原始 ACCESS_API_KEY 混为一谈
host admin token / bearer 宿主管理员 创建 group/channel/plan/account、分配 subscription、读取 admin API 看 admin API 是否能成功执行管理动作 不能直接证明普通用户访问已可用 以为“管理接口全成功 = 普通用户链路也成功”

一眼区分规则

  1. 供应链 key
    • 验证的是“上游供应商 account 是否健康”
    • 不直接验证普通用户访问
  2. 普通用户 key
    • 验证的是“宿主网关路径是否对普通用户开放”
    • 不直接验证上游供应链是否健康
  3. subscription 原始外部 key
    • 只是一种流程输入
    • 不一定等于最终探测 key
  4. managed key
    • 才是 subscription 场景里更接近“最终真实普通用户访问”的 key
  5. admin token
    • 只证明管理面可用
    • 不证明用户面可用

两套最小判断口径

口径 A：供应链账号是否成功

看：

  1. account 是否创建成功
  2. /api/v1/admin/accounts/:id/test 是否成功
  3. /api/v1/admin/accounts/:id/models 是否返回目标模型

口径 B：普通用户是否真的可用

看：

  1. key/group/subscription/balance 前置是否到位
  2. /v1/models 是否返回目标模型
  3. /v1/chat/completions 是否成功

明确禁止的混用

  • ❌ 用 account /test 成功替代普通用户 /v1/models
  • ❌ 用 /v1/models 成功替代 /v1/chat/completions
  • ❌ 用外部原始 ACCESS_API_KEY 替代 subscription managed key
  • ❌ 用 admin API 成功替代普通用户链路成功
  • ❌ 看到普通用户 403 就直接判定供应链 key 不可用

FAQ：新增模型 / 新增供应链账号 / 普通用户访问

1. “新增模型参数”到底指什么？

这里至少分四层，不能混成一句“模型加上了”：

  1. pack/provider 定义层
    • base_url
    • default_models
    • smoke_test_model
    • channel_template.model_mapping
  2. host 落库层
    • account credentials.model_mapping
    • channel model_mapping
    • channel model_pricing
    • restrict_models
    • billing_model_source
  3. 模型暴露层
    • GET /api/v1/admin/accounts/:id/models
    • GET /v1/models
  4. completion 层
    • POST /v1/chat/completions

经验结论：

  • 前三层正确，不等于第四层一定正确
  • 当前项目最新真相就是：模型暴露层大体已经打通，但 completion 层仍可能受 host 兼容性或上游 quota 影响

2. “新增供应链账号成功”到底以什么为准？

建议区分三档成功标准：

  1. 窄口径成功（只看供应链 account）
    • account 创建成功
    • POST /api/v1/admin/accounts/:id/test 成功
    • GET /api/v1/admin/accounts/:id/models 返回目标模型
  2. 完整接入成功（看普通用户是否能看到模型）
    • 上述 account 条件成立
    • 普通用户或 managed key 的 GET /v1/models 返回目标模型
  3. 业务可用成功（看真实调用）
    • 上述条件都成立
    • POST /v1/chat/completions 成功

经验结论：

  • 如果你只说“供应链账号成功”，默认最多只能代表前两档
  • 如果要说“模型完全可用”，必须把 completion smoke 也过掉

3. 新增供应链账号时，系统会不会自动补 group / channel / plan？

会，但要分资源类型看：

  1. group
    • 一定会先 ensure
    • 不存在就创建，存在就复用
  2. channel
    • 一定会先 ensure
    • 不存在就创建，存在就 UpdateChannel 纠偏
  3. plan
    • 只在 subscription 模式下需要
    • 不存在就创建，存在就复用
  4. account
    • 最后创建，并绑定到目标 group_ids

经验结论：

  • 新增供应链账号不是“只加 account”
  • 它本质上是“确保资源面完整后再挂 account”

4. 新增模型时，哪些字段必须同时对齐？

至少要对齐：

  • provider base_url
  • default_models
  • smoke_test_model
  • channel_template.model_mapping
  • account credentials.model_mapping
  • channel model_mapping
  • channel model_pricing
  • restrict_models=true
  • billing_model_source=channel_mapped

经验结论：

  • 少了 model_mapping，模型列表可能回退到默认集合
  • 少了 model_pricing，/v1/models 可能看起来没问题，但实际聊天流量可能仍失败
  • 只修 account 不修 channel，或者只修 channel 不修 account，都会留下半通不通的假阳性

5. 如果是“中转 URL / relay URL”，而且不在宿主官方已知库里，标准会不会不一样？

本项目的标准本质不变，但前提是：

  • 这个 provider 必须先在本项目的 pack/provider manifest 中被正确定义

也就是说：

  • “不在宿主官方库里”没关系
  • “没有在本项目 pack 中定义”才不行

只要 manifest 正确提供了：

  • base_url
  • default_models
  • smoke_test_model
  • channel_template.model_mapping

系统就仍然可以自动做：

  • account 创建
  • account /test
  • account /models
  • 普通用户 /v1/models
  • completion smoke（如果你把这一步也纳入验收）

经验结论：

  • 系统不是“任意 URL 自动猜测器”
  • 系统是“pack/provider 驱动的导入与验证器”

6. 只要 /v1/models 成功，是不是就说明新模型已经完全可用了？

不是。

/v1/models 成功，只能证明：

  • 普通用户或 managed key 访问路径至少已经看到了模型列表

它不能自动证明：

  • provider 上游有 quota
  • host 对该 provider 的 completion 兼容性没问题
  • POST /v1/chat/completions 一定能成功

经验结论：

  • /v1/models = 200 是“模型暴露通过”
  • /v1/chat/completions = 200 才更接近“模型可用通过”

7. 新增供应链账号后，普通用户 key 的 group 信息要不要更新？

通常要，取决于 access mode。

self_service

  • 普通用户 key 必须绑定目标标准 group
  • 如果新模型落在新的 group，而 key 没绑定过去，普通用户就看不到或用不到它
  • 若目标 group 是标准计费组，通常还需要余额

subscription

  • 目标 group 必须是 subscription 类型
  • 普通用户必须完成 subscription 分配
  • 普通用户 key 必须绑定该 group
  • 当前 closure 最终优先使用宿主 managed key，而不是外部原始 access_api_key

经验结论：

  • “新增了供应链模型”不等于“所有普通用户 key 自动获得访问权”
  • 最终是否能访问，取决于 key/group/subscription 这条链是否同步完成

8. 新增供应链账号后，如果普通用户看不到模型，优先查哪里？

建议按这个顺序查：

  1. account 视角
    • GET /api/v1/admin/accounts/:id
    • GET /api/v1/admin/accounts/:id/models
  2. channel 视角
    • GET /api/v1/admin/channels/:id
    • 看 model_mapping/model_pricing/restrict_models/billing_model_source
  3. 普通用户视角
    • GET /v1/models
  4. completion 视角
    • POST /v1/chat/completions
  5. 环境与运行时
    • CRM 是否是最新提交
    • PACK_PATH 是否正确
    • CRM_HOST_BASE 是否正确

经验结论：

  • 不要一上来就看普通用户 403/502
  • 先查 account 和 channel 落库，更容易快速定位根因

9. 什么时候应该判定是“运营前置没做”，而不是“导入代码失败”？

常见场景：

  1. self_service
    • key 没绑 group
    • 用户没余额
  2. subscription
    • group 不是 subscription 类型
    • user subscription 没写入
    • key 没绑 group
  3. probe key 用错
    • subscription 场景拿外部原始 key 去打 /v1/models
  4. 脚本参数错
    • PACK_PATH 错
    • 命中错的 Postgres/Redis 容器
    • probe auth 用错

经验结论：

  • 如果 account /models 已对、channel 落库也对，但普通用户流量不对，优先怀疑运营前置或 harness 参数
  • 不要立即重开“导入代码失效”的结论

10. 新增供应链账号或模型后，哪些结果可以算“已确认”，哪些只能算“部分确认”？

可算“已确认”

  • account 已创建
  • account /test 成功
  • account /models 返回目标模型
  • channel 落库包含完整 routing/pricing 字段
  • 普通用户 /v1/models 返回目标模型

只能算“部分确认”

  • 只有 import API 返回成功
  • 只有 batch status 成功
  • 只有 account 创建成功但还没测 /models
  • 只有 /v1/models 成功但没测 /v1/chat/completions

经验结论：

  • “新增模型成功”这句话必须说明你指的是哪一层成功
  • 最容易误导人的说法，就是把“导入成功”直接说成“模型可用成功”

11. 如果新增供应链账号是复用旧 channel，而不是新建 channel，需要特别注意什么？

特别注意两件事：

  1. 旧 channel 不能只复用名字
    • 必须做配置纠偏
    • 至少要补齐 model_mapping + model_pricing + restrict_models + billing_model_source
  2. 不能默认“有 model_mapping 就够了”
    • 这正是之前 MiniMax live 问题踩过的坑

经验结论：

  • 旧 channel 复用比新建更危险
  • 因为它最容易留下“看起来有模型，实际上定价/路由没补齐”的半漂移状态

12. 如果我要把“新增模型/新增供应链账号”做成标准验收 checklist，最小应包含哪些项？

最小 checklist：

  1. provider manifest 已更新
    • base_url
    • default_models
    • smoke_test_model
    • channel_template.model_mapping
  2. import 成功
    • group/channel/(subscription: plan)/accounts 已生成或被正确复用
  3. account 验证成功
    • /test
    • /models
  4. channel 回读成功
    • model_mapping
    • model_pricing
    • restrict_models
    • billing_model_source
  5. 普通用户路径验证成功
    • /v1/models
  6. 业务路径验证成功（推荐）
    • /v1/chat/completions
  7. 若失败，明确归类
    • provider definition drift
    • host compatibility
    • upstream quota/key 问题
    • key/group/subscription/balance 前置问题
    • harness 参数问题

相关证据入口

  • 当前执行真相：docs/EXECUTION_BOARD.md
  • 当前收口真相：docs/PRODUCTION_CLOSURE_BOARD.md
  • 标准操作步骤：docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md
  • 关键 live 证据：
    • artifacts/real-host-acceptance/20260520_222713_crm18100_live_model_mapping_validation
    • artifacts/real-host-acceptance/20260521_011544_remote43_minimax_key_import
    • artifacts/real-host-acceptance/20260521_011717_remote43_deepseek_key_import
    • artifacts/real-host-acceptance/20260521_064910_completion_smoke_calibration.md
Reference in New Issue View Git Blame Copy Permalink