第2章 Ollama API入门

Ollama API 入门：从 REST 到实战调优

聊到 Ollama 的 API，我得先说说自己的感受。刚开始接触时，我以为就是个简单的 HTTP 调用，后来才发现——嗯，这里面的门道还真不少。今天咱们就把 REST API 的底裤扒干净，从生成接口到聊天接口，再到参数调优，一步到位。

REST API 概览：你需要的就这几个端点

Ollama 的 API 设计得很干净。说白了，就是几个核心端点，没有花里胡哨的东西。我个人习惯把 API 分成三类：

生成接口（/api/generate）—— 一次请求，一次响应，适合补全任务
聊天接口（/api/chat）—— 多轮对话，带上下文，适合聊天场景
管理接口（/api/tags、/api/pull 等）—— 模型管理，日常运维

你想想看，这三个端点基本覆盖了 90% 的使用场景。我在项目中遇到过最坑的事，就是有人把生成接口当聊天接口用，结果上下文全丢了。所以咱们先搞清楚它们的区别。

核心区别一句话：生成接口是无状态的，每次请求都是独立推理；聊天接口是有状态的，会自动维护对话历史。

生成接口详解：/api/generate

这个接口最直接。你给一段文本，它给你续写。我刚开始做 AI 应用时，第一个调的就是它。

来看个最简单的例子：

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "为什么天空是蓝色的？",
  "stream": false
}'

返回结果长这样：

{
  "model": "llama3.2",
  "created_at": "2024-01-15T12:00:00Z",
  "response": "天空呈现蓝色是因为瑞利散射...",
  "done": true,
  "context": [/* 上下文向量 */],
  "total_duration": 1234567890,
  "load_duration": 123456,
  "prompt_eval_count": 10,
  "eval_count": 50,
  "eval_duration": 987654321
}

注意那个 context 字段。它是个向量数组，代表当前对话的上下文。如果你想做多轮对话，就得手动把 context 传回去。我曾经踩过这个坑——忘了传 context，结果模型每次都是「初次见面」，回答完全对不上。

我的小技巧：生成接口适合做文本补全、代码生成、摘要提取这类单次任务。如果要做聊天机器人，还是用聊天接口更省心。

聊天接口详解：/api/chat

这个接口才是为对话场景设计的。它接收一个消息列表，自动帮你维护上下文。

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [
    {"role": "system", "content": "你是一个物理学家。"},
    {"role": "user", "content": "解释一下量子纠缠"}
  ],
  "stream": false
}'

返回结果：

{
  "model": "llama3.2",
  "created_at": "2024-01-15T12:01:00Z",
  "message": {
    "role": "assistant",
    "content": "量子纠缠是量子力学中的一种现象..."
  },
  "done": true,
  "total_duration": 2345678901,
  "load_duration": 123456,
  "prompt_eval_count": 25,
  "eval_count": 80,
  "eval_duration": 1234567890
}

这里有个关键点：messages 数组里的顺序就是对话顺序。系统消息（system）通常放在最前面，用来设定角色或行为规则。用户消息（user）和助手消息（assistant）交替出现。

为什么会这样设计？因为大模型本质上是在做「下一个词预测」，你给的消息序列越长，它越能理解上下文。我在做客服机器人时，就把历史对话全部塞进 messages 里，效果出奇的好。

注意：消息列表越长，消耗的 token 越多，推理速度也会变慢。建议控制历史轮数，比如只保留最近 10 轮对话。

参数调优基础：让模型听你的话

调参这事儿，说白了就是跟模型「讨价还价」。我刚开始时也是一头雾水，后来慢慢摸索出一些门道。

先看几个核心参数：

参数名	类型	默认值	说明
temperature	float	0.8	控制随机性。值越大，回答越「天马行空」
top_p	float	0.9	核采样。只考虑概率累计到 top_p 的 token
top_k	int	40	只从概率最高的 k 个 token 中采样
repeat_penalty	float	1.1	重复惩罚。值越大，越不容易重复
num_predict	int	128	最大生成 token 数

来个实际例子，看看参数怎么用：

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "写一首关于春天的诗",
  "options": {
    "temperature": 0.7,
    "top_p": 0.9,
    "repeat_penalty": 1.2,
    "num_predict": 200
  },
  "stream": false
}'

我个人习惯这样调参：

需要精确回答（比如代码生成）：temperature 设 0.1~0.3，repeat_penalty 设 1.0
需要创意内容（比如写故事）：temperature 设 0.8~1.0，top_p 设 0.95
需要平衡（比如客服对话）：temperature 设 0.5~0.7，repeat_penalty 设 1.1

我曾经犯过一个错误：把 temperature 设成 2.0，结果模型开始胡言乱语，输出了一堆乱码。嗯，后来才知道 temperature 一般不超过 1.5，超过 1.0 就已经很「放飞自我」了。

避坑指南：调参时一次只改一个参数。我见过有人同时改 temperature、top_p、top_k，结果出了问题根本不知道是哪个参数导致的。先固定其他参数，逐个调试，这是最稳妥的方法。

知识体系总览

下面这张图是我自己整理的 API 调用流程，你看一眼就能明白整体逻辑：

这张图把整个调用链路串起来了。从客户端发起请求，到 API 网关路由，再到具体的接口处理，最后经过参数调优层进入模型推理。你想想看，每一步都有优化的空间。

实战小贴士

最后分享几个我在项目中积累的经验：

流式输出：把 stream 设为 true，可以实时看到模型生成的内容。用户体验会好很多，但后端处理要复杂一些。
模型热切换：调用时直接改 model 字段就行，Ollama 会自动加载。我经常在代码里写个配置，动态切换模型做对比测试。
错误处理：API 返回 404 通常是模型没拉取，返回 500 可能是参数越界。记得加 try-catch。

重要提醒：生产环境一定要加超时控制。我见过有人没设超时，结果模型卡住了，整个服务线程池被占满，最后服务挂了。建议超时时间设为 30 秒。

好了，API 入门这块就聊到这儿。参数调优是个细活，需要多试多练。你只要把今天讲的这几个接口和参数搞明白，Ollama 的基本操作就稳了。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

Ollama API 入门：从 REST 到实战调优

REST API 概览：你需要的就这几个端点

生成接口详解：/api/generate

聊天接口详解：/api/chat

参数调优基础：让模型听你的话

知识体系总览

实战小贴士