中级 15 分钟API

通过 API 将 Ollama 集成到 Python 应用中 REST

通过 REST API 在 Python 应用中集成 Ollama

Ollama 在 11434 端口提供两个 HTTP API:原生 API(/api/generate、/api/chat)和兼容 OpenAI 的 API(/v1/chat/completions)。后者是在 Python 中集成 Ollama API 的首选方式:您的代码使用与调用 GPT-4 完全相同的 SDK,但运行在您自己的机器上。本指南介绍具体的实现模式——流式输出、结构化 JSON、函数调用——并提供可直接粘贴到项目中的 FastAPI 和 Flask 示例。

作者: Mohamed Meguedmi·更新于 2026-08-27·已在 Windows、macOS 和 Linux 上测试

#为什么使用 REST API

CLI 工具 ollama run 适合测试,但并非为应用程序调用而设计。REST API 则是为此而设计:支持标准 HTTP 请求,输入输出为 JSON,通过 Server-Sent Events 实现流式传输。所有界面(Open WebUI、Cline、LangChain)底层均采用此方案。

OpenAI 兼容性
/v1/chat/completions 端点接受的 payload 与 api.openai.com/v1/chat/completions 完全相同。只需更改 URL 和密钥,现有代码即可运行。
无需重复造轮子
Python 版官方 openai SDK(或任意 HTTP 客户端)可以直接与 Ollama 通信。无需学习使用专用客户端。
运行时解耦
您的 Python 应用和 Ollama 分别在各自的容器中运行。将来切换到 vLLM 或 LM Studio 时,只需更改 base_url。
同时服务多个客户端
多个 Python 脚本、一个 Jupyter 笔记本和 Open WebUI 可以同时访问同一个 Ollama 实例。守护进程会自动管理请求队列。
i
原生 API 与 OpenAI 兼容 API
Ollama 同时维护这两种 API。原生 API(/api/chat)提供专有参数(num_ctx、num_predict、mirostat),但可移植性较差。OpenAI 兼容 API 能满足 95% 的需求,换用任何其他提供商时也能继续使用。默认建议选择后者。

#先决条件

打造专属 AI 副驾驶的完整套件。

借助我们的经验和引导式路径,打造你的本地副驾驶,上手你的代码助手。

  • 在线空间,终身可用
  • PDF + 文件
  • 30 天内退款
已安装并启动 Ollama
守护进程必须在 http://localhost:11434 上监听。运行 curl http://localhost:11434 进行检查——您应看到 "Ollama is running"。
Python 3.10+
较新的 SDK(openai 1.x)要求至少使用 Python 3.8,但使用现代注解需要 Python 3.10 或更高版本。
兼容聊天的模型
ollama pull qwen3.5:9b 或 gemma4:12b。对于 function calling,请选择支持该功能的模型:Qwen 3.5、Granite 4.2、Mistral Small 24B、Devstral。
显存充足
一个 9B Q4 模型(如 Qwen 3.5 9B)需要约 6-7 GB 显存,一个 12B 模型(Gemma 4 12B)需要约 8 GB。没有 GPU 也可以运行,但速度为 5-10 tok/s。

#1. Ollama 端的两种 API

在编写 Python 之前,我们先从终端查看端点,以便清楚了解发生了什么。使用 curl,我们可以直接与守护进程通信,不经过任何抽象层。

原生 API — /api/chat
curl http://localhost:11434/api/chat -d '{
  "model": "qwen3.5:9b",
  "messages": [{"role": "user", "content": "Bonjour"}],
  "stream": false
}'
OpenAI API — /v1/chat/completions
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5:9b",
    "messages": [{"role": "user", "content": "Bonjour"}]
  }'

第二个会返回与 OpenAI 完全相同的载荷,包含 choices[0].message.content、id、model、usage 字段。正是这种一致性使得直接替换成为可能。

