大模型应用开发 / 系统课时
使用 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 和工具。实现要求:逐项验证并记录差异。验收条件:不支持或行为不同的功能有降级方案。
按自己的节奏,确认真正理解。