大模型应用开发 / 系统课时

认识 Ollama API 服务

认识 Ollama API 服务

学习目标

完成本课后,你将能够:

  • 说明 Ollama 原生 API 的默认地址和基本约定
  • 区分原生 /api 与 OpenAI 兼容 /v1 接口
  • 理解流式、非流式和常见响应元数据
  • 使用健康检查定位服务、模型和请求三类问题

默认地址与协议

本地 Ollama 服务默认监听:

text
http://localhost:11434

原生 API 以 /api 开头,例如:

  • GET /api/tags:本地模型列表
  • POST /api/generate:文本生成
  • POST /api/chat:对话生成
  • POST /api/embed:嵌入向量
  • GET /api/ps:运行模型列表

默认本地 API 不要求认证。将服务开放到局域网或公网前,必须在代理层增加访问控制。

原生 API 与兼容 API

接口 基础路径 适用场景
Ollama 原生 API http://localhost:11434/api 使用 Ollama 特有字段和完整能力
OpenAI 兼容 API http://localhost:11434/v1 迁移现有 OpenAI SDK 或框架

两套接口字段不完全相同。原生 API 的 options、keep_alive 和响应耗时字段,不应直接套用到所有兼容端点。

检查服务可用性

执行:

bash
curl --fail --silent --show-error http://localhost:11434/api/tags

预期响应结构:

json
{
  "models": []
}

本地已有模型时,models 数组不为空。HTTP 成功只能证明服务可访问,不代表指定模型一定可加载。

请求格式

大多数写接口使用 JSON 请求体,并应发送:

text
Content-Type: application/json

典型请求由以下字段组成:

  • model:本地模型名称
  • prompt 或 messages:输入内容
  • stream:是否流式返回
  • options:上下文、温度和输出长度等运行参数
  • keep_alive:模型驻留时间
  • format:结构化输出约束,适用于支持的接口

流式与非流式

原生生成接口默认常以流式方式返回多个 JSON 对象,每行是一个完整 JSON 对象,格式属于 NDJSON。最后一个对象的 done 为 true,并附带性能统计。设置:

json
{
  "stream": false
}

后,服务等待生成完成,再返回单个 JSON 对象。非流式适合短任务、测试和结构化处理;流式适合聊天界面和长回答。

常见响应元数据

完成响应可能包含:

字段 说明
model 实际调用模型
created_at 响应时间
done 是否完成
done_reason 停止原因
total_duration 总耗时,纳秒
load_duration 加载耗时,纳秒
prompt_eval_count 输入 Token 数
prompt_eval_duration 输入处理耗时
eval_count 输出 Token 数
eval_duration 输出生成耗时

客户端应允许新增字段,避免严格拒绝服务端扩展。

错误分层

排错时区分三层:

  1. 连接错误:服务未启动、地址错误、端口被阻断。
  2. HTTP 错误:请求体无效、模型不存在、服务过载。
  3. 模型结果错误:回答不符合需求、结构不合法、上下文不足。

连接失败不应通过修改提示词解决,回答质量问题也不应通过反复重启服务解决。

最小诊断命令

检查模型列表:

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

预期结果:

text
HTTP/1.1 200 OK
Content-Type: application/json
...
{"models":[...]}

检查运行模型:

bash
curl --fail --silent --show-error http://localhost:11434/api/ps

预期响应:

json
{
  "models": []
}

没有已加载模型时数组为空,这是正常状态。

本课练习

练习 1:绘制接口地图

任务目标:区分 API 的资源和职责。输入或初始条件:已启动 Ollama。

实现要求:列出 tags、generate、chat、embed 和 ps。验收条件:每个端点写明方法、输入和输出用途。

练习 2:比较流式与非流式

任务目标:观察响应传输差异。输入或初始条件:本地已有文本模型。

实现要求:对同一提示词分别设置 stream true 和 false

验收条件:说明 NDJSON 与单 JSON 的解析方式。

练习 3:建立错误分类

任务目标:提高排查效率。输入或初始条件:准备三个故障:服务停止、模型名错误、回答格式错误。实现要求:为每个故障定义检测命令。验收条件:能准确归入连接、HTTP 或模型结果层。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

认识 Ollama API 服务

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通