→
API 密钥会被忽略,但它是必需的
openai SDK 要求提供 api_key 参数。Ollama 不会验证任何内容——传入 "ollama" 或任意非空字符串即可。如果你习惯性地填入真实的 OpenAI 密钥,它会保留在你的机器上,但最好使用中性字符串,以免造成混淆。

#2. 指向 Ollama 的 OpenAI SDK

集成 Ollama Python API 的基本模式只需五行:安装 OpenAI SDK,使用本地 base_url 实例化,然后像往常一样调用 chat.completions.create。

安装
pip install openai
client.py — 基本调用
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # ignoré, mais requis par le SDK
)

reponse = client.chat.completions.create(
    model="qwen3.5:9b",
    messages=[
        {"role": "system", "content": "Tu réponds en français, de façon concise."},
        {"role": "user", "content": "Explique en une phrase ce qu'est un LLM."},
    ],
    temperature=0.3,
)

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

运行脚本。如果 Ollama 正在运行且模型已下载,您将得到一个句子。如果看到 ConnectionRefusedError,请使用 ollama ps 检查守护进程是否处于活动状态。

model
ollama list 中列出的确切名称(qwen3.5:9b、gemma4:12b、mistral-small 等)。
messages
对话消息列表。支持的角色:system、user、assistant、tool。
temperature
确定性任务使用 0,创意任务使用 0.7。对于数据提取,保持在 0 或 0.1。
max_tokens
响应长度上限。可选——Ollama 会为 num_predict 应用一个合理的默认值。

#3. 通过 SSE 逐个 token 进行流式传输

对于良好的 UX(聊天机器人、长文本生成),您需要逐个显示 tokens,而不是等到生成结束。Ollama 支持通过 Server-Sent Events 进行流式传输,而 OpenAI SDK 可以用一个简单的 Python 循环实现这一点。

streaming.py
from openai import OpenAI

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

flux = client.chat.completions.create(
    model="qwen3.5:9b",
    messages=[{"role": "user", "content": "Raconte une courte histoire de robot."}],
    stream=True,
)

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

每个分块都包含一个 delta(新增的文本片段)。最后一个分块的 delta.content 为 None,并且填有 finish_reason——这就是停止信号。

!
不要忘记 flush=True
没有 flush=True 时,Python 会按行缓冲 stdout,终端中的流式效果就会消失。不过,对于 HTTP API,负责 flush 的是 Web 服务器(uvicorn、gunicorn),无需手动处理。

#4. 使用 JSON 模式生成结构化输出

当您需要解析响应(提取、分类、生成 payload)时,仅在提示词中要求“返回 JSON”并不够——模型经常会在外围插入文本。JSON mode 会强制解码器只生成有效 JSON。

json_mode.py
from openai import OpenAI
import json

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

reponse = client.chat.completions.create(
    model="qwen3.5:9b",
    messages=[
        {"role": "system", "content": (
            "Tu extrais des informations structurées. "
            "Réponds uniquement avec un objet JSON contenant les clés : "
            "nom (string), age (int), ville (string)."
        )},
        {"role": "user", "content": "Marie a 34 ans, elle habite à Lyon."},
    ],
    response_format={"type": "json_object"},
    temperature=0,
)

donnees = json.loads(reponse.choices[0].message.content)
print(donnees)
# {'nom': 'Marie', 'age': 34, 'ville': 'Lyon'}

response_format={"type": "json_object"} 会启用 JSON 模式。在 Ollama 方面,这会转化为采样器级别的约束:任何会生成无效 JSON 的 token 都会被拒绝。这比提示“以 JSON 格式回答”后祈祷结果正确更可靠。

→
在 prompt 中提及“JSON”
与 OpenAI 一样,JSON 模式要求对话中(system 或 user)至少出现一次“JSON”一词。否则,某些模型会生成空对象。请在 system prompt 中描述预期的架构——这会引导内容,而 JSON 模式只负责保证语法正确。

#5. Function calling(工具使用)

function calling 允许模型发出调用 Python 函数的信号,而不是直接回答。并非所有模型都支持此功能——请在 ollama.com/library 上确认其能力中出现了 "tools"。Qwen 3.5、Granite 4.2、Mistral Small 24B 和 Devstral 原生支持该功能。

