大模型应用开发 / 系统课时
认识 Ollama API 服务
认识 Ollama API 服务
学习目标
完成本课后,你将能够:
- 说明 Ollama 原生 API 的默认地址和基本约定
- 区分原生
/api与 OpenAI 兼容/v1接口- 理解流式、非流式和常见响应元数据
- 使用健康检查定位服务、模型和请求三类问题
默认地址与协议
本地 Ollama 服务默认监听:
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 和响应耗时字段,不应直接套用到所有兼容端点。
检查服务可用性
执行:
curl --fail --silent --show-error http://localhost:11434/api/tags预期响应结构:
{
"models": []
}本地已有模型时,models 数组不为空。HTTP 成功只能证明服务可访问,不代表指定模型一定可加载。
请求格式
大多数写接口使用 JSON 请求体,并应发送:
Content-Type: application/json典型请求由以下字段组成:
model:本地模型名称prompt或messages:输入内容stream:是否流式返回options:上下文、温度和输出长度等运行参数keep_alive:模型驻留时间format:结构化输出约束,适用于支持的接口
流式与非流式
原生生成接口默认常以流式方式返回多个 JSON 对象,每行是一个完整 JSON 对象,格式属于 NDJSON。最后一个对象的 done 为 true,并附带性能统计。设置:
{
"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 |
输出生成耗时 |
客户端应允许新增字段,避免严格拒绝服务端扩展。
错误分层
排错时区分三层:
- 连接错误:服务未启动、地址错误、端口被阻断。
- HTTP 错误:请求体无效、模型不存在、服务过载。
- 模型结果错误:回答不符合需求、结构不合法、上下文不足。
连接失败不应通过修改提示词解决,回答质量问题也不应通过反复重启服务解决。
最小诊断命令
检查模型列表:
curl -i http://localhost:11434/api/tags预期结果:
HTTP/1.1 200 OK
Content-Type: application/json
...
{"models":[...]}检查运行模型:
curl --fail --silent --show-error http://localhost:11434/api/ps预期响应:
{
"models": []
}没有已加载模型时数组为空,这是正常状态。
本课练习
练习 1:绘制接口地图
任务目标:区分 API 的资源和职责。输入或初始条件:已启动 Ollama。
实现要求:列出 tags、generate、chat、embed 和 ps。验收条件:每个端点写明方法、输入和输出用途。
练习 2:比较流式与非流式
任务目标:观察响应传输差异。输入或初始条件:本地已有文本模型。
实现要求:对同一提示词分别设置 stream true 和 false
验收条件:说明 NDJSON 与单 JSON 的解析方式。
练习 3:建立错误分类
任务目标:提高排查效率。输入或初始条件:准备三个故障:服务停止、模型名错误、回答格式错误。实现要求:为每个故障定义检测命令。验收条件:能准确归入连接、HTTP 或模型结果层。