Ollama API 基础：从 REST 到实战

聊到 Ollama 的 API，我得先说说自己的经历。最早接触 Ollama 时，我习惯用命令行敲 ollama run，觉得挺方便。直到有一次，我需要把大模型集成到公司的知识库系统里——嗯，命令行就不够用了。那时候我才真正开始研究它的 REST API。

说白了，Ollama 的 API 就是一套 HTTP 接口。你通过它跟模型对话，传参数，拿结果。它不复杂，但很实用。今天我就带你过一遍核心内容。

Ollama REST API 概览

Ollama 默认跑在本地，端口是 11434。你启动服务后，所有 API 都基于 http://localhost:11434 这个地址。

我个人习惯用 curl 测试接口，因为快。你想想看，写几行命令就能验证模型能不能跑，比写 Python 脚本省事多了。

这些端点里，/api/generate 和 /api/chat 是我最常用的。做 RAG 系统时，/api/embeddings 也经常用到——毕竟要把文档转成向量嘛。

API 端点详细介绍

1. /api/generate — 单次生成

这个端点最简单。你给一段提示词，它返回一段文本。适合做问答、摘要、翻译这类任务。

举个例子：

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "用一句话解释什么是RAG",
  "stream": false
}'

返回结果大概长这样：

{
  "model": "llama3.2",
  "response": "RAG（检索增强生成）是一种结合信息检索与文本生成的技术，先检索相关文档，再基于这些文档生成答案。",
  "done": true
}

注意 stream 参数。默认是 true，会流式返回结果。我建议在调试时设成 false，方便看完整响应。生产环境里，流式输出体验更好——用户不用等全部生成完才看到文字。

2. /api/chat — 多轮对话

这个端点支持上下文。你传一个消息列表，模型会基于历史回复。

我在项目中遇到过一个问题：用户连续问几个问题，如果每次都用 /api/generate，模型会丢失上下文。后来改用 /api/chat，把历史消息都传进去，效果就好多了。

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [
    {"role": "user", "content": "什么是RAG？"},
    {"role": "assistant", "content": "RAG是检索增强生成..."},
    {"role": "user", "content": "它有什么优点？"}
  ],
  "stream": false
}'

返回结果里，message.content 就是模型的回答。

3. /api/embeddings — 向量嵌入

做 RAG 系统，这一步绕不开。你把文本传进去，它返回一个向量数组。这个向量可以用来做相似度检索。

curl http://localhost:11434/api/embeddings -d '{
  "model": "llama3.2",
  "prompt": "今天天气怎么样？"
}'

返回的 embedding 字段是一个浮点数数组，长度取决于模型。比如 llama3.2 的嵌入维度是 4096。

4. /api/tags — 查看本地模型

这个端点很简单，就是列出你本地已经拉取的所有模型。

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

返回结果里有个 models 数组，每个模型包含名称、大小、修改时间等信息。

5. /api/pull — 拉取模型

如果你想在代码里动态下载模型，用这个端点。不用每次都跑 ollama pull 命令。

curl http://localhost:11434/api/pull -d '{
  "model": "llama3.2"
}'

它会返回进度信息，你可以根据 status 字段判断是否下载完成。

使用 curl 调用 Ollama

刚才的示例都是基于 curl 的。我再补充几个实用技巧。

设置超时： 大模型生成可能比较慢，尤其是长文本。我习惯加个 --max-time 参数：

curl --max-time 60 http://localhost:11434/api/generate -d '{...}'

处理流式输出： 如果你想看实时效果，用 -N 参数：

curl -N http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "讲个笑话",
  "stream": true
}'

这样每个 token 生成后立即显示，不用等全部完成。

调试模式： 加 -v 参数可以看到完整的 HTTP 请求和响应头，方便排查问题。

API 认证与安全

Ollama 默认没有认证。这意味着，只要知道你的 IP 和端口，任何人都能调用你的模型。这在本地开发没问题，但如果你把服务暴露到公网，就危险了。

我曾经犯过一个错误：为了方便远程调试，直接把 Ollama 端口映射到了公网。结果第二天发现模型被陌生人调用了无数次，账单上多了不少流量费。嗯，从那以后我再也不敢这么干了。

安全建议：

• 不要暴露到公网： 只在局域网内使用。如果必须远程访问，用 VPN 或 SSH 隧道。
• 加一层反向代理： 用 Nginx 或 Caddy 做代理，在代理层加认证。比如用 Basic Auth 或 API Key。
• 限制 IP： 如果只有固定几个客户端，可以在防火墙层面限制来源 IP。
• 使用 HTTPS： 如果数据敏感，建议用 HTTPS 加密传输。Ollama 本身不支持 HTTPS，但反向代理可以帮你做。

下面是一个简单的 Nginx 配置示例，加了 Basic Auth：

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        auth_basic "Ollama API";
        auth_basic_user_file /etc/nginx/.htpasswd;

        proxy_pass http://localhost:11434;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

这样配置后，每次调用 API 都需要输入用户名和密码。

知识体系图

下面这张图帮你理清本章的核心逻辑：

这张图把 Ollama API 的核心脉络画出来了。你从 REST API 出发，左边是调用方式，右边是安全防护，中间是五个核心端点。做 RAG 系统时，你主要跟 generate、chat 和 embeddings 打交道。

好了，这一章的内容就到这里。API 这东西，光看文档不够，建议你打开终端，把上面的 curl 命令都跑一遍。亲手试过，印象才深。