tools.py
from openai import OpenAI
import json

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

# 1. Une fonction Python réelle
def meteo(ville: str) -> dict:
    # En vrai, vous appelleriez Open-Meteo ou autre
    return {"ville": ville, "temperature_c": 18, "conditions": "nuageux"}

# 2. Sa description au format OpenAI
outils = [{
    "type": "function",
    "function": {
        "name": "meteo",
        "description": "Donne la météo actuelle d'une ville française.",
        "parameters": {
            "type": "object",
            "properties": {
                "ville": {"type": "string", "description": "Nom de la ville"},
            },
            "required": ["ville"],
        },
    },
}]

messages = [{"role": "user", "content": "Quel temps fait-il à Bordeaux ?"}]

# 3. Premier appel : le modèle décide d'appeler la fonction
reponse = client.chat.completions.create(
    model="qwen3.5:9b",
    messages=messages,
    tools=outils,
)

appel = reponse.choices[0].message.tool_calls[0]
args = json.loads(appel.function.arguments)
resultat = meteo(**args)

# 4. Second appel : on renvoie le résultat au modèle pour la réponse finale
messages.append(reponse.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": appel.id,
    "content": json.dumps(resultat),
})

finale = client.chat.completions.create(model="qwen3.5:9b", messages=messages)
print(finale.choices[0].message.content)

这个循环有两轮:第一轮返回tool_calls(模型表示“调用meteo,参数为ville=Bordeaux”);第二轮在您执行函数并注入其结果后,返回自然语言回答。在生产环境中,只要tool_calls非空,就继续循环。

!
模型的能力并不都一样
如果模型对工具调用的支持较差(如旧版 Llama 2、Mistral 7B v0.1),就会出现格式错误的调用或凭空编造的参数。如果遇到这种情况:(1)确认模型官方支持工具调用,(2)将温度降至 0,(3)简化参数模式。

#6. 通过 FastAPI 暴露 Ollama

典型情况:你的前端调用 Python 后端,而后端调用 Ollama。FastAPI 可以妥善处理异步操作,流式响应则通过 StreamingResponse 一直传送到浏览器。

依赖项
pip install fastapi uvicorn openai
main.py
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
from openai import OpenAI

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

class Question(BaseModel):
    message: str
    model: str = "qwen3.5:9b"

@app.post("/chat")
def chat(q: Question):
    reponse = client.chat.completions.create(
        model=q.model,
        messages=[{"role": "user", "content": q.message}],
    )
    return {"reponse": reponse.choices[0].message.content}

@app.post("/chat/stream")
def chat_stream(q: Question):
    def generateur():
        flux = client.chat.completions.create(
            model=q.model,
            messages=[{"role": "user", "content": q.message}],
            stream=True,
        )
        for chunk in flux:
            delta = chunk.choices[0].delta.content
            if delta:
                yield delta
    return StreamingResponse(generateur(), media_type="text/plain")
启动服务器
uvicorn main:app --reload --port 8000
通过 CLI 测试
curl -N -X POST http://localhost:8000/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Écris un haïku sur Paris."}'

curl 的 -N(--no-buffer)选项会禁用客户端缓冲,以便实时查看流式传输。在 JS 前端中,您可以读取 fetch 响应的 ReadableStream——与 OpenAI API 的情况相同。

#7. 带历史记录的 Flask 聊天机器人

要实现完整的聊天机器人,需要在各轮对话之间保留消息历史。下面是一个极简 Flask 版本,它将对话存储在内存中(生产环境中应改用真正的会话或数据库)。

依赖项
pip install flask openai
app.py
from flask import Flask, request, jsonify, Response
from openai import OpenAI
from collections import defaultdict

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

# Historiques par session — en prod : Redis, Postgres, etc.
historiques: dict[str, list] = defaultdict(lambda: [
    {"role": "system", "content": "Tu es un assistant en français, concis et utile."},
])

