大模型应用开发 / 系统课时

处理兼容接口差异

处理兼容接口差异

学习目标

完成本课后,你将能够:

  • 识别原生 API 与 OpenAI 兼容 API 的字段差异
  • 处理上下文长度和模型名称配置
  • 为不支持或行为不同的功能设计降级
  • 避免根据供应商错误文本编写脆弱逻辑

兼容层的边界

兼容层的目标是复用常见客户端,并不保证每个 OpenAI 参数、端点和返回字段都完全等价。应用应以 Ollama 当前兼容文档的支持列表为准,并在启动时做能力检测。

上下文设置差异

OpenAI Chat Completions 请求没有 Ollama 原生 options.num_ctx 的通用字段。需要固定上下文时,可以创建自定义模型:

text
FROM gemma3:1b
PARAMETER num_ctx 8192

构建后调用新模型名称:

bash
ollama create anystack-chat:8k -f Modelfile

预期输出最终包含:

text
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 等,但不同端点与模型支持范围不同。应用启动时可执行最小测试,或维护模型能力配置:

json
{
  "model": "anystack-chat:8k",
  "chat": true,
  "vision": false,
  "tools": true,
  "thinking": false,
  "structured_output": true
}

该配置必须来自验证,不应根据模型名称猜测。

错误处理差异

不要依赖完整错误字符串。例如:

text
model not found

未来版本可能改变文案。优先使用:

  • HTTP 状态码
  • SDK 异常类型
  • 响应错误字段
  • 自己的请求上下文
  • 模型清单预检

业务层再转换为稳定内部错误码。

参数降级

某些客户端会发送 Ollama 不识别的参数。可采用:

  1. 明确拒绝并返回可理解错误。
  2. 在适配层移除无关参数。
  3. 映射到等价参数。
  4. 通过 Modelfile 固化。
  5. 标记功能不可用。

静默忽略关键参数可能让用户误以为配置已生效。

兼容回归脚本

保存为 compatibility_check.py:

python
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())}")

运行:

bash
python compatibility_check.py

预期输出:

text
basic: non_empty=True
system: non_empty=True

本课练习

练习 1:建立字段映射

任务目标:统一两套接口。输入或初始条件:应用同时支持原生与兼容 API。实现要求:定义内部请求和响应模型。验收条件:业务代码不直接依赖供应商字段。

练习 2:测试不支持参数

任务目标:避免静默失效。输入或初始条件:选择一个兼容层未知参数。实现要求:决定拒绝、映射或忽略并记录。验收条件:用户能知道参数是否生效。

练习 3:实现能力探测

任务目标:按模型启用功能。输入或初始条件:准备两个能力不同的模型。实现要求:启动时测试或读取配置。验收条件:界面不会给不支持模型展示视觉或工具入口。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理兼容接口差异

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通