Python 调用 Ollama 本地大模型 API 完全指南
Ollama 是一个开源工具，允许开发者在本地轻松运行 Llama、Mistral、Gemma 等主流大语言模型（LLM）。它不仅提供命令行交互，还内置了 HTTP API 服务，使得我们可以通过 Python 等编程语言远程调用本地模型，实现私有化、低延迟、无网络依赖的 AI 应用开发。
本文将手把手教你如何在 Python 中通过 HTTP 请求调用 Ollama 的 API，完成文本生成、对话交互等任务。
一、前提准备
1. 安装并启动 Ollama
-
官网下载安装：https://ollama.com/
-
安装后，在终端运行：
ollama run llama3 # 或 mistral、gemma、qwen 等 -
首次运行会自动下载模型（需联网），之后即可离线使用。
✅ 重要 ：Ollama 默认启动一个本地 HTTP 服务（
http://localhost:11434），即使你只运行ollama run，API 也会在后台可用。
二、Ollama API 简介
Ollama 提供了简洁的 RESTful API，核心接口为：
- POST /api/generate：用于单轮文本生成（非对话）
- POST /api/chat：用于多轮对话（推荐用于聊天场景）
本文以 /api/chat 为主，更贴近实际应用。
三、Python 调用示例（使用 requests）
首先安装依赖（如未安装）：
pip install requests示例 1：基础对话（单轮）
import requests
import json
def chat_with_ollama(prompt: str, model: str = "llama3") -> str:
url = "http://localhost:11434/api/chat"
payload = {
"model": model,
"messages": [{"role": "user", "content": prompt}],
"stream": False # 关闭流式响应，获取完整结果
}
response = requests.post(url, json=payload)
if response.status_code == 200:
result = response.json()
return result["message"]["content"]
else:
raise Exception(f"请求失败: {response.text}")
# 使用示例
answer = chat_with_ollama("你好！你能介绍一下自己吗？")
print(answer)示例 2：多轮对话（带上下文）
def multi_turn_chat():
messages = []
model = "mistral" # 可替换为你本地已安装的模型
while True:
user_input = input("你: ")
if user_input.lower() in ["退出", "quit", "exit"]:
break
messages.append({"role": "user", "content": user_input})
resp = requests.post(
"http://localhost:11434/api/chat",
json={
"model": model,
"messages": messages,
"stream": False
}
)
if resp.ok:
reply = resp.json()["message"]["content"]
print(f"AI: {reply}")
messages.append({"role": "assistant", "content": reply})
else:
print("出错了:", resp.text)
break
# 启动对话
multi_turn_chat()四、关键参数说明
| 参数 | 说明 |
|---|---|
model |
模型名称，必须是你本地已通过 ollama pull 或 run 下载的（如 llama3, qwen:7b, gemma:2b） |
messages |
对话历史，格式为 [{"role": "user/assistant", "content": "..."}] |
stream |
是否启用流式输出。设为 True 时需逐块解析响应（适合 Web 实时展示），False 则返回完整结果 |
options |
可选，用于设置 temperature、max_tokens 等（见下文） |
添加生成参数（如温度、最大长度）：
payload = {
"model": "llama3",
"messages": [{"role": "user", "content": "写一首诗"}],
"stream": False,
"options": {
"temperature": 0.7,
"num_predict": 100, # 最大生成 token 数
"top_p": 0.9
}
}五、常见问题排查
❌ 问题 1：Connection refused 或无法连接
- 原因：Ollama 服务未运行
- 解决 ：确保终端中已运行
ollama serve或至少执行过一次ollama run xxx
❌ 问题 2：model not found
- 原因：指定的模型未下载
- 解决 ：先在终端执行
ollama pull llama3（替换为你想用的模型）
❌ 问题 3：响应慢或卡住
- 尝试关闭
stream（设为False） - 检查模型是否过大（如 70B 模型需高性能 GPU）
六、进阶：流式响应（Stream）
若需实时输出（如打字机效果），可启用流式模式：
def stream_chat(prompt: str, model: str = "llama3"):
url = "http://localhost:11434/api/chat"
payload = {
"model": model,
"messages": [{"role": "user", "body": prompt}],
"stream": True
}
with requests.post(url, json=payload, stream=True) as r:
for line in r.iter_lines():
if line:
chunk = json.loads(line)
if "message" in chunk:
print(chunk["message"]["content"], end="", flush=True)
print() # 换行⚠️ 注意：流式响应返回的是 JSON Lines（每行一个 JSON 对象），需逐行解析。
七、总结
通过 Ollama 的 HTTP API，Python 开发者可以：
- 在本地安全、私有地调用大模型；
- 构建离线 AI 应用（如智能客服、文档摘要、代码助手）；
- 无缝集成到 Flask/FastAPI/Web 应用中。
核心优势 ：
✅ 无需联网
✅ 支持多种开源模型
✅ API 简洁易用
✅ 完全免费 & 开源
📌 提示：Ollama 还支持自定义 Modelfile 微调提示词，进一步提升模型表现。
现在，你已经掌握了在 Python 中调用 Ollama 的全部基础知识。快去试试用本地 LLM 构建你的第一个 AI 应用吧！