OpenAI 兼容性

Ollama 提供了与 OpenAI API 兼容的接口，让您可以轻松地将现有的 OpenAI 应用迁移到 Ollama，或者使用熟悉的 OpenAI SDK 来访问本地模型。

基础配置

API 端点

Ollama 的 OpenAI 兼容端点：

http://localhost:11434/v1

认证

Ollama 本地运行时不需要 API 密钥，但为了兼容性，您可以设置任意值：

export OPENAI_API_KEY="ollama"
export OPENAI_BASE_URL="http://localhost:11434/v1"

支持的端点

Chat Completions

与 OpenAI 的 /v1/chat/completions 端点兼容。

POST /v1/chat/completions

请求示例:

{
  "model": "gemma3",
  "messages": [
    {
      "role": "system",
      "content": "你是一个有用的助手。"
    },
    {
      "role": "user",
      "content": "解释什么是机器学习"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 1000,
  "stream": false
}

Completions

与 OpenAI 的 /v1/completions 端点兼容。

POST /v1/completions

请求示例:

{
  "model": "gemma3",
  "prompt": "人工智能的未来发展趋势是",
  "max_tokens": 500,
  "temperature": 0.8
}

Models

列出可用的模型。

GET /v1/models

客户端库使用

Python (OpenAI SDK)

安装 OpenAI Python 库：

pip install openai

基本使用:

from openai import OpenAI

# 配置客户端
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"  # 任意值
)

# 聊天完成
response = client.chat.completions.create(
    model="gemma3",
    messages=[
        {"role": "system", "content": "你是一个编程助手。"},
        {"role": "user", "content": "如何用 Python 读取 CSV 文件？"}
    ],
    temperature=0.7,
    max_tokens=1000
)

print(response.choices[0].message.content)

流式响应:

stream = client.chat.completions.create(
    model="gemma3",
    messages=[
        {"role": "user", "content": "写一首关于春天的诗"}
    ],
    stream=True
)

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

文本完成:

response = client.completions.create(
    model="gemma3",
    prompt="人工智能的三个主要应用领域是：",
    max_tokens=200,
    temperature=0.5
)

print(response.choices[0].text)

JavaScript/Node.js

安装 OpenAI JavaScript 库：

npm install openai

基本使用:

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'http://localhost:11434/v1',
  apiKey: 'ollama' // 任意值
});

async function main() {
  const completion = await openai.chat.completions.create({
    messages: [
      { role: 'system', content: '你是一个有用的助手。' },
      { role: 'user', content: '解释什么是深度学习' }
    ],
    model: 'gemma3',
    temperature: 0.7,
    max_tokens: 1000
  });

  console.log(completion.choices[0].message.content);
}

main();

流式响应:

async function streamExample() {
  const stream = await openai.chat.completions.create({
    model: 'gemma3',
    messages: [{ role: 'user', content: '讲一个有趣的故事' }],
    stream: true,
  });

  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || '');
  }
}

cURL 示例

聊天完成:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ollama" \
  -d '{
    "model": "gemma3",
    "messages": [
      {
        "role": "system",
        "content": "你是一个有用的助手。"
      },
      {
        "role": "user",
        "content": "什么是量子计算？"
      }
    ],
    "temperature": 0.7
  }'

流式响应:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ollama" \
  -d '{
    "model": "gemma3",
    "messages": [
      {
        "role": "user",
        "content": "写一个 Python 函数来计算斐波那契数列"
      }
    ],
    "stream": true
  }'

参数映射

支持的参数

OpenAI 参数	Ollama 支持	说明
model	✅	模型名称
messages	✅	聊天消息数组
prompt	✅	文本提示（completions 端点）
temperature	✅	温度参数 (0.0-2.0)
max_tokens	✅	最大令牌数
top_p	✅	Top-p 采样
stream	✅	流式响应
stop	✅	停止词
presence_penalty	❌	不支持
frequency_penalty	❌	不支持
logit_bias	❌	不支持
user	❌	不支持

参数转换

Ollama 会自动将 OpenAI 参数转换为内部参数：

{
  "temperature": 0.7,     // → temperature
  "max_tokens": 1000,     // → num_predict
  "top_p": 0.9,          // → top_p
  "stop": ["<|end|>"]    // → stop
}

模型映射

可用模型

您可以使用 Ollama 中的任何模型：

