Ollama API实战：用Python玩转文本生成与多轮对话（兼容OpenAI格式）
Ollama API实战：用Python玩转文本生成与多轮对话（兼容OpenAI格式）
最近在折腾本地大模型部署的朋友，估计没少跟Ollama打交道。这玩意儿确实方便，一条命令就能把各种开源模型拉下来跑起来，省去了手动配置环境的麻烦。但很多开发者把模型跑起来之后，卡在了下一步：怎么把它真正用起来？怎么集成到自己的Python应用里？特别是那些习惯了OpenAI API简洁风格的开发者，面对Ollama的原生接口总觉得有点“水土不服”。
其实，Ollama的API设计得相当友好，不仅提供了功能完备的原生接口，还贴心地兼容了OpenAI的API格式。这意味着，你之前为ChatGPT写的代码，稍作修改就能直接对接本地部署的模型。无论是想做个能记住聊天历史的智能助手，还是批量生成营销文案的自动化工具，Ollama都能成为你可靠的后端引擎。
这篇文章，我就以一个实际项目开发者的角度，带你深入Ollama的API世界。我们不只讲简单的调用，还会聊聊如何根据实际需求调整配置、如何处理流式响应提升用户体验，以及如何利用OpenAI客户端库写出更优雅的代码。目标很明确：让你手里的Ollama，从一个“玩具”变成能扛起生产任务的“利器”。
1. 基础准备与环境调优
在开始写代码之前，确保你的Ollama服务处于最佳工作状态很重要。默认安装后，它只监听本机的11434端口，这适合快速测试，但如果你想从其他机器（比如另一台开发机或Docker容器）调用，或者需要调整模型存储位置，就得动一动环境变量了。
1.1 服务访问范围配置
默认情况下，Ollama绑定在127.0.0.1上，这是出于安全考虑。但在开发阶段，你可能需要从局域网内的另一台电脑进行调试，或者在服务器上部署供多个应用调用。这时，修改OLLAMA_HOST环境变量就能轻松实现。
在Linux或macOS上，你可以通过终端直接设置：
export OLLAMA_HOST=0.0.0.0:11434
然后重启Ollama服务。这个0.0.0.0意味着监听所有网络接口，让任何能访问到这台机器的IP都能连接。
在Windows上，步骤类似：
- 打开“系统属性” -> “高级” -> “环境变量”。
- 在“系统变量”或“用户变量”中，点击“新建”。
- 变量名填
OLLAMA_HOST，变量值填0.0.0.0:11434。 - 保存后，重启Ollama（可能需要重启命令行或整个系统使变量生效）。
注意：将服务暴露在
0.0.0.0会带来安全风险，请确保仅在可信的局域网环境或配置了防火墙规则的生产环境中使用。对于公网访问，务必结合更严格的身份验证和网络隔离措施。
1.2 自定义模型存储路径
Ollama下载的模型默认会放在用户目录下（例如Windows的C:\Users\你的用户名\.ollama\models）。如果C盘空间紧张，或者你希望统一管理所有AI资源，可以指定一个新的存储位置。
通过设置OLLAMA_MODELS环境变量即可实现：
- 变量名:
OLLAMA_MODELS - 变量值: 你想要存放模型的完整路径，例如
D:\AI_Models\ollama或/mnt/data/ollama_models。
设置完成后，务必重启Ollama服务。之后所有ollama pull命令下载的模型，都会乖乖地存放到你指定的新目录里。这个功能对于使用NAS、网络存储或者Docker卷映射的场景特别有用。
1.3 处理跨域请求（CORS）
如果你正在开发一个前端Web应用（比如用Vue或React写的聊天界面），并且前端页面与Ollama服务不在同一个域名或端口下，浏览器会因为同源策略而阻止API调用。为了解决这个问题，需要配置Ollama允许跨域请求。
通过设置OLLAMA_ORIGINS环境变量，你可以指定允许访问的来源：
- 允许特定前端地址：
export OLLAMA_ORIGINS=https://your-app.com,http://localhost:3000 - 开发阶段允许所有来源（不推荐用于生产）：
export OLLAMA_ORIGINS=*
这里有一个关键细节：Ollama的环境变量名称必须全部大写，像OLLAMA_ORIGINS，写成ollama_origins是无效的。我刚开始就踩过这个坑，排查了半天才发现是大小写问题。
为了方便管理，我通常会把所有配置写进一个启动脚本里。下面是一个Linux服务单元文件（/etc/systemd/system/ollama.service）的配置片段示例，展示了如何集中设置这些变量：
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_MODELS=/data/ollama/models"
Environment="OLLAMA_ORIGINS=http://localhost:5173,http://192.168.1.100:8080"
ExecStart=/usr/local/bin/ollama serve
2. 掌握Ollama原生API的核心调用
搞定了环境，我们终于可以进入正题——写代码。Ollama的原生API设计得很直观，主要围绕两个核心端点：/api/generate 用于单轮文本补全，/api/chat 用于多轮对话。我们用最常用的requests库来演示。
2.1 文本生成：/api/generate 接口详解
这个接口的行为很像一个“高级版的文本预测”，你给它一段提示（prompt），它根据模型所学，生成后续的文本。它不关心对话历史，每次请求都是独立的。这非常适合内容创作、代码补全、摘要生成等场景。
一个最基本的请求看起来是这样的：
import requests
import json
url = "http://localhost:11434/api/generate"
payload = {
"model": "llama3.2:1b", # 指定要使用的模型
"prompt": "请用Python写一个函数，计算斐波那契数列的第n项。",
"stream": False, # 是否使用流式输出，稍后细说
"options": {
"temperature": 0.8, # 创造性，值越高输出越随机
"top_p": 0.9, # 核采样，控制输出词汇的集中度
"num_predict": 256 # 最多生成多少个token
}
}
response = requests.post(url, json=payload)
if response.status_code == 200:
result = response.json()
print("生成结果：", result['response'])
else:
print(f"请求失败: {response.status_code}", response.text)
关键参数解析：
model: 字符串，必须是你本地通过ollama pull下载好的模型名。prompt: 字符串，你的输入指令或问题。stream: 布尔值。设为False时，服务器会等整个文本生成完毕一次性返回；设为True时，会以SSE（Server-Sent Events）流的形式逐步返回token，适合需要实时显示的场景。options: 一个字典，用于精细控制生成过程。除了上面提到的，还有几个常用的：seed: 设置随机种子，让每次生成结果可复现，对调试很有帮助。repeat_penalty: 抑制重复词汇的惩罚系数，设置1.1左右可以有效减少车轱辘话。stop: 一个字符串列表，遇到这些词时停止生成，例如["\n", "。", "User:"]。
2.2 流式响应处理：提升用户体验的关键
当stream=True时，API的响应不再是单一的JSON对象，而是一行行的事件流。每行都是一个独立的JSON对象，包含当前生成的片段或最终状态。处理流式响应能让你在生成长篇内容时，实时地将文字“打印”出来，就像真正的对话一样，体验好很多。
def generate_with_stream(prompt_text, model_name="llama3.2:1b"):
url = "http://localhost:11434/api/generate"
payload = {
"model": model_name,
"prompt": prompt_text,
"stream": True,
"options": {"temperature": 0.7}
}
full_response = ""
try:
# 使用stream=True参数，使requests迭代响应内容
with requests.post(url, json=payload, stream=True) as r:
r.raise_for_status()
for line in r.iter_lines():
if line:
# 每行数据以 "data: " 开头
decoded_line = line.decode('utf-8')
if decoded_line.startswith('data: '):
json_str = decoded_line[6:] # 去掉"data: "前缀
if json_str.strip() == '[DONE]':
break
try:
chunk = json.loads(json_str)
word = chunk.get('response', '')
if word:
print(word, end='', flush=True) # 关键：实时打印
full_response += word
except json.JSONDecodeError:
continue
print() # 最后换行
return full_response
except requests.exceptions.RequestException as e:
print(f"\n请求发生错误: {e}")
return None
# 使用示例
result = generate_with_stream("给我讲一个关于机器学习的短故事。")
这种流式处理在开发聊天机器人前端时是标配。前端可以通过WebSocket或EventSource API连接到这个流，实现打字机效果。
2.3 对话聊天：/api/chat 接口与上下文管理
聊天接口才是Ollama的“完全体”。它要求你以消息列表（messages）的形式提供输入，模型会基于整个对话历史来生成回复，从而实现有记忆的、连贯的多轮对话。
消息列表中的每个元素都是一个字典，包含role和content两个键。role有三种：
system: 在对话开始时设定助手的行为和角色，例如“你是一个幽默的编程专家”。user: 代表用户说的话。assistant: 代表模型之前的回复。
下面是一个模拟技术客服的完整示例：
import requests
import json
def chat_with_ollama(messages_history, model="qwen2.5:7b"):
url = "http://localhost:11434/api/chat"
payload = {
"model": model,
"messages": messages_history,
"stream": False,
"options": {"temperature": 0.5} # 客服回答可以更稳定一些
}
response = requests.post(url, json=payload)
if response.status_code == 200:
result = response.json()
# 注意：聊天接口返回的回复在 `message['content']` 里
assistant_reply = result['message']['content']
return assistant_reply
else:
print(f"聊天请求失败: {response.status_code}")
return None
# 初始化对话
conversation = [
{"role": "system", "content": "你是一名专业的云计算技术支持工程师，回答要清晰、准确、有条理。"},
{"role": "user", "content": "我的服务器CPU使用率突然飙升到100%，可能是什么原因？"}
]
# 第一轮
reply1 = chat_with_ollama(conversation)
print(f"AI客服: {reply1}")
# 将AI的回复加入历史，再提出后续问题
conversation.append({"role": "assistant", "content": reply1})
conversation.append({"role": "user", "content": "如果是代码死循环，用什么Linux命令能最快定位到问题进程？"})
# 第二轮（模型能基于之前的对话历史理解上下文）
reply2 = chat_with_ollama(conversation)
print(f"AI客服: {reply2}")
管理上下文长度的技巧：
模型能处理的上下文长度（Token数）是有限的。在长时间对话后，你可能需要手动修剪历史消息，以防止超出限制导致错误或性能下降。一个常见的策略是保留最近的N轮对话，或者只保留system提示和最近几组user/assistant配对。
3. 拥抱兼容性：使用OpenAI客户端库调用Ollama
如果你之前开发过基于ChatGPT的应用，那么你对openai这个Python库一定不陌生。好消息是，Ollama直接兼容了OpenAI的API格式，这意味着你几乎可以零成本地将现有代码迁移到本地模型上。只需要把API的基地址（base_url）指向你的Ollama服务即可。
3.1 单次对话请求的迁移
对比一下，使用OpenAI库的代码有多么简洁：
from openai import OpenAI
# 关键一步：将客户端指向本地的Ollama服务
client = OpenAI(
base_url="http://localhost:11434/v1", # Ollama的OpenAI兼容端点
api_key="ollama" # 这个字段必填，但Ollama不验证，可以填任意非空字符串
)
response = client.chat.completions.create(
model="mistral:7b", # 使用你本地有的模型
messages=[
{"role": "system", "content": "你是一位资深美食评论家。"},
{"role": "user", "content": "从色、香、味、形四个方面，评价一下红烧肉这道菜。"}
],
temperature=0.8,
max_tokens=500
)
# 输出结果
print(response.choices[0].message.content)
看，除了base_url和model名称，其他部分和调用真正的OpenAI API一模一样。api_key参数在这里只是个形式，Ollama并不做认证。这种兼容性极大地降低了学习和集成成本。
3.2 构建一个交互式多轮对话终端
利用OpenAI库和其返回的标准化对象，我们可以轻松构建一个更健壮、功能更丰富的命令行聊天程序。下面这个例子增加了错误处理、对话历史持久化的可能性：
from openai import OpenAI
import json
from pathlib import Path
class OllamaChatSession:
def __init__(self, model_name="llama3.2:3b", history_file=None):
self.client = OpenAI(
base_url="http://localhost:11434/v1",
api_key="not-needed"
)
self.model = model_name
self.history = []
self.history_file = Path(history_file) if history_file else None
self.load_history()
def load_history(self):
"""从文件加载对话历史"""
if self.history_file and self.history_file.exists():
try:
with open(self.history_file, 'r', encoding='utf-8') as f:
self.history = json.load(f)
print(f"已从 {self.history_file} 加载 {len(self.history)} 条历史消息。")
except Exception as e:
print(f"加载历史记录失败: {e}")
def save_history(self):
"""保存对话历史到文件"""
if self.history_file:
try:
with open(self.history_file, 'w', encoding='utf-8') as f:
json.dump(self.history, f, ensure_ascii=False, indent=2)
except Exception as e:
print(f"保存历史记录失败: {e}")
def chat_once(self, user_input):
"""发送单次用户输入并获取回复"""
self.history.append({"role": "user", "content": user_input})
try:
response = self.client.chat.completions.create(
model=self.model,
messages=self.history,
temperature=0.7,
stream=False # 这里为了简化，关闭了流式
)
ai_reply = response.choices[0].message.content
self.history.append({"role": "assistant", "content": ai_reply})
return ai_reply
except Exception as e:
return f"抱歉，请求模型时出现错误: {e}"
def start_interactive(self):
"""启动交互式对话循环"""
print(f"开始与 {self.model} 对话。输入 'exit' 退出，输入 '/clear' 清空历史。")
while True:
try:
user_input = input("\n你: ").strip()
except (EOFError, KeyboardInterrupt):
print("\n对话结束。")
break
if not user_input:
continue
if user_input.lower() == 'exit':
self.save_history()
print("对话已保存，再见！")
break
if user_input == '/clear':
self.history = []
print("对话历史已清空。")
continue
print("AI: ", end='', flush=True)
reply = self.chat_once(user_input)
print(reply)
# 使用示例
if __name__ == "__main__":
# 可以指定一个文件来保存历史，实现“记忆”功能
session = OllamaChatSession(model_name="qwen2.5:7b", history_file="./chat_history.json")
session.start_interactive()
这个类不仅实现了基础对话，还增加了历史记录保存与加载的功能。你可以随时中断对话，下次启动时从上次聊到的地方继续。/clear指令则提供了快速清空上下文的方法，这在模型开始“胡言乱语”或你想开启全新话题时非常有用。
3.3 高级功能探索：函数调用与JSON模式
一些较新的或经过微调的模型（如某些版本的Llama 3或Qwen）开始支持类似OpenAI的“函数调用”（Function Calling）或“JSON模式”（JSON Mode）。虽然Ollama的OpenAI兼容端点对这些功能的支持程度取决于后端模型本身，但尝试使用标准语法来调用是可行的。
例如，强制模型以JSON格式返回数据，这对于需要结构化输出的自动化任务（如信息提取、数据格式化）至关重要：
from openai import OpenAI
import json
client = OpenAI(base_url="http://localhost:11434/v1", api_key="test")
response = client.chat.completions.create(
model="你的模型名称", # 需要确认模型是否支持此功能
messages=[
{"role": "user", "content": "提取下面句子中的公司名、人名和产品名：'苹果公司的CEO蒂姆·库克近日发布了新款iPhone 16。'"}
],
response_format={"type": "json_object"}, # 尝试要求JSON格式输出
temperature=0.1 # 低温度保证输出格式稳定
)
try:
# 假设模型返回了合法的JSON字符串
result_json = json.loads(response.choices[0].message.content)
print("结构化提取结果：", json.dumps(result_json, indent=2, ensure_ascii=False))
except json.JSONDecodeError:
# 如果模型不支持，可能会返回普通文本
print("模型返回了非JSON内容：", response.choices[0].message.content)
4. 实战项目：构建一个智能文档问答助手
理论讲得再多，不如动手做一个项目。让我们综合运用以上知识，构建一个简单的本地文档问答助手。它的流程是：用户上传一个文本文件（比如项目报告、论文），然后可以针对文档内容进行提问。
这个项目会涉及：
- 读取并预处理文档文本。
- 将文档内容作为系统上下文提供给模型。
- 处理可能超长的上下文（通过摘要或分块）。
- 实现一个简洁的问答循环。
from openai import OpenAI
import re
class DocumentQAAssistant:
def __init__(self, model="mistral:7b"):
self.client = OpenAI(base_url="http://localhost:11434/v1", api_key="x")
self.model = model
self.document_text = ""
self.chunk_size = 2000 # 每个文本块的大致字符数，避免超出模型上下文限制
def load_document(self, file_path):
"""加载文本文档"""
try:
with open(file_path, 'r', encoding='utf-8') as f:
self.document_text = f.read()
print(f"文档加载成功，长度: {len(self.document_text)} 字符。")
return True
except Exception as e:
print(f"加载文档失败: {e}")
return False
def _chunk_document(self):
"""将长文档分割成易于处理的块（简单的按段落分割）"""
if not self.document_text:
return []
# 按换行符分割，并过滤空行
paragraphs = [p.strip() for p in self.document_text.split('\n') if p.strip()]
chunks = []
current_chunk = ""
for para in paragraphs:
if len(current_chunk) + len(para) < self.chunk_size:
current_chunk += para + "\n"
else:
if current_chunk:
chunks.append(current_chunk.strip())
current_chunk = para + "\n"
if current_chunk:
chunks.append(current_chunk.strip())
print(f"文档被分割成 {len(chunks)} 个块。")
return chunks
def ask_about_chunk(self, question, chunk_text):
"""针对一个文档块进行提问"""
prompt = f"""请基于以下文档片段回答问题。如果片段中不包含答案，请直接说“根据提供的文档，无法回答此问题”。
文档片段：
{chunk_text}
问题：{question}
答案："""
try:
response = self.client.chat.completions.create(
model=self.model,
messages=[{"role": "user", "content": prompt}],
temperature=0.1, # 问答任务需要高准确性
max_tokens=300
)
return response.choices[0].message.content.strip()
except Exception as e:
return f"请求出错: {e}"
def ask_question(self, question):
"""主问答函数：遍历所有文档块寻找答案"""
if not self.document_text:
return "请先加载一个文档。"
chunks = self._chunk_document()
answers = []
for i, chunk in enumerate(chunks):
print(f"正在检索文档块 {i+1}/{len(chunks)}...")
answer = self.ask_about_chunk(question, chunk)
# 简单判断是否为有效答案
if answer and "无法回答" not in answer:
answers.append((i, answer))
# 如果找到一个答案，可以提前结束（或继续找更多佐证）
# break
if not answers:
return "在文档中未找到相关答案。"
else:
# 这里简单返回第一个找到的答案，更复杂的实现可以合并多个答案
return f"根据文档第{answers[0][0]+1}部分：\n{answers[0][1]}"
# 使用示例
if __name__ == "__main__":
assistant = DocumentQAAssistant(model="llama3.2:3b")
# 假设有一个名为“report.txt”的文档
if assistant.load_document("report.txt"):
while True:
q = input("\n请输入你的问题 (输入'quit'退出): ")
if q.lower() == 'quit':
break
print("\n正在思考...")
result = assistant.ask_question(q)
print(f"\n助手: {result}")
这个示例只是一个起点，但它清晰地展示了如何将Ollama API融入一个具体的应用场景。在实际项目中，你可能会引入更复杂的文本分块策略（如按语义分割）、向量数据库进行相似性检索（RAG架构），以及更优雅的答案融合逻辑。但无论如何，其核心——通过API与本地模型交互——已经通过上面的代码牢牢掌握在你手中了。
更多推荐
22
0- 0
已为社区贡献14条内容
所有评论(0)