在一个 OpenAI 兼容入口下同时配置 Luna、Terra、Sol，真正困难的部分并不是填写 Base URL 和 API Key，而是让 Cursor、Chatbox、Cherry Studio 正确完成模型发现、模型选择、路由解析和流式响应。

本文把截图中的三个名称视为工具侧展示标签：

• Luna：创意洞察；
• Terra：旗舰推理；
• Sol：高效日常。

它们在接口中对应什么 model 值，应以模型目录和路由配置为准。本文不评价具体模型，也不讨论平台选择，重点只分析多模型接入中的技术问题。

整条链路可以拆成六层：

客户端展示层
→ 模型目录层
→ 模型别名层
→ 权限与路由层
→ 上游请求层
→ 响应适配层

HTTP 请求返回 200，只能证明某次传输完成。客户端能否正常工作，还取决于模型 ID、权限、SSE、错误结构和超时行为是否符合预期。

---

一、先建立对象模型：不要把所有名称都塞进 model

同一个模型在系统里可能同时存在四类名称。

1. 展示名称

展示名称用于界面，例如：

GPT 5.6 Luna｜创意洞察
GPT 5.6 Terra｜旗舰推理
GPT 5.6 Sol｜高效日常

展示名称可以包含空格、中文说明和产品标签，目标是帮助用户理解模型定位。

它不一定能直接写入请求。

2. 请求模型 ID

请求模型 ID 是客户端实际发送的值：

{
  "model": "actual-terra-model-id"
}

客户端最终提交什么，必须通过网络日志、调试日志或服务端访问日志确认，不能只看界面选中了什么。

3. 稳定别名

为了减少上游变化对客户端的影响，可以在路由层设置稳定别名：

creative-route
reasoning-route
daily-route

别名与上游目标之间的映射为：

creative-route → Luna 对应目标
reasoning-route → Terra 对应目标
daily-route → Sol 对应目标

客户端长期使用稳定别名，上游目标发生调整时只修改路由配置。

4. 上游目标

上游目标是路由解析后真正调用的模型标识：

provider-a/model-x
provider-b/model-y
provider-c/model-z

一次请求可能经历：

界面显示：GPT 5.6 Terra
请求模型：reasoning-route
路由名称：terra-primary
上游目标：provider-a/model-x

日志如果只记录最后一层，就无法判断用户选择是否正确；如果只记录展示名称，又无法排查上游错误。

建议同时记录：

{
  "display_name": "GPT 5.6 Terra",
  "requested_model": "reasoning-route",
  "resolved_route": "terra-primary",
  "upstream_model": "provider-a/model-x"
}

---

二、模型发现：/v1/models 是客户端与路由层的第一份契约

Cursor、Chatbox、Cherry Studio 对自定义模型的处理方式不同，但模型发现通常依赖类似 /v1/models 的端点。

模型目录响应通常采用以下结构：

{
  "object": "list",
  "data": [
    {
      "id": "creative-route",
      "object": "model"
    },
    {
      "id": "reasoning-route",
      "object": "model"
    },
    {
      "id": "daily-route",
      "object": "model"
    }
  ]
}

客户端通常读取：

data[].id

下面这种响应虽然是合法 JSON，却可能无法被客户端识别：

{
  "models": [
    {
      "name": "reasoning-route"
    }
  ]
}

如果客户端只实现了 data[].id，它会把第二种响应当成空列表。

模型目录检查项

请求完成后逐项检查：

HTTP 状态是否为 2xx
Content-Type 是否为 application/json
顶层是否存在 data
data 是否为数组
每个元素是否存在字符串类型的 id
id 是否与聊天接口接受的 model 一致
当前密钥是否可以看到预期模型

模型目录不能证明全部能力

模型出现在列表中，只代表它可以被当前客户端或密钥发现，不能据此推断：

• 支持 SSE；
• 支持工具调用；
• 支持视觉输入；
• 支持某个上下文长度；
• 适合某类客户端工作流；
• 当前路由一定可用。

因此，模型目录验证后还要分别执行：

非流式聊天测试
流式聊天测试
长上下文测试
工具调用测试
错误响应测试

---

三、模型目录与聊天路由必须使用同一份配置来源