@app.post("/chat/<session_id>")
def chat(session_id: str):
    message = request.json["message"]
    historique = historiques[session_id]
    historique.append({"role": "user", "content": message})

    reponse = client.chat.completions.create(
        model="qwen3.5:9b",
        messages=historique,
    )
    contenu = reponse.choices[0].message.content
    historique.append({"role": "assistant", "content": contenu})
    return jsonify({"reponse": contenu})

@app.post("/chat/<session_id>/stream")
def chat_stream(session_id: str):
    message = request.json["message"]
    historique = historiques[session_id]
    historique.append({"role": "user", "content": message})

    def generateur():
        morceaux = []
        flux = client.chat.completions.create(
            model="qwen3.5:9b",
            messages=historique,
            stream=True,
        )
        for chunk in flux:
            delta = chunk.choices[0].delta.content
            if delta:
                morceaux.append(delta)
                yield delta
        historique.append({"role": "assistant", "content": "".join(morceaux)})

    return Response(generateur(), mimetype="text/plain")

@app.delete("/chat/<session_id>")
def reset(session_id: str):
    historiques.pop(session_id, None)
    return "", 204

if __name__ == "__main__":
    app.run(port=5000, debug=True)
i
上下文限制
历史记录越长,每次调用消耗的 token 就越多。对于 Qwen 3.5,Ollama 端的默认上下文窗口为 2048 个 token——超过这一长度时,旧消息会被截断,且不会有任何提示。可以通过原生 API,或使用 Modelfile 覆盖设置来增大窗口(num_ctx 8192 或 32768)。

#用于生产环境

让网络上的设备能够访问 Ollama
默认情况下,守护进程仅监听 127.0.0.1。若要允许其他机器访问,请设置 OLLAMA_HOST=0.0.0.0 后启动,并在其前面部署带身份验证的反向代理,否则网络上的任何人都能调用您的模型。
并发与请求队列
Ollama 对每个模型的请求进行串行处理。要同时服务多个用户,请启动多个实例,或切换到原生支持动态批处理的 vLLM。
客户端超时
对尚未加载的模型发起请求可能需要 10-30 秒(加载到显存)。请设置 OpenAI 客户端的超时时间:使用 OpenAI(..., timeout=120),而不是库端默认的 10 分钟;不过对于反向代理来说通常太短。
保持模型处于加载状态
默认情况下,Ollama 会在闲置 5 分钟后卸载模型。使用 API 时,可通过原生 /api/chat 接口传入 keep_alive="30m",或定期发送 ping 请求,避免首个用户请求遇到冷启动。
可观测性
始终记录 model、prompt_tokens、completion_tokens(位于 reponse.usage 中)。这些是您的推理指标,有助于发现模型变慢或提示词长度暴增的情况。
→
从 OpenAI API 迁移
如果你已有调用 api.openai.com 的代码,切换到 Ollama 只需两行:将 base_url="https://api.openai.com/v1" 改为 base_url="http://localhost:11434/v1",并调整模型名称。其余部分——流式传输、JSON 模式、工具——都以相同方式运行。这正是 OpenAI 兼容端点的主要优势。

#深入了解

你已经具备了基础组件。根据你的使用场景,可以从三个方向进一步扩展:

构建一个能够自行决策的智能体
关于使用 LangChain 在 Python 中构建本地 AI 智能体的指南,将函数调用扩展为完整的智能体循环,涵盖多个工具的管理和多步推理。
为您的文档添加 RAG 功能
要让你的应用基于内部语料库(PDF、笔记、代码)生成回答,请接入向量数据库。本地 RAG 入门指南介绍了基础知识。
自定义模型行为
与其每次调用都重复系统提示,不如通过Modelfile创建一个模型变体。Ollama Modelfile定制指南介绍了如何将法语助手或编程模式的设置固定下来,并保存为一个可重复使用的模型名称。
这份指南对您有帮助吗?

有反馈、发现了错误,或想补充说明?请告诉我们,让这份指南对每个人都更有帮助。