大模型应用开发 / 系统课时
处理兼容接口差异
处理兼容接口差异
学习目标
完成本课后,你将能够:
- 识别原生 API 与 OpenAI 兼容 API 的字段差异
- 处理上下文长度和模型名称配置
- 为不支持或行为不同的功能设计降级
- 避免根据供应商错误文本编写脆弱逻辑
兼容层的边界
兼容层的目标是复用常见客户端,并不保证每个 OpenAI 参数、端点和返回字段都完全等价。应用应以 Ollama 当前兼容文档的支持列表为准,并在启动时做能力检测。
上下文设置差异
OpenAI Chat Completions 请求没有 Ollama 原生 options.num_ctx 的通用字段。需要固定上下文时,可以创建自定义模型:
FROM gemma3:1b
PARAMETER num_ctx 8192构建后调用新模型名称:
ollama create anystack-chat:8k -f Modelfile预期输出最终包含:
success不能把原生 options 对象直接放入所有兼容请求并假定生效。
字段映射
| 需求 | 原生 API | 兼容 API |
|---|---|---|
| 单轮生成 | /api/generate |
/v1/responses 或兼容端点 |
| 对话 | /api/chat |
/v1/chat/completions |
| 内容字段 | response 或 message.content |
choices[].message.content |
| Token 统计 | prompt_eval_count、eval_count |
usage |
| 驻留时间 | keep_alive |
不一定有直接对应 |
| Ollama options | options |
使用兼容参数或自定义模型 |
业务适配层应把两种响应转换为统一内部对象。
模型名称差异
云端代码可能使用 gpt-* 名称,本地模型使用 Ollama 名称和标签。处理方式:
- 配置映射表
- 使用
ollama cp创建兼容别名 - 启动时检查模型是否存在
- 显示真实底层模型
- 禁止用户任意指定未批准模型
模型别名不能解决能力差异。
支持功能检测
当前兼容文档列出的功能可能包含聊天、流式、JSON、可复现输出、视觉、工具、思考控制和 logprobs 等,但不同端点与模型支持范围不同。应用启动时可执行最小测试,或维护模型能力配置:
{
"model": "anystack-chat:8k",
"chat": true,
"vision": false,
"tools": true,
"thinking": false,
"structured_output": true
}该配置必须来自验证,不应根据模型名称猜测。
错误处理差异
不要依赖完整错误字符串。例如:
model not found未来版本可能改变文案。优先使用:
- HTTP 状态码
- SDK 异常类型
- 响应错误字段
- 自己的请求上下文
- 模型清单预检
业务层再转换为稳定内部错误码。
参数降级
某些客户端会发送 Ollama 不识别的参数。可采用:
- 明确拒绝并返回可理解错误。
- 在适配层移除无关参数。
- 映射到等价参数。
- 通过 Modelfile 固化。
- 标记功能不可用。
静默忽略关键参数可能让用户误以为配置已生效。
兼容回归脚本
保存为 compatibility_check.py:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:11434/v1/",
api_key="ollama",
)
tests = [
("basic", [{"role": "user", "content": "只回答:ok"}]),
(
"system",
[
{"role": "system", "content": "只使用中文。"},
{"role": "user", "content": "Say hello."},
],
),
]
for name, messages in tests:
response = client.chat.completions.create(
model="gemma3:1b",
messages=messages,
temperature=0,
)
content = response.choices[0].message.content or ""
print(f"{name}: non_empty={bool(content.strip())}")运行:
python compatibility_check.py预期输出:
basic: non_empty=True
system: non_empty=True本课练习
练习 1:建立字段映射
任务目标:统一两套接口。输入或初始条件:应用同时支持原生与兼容 API。实现要求:定义内部请求和响应模型。验收条件:业务代码不直接依赖供应商字段。
练习 2:测试不支持参数
任务目标:避免静默失效。输入或初始条件:选择一个兼容层未知参数。实现要求:决定拒绝、映射或忽略并记录。验收条件:用户能知道参数是否生效。
练习 3:实现能力探测
任务目标:按模型启用功能。输入或初始条件:准备两个能力不同的模型。实现要求:启动时测试或读取配置。验收条件:界面不会给不支持模型展示视觉或工具入口。