本指南向你展示原理。 该工具包提供完整配置——Cline + Aider + 已调优的配置,30 分钟内即可就绪。 本地编程副驾驶套件 → # 为什么使用 REST APICLI 工具 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 副驾驶的完整套件。
借助我们的经验和引导式路径,打造你的本地副驾驶,上手你的代码助手。
已安装并启动 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。
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 模式只负责保证语法正确。
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 openaimain.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 openaiapp.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定制指南介绍了如何将法语助手或编程模式的设置固定下来,并保存为一个可重复使用的模型名称。 本地编程副驾驶套件
这套开箱即用、首次运行就能正常工作的配置
本指南向你展示原理。该套餐 「本地代码副驾」 提供所有可直接粘贴的配置(Ollama + Cline + Aider + Tabby)、已调优的 Modelfiles 以及故障排除章节,让你在 30 分钟内用起来。我们也会坦诚地说明本地运行在哪些方面并不能替代云端。
查看工具包 → 一次性付费 · 终身更新 免费备忘录
接收速查表 显存 → 最佳代码模型 → Ollama 命令 通过电子邮件。一个屏幕,复制粘贴,保持最新。
无垃圾邮件。1 次点击即可退订。你的数据保留在我们这里。
这份指南对您有帮助吗?
有反馈、发现了错误,或想补充说明?请告诉我们,让这份指南对每个人都更有帮助。
👍 有用 👎 不清楚 ✏️ 报告错误