# 列出可用模型
curl http://localhost:11434/v1/models

响应示例:

{
  "object": "list",
  "data": [
    {
      "id": "gemma3",
      "object": "model",
      "created": 1699564800,
      "owned_by": "ollama"
    },
    {
      "id": "qwen3",
      "object": "model",
      "created": 1699564800,
      "owned_by": "ollama"
    }
  ]
}

迁移指南

从 OpenAI 迁移

1. 更新基础 URL:

# 原来
client = OpenAI(api_key="your-openai-key")

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

2. 更新模型名称:

# 原来
model="gpt-3.5-turbo"

# 现在
model="gemma3"

3. 调整参数:

# 某些 OpenAI 特有参数需要移除
response = client.chat.completions.create(
    model="gemma3",
    messages=messages,
    temperature=0.7,
    max_tokens=1000,
    # presence_penalty=0.1,  # 移除不支持的参数
    # frequency_penalty=0.1  # 移除不支持的参数
)

环境变量配置

创建 .env 文件：

OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1

在代码中使用：

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv("OPENAI_BASE_URL"),
    api_key=os.getenv("OPENAI_API_KEY")
)

高级用法

自定义系统提示

def create_assistant(system_prompt, model="gemma3"):
    def chat(user_message):
        response = client.chat.completions.create(
            model=model,
            messages=[
                {"role": "system", "content": system_prompt},
                {"role": "user", "content": user_message}
            ]
        )
        return response.choices[0].message.content
    return chat

# 创建编程助手
code_assistant = create_assistant(
    "你是一个专业的编程助手，请提供清晰的代码示例。"
)

result = code_assistant("如何用 Python 连接数据库？")
print(result)

批量处理

def batch_process(prompts, model="gemma3"):
    results = []
    for prompt in prompts:
        response = client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": prompt}],
            temperature=0.3
        )
        results.append(response.choices[0].message.content)
    return results

prompts = [
    "解释机器学习",
    "什么是深度学习",
    "人工智能的应用"
]

results = batch_process(prompts)
for i, result in enumerate(results):
    print(f"问题 {i+1}: {result}\n")

函数调用模拟

虽然 Ollama 不直接支持 OpenAI 的函数调用，但可以通过提示工程实现类似功能：

def simulate_function_calling(user_query, available_functions):
    system_prompt = f"""
你是一个助手，可以调用以下函数：
{available_functions}

请根据用户查询决定是否需要调用函数，如果需要，请返回 JSON 格式的函数调用。
"""
    
    response = client.chat.completions.create(
        model="gemma3",
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_query}
        ]
    )
    
    return response.choices[0].message.content

functions = """
- get_weather(location): 获取指定位置的天气
- calculate(expression): 计算数学表达式
- search_web(query): 搜索网络信息
"""

result = simulate_function_calling("北京今天天气怎么样？", functions)
print(result)

性能优化

连接池

import httpx
from openai import OpenAI

# 使用自定义 HTTP 客户端
http_client = httpx.Client(
    limits=httpx.Limits(max_connections=10, max_keepalive_connections=5)
)

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

异步处理

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"
)

async def async_chat(message):
    response = await async_client.chat.completions.create(
        model="gemma3",
        messages=[{"role": "user", "content": message}]
    )
    return response.choices[0].message.content

async def main():
    tasks = [
        async_chat("什么是 AI？"),
        async_chat("什么是 ML？"),
        async_chat("什么是 DL？")
    ]
    results = await asyncio.gather(*tasks)
    for result in results:
        print(result)

asyncio.run(main())

故障排除

常见问题

问题: 连接被拒绝

Connection refused

解决方案: 确保 Ollama 服务器正在运行：

ollama serve

问题: 模型未找到

Model not found

解决方案: 确保模型已下载：

ollama pull gemma3

问题: 参数不支持

Invalid parameter

解决方案: 移除 Ollama 不支持的 OpenAI 特有参数

调试技巧

启用详细日志：

import logging
logging.basicConfig(level=logging.DEBUG)

# 或者使用 httpx 的调试
import httpx
http_client = httpx.Client(event_hooks={'request': [print], 'response': [print]})

更多资源

• API 文档
• CLI 参考
• 模型库

---

通过 OpenAI 兼容接口，您可以无缝地将现有应用迁移到 Ollama，享受本地部署的优势同时保持熟悉的开发体验。