一个常见故障是：模型可以在列表中看到，实际调用却返回 model_not_found。

这通常不是客户端显示问题，而是模型目录与聊天路由没有同步。

例如：

模型目录配置：
reasoning-route 已发布

聊天路由配置：
reasoning-route 尚未发布

客户端执行：

GET /v1/models

能够看到 reasoning-route，随后执行：

POST /v1/chat/completions

却无法解析该别名。

为什么会不同步

可能原因包括：

• 模型目录使用缓存；
• 聊天路由使用实时配置；
• 两个端点读取不同数据库；
• 灰度实例没有同时更新；
• 模型目录已经发布，路由变更尚未生效；
• 部分服务节点仍使用旧配置；
• 回滚只恢复了其中一个组件。

配置发布应具有原子性

如果条件允许，模型目录和聊天路由应从同一份版本化配置生成：

version: 2026-07-16-01

models:
  - id: creative-route
    route: luna-primary
    enabled: true

  - id: reasoning-route
    route: terra-primary
    enabled: true

  - id: daily-route
    route: sol-primary
    enabled: true

发布时记录配置版本：

{
  "catalog_version": "2026-07-16-01",
  "router_version": "2026-07-16-01"
}

如果两个版本不同，日志应直接告警，而不是等用户遇到 model_not_found。

---

四、Base URL 排错的重点是最终路径

不同客户端对 Base URL 的拼接方式可能不同。常见填写形式包括：

https://example.com
https://example.com/v1
https://example.com/v1/chat/completions

某些客户端会自动追加 /v1，另一些只追加 /models 或 /chat/completions。

错误组合可能形成：

/v1/v1/models
/models
/v1/chat/completions/chat/completions

因此，排错时不要只检查配置框中的内容，而要检查客户端最终发出的 URL。

建立两个基线端点

GET /v1/models
POST /v1/chat/completions

使用同一套 Base URL、API Key 和模型 ID 分别验证。

示例配置地址可以写成：

Base URL: https://api.vectorengine.cn/v1

相关接入记录若需要在团队内部归档，可以集中放在 https://178.nz/dn 对应的技术备忘入口中；实际请求仍应以客户端网络日志为准。

最终路径比配置名称更可靠

客户端界面可能使用以下名称：

API Host
API Endpoint
Base URL
OpenAI URL
Provider URL

这些名称不能证明客户端的拼接规则。判断依据应是：

客户端最终请求路径
服务端访问日志
反向代理日志
请求返回状态

如果 curl 基线成功而客户端失败，应优先对比最终 URL、请求头和请求 JSON。

---

五、API Key 权限要与模型目录绑定

同一个入口下，不同 API Key 可能看到不同模型。

例如：

Key 类型	creative-route	reasoning-route	daily-route
开发 Key	允许	禁止	允许
审查 Key	允许	允许	允许
演示 Key	禁止	禁止	允许

因此，下面两种情况可能同时成立：

使用 Key A 请求 /v1/models，看不到 reasoning-route
使用 Key B 请求 /v1/models，可以看到 reasoning-route

权限过滤有两种实现方式

第一种是在模型目录阶段过滤：

无权访问的模型不出现在 data 数组中

第二种是在调用阶段判断：

模型出现在目录中
调用时再检查权限

第一种更符合最小暴露原则，第二种便于展示完整目录。无论采用哪一种，模型目录和调用端点必须保持一致。

权限错误不要全部映射为 model_not_found

权限不足与模型不存在是不同问题：

model_not_found：路由表中没有该模型或别名
permission_denied：模型存在，但当前 Key 无权调用

出于安全考虑，对外可以减少模型存在性信息，但内部日志必须保留真实原因。

建议记录：

{
  "requested_model": "reasoning-route",
  "key_alias": "dev-key",
  "permission_result": "denied",
  "public_error": "model_not_found",
  "internal_error": "model_permission_denied"
}

API Key 不进入普通日志

可以记录不可逆指纹：

import hashlib

def key_fingerprint(value: str) -> str:
    return hashlib.sha256(
        value.encode("utf-8")
    ).hexdigest()[:12]

使用指纹可以关联请求，但不能用于还原密钥。

---

六、客户端适配的差异不应靠猜

Cursor

