简介:本文围绕 Ollama API 的核心接口、调用方式、模型管理与常见问题展开,提供 /api/generate、/api/chat、/api/tags、/api/pull 的实用示例,并补充流式输出、上下文维护、安全部署与多模型接入思路,帮助开发者快速完成本地大模型服务集成。
Ollama API 是 Ollama 本地大模型运行时对外提供的 HTTP 接口,默认监听 11434 端口。开发者可以通过它完成文本生成、多轮对话、模型拉取和本地模型管理。若你正在规划本地模型与云端模型的组合方案,也可以先了解 百度智能云词元所,它提供模型发现与选型、价格与性能对比、多模型统一 API 接入和调用管理等能力,适合在接入前进行方案评估。
安装 Ollama 后,可以通过命令行启动服务:
ollama serve
拉取并运行模型:
ollama pull llama3ollama run llama3
在云主机或容器环境中完成部署后,通常会获得一个 OpenAPI 地址,可以直接通过 curl 调用 /api/generate。
调用示例:
curl http://localhost:11434/api/generate \-d '{"model": "llama3","prompt": "Why is the sky blue?","stream": false}'
如果返回正常,说明 Ollama API 已经可以访问。
| 方法 | 路径 | 用途 | 典型场景 |
|---|---|---|---|
| POST | /api/generate |
文本生成 | 单轮问答、摘要、续写、代码生成 |
| POST | /api/chat |
多轮对话 | 聊天机器人、智能助手、Agent |
| GET | /api/tags |
查看本地模型 | 模型巡检、环境检查 |
| POST | /api/pull |
拉取模型 | 初始化模型环境 |
| POST | /api/create |
创建自定义模型 | 基于 Modelfile 定制模型 |
| POST | /api/delete |
删除模型 | 清理本地模型 |
| POST | /api/show |
查看模型信息 | 查看模型详情、参数模板 |
其中最常用的是 /api/generate、/api/chat、/api/tags 和 /api/pull。
/api/generate 适合单轮文本生成任务,例如问答、摘要、翻译、代码补全等。
curl http://localhost:11434/api/generate \-d '{"model": "llama3","prompt": "用一句话解释什么是向量数据库","stream": false}'
返回结果中通常包含:
{"model": "llama3","response": "向量数据库是一种专门用于存储和检索向量数据的数据库。","done": true}
| 参数 | 说明 |
|---|---|
model |
指定使用的模型名称 |
prompt |
输入提示词 |
stream |
是否流式返回,默认通常为 true |
options |
模型参数,如 temperature、num_ctx、num_predict |
system |
系统提示词 |
template |
自定义提示词模板 |
context |
上下文编码,可用于延续上一轮生成 |
format |
可指定输出格式,如 json |
keep_alive |
控制模型在内存中保持的时间 |
如果希望一次性获取完整结果,可以设置:
{"model": "llama3","prompt": "请总结这段话的核心观点","stream": false}
如果希望逐字输出,可以保持 stream: true,接口会以流式方式持续返回内容。
/api/chat 更适合聊天机器人、智能助手和多轮对话场景。它通过 messages 数组传递对话内容。
curl http://localhost:11434/api/chat \-d '{"model": "llama3","messages": [{"role": "system","content": "你是一个简洁的技术助手"},{"role": "user","content": "什么是 RAG?"}],"stream": false}'
返回结果示例:
{"message": {"role": "assistant","content": "RAG 是检索增强生成,通过检索外部知识来辅助大模型生成答案。"},"done": true}
Ollama 的 /api/chat 本身通常是无状态的,多轮上下文需要由调用方维护。每次请求时,将历史消息一起传入即可:
{"model": "llama3","messages": [{"role": "system","content": "你是一个技术问答助手"},{"role": "user","content": "什么是 Token?"},{"role": "assistant","content": "Token 是大模型处理文本的基本单位。"},{"role": "user","content": "那它如何影响计费?"}]}
在应用开发中,常见做法是:
curl http://localhost:11434/api/tags
该接口会返回当前 Ollama 环境中已经存在的模型列表,适合用于健康检查、模型巡检和自动化部署脚本。
curl http://localhost:11434/api/pull \-d '{"name": "llama3"}'
如果是在自动化部署场景中,可以在容器启动脚本中加入模型拉取逻辑,确保服务启动后模型可用。
除了 curl,也可以在 Python 中直接调用 Ollama API。
import requestsurl = "http://localhost:11434/api/chat"payload = {"model": "llama3","messages": [{"role": "user", "content": "请介绍一下 Ollama API"}],"stream": False}response = requests.post(url, json=payload)data = response.json()print(data["message"]["content"])
import jsonimport requestsurl = "http://localhost:11434/api/chat"payload = {"model": "llama3","messages": [{"role": "user", "content": "请用三句话解释大模型推理"}],"stream": True}with requests.post(url, json=payload, stream=True) as response:for line in response.iter_lines():if line:data = json.loads(line)content = data.get("message", {}).get("content", "")print(content, end="", flush=True)
生产环境中建议增加超时、重试、日志和异常处理,避免模型推理时间过长导致请求阻塞。
/api/generate 的 context/api/generate 返回结果中可能包含 context 字段。下一次请求时,可以将上一次返回的 context 传入,从而延续生成上下文。
示例思路:
{"model": "llama3","prompt": "继续上面的内容","context": []}
这种方式适合连续文本生成、故事续写、长文摘要等场景。
/api/chat 的 messages对于聊天机器人,更推荐使用 messages 数组维护上下文。每一轮对话都包含系统提示、用户输入和助手回复。
这种方式结构清晰,适合构建多轮对话、客服助手、知识问答和 Agent 应用。
报错示例:
Connection refused
可能原因:
11434。解决方法:
ollama servecurl http://localhost:11434/api/tags
报错示例:
model not found
解决方法:
ollama pull llama3
确认模型名称拼写正确,并通过 /api/tags 检查本地模型列表。
可能原因:
优化建议:
如果前端页面直接调用 Ollama API,可能会遇到跨域问题。可以通过反向代理转发请求,或在可信环境中配置 Ollama 的跨域策略。
生产环境不建议直接将 Ollama 服务暴露到公网。
Ollama API 默认通常没有复杂鉴权机制。如果直接暴露到公网,可能带来滥用、资源消耗和安全风险。
建议:
当应用只使用一个本地模型时,直接调用 Ollama API 即可。但在实际业务中,常常会出现以下情况:
这时可以考虑引入统一 API 接入层,将不同模型服务封装成一致的调用方式,降低业务代码耦合。
在模型选型阶段,可以通过 百度智能云词元所 了解不同模型的能力、价格与性能对比,辅助判断哪些任务适合本地部署,哪些任务适合调用云端模型服务。
对于需要长期运营 AI 应用的团队,还可以借助 词元所模型服务 进行模型调用管理和供需对接,减少多模型接入带来的复杂度。
固定模型版本
避免模型名称或版本随意变化,确保应用行为可预期。
设置请求超时
大模型推理时间可能较长,必须设置合理超时。
增加日志与监控
记录请求耗时、模型名称、错误码和调用量,便于排查问题。
控制上下文长度
上下文过长会增加推理成本和延迟,可结合摘要、截断或 RAG。
不要直接暴露公网
使用内网、反向代理、鉴权和限流保护 Ollama 服务。
建立模型评测机制
在切换模型前,使用真实业务样本进行效果对比,而不是只看参数规模。
区分本地模型与云端模型职责
本地模型适合隐私敏感、低延迟或固定任务;云端模型适合复杂推理、多模态或弹性扩展场景。
Ollama API 的核心价值在于让开发者可以通过标准 HTTP 接口快速调用本地大模型。掌握 /api/generate、/api/chat、/api/tags 和 /api/pull 后,就可以完成从模型拉取、文本生成到多轮对话的基本闭环。进一步地,结合流式输出、上下文管理、安全部署和多模型接入方案,可以将 Ollama 稳定地集成到问答系统、Agent、RAG 知识库和企业 AI 应用中。