兼容接口的边界
自托管引擎几乎都提供 OpenAI 兼容接口：对话、补全、向量化与模型清单对齐同一套路径与请求结构。好处是客户端只换基地址与密钥，生态里的工具与 SDK 可以直接复用。但兼容不等于完全一致：个别参数被忽略、错误结构与用量字段存在差异，接入前要用目标 SDK 跑通最小用例。
快速核对可用端点
快速核对可用端点
# 模型清单：确认对外模型名与服务是否就绪
curl -s http://127.0.0.1:8000/v1/models
# 对话端点：最小请求体验通
curl -s http://127.0.0.1:8000/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"<模型名>","messages":[{"role":"user","content":"ping"}]}'
# 向量化端点：按部署的模型类型验证
curl -s http://127.0.0.1:8000/v1/embeddings -H 'Content-Type: application/json' \
-d '{"model":"<嵌入模型名>","input":"你好"}'常用端点
| 端点 | 用途 | 核对要点 |
|---|---|---|
| 列模型 | 返回可用模型清单 | 对外模型名与配置一致 |
| 对话 | 多轮对话主端点 | 消息结构与停止原因字段 |
| 文本补全 | 单轮生成端点 | 部分新模型仅支持对话形态 |
| 向量化 | 把文本转成向量 | 维度与归一化方式要记入文档 |
典型使用场景
- 把自建服务接入现有业务代码：只改基地址与密钥，逻辑不动
- 灰度切换出口：网关按比例把流量分给自建引擎与云端接口
- 本地开发调试：用同一套 SDK 在本机验证功能，降低环境差异
- 生态工具复用：已有前端与评测工具通过兼容接口直接对接
- 对照排查：同一请求分别打到自建与云端，比较返回结构差异
兼容性核对清单
| 参数支持 | 哪些采样参数被忽略或语义不同 |
|---|---|
| 错误结构 | 错误码与错误体字段是否与 SDK 预期一致 |
| 用量字段 | 输入输出 token 统计是否齐全，用于对账 |
| 流式行为 | 流式开关默认值与分片格式 |
| 模型名解析 | 别名与版本映射规则 |
兼容不等于完全一致：集成测试要覆盖错误分支与边界参数，否则线上遇到偶发失败时很难判断是客户端还是服务端的问题。
网关与引擎都实现兼容层时不要叠加两次转换：中间环节的字段改写会掩盖原始错误，排障时应能直连引擎验证一次。