Python 调用 Ollama 本地大模型 API 完全指南
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"],, flush=True) print() # 换行 ⚠️ 注意：流式响应返回的是 JSON Lines（每行一个 JSON 对象），需逐行解析。
七、总结
通过 Ollama 的 HTTP API，Python 开发者可以：
- 在本地安全、私有地调用大模型；
- 构建离线 AI 应用（如智能客服、文档摘要、代码助手）；
- 无缝集成到 Flask/FastAPI/Web 应用中。
核心优势：
✅ 无需联网
✅ 支持多种开源模型
✅ API 简洁易用
✅ 完全免费 & 开源
📌 提示：Ollama 还支持自定义 Modelfile 微调提示词，进一步提升模型表现。
现在，你已经掌握了在 Python 中调用 Ollama 的全部基础知识。快去试试用本地 LLM 构建你的第一个 AI 应用吧！
