Ollama Chat 端点

POST /api/chat 是多轮对话的标准入口。相比 /api/generate 的单段提示词，它接收 messages 数组，能表达完整的角色与历史，也是唯一支持工具调用的端点。

版本基线 v0.40.12，官方 docs.ollama.com/api/chat。

一、最小调用

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [
    { "role": "user", "content": "why is the sky blue?" }
  ]
}'

返回：

{
  "model": "gemma4",
  "created_at": "2025-10-17T23:14:07.414671Z",
  "message": {
    "role": "assistant",
    "content": "Hello! How can I help you today?"
  },
  "done": true,
  "done_reason": "stop",
  "total_duration": 174560334,
  "load_duration": 101397084,
  "prompt_eval_count": 11,
  "prompt_eval_duration": 13074791,
  "eval_count": 18,
  "eval_duration": 52479709
}

答案在 message.content——注意不是 response，这是和 generate 端点的关键差别。

二、请求字段

messages 的结构

[
  {"role": "system",    "content": "你是一名严谨的技术助手"},
  {"role": "user",      "content": "什么是 KV 缓存？"},
  {"role": "assistant", "content": "KV 缓存是……"},
  {"role": "user",      "content": "那它占多少显存？"}
]

三个角色：system（系统提示，通常放第一条）、user、assistant（历史回复）。

多轮对话必须自己维护这个数组——每次请求把完整历史带上，服务端不保存会话状态。这也是 prompt_eval_cached_count 会有值的原因：历史前缀被缓存复用了。

三、工具调用（最实用的能力）

先定义工具：

{
  "model": "qwen3",
  "messages": [{"role": "user", "content": "北京今天天气怎么样？"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的当前天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "城市名"}
          },
          "required": ["city"]
        }
      }
    }
  ]
}

模型不会直接回答，而是返回一个工具调用：

{
  "message": {
    "role": "assistant",
    "content": "",
    "tool_calls": [
      {
        "function": {
          "name": "get_weather",
          "arguments": { "city": "北京" }
        }
      }
    ]
  },
  "done": true,
  "done_reason": "stop"
}

接着把你的执行结果作为 tool 角色消息追加进去，再请求一次：

{
  "model": "qwen3",
  "messages": [
    {"role": "user", "content": "北京今天天气怎么样？"},
    {"role": "assistant", "content": "", "tool_calls": [ /* 上一步返回的 */ ]},
    {"role": "tool", "content": "{\"temp\": 18, \"condition\": \"晴\"}"}
  ],
  "tools": [ /* 同一份工具定义 */ ]
}

模型会基于工具结果生成最终答案。

三个容易出错的点：

1. tools 每次请求都要带，不是只在第一次带
2. tool_calls 的 arguments 可能是对象也可能需要序列化，取决于客户端库版本，处理前先打印确认
3. tool 消息要和 tool_calls 一一对应，数量或顺序错了模型会混乱

完整的工具调用机制见 3.8 Ollama 工具调用。

四、响应字段

五、流式对话

默认流式，每个 chunk 的 message.content 是增量：

import json, requests

history = [{"role": "user", "content": "讲个短笑话"}]

with requests.post("http://localhost:11434/api/chat", json={
    "model": "gemma4",
    "messages": history,
}, stream=True) as r:
    parts = []
    for line in r.iter_lines():
        if not line:
            continue
        c = json.loads(line)
        if "error" in c:
            raise RuntimeError(c["error"])
        parts.append(c["message"]["content"])
        print(c["message"]["content"], end="", flush=True)
        if c.get("done"):
            break

## 把回复追加进历史，下一轮带上
history.append({"role": "assistant", "content": "".join(parts)})

注意最后一行——流式响应结束后要自己把 assistant 回复塞进历史，否则下一轮模型不知道它说过什么。

六、generate 还是 chat

常见问题

动手试

## ① 单轮
curl -s http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [{"role":"user","content":"hi"}],
  "stream": false
}' | python -m json.tool

## ② 查模型支持哪些能力（含 tools）
curl -s http://localhost:11434/api/show -d '{"model":"qwen3"}' | python -c "
import sys,json;print(json.load(sys.stdin).get('capabilities'))"

第二条返回里有 tools，这个模型才能做工具调用。