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

使用 OpenAI 兼容接口

使用 OpenAI 兼容接口

学习目标

完成本课后,你将能够:

  • 使用 /v1 基础地址连接 Ollama
  • 通过 OpenAI Python SDK 调用聊天接口
  • 理解本地 API Key 的占位作用
  • 在迁移前拉取并验证模型名称

兼容接口的价值

许多应用和框架已经支持 OpenAI API。Ollama 提供 /v1 兼容端点,使现有客户端只需修改基础地址和模型名即可接入本地模型。

兼容不等于完全一致。迁移后仍要测试字段、流式、工具、思考和上下文设置。

准备模型

执行:

bash
ollama pull gemma3:1b

预期输出最终包含:

text
success

验证模型名称:

bash
ollama list

预期输出中包含:

text
gemma3:1b    <MODEL_ID>    <SIZE>    <MODIFIED>

使用 curl 调用

执行:

bash
curl --fail --silent --show-error   http://localhost:11434/v1/chat/completions   -H "Content-Type: application/json"   -d '{
    "model": "gemma3:1b",
    "messages": [
      {
        "role": "user",
        "content": "用一句话解释 OpenAI 兼容接口。"
      }
    ],
    "temperature": 0
  }'

预期响应结构:

json
{
  "id": "<ID>",
  "object": "chat.completion",
  "created": 0,
  "model": "gemma3:1b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "<MODEL_RESPONSE>"
      },
      "finish_reason": "<FINISH_REASON>"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

ID、时间和 Token 计数为动态值。

Python OpenAI SDK

安装:

bash
python -m pip install openai

预期输出:

text
Successfully installed openai-<VERSION> ...

保存为 openai_compatible.py:

python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",
)

response = client.chat.completions.create(
    model="gemma3:1b",
    messages=[
        {
            "role": "system",
            "content": "你是技术助教,使用简体中文。",
        },
        {
            "role": "user",
            "content": "Ollama 兼容接口适合什么场景?",
        },
    ],
    temperature=0,
)

content = response.choices[0].message.content
if not content:
    raise SystemExit("模型返回空内容")

print(content.strip())
print(f"model={response.model}")

运行:

bash
python openai_compatible.py

预期输出结构:

text
<MODEL_RESPONSE>
model=<MODEL_NAME>

API Key 的含义

OpenAI SDK 通常要求 api_key 非空。本地 Ollama 兼容接口示例中可使用 "ollama",该值在默认本地服务中不会提供真正认证。

一旦服务经过企业网关,API Key 是否有效由网关实现决定。不要因为 SDK 中填写了字符串,就认为默认 Ollama 已受保护。

固定默认模型名称

某些旧工具写死 gpt-3.5-turbo。可以创建本地别名:

bash
ollama cp gemma3:1b gpt-3.5-turbo

预期结果:

text
ollama list 中出现 gpt-3.5-turbo。

这种别名只解决名称兼容,不会让本地模型具备云端模型相同能力。应用应在界面和文档中明确真实模型来源。

流式调用

Python SDK:

python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",
)

stream = client.chat.completions.create(
    model="gemma3:1b",
    messages=[{"role": "user", "content": "列出三个迁移检查项。"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

print()

预期输出:

text
<INCREMENTAL_MODEL_RESPONSE>

迁移验收

至少验证:

  • 非流式聊天
  • 流式聊天
  • 系统消息
  • JSON 模式
  • 工具调用
  • 错误响应
  • 超时与取消
  • 模型名称
  • Token 统计
  • 上下文配置

只有基础聊天成功,不能证明整个框架兼容。

本课练习

练习 1:迁移现有脚本

任务目标:只修改地址和模型名完成本地调用。输入或初始条件:一个使用 OpenAI Python SDK 的聊天脚本。实现要求:接入 /v1/。验收条件:非流式和流式均正常。

练习 2:验证 API Key 边界

任务目标:理解占位值不是认证。输入或初始条件:默认本地 Ollama 服务。实现要求:使用不同非空 key 调用。验收条件:说明为什么仍需代理层认证。

练习 3:建立兼容测试表

任务目标:覆盖真实功能。输入或初始条件:应用使用聊天、JSON 和工具。实现要求:逐项验证并记录差异。验收条件:不支持或行为不同的功能有降级方案。

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

目录与阅读设置

阅读设置

17

记录一个想法

使用 OpenAI 兼容接口

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

登录哪都通