4.2 REST API 深度指南

4.2 REST API 深度指南

本节摘要：Ollama 的全部能力都暴露在 localhost:11434 上。本节逐个过一遍核心端点——/api/generate 与 /api/chat 的差异、流式与非流式的取舍、format: json 的结构化输出、images 的多模态入口、options 里的运行时参数，以及嵌入接口 /api/embed——并给出每个端点可直接复制的请求样例与响应解读。

两个生成端点：generate 与 chat 怎么选

/api/generate 是"单轮补全"语义：你给一段 prompt，它接着写。没有角色结构，上下文要你自己拼接。适合一次性任务——改写、抽取、生成代码注释：

curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "为函数 void retry(int n) 写一行中文注释",
  "stream": false
}'
​

"stream": false 让服务一次性返回完整结果（默认为 true，逐 JSON 行推送增量）。非流式便于脚本处理，流式让界面有"打字机"体感，长生成时还能提前止损。

/api/chat 是"消息列表"语义，messages 数组里 system / user / assistant 三种角色交替，服务端会按模型模板正确排版。所有多轮对话都应走这个端点——历史由调用方维护，每次把整段历史发回：

curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [
    {"role": "system", "content": "你是精简的中文技术问答助手"},
    {"role": "user", "content": "TCP 三次握手用一句话讲清"},
    {"role": "assistant", "content": "客户端和服务端各打招呼并确认收发能力，三次交换后连接建立。"},
    {"role": "user", "content": "那四次挥手呢？"}
  ],
  "stream": false
}'
​

响应中的 message.content 是答案；流式模式下每条增量放在 message.content 字段，最终帧带 done_reason、eval_count 等统计。

结构化输出：format 字段的两种用法

轻度约束传 "format": "json"，模型输出会被引导为合法 JSON（不保证 schema，需自行校验）；Ollama 0.5 起更进一步，支持传 JSON Schema，字段、类型、必填都被硬约束：

curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "stream": false,
  "format": {
    "type": "object",
    "properties": {
      "sentiment": {"type": "string", "enum": ["正面", "中性", "负面"]},
      "score": {"type": "number"},
      "keywords": {"type": "array", "items": {"type": "string"}}
    },
    "required": ["sentiment", "score"]
  },
  "messages": [
    {"role": "user", "content": "分析这条评论：物流很快，包装有点损"}
  ]
}'
# 返回 message.content 为符合 schema 的 JSON 字符串
​

配合 temperature: 0，分类、抽取类任务可以稳定到无需重试。

options：请求级的全部旋钮

每个请求可携带 options 对象覆盖默认值，常用字段：temperature、top_p、top_k、num_ctx（本次请求的上下文窗口，默认 2048，长输入必调）、num_predict（最大生成 token）、repeat_penalty、seed（固定种子可复现采样）、num_gpu（送 GPU 的层数）。另有请求级 keep_alive（如 "10m"、"-1"、"0"）控制模型驻留：

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.1:8b",
  "prompt": "50字内解释数据库索引",
  "stream": false,
  "options": {"temperature": 0.2, "num_predict": 120, "seed": 42},
  "keep_alive": "30m"
}'
​

一个容易踩的坑：把 num_ctx 调到 32k，KV 缓存内存也随之放大，8B 模型可能因此从"刚好装进显存"变成"溢出到内存"，速度骤降。窗口按需给，不要一步到位拉满。

模型管理与状态端点

# 探活
curl http://localhost:11434/

# 本机已有模型
curl http://localhost:11434/api/tags

# 当前驻留模型与显存占用
curl http://localhost:11434/api/ps

# 拉取/删除模型（pull 为流式进度）
curl http://localhost:11434/api/pull -d '{"name": "llama3.1:8b"}'
curl -X DELETE http://localhost:11434/api/delete -d '{"model": "llama3.1:8b"}'

# 从 Modelfile 创建（含已有模型的副本）
curl http://localhost:11434/api/create -d '{"name": "myproj/base", "from": "llama3.1:8b"}'
​

嵌入与多模态端点

文本嵌入走 /api/embed（旧接口 /api/embeddings 已弃用），输入一个数组，输出 embeddings 二维列表，是自建 RAG 的基石：

curl http://localhost:11434/api/embed -d '{
  "model": "nomic-embed-text",
  "input": ["向量检索的第一步", "把文本转成定长向量"]
}'
# {"embeddings": [[...1024 floats...], [...]], "model": "nomic-embed-text"}
​

视觉模型（llava、llama3.2-vision、qwen2.5vl）在消息里加 images 字段，传 base64 编码图片：

IMG=$(base64 -w0 diagram.png)
curl http://localhost:11434/api/chat -d "{
  \"model\": \"llava\",
  \"stream\": false,
  \"messages\": [{
    \"role\": \"user\",
    \"content\": \"列出图中的流程步骤\",
    \"images\": [\"$IMG\"]
  }]
}"
​

兼容层：/v1 OpenAI 端点

Ollama 同时暴露 OpenAI 风格的 /v1/chat/completions，意味着所有现成的 OpenAI 客户端只需改 base_url 即可迁移：

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[{"role": "user", "content": "一句话介绍向量化"}],
)
print(resp.choices[0].message.content)
​

注意兼容层只覆盖 chat/completions 与 embeddings 常用参数，format schema 约束等 Ollama 特有能力仍需原生端点。原生 API 是"全功能菜单"，兼容层是"为了让老客户端免改代码"。两者背后同一个 server，模型加载与缓存共享。

下一节把镜头拉到语言生态：Python、JavaScript 官方库与其他语言社区库，如何在原生 API 之上再封装一层便利。