Cursor 的普通聊天、代码编辑和代理工作流不是同一种请求。

普通聊天成功后，还要验证：

流式输出
长上下文
工具调用
跨文件任务
客户端取消

某个模型可以返回文本，不代表它适合代理工作流。代理模式可能依赖工具调用字段、调用 ID、多轮消息和较长上下文。

Chatbox

Chatbox 更依赖模型选择器，因此展示名称与模型 ID 必须分离：

{
  "display_name": "Terra｜旗舰推理",
  "model_id": "reasoning-route"
}

界面展示 display_name，请求发送 model_id。

如果把整个展示名称发送到 model 字段，服务端无法识别时就会返回 model_not_found。

Cherry Studio

Cherry Studio 中通常需要同时维护：

供应商配置
Base URL
API Key
模型目录
能力标签

能力标签应来自测试，而不是根据模型名称推断。是否支持流式、工具或视觉输入，需要分别验证。

客户端适配矩阵

测试项	Cursor	Chatbox	Cherry Studio
自动获取模型列表	检查	检查	检查
手动填写模型 ID	检查	检查	检查
非流式聊天	必测	必测	必测
SSE 流式响应	必测	必测	必测
工具调用	代理场景必测	按需	工作流场景必测
长上下文	必测	按需	按需
模型切换	必测	必测	必测
错误展示	必测	必测	必测

---

七、model_not_found 应按证据逐层定位

典型错误响应可能是：

{
  "error": {
    "type": "model_not_found",
    "message": "The requested model was not found"
  }
}

不要看到这段信息就反复修改模型名称，应按以下顺序排查。

第一步：记录客户端实际发送的 model

界面显示的名称不等于请求值。必须检查请求 JSON：

{
  "model": "reasoning-route"
}

第二步：使用同一 Key 请求模型目录

检查 reasoning-route 是否存在于 data[].id。

第三步：逐字符比较

检查：

大小写
前后空格
供应商前缀
连字符与下划线
版本后缀
不可见字符

第四步：检查权限

模型存在于全局目录，不代表当前 Key 有权调用。

第五步：检查路由发布

确认别名已经存在于聊天路由，而不只是出现在模型列表中。

第六步：检查环境

确认客户端模型列表和聊天请求使用同一个 Base URL，避免列表来自测试环境、请求发往生产环境。

第七步：检查缓存

客户端、网关、模型目录和路由服务都可能缓存模型信息。

第八步：关联请求 ID

最终应通过 trace_id 或上游请求 ID 确认错误发生在哪一层。

---

八、非流式响应正常，不代表 SSE 正常

非流式响应通常从以下路径读取正文：

choices[0].message.content

流式响应则读取：

choices[0].delta.content

典型 SSE 事件如下：

data: {“choices”:[{“index”:0,“delta”:{“role”:“assistant”},“finish_reason”:null}]}

data: {“choices”:[{“index”:0,“delta”:{“content”:“正在”},“finish_reason”:null}]}

data: {“choices”:[{“index”:0,“delta”:{“content”:“处理”},“finish_reason”:null}]}

data: {“choices”:[{“index”:0,“delta”:{},“finish_reason”:“stop”}]}

data: [DONE]

SSE 验证项

Content-Type 是否为 text/event-stream
每个事件是否以 data: 开头
事件之间是否存在空行
每帧 JSON 是否能够独立解析
正文是否位于 delta.content
finish_reason 是否正确
是否存在 [DONE]

网络分块不等于 SSE 事件

一次网络读取可能包含：

半个 SSE 事件
一个完整事件
多个完整事件
一个完整事件加下一个事件的一部分

客户端不能假设一次读取就是一个完整 JSON。

正确处理方式是：

读取字节
→ 使用 UTF-8 增量解码
→ 放入缓冲区
→ 按 SSE 空行切分事件
→ 读取 data 字段
→ 解析事件中的 JSON

代理缓冲

服务端可能持续输出事件，但反向代理或压缩模块将小块内容聚合，客户端最后一次性收到全文。

需要分别记录：

上游首个事件时间
网关首次写出时间
客户端首个事件时间
事件流完成时间

如果上游很快、客户端很慢，问题可能位于代理与下游传输之间。

