Ollama 模型交互接口全解析
Ollama 提供了简洁易用的模型交互接口，核心通过 REST API 实现与本地部署模型的对话、文本生成等功能。
一、功能介绍
Ollama 的模型交互接口主要有两个：/chat（对话接口）和 /generate（文本生成接口），两者均通过 POST 方法调用，支持 JSON 格式交互。
| 接口地址 | 核心功能 | 适用场景 | 特点 |
|---|---|---|---|
/api/chat |
多轮对话，支持上下文关联 | 聊天机器人、智能助手、多轮问答 | 保留对话历史，支持 system 提示词 |
/api/generate |
单次文本生成，无上下文（独立请求） | 内容续写、代码生成、摘要生成 | 直接基于 prompt 生成，无历史依赖 |
1. /chat 接口：多轮对话场景
- 核心能力：维护对话上下文，支持
user（用户）、assistant（模型）、system（系统提示）三种角色的消息交互。 - 典型流程：用户输入 → 模型基于历史对话生成响应 → 新增响应到对话历史 → 下一轮交互。
2. /generate 接口：单次生成场景
- 核心能力：基于单次输入的
prompt生成文本，不保留历史记录，每次请求相互独立。 - 典型流程：输入提示词 → 模型生成结果 → 直接返回（无状态存储）。
二、参数说明（请求与响应）
1. 通用请求参数（两类接口共通）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
model |
string | 是 | 模型名称（需提前下载，如 phi3、mistral:7b、qwen:1.8b） |
stream |
boolean | 否 | 是否启用流式响应： - true：逐段返回结果（适合实时显示）- false：一次性返回完整结果 |
options |
object | 否 | 生成参数（覆盖模型默认配置）： - temperature：随机性（0~1，默认 0.7，值越低越确定）- max_tokens：最大生成 token 数（默认 2048）- stop：停止符数组（如 ["\n"]，遇到则停止生成）- top_p：核采样参数（0~1，控制输出多样性） |
2. 接口专属参数
/chat 接口特有参数
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
messages |
array | 是 | 对话历史数组，每个元素为包含 role 和 content 的对象：- role：角色（user/assistant/system）- content：消息内容（文本） |
/generate 接口特有参数
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
prompt |
string | 是 | 生成提示词（输入文本） |
3. 响应参数说明
非流式响应（stream: false）
{
"model": "phi3", // 模型名称
"created_at": "2024-09-12T15:30:00Z", // 生成时间
"message": { "role": "assistant", "content": "响应内容..." }, // /chat 接口返回
"response": "响应内容...", // /generate 接口返回（替代 message）
"done": true, // 是否完成
"total_duration": 1500000000, // 总耗时（纳秒）
"eval_count": 180, // 生成的 token 数
"eval_duration": 1200000000 // 生成耗时（纳秒）
}
流式响应（stream: true）
逐段返回结果，最后一段包含完整统计信息：
// 中间段
{
"model": "phi3",
"created_at": "2024-09-12T15:30:00Z",
"message": { "role": "assistant", "content": "部分内容..." }, // 或 response 字段
"done": false
}
// 最后段
{
"model": "phi3",
"created_at": "2024-09-12T15:30:01Z",
"message": { "role": "assistant", "content": "完整内容" },
"done": true,
"total_duration": 1500000000,
"eval_count": 180
}
三、注意事项
模型上下文窗口限制
每个模型有最大上下文 token 数（可通过/show接口查询num_ctx），例如phi3默认为 8192。若messages总长度超过限制，会返回context too large错误，需截断历史对话。流式响应的处理逻辑
流式响应需逐段拼接内容（适合 UI 实时显示），非流式适合后台处理（一次性获取结果）。资源占用控制
- 7B 模型（INT4 量化）约占用 4GB 内存，边缘设备建议优先选择 3.8B 以下模型（如
phi3、qwen:1.8b）。 - 避免短时间内高频调用，防止 CPU/内存占用过高。
- 7B 模型（INT4 量化）约占用 4GB 内存，边缘设备建议优先选择 3.8B 以下模型（如
错误处理
- 常见错误：
model not found（模型未下载，需先pull）、invalid request（参数格式错误）、context too large（上下文过长）。 - 建议在代码中捕获 HTTP 400/500 状态码，解析
error字段提示用户。
- 常见错误：
参数调优建议
- 事实性问答：
temperature=0.2（降低随机性）、top_p=0.9。 - 创意生成：
temperature=0.8、max_tokens=2048（增加长度）。 - 代码生成：
stop=["\n\n"]（避免无意义续写）。
- 事实性问答：
四、代码示例
示例 1：Python 调用 /chat 接口（多轮对话，非流式）
import requests
import json
def chat_with_model(user_input, history=None):
"""
与模型进行多轮对话
:param user_input: 当前用户输入
:param history: 历史对话列表（默认空）
:return: 模型响应 + 更新后的历史
"""
# 初始化历史对话
if history is None:
history = []
# 接口地址
url = "http://localhost:11434/api/chat"
# 新增用户输入到历史
history.append({"role": "user", "content": user_input})
# 请求参数
payload = {
"model": "phi3", # 使用轻量模型phi3
"messages": history,
"stream": False,
"options": {
"temperature": 0.5, # 降低随机性，适合问答
"max_tokens": 1000
}
}
try:
# 发送请求
response = requests.post(url, json=payload)
response.raise_for_status() # 检查HTTP错误
result = response.json()
# 提取模型响应
assistant_reply = result["message"]["content"]
# 更新历史对话
history.append({"role": "assistant", "content": assistant_reply})
return assistant_reply, history
except Exception as e:
return f"调用失败：{str(e)}", history
# 测试多轮对话
if __name__ == "__main__":
history = None
# 第一轮
reply, history = chat_with_model("什么是边缘计算？", history)
print(f"模型：{reply}")
# 第二轮（基于历史）
reply, history = chat_with_model("它和云计算有什么区别？", history)
print(f"模型：{reply}")
示例 2：Python 调用 /generate 接口（流式生成代码）
import requests
import json
def generate_code_stream(prompt):
"""
流式生成代码（适合实时显示）
:param prompt: 代码生成提示词
"""
url = "http://localhost:11434/api/generate"
payload = {
"model": "codellama:7b", # 代码专用模型
"prompt": prompt,
"stream": True,
"options": {
"temperature": 0.3, # 代码生成需低随机性
"stop": ["\n\n"] # 遇到空行停止
}
}
try:
# 流式请求（stream=True 需用iter_lines）
with requests.post(url, json=payload, stream=True) as r:
r.raise_for_status()
full_response = ""
# 逐行处理流式响应
for line in r.iter_lines():
if line:
# 解析单行JSON
data = json.loads(line)
# 拼接内容
if "response" in data:
full_response += data["response"]
# 实时打印（模拟UI实时更新）
print(data["response"], end="", flush=True)
# 生成完成
if data.get("done", False):
print("\n\n生成完成！")
return full_response
return full_response
except Exception as e:
return f"生成失败：{str(e)}"
# 测试代码生成
if __name__ == "__main__":
prompt = "用Python写一个简单的HTTP服务器，支持返回当前时间"
generate_code_stream(prompt)
总结
Ollama 的 \chat 和 \generate 接口为本地化模型交互提供了灵活支持，通过合理配置参数（如 stream、temperature）和管理对话历史，可满足从简单文本生成到复杂多轮对话的各类需求。实际开发中需注意上下文长度、资源占用和错误处理，结合具体场景选择合适的模型和接口。上述代码示例可直接作为集成模板，快速实现本地化 AI 功能。