openai-api-compatible

OpenAI 兼容 API 对照：vLLM、SGLang、Ollama、TGI 等服务的端点与字段差异

补充说明

很多推理服务都提供“OpenAI 兼容”端点，让现有 OpenAI SDK/客户端通过改 base_url 就能接入。但兼容程度不一致：聊天补全、流式输出、工具调用、视觉/音频、embedding、错误码和用量字段都可能不同。选型时不要只看“支持 OpenAI API”，要按实际用到的端点和字段逐项验证。

常见服务：vLLM、SGLang、Ollama、TGI、LMDeploy、llama-server、Xinference、BentoML、Ray Serve，以及 TEI/Infinity 的 embedding 端点。多数聊天服务提供 /v1/chat/completions 和 /v1/models，embedding 服务提供 /v1/embeddings 或自有 /embed。

常用示例

# 通用聊天补全
curl http://localhost:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"Qwen/Qwen2.5-7B-Instruct","messages":[{"role":"user","content":"你好"}],"stream":false}'

# 流式输出（SSE）
curl -N http://localhost:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"Qwen/Qwen2.5-7B-Instruct","messages":[{"role":"user","content":"写一个 shell 循环"}],"stream":true}'

# 列出模型
curl http://localhost:8000/v1/models

# 工具调用
curl http://localhost:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"Qwen/Qwen2.5-7B-Instruct","messages":[{"role":"user","content":"北京天气"}],"tools":[{"type":"function","function":{"name":"get_weather","parameters":{"type":"object","properties":{"city":{"type":"string"}}}}}]}'

# OpenAI SDK：改 base_url 和 api_key 即可接入
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")
resp = client.chat.completions.create(
    model="Qwen/Qwen2.5-7B-Instruct",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

上线前做一张兼容性矩阵：端点、流式、工具调用、JSON mode、视觉、音频、embedding、错误格式、usage 字段，逐项用真实请求验证。

易错点与排错

• base_url 少了 /v1：OpenAI SDK 会在 base_url 后拼 /chat/completions；多数服务需要 http://host:port/v1，少了会 404。
• model 名称写错：不同服务对模型名的要求不同（注册名、Hugging Face ID、适配器名）；用 /v1/models 确认。
• 把“兼容”当“完全一致”：工具调用、JSON mode、视觉、音频、logprobs、usage 字段常有差异；按业务实际用到的能力逐项测试。
• 流式解析错误：SSE 的 data: 行、[DONE] 结束标记和错误事件格式可能不同；不要假设所有服务都和 OpenAI 一样。
• 错误码/错误体不同：OpenAI SDK 会按 error 结构解析；服务返回纯文本或不同字段时，客户端可能拿不到可读错误。
• 认证方式不同：有的服务要求 Bearer token，有的默认无鉴权；不要在没有鉴权的服务上直接暴露公网。
• 工具调用格式差异：tool_calls 的字段、并行调用、参数 JSON 字符串的转义可能不同；用真实模型回归。
• 版本升级后兼容性回退：服务升级可能改变默认字段或端点行为；锁定版本并保留兼容性测试。

相关命令

• vllm — OpenAI 兼容服务的主力实现。
• sglang — 高吞吐推理与 OpenAI 兼容端点。
• ollama — 本地模型的 OpenAI 兼容接口。
• tgi — Hugging Face 推理服务。
• text-embeddings-inference — embedding 端点。
• openai-agents-sdk — 基于 OpenAI API 的 Agent SDK。

参考链接

• OpenAI API 参考
• vLLM OpenAI 兼容服务
• Ollama OpenAI 兼容性

读完自测

合上页面，先回答，再展开对照。

1. 用 OpenAI SDK 接入本地服务时，base_url 通常要写到哪一层？
2. 为什么“支持 OpenAI API”不等于可以直接替换？
3. 工具调用兼容性要重点验证哪些点？