---

九、不同模型经过不同适配器时，SSE 行为可能不一致

同一个入口下的多个模型，可能路由到不同上游：

creative-route → 适配器 A
reasoning-route → 适配器 B
daily-route → 适配器 C

如果三个适配器没有输出统一结构，就可能出现：

daily-route 在三个客户端都正常
creative-route 非流式正常，流式空白
reasoning-route 输出一半后断开

排查时应对每个路由分别保存原始 SSE，不要只验证一个模型后把结论推广到全部模型。

统一内部增量对象

适配器可以先将上游事件转换为内部对象：

{
  "request_id": "req-001",
  "choice_index": 0,
  "role_delta": null,
  "content_delta": "正在分析",
  "finish_reason": null
}

再由统一输出层生成兼容 SSE。这样能够避免每个客户端分别适配每个上游。

结束语义也要统一

需要区分：

finish_reason：本次生成为什么停止
[DONE]：整个事件流已经结束
TCP 关闭：传输连接结束

三者不是同一个概念。只关闭连接、不发送结束事件，某些客户端可以容忍，另一些客户端会显示断流。

---

十、timeout 要按阶段拆分

只记录一个 timeout 无法定位问题。至少应区分：

connect_timeout
tls_timeout
upstream_first_byte_timeout
stream_idle_timeout
total_timeout
client_cancelled

connect_timeout

尚未建立连接，通常检查：

DNS
TLS
代理
防火墙
连接池
上游地址

upstream_first_byte_timeout

连接已经建立，但上游迟迟没有首包，通常检查：

模型排队
输入上下文规模
路由实例状态
代理缓冲
上游负载

stream_idle_timeout

流式输出已经开始，但长时间没有新事件。它不能与首包超时混为一谈。

total_timeout

整个任务超过总时长。持续输出的长任务与完全无响应的请求不应使用相同处理策略。

client_cancelled

用户停止生成或关闭任务后，下游连接已经取消。网关应尽量同步取消上游，避免继续消耗资源。

按任务类型配置

日常短任务更关注首包速度；复杂分析可能允许较长预处理；长文本生成可以拥有更长总时长，但只要 SSE 仍在持续，就不应被过短的流空闲阈值切断。

---

十一、rate_limit 要检查并发放大和多层重试

多模型协作和无限画布会产生请求放大。

例如：

6 个节点并行运行
× 每个节点调用 3 个模型步骤
× 客户端重试 2 次
× 网关再次重试 2 次

如果每一层都独立重试，单次用户操作会迅速产生大量请求。

限流应按多个维度设置

用户级并发
项目级并发
API Key 并发
模型级并发
路由级并发
上游供应商并发

重试策略

限制最大次数
使用指数退避
加入随机抖动
识别客户端取消
避免多个层级重复重试
记录每次重试原因

不是所有请求都适合自动重放。已经产生部分流式输出的请求，重新调用后可能出现重复内容；包含工具副作用的请求，更不能简单重试。

---

十二、模型路由要优先尊重用户显式选择

自动路由可以依据任务类型选择模型，但不能覆盖用户明确选择而不提示。

一个路由请求可以包含：

{
  "task_type": "code_review",
  "creative": false,
  "deep_reasoning": true,
  "latency_sensitive": false,
  "needs_tools": true,
  "user_selected_model": "reasoning-route"
}

路由结果应返回：

{
  "selected_model": "reasoning-route",
  "route_reason": [
    "user_selected",
    "deep_reasoning",
    "needs_tools"
  ],
  "fallback_allowed": false
}

降级必须可见

如果用户选择的路由不可用，可以：

• 排队等待；
• 提示缩小上下文；
• 提示稍后重试；
• 询问是否切换；
• 返回明确错误。

不应让界面显示一个模型，实际请求另一个模型。

路由不是只看任务名称

更完整的决策条件包括：

用户显式选择
任务复杂度
上下文规模
工具调用需求
输出长度
延迟目标
失败代价
模型能力标签
当前路由容量
API Key 权限

其中能力标签必须来自测试结果，而不是根据名称推断。

---

十三、多模型协作要限制步骤和上下文传播

多模型协作不应简单地把同一个问题重复发送三次。

更合理的编排是：

