Ollama API 有哪些核心端点，怎样正确调用？

Ollama 启动后默认在 http://localhost:11434 提供 RESTful API，所有端点均以 JSON 交互。调用前先验证服务是否就绪：

bash
curl http://localhost:11434
# 返回 "Ollama is running" 即表示正常

文本生成与对话

POST /api/generate —— 单轮文本生成

向模型发送 prompt 并获取生成结果，适合一次性问答、代码补全等场景：

bash
curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "用 Python 写一个快速排序",
  "stream": false
}'

关键参数：stream 控制是否流式返回（默认 true），options 可设置 temperature、num_predict 等模型超参。非流式响应在 response 字段返回完整文本，流式响应逐行返回 JSON 片段，每片包含 response 和 done 字段。

POST /api/chat —— 多轮对话

支持 messages 数组传入对话历史，是构建聊天应用的核心端点：

bash
curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手"},
    {"role": "user", "content": "解释一下 RAG 的原理"},
    {"role": "assistant", "content": "RAG 是检索增强生成..."},
    {"role": "user", "content": "它和微调有什么区别？"}
  ],
  "stream": false
}'

角色支持 system、user、assistant 三种，对话历史越长上下文越完整，但也会增加显存占用和响应延迟。

模型管理

GET /api/tags —— 列出本地模型

返回已下载模型的名称、大小和修改时间：

bash
curl http://localhost:11434/api/tags

响应中 models 数组的每个元素包含 name、size、modified_at 等字段。当你不确定本地有哪些模型可用时，先调这个接口。

POST /api/show —— 查看模型详情

获取模型的模版、系统提示词、参数等元信息：

bash
curl http://localhost:11434/api/show -d '{
  "name": "qwen2.5:7b"
}'

返回的 template 字段是模型使用的提示词模板，parameters 是默认参数，system 是内置系统提示词。调试模型行为时很有用。

POST /api/pull —— 下载模型

从 Ollama 仓库拉取模型到本地：

bash
curl http://localhost:11434/api/pull -d '{
  "name": "qwen2.5:7b"
}'

大模型下载耗时较长，默认以流式返回进度信息（status: "pulling ..."），完成后 status 变为 success。

POST /api/copy —— 复制模型

创建模型副本，常用于在微调前备份原始模型：

bash
curl http://localhost:11434/api/copy -d '{
  "source": "qwen2.5:7b",
  "destination": "my-qwen-backup"
}'

DELETE /api/delete —— 删除模型

删除本地模型释放磁盘空间：

bash
curl -X DELETE http://localhost:11434/api/delete -d '{
  "name": "my-qwen-backup"
}'

注意此操作不可恢复，删除后需要重新 pull。

向量与嵌入

POST /api/embeddings —— 生成文本向量

将文本转为向量表示，是构建 RAG 应用的关键端点：

bash
curl http://localhost:11434/api/embeddings -d '{
  "model": "nomic-embed-text",
  "prompt": "什么是向量数据库？"
}'

返回的 embedding 字段是浮点数数组，维度取决于模型。嵌入模型推荐使用 nomic-embed-text 或 mxbai-embed-large，它们专为文本向量化设计，不要用对话模型生成嵌入。

OpenAI 兼容端点

POST /v1/chat/completions

Ollama 提供与 OpenAI API 兼容的端点，方便现有项目零改造迁移：

bash
curl http://localhost:11434/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "qwen2.5:7b",
  "messages": [{"role": "user", "content": "你好"}],
  "stream": false
}'

同理 /v1/completions 和 /v1/embeddings 也已支持。将 OpenAI SDK 的 base_url 改为 http://localhost:11434/v1，api_key 填任意字符串即可使用。

Python 集成

除了直接 HTTP 调用，Ollama 官方提供了 Python SDK：

bash
pip install ollama

python
import ollama

# 单轮生成
response = ollama.generate(model='qwen2.5:7b', prompt='用 Python 写一个快速排序')
print(response['response'])

# 多轮对话
stream = ollama.chat(
    model='qwen2.5:7b',
    messages=[{'role': 'user', 'content': '解释一下 RAG 的原理'}],
    stream=True
)
for chunk in stream:
    print(chunk['message']['content'], end='', flush=True)

常见问题

Q: 调用 API 返回 connection refused？ 确认 Ollama 服务已启动。macOS 检查是否在运行，Linux 执行 systemctl status ollama。若 Ollama 监听在非默认端口，需设置环境变量 OLLAMA_HOST。

Q: 生成速度很慢怎么办？ 检查是否使用了 GPU。执行 ollama run qwen2.5:7b 进入交互模式后输入 /show info 查看推理设备。若显示 CPU 而非 GPU，需安装对应的 CUDA 或 Metal 驱动。

Q: 如何在局域网内其他机器访问？ 默认 Ollama 只监听 localhost。设置 OLLAMA_HOST=0.0.0.0 后重启服务即可开放局域网访问，但务必注意此操作无认证保护，不要暴露到公网。