#OpenAI 兼容 API

vLLM 在线服务实现了 OpenAI 风格的 HTTP，让现有 SDK 只改 base URL（和 model 名）。默认：

聊天接口要求模型带 chat template（如 Qwen/Qwen2.5-0.5B-Instruct）。facebook/opt-125m 这类底座更适合 /v1/completions。完整能力表以 OpenAI-Compatible Server 为准（新版路径可能是 serving/online_serving/openai_compatible_server/，以当前文档为准）。

#启动时带上 Key（可选）

vllm serve Qwen/Qwen2.5-0.5B-Instruct --api-key token-abc123

也可用环境变量 VLLM_API_KEY（名称以当前文档为准）。客户端：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="token-abc123",
)

重要： --api-key 主要保护 /v1（以及文档列出的 /v2、/inference 等前缀）。同一进程上仍可能有未纳入该鉴权的路径（官方点名过 /invocations 一类）。不要把 API Key 当成唯一安全边界；对公网应加反向代理、网络隔离。见 生产服务。

#Chat Completions

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token-abc123" \
  -d '{
    "model": "Qwen/Qwen2.5-0.5B-Instruct",
    "messages": [
      {"role": "system", "content": "用简洁中文回答。"},
      {"role": "user", "content": "连续批处理和静态批处理差在哪？"}
    ],
    "temperature": 0.7,
    "max_tokens": 200
  }'

流式："stream": true，按 SSE 读行。Python：

stream = client.chat.completions.create(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    messages=[{"role": "user", "content": "Count from 1 to 5."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

官方兼容层还可能提供 Embeddings、音频转写、Responses 等——仅当加载的模型类型匹配时才有意义。本课聚焦文本 chat/completions。

#Completions（非聊天）

comp = client.completions.create(
    model="facebook/opt-125m",
    prompt="The meaning of life is",
    max_tokens=32,
)
print(comp.choices[0].text)

OpenAI 已把 Completions 标为遗留，但 vLLM 仍支持，便于底座 LM 与旧脚本。新应用优先 Chat。

#OpenAI 没有的参数：extra_body

例如 top_k、结构化输出等，可通过 extra_body 传入（字段名随版本变，以当前文档为准）：

completion = client.chat.completions.create(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    messages=[{"role": "user", "content": "Reply with a single word: yes or no."}],
    extra_body={"top_k": 20},
)

直接 HTTP 时，把这些键并进 JSON 即可。更多采样语义见 采样与生成参数。

#默认采样从哪来？

若 Hub 仓库带 generation_config.json，服务器可能用模型作者的推荐值覆盖部分默认采样。这是特性不是 bug。若要强制 vLLM 自带默认，启动时可试：

vllm serve Qwen/Qwen2.5-0.5B-Instruct --generation-config vllm

该标志是否仍叫这个名字，以 --help 为准。

#接到 LangChain / 其他框架

把 OpenAI 兼容客户端的 base_url 指过来即可。LangChain 侧通常是自定义 OpenAI 兼容 endpoint（包名随 1.x 变化，见 LangChain）。model= 必须与 vllm serve 加载的 ID 一致。

应用在 Docker、vLLM 在宿主机时，容器内不要写 localhost，应使用 host.docker.internal 或 compose 网络名。

#常见错误

#下一步

• 采样与生成参数
• 生产服务
• 实战案例