步骤 1：提取事实与约束
步骤 2：生成候选方案
步骤 3：检查冲突与遗漏
步骤 4：形成最终结果

每个步骤可以绑定不同路由，但需要限制：

最大步骤数
最大重试数
单步超时
总上下文预算
中间结果长度
并发数量

避免上下文指数增长

如果每个模型都接收前面全部原始输出，协作上下文会快速膨胀。

可以只传递结构化中间结果：

{
  "facts": [],
  "constraints": [],
  "candidate_options": [],
  "unresolved_questions": []
}

而不是把多个模型的完整自然语言回答全部拼接。

无限画布按节点执行

画布节点应拥有独立状态：

{
  "node_id": "node-17",
  "route": "reasoning-route",
  "status": "running",
  "retry_count": 0,
  "parent_nodes": ["node-12"],
  "context_budget": 8000
}

节点取消后，应停止后续路由和未执行请求。

---

十四、日志要能还原一次完整路由

建议记录以下字段：

{
  "trace_id": "trace-demo",
  "client": "Cursor",
  "endpoint": "/v1/chat/completions",
  "requested_model": "reasoning-route",
  "resolved_route": "terra-primary",
  "upstream_model": "provider-a/model-x",
  "key_alias": "cursor-dev",
  "stream": true,
  "route_reason": [
    "user_selected"
  ],
  "connect_ms": 92,
  "first_byte_ms": 3280,
  "total_ms": 12600,
  "http_status": 200,
  "finish_reason": "stop",
  "retry_count": 0
}

这些数值只是日志结构示例，不代表任何服务的性能。

日志应回答的问题

客户端选择了什么
实际发送了什么 model
路由解析成什么
最终调用哪个上游
当前 Key 是否有权限
首包慢发生在哪一层
是否发生重试或降级
SSE 是否正常结束
用户是否主动取消

数据安全

API Key 只记录指纹或别名
对话正文默认不进入普通日志
代码内容按安全等级处理
工具参数按字段脱敏
设置日志保留周期
限制审计数据访问

可观测性用于还原行为，不等于保存全部用户内容。

---

十五、自动化契约测试比手工点击更可靠

每次路由、网关或适配器变更后，应运行固定契约测试。

模型目录测试

M01 返回 data 数组
M02 每个元素具有字符串 id
M03 不同 Key 返回正确可见范围
M04 禁用模型不会继续出现在目录中
M05 模型别名与聊天路由同步

非流式测试

N01 普通短文本
N02 中文与代码
N03 长文本
N04 finish_reason 正确
N05 错误不包装为 200

SSE 测试

S01 首帧只有 role
S02 content 跨多个事件
S03 一个事件跨多个网络读取
S04 一次读取包含多个事件
S05 UTF-8 多字节边界
S06 finish_reason 正确
S07 正常发送 [DONE]
S08 中途断开可以识别

权限与错误测试

E01 无效 Key
E02 无权限模型
E03 不存在的模型别名
E04 模型目录与聊天路由不同步
E05 连接超时
E06 首包超时
E07 流空闲超时
E08 rate_limit

客户端测试

C01 Cursor 普通聊天
C02 Cursor 工具或代理任务
C03 Chatbox 模型切换
C04 Chatbox 长对话
C05 Cherry Studio 模型刷新
C06 Cherry Studio SSE

测试结果应与配置版本、路由版本关联，便于发现是哪次变更造成回归。

---

结语

同一个 OpenAI 兼容入口下配置多个模型，真正需要解决的不是如何把名称放进下拉框，而是以下技术契约能否保持一致：

模型目录能够发现真实模型 ID
模型别名能够稳定解析
API Key 权限与目录保持一致
Base URL 最终路径正确
客户端能够解析非流式与 SSE
错误能够定位到具体责任层
timeout 能够区分不同阶段
路由和降级行为可以审计

只要其中一层存在偏差，就可能出现模型列表为空、model_not_found、流式空白、timeout 或错误路由。

因此，验收标准不应是“某次请求返回 200”，而应是 Cursor、Chatbox、Cherry Studio 在模型发现、模型切换、SSE、权限错误和超时场景中都表现一致，并且每次失败都能通过请求 ID 和路由日志还原。