OmniCortex每个应用，各自维护。
业务应用 A模型 A · 模型 B · 模型 C
业务应用 B模型 A · 模型 B · 模型 C
入口、上游凭证与异常处理，分散在不同应用。
01 / BRING CONNECTIONS TOGETHER模型可以多样，
模型可以多样，
接入关系需要清晰。
从各自维护连接，
到集中组织模型入口。
连接关系，集中管理。
业务应用 A / BOmniCortex已配置的模型与通道
应用使用网关凭证，上游连接凭证集中管理。
02 / NAME. MODEL. CONNECTION.业务名称背后，
业务名称背后，
每一层都各司其职。
目录帮助了解模型，别名组织调用目标，
供应商与通道定义连接。
模型目录规格与能力参考
- 01业务应用发起请求
- 02assistant-chat业务名称
- 03目标模型 A调用目标
- 04通道 A供应商通道
概念关系示意，非内核执行顺序。目标模型 A · 核对能力与可调用状态。
了解模型
先了解能力，再建立连接。
模型目录组织模型信息与规格，帮助核对上下文、模态与工具能力。目录里有记录，不代表已经接通。
模型目录规格与能力参考
- 01业务应用发起请求
- 02assistant-chat业务名称
- 03目标模型 A调用目标
- 04通道 A供应商通道
概念关系示意，非内核执行顺序。assistant-chat · 需自行配置的业务别名。
使用业务别名
让业务使用清晰的调用名称。
将业务名称与后端目标建立映射，集中维护调用关系。替换目标前，仍需验证参数、响应与业务效果。
模型目录规格与能力参考
- 01业务应用发起请求
- 02assistant-chat业务名称
- 03目标模型 A调用目标
- 04通道 A供应商通道
概念关系示意，非内核执行顺序。通道 A · 供应商连接下的已配置通道。
查看连接通道
明确请求去向与连接凭证。
供应商连接定义服务地址与网络配置，通道组织可用的上游凭证或端点，并按配置参与选择。
03 / START WITH YOUR INTERFACE沿用熟悉的接口，
沿用熟悉的接口，
连接不同模型服务。
配置地址、凭证与模型名称，
再验证业务依赖的参数和响应。
M / 应用侧协议
- Chat Completions
- Responses
- Anthropic Messages
OMNICORTEX
协议适配
请求转换 · 目标路由
响应与流式事件适配
N / 模型服务
- 云端模型服务
- 托管模型端点
- 自托管模型服务
应用采用的接口与后端模型服务分别组织。右侧展示部署形态，M、N 表示多种接入与目标，不是已验证的数量；连线不代表任意组合均完整兼容。
每个组合分别核对：普通请求、流式返回、工具调用与多模态能力。具体支持范围取决于接口、目标模型及接入配置。
Chat Completions
POST /v1/chat/completions采用 Chat Completions 请求结构的应用。
查看接口文档Responses
POST /v1/responses采用 Responses 请求结构的应用。
查看接口文档Anthropic Messages
POST /anthropic/v1/messages采用 Anthropic Messages 请求结构的应用。
查看接口文档import os
from openai import OpenAI
client = OpenAI(
base_url=os.environ["OMNICORTEX_BASE_URL"],
api_key=os.environ["OMNICORTEX_VIRTUAL_KEY"],
)
response = client.chat.completions.create(
model=os.environ["OMNICORTEX_MODEL"],
messages=[{"role": "user", "content": "你好"}],
)- 网关地址
- OMNICORTEX_BASE_URL：含
/v1的基础地址。 - 应用凭证
- OMNICORTEX_VIRTUAL_KEY：已授权的应用虚拟密钥。
- 调用目标
- OMNICORTEX_MODEL：已配置、可调用的模型名称。
先配置上述环境变量。此处仅展示调用结构，不发送真实请求。
统一入口不代表协议完全等价。特殊参数、工具调用、响应结构及模型能力，需要按实际组合验证。
04 / A CLEAR PATH FOR EVERY OUTCOME正常调用有分工，
阅读重试与降级说明 ↗正常调用有分工，
上游异常有路径。
加权选择
按配置权重参与通道选择，不代表每一小批请求都满足固定比例。
重试
当前目标出现可重试错误时，在配置范围内再次尝试。
候选降级
满足条件时尝试已配置的候选模型或供应商，候选仍可能失败。
REQUEST ROUTING路径示意，不发送真实请求
- 01业务请求请求进入
- 02首选目标✓ 首选返回
- 03候选目标— 未执行
- 04应用结果✓ 调用完成
首选目标返回，本次调用完成。
候选目标保留待用，本次没有执行。
- 01业务请求请求进入
- 02首选目标× 首选失败
- 03候选目标✓ 候选返回
- 04应用结果✓ 调用完成
首选失败后，由候选完成响应。
本例满足降级条件，已配置的候选目标返回；实际结果取决于目标可用性与请求能力匹配。
本例假设请求允许降级，且尚未向客户端交付流式输出。
- 01业务请求请求进入
- 02首选目标× 首选失败
- 03候选目标× 候选失败
- 04应用结果× 返回错误
没有目标成功，向应用返回错误。
可尝试目标均未成功。应用需要处理失败结果，并结合调用记录排查。
本例假设请求允许降级，且尚未向客户端交付流式输出。
不承诺中途换模型续写，客户端应处理异常结束。
不能以更换供应商为由绕过访问规则或安全策略。
提前核对上下文、模态、工具与参数的支持范围。
05 / KEEP THE INTERACTION INTACT保留交互体验，
保留交互体验，
也看清能力差异。
按模型与协议的实际支持范围，
逐项核对业务需要的交互。
流式返回
逐步接收生成结果核对首段、增量、正常结束、异常结束与客户端超时。
推理信息
处理支持的推理字段核对返回范围、字段形态、客户端展示与多轮回传要求。
工具调用
交换工具调用信息核对工具定义、调用参数、结果回传与多轮连续性。
多模态与上下文
匹配模型的输入与输出核对输入类型、上下文限制与候选模型的能力。
网关适配不会让目标模型获得其原本不支持的能力。工具调用信息的传递，也不等于网关已执行外部工具。
GOOD QUESTIONS. CLEAR ANSWERS.接入之前，
接入之前，
你可能还想了解。
统一模型网关解决什么问题？
将应用与模型服务之间分散的连接、凭证和调用名称集中组织，并为适用的上游异常配置后续尝试路径。
它与普通 API 网关有什么区别？
普通 API 网关主要处理通用 HTTP 转发与访问控制；模型网关进一步处理模型名称、供应商协议、流式响应和工具调用等模型接口语义。具体适配范围取决于模型与协议组合。
接入后，应用还需要保存上游模型的凭证吗？
应用通常使用分配的网关调用凭证，上游连接凭证在网关侧管理。具体鉴权和访问范围按部署方式及策略配置确认。
修改地址和凭证就一定能完成迁移吗？
这是常见接入起点。模型名称、特殊参数、响应格式以及流式和工具调用仍需验证，兼容入口不代表所有功能完全等价。
业务别名能保证替换模型后效果一致吗？
别名帮助维护稳定的调用名称，不保证不同模型的输出质量和能力一致。替换前应验证业务样例、上下文和工具调用。
可以同时连接云端与自托管模型吗？
可按支持的协议和连接配置接入不同部署形态的模型。自部署网关仍可能向云端模型发送请求，数据路径取决于选用的目标和服务配置。
上游失败后一定会切换到候选模型吗？
不会。需要存在候选配置并满足降级条件，候选也可能失败；不允许降级的错误应终止后续尝试。
流式回答中断后，可以直接换模型继续输出吗？
不承诺已经输出后的跨模型续写。客户端需要处理异常结束，是否重发以及如何组织上下文由应用自身决定。
模型目录中有记录，就代表可以调用吗？
不代表。还需要有效连接、可用通道、相应访问权限，以及模型与请求能力匹配。