第4章 交互API与开发集成
第 4 章 · 交互 API 与开发集成
章节摘要：模型建好了，怎么跟它对话、怎么把它接进自己的程序？这一章讲 Ollama 的交互协议栈——CLI、REST API、SDK 三个层次。CLI 面向人，有交互式对话、斜杠命令、多行输入等高级用法；REST API 面向程序，提供 /api/chat、/api/generate、/api/embeddings 三个核心端点；官方 SDK 则把 API 封装成 Python、JavaScript、Go 等语言的原生体验。读完本章，你能用三种方式跟本地模型对话，并知道它们共享的是同一套语义契约。
你能学到什么
阅读完本章，你应当能够：
- 用 CLI 的交互模式、/set 与 /show 斜杠命令完成高级交互
- 构造
/api/chat、/api/generate、/api/embeddings的请求与解析流式响应 - 用官方 SDK 写一段调用本地模型的最小程序
- 说清 CLI、API、SDK 三者共享的语义契约
- 理解无状态设计：为什么每次请求都要携带完整上下文
核心概念速览
金句：CLI 是协议的人格化入口，API 是协议的标准化载体，SDK 是协议的生态化延伸——三者共同回答"如何让大模型能力像 HTTP 之于 Web 一样可被普遍调用"。
交互协议栈三层
三个让你眼前一亮的能力
这一章你会解锁三个具体能力，提前预告：第一，用 curl 一条命令就能让本地模型干活，不需要任何 SDK——这让你可以把它接进任何语言、任何脚本；第二，流式接口让响应像打字机一样逐字输出——聊天机器人、代码补全这类交互式体验都依赖它；第三，/api/embeddings 一个接口就能拿到文本向量——它是第 6 章 RAG 的地基，你现在就学会，后面知识库问答直接复用。这三样合起来意味着：本地模型从"终端里能聊天"变成"任何程序里都能调用"。
子章节导航
4.1 CLI 高级用法
交互式对话模式、斜杠命令系统（/set /show /bye）、多行输入与内容类型感知，以及 CLI 如何成为理解 API 语义的最佳教学案例。
4.2 REST API 深度指南
三个核心端点的语义、无状态设计哲学、流式响应的实现与观测字段，以及统一架构下的错误与指标一致性。
4.3 SDK 与多语言支持
官方 SDK 的双轨生成范式、四层技术栈，以及本地胶水、微服务节点、企业智能中枢三种应用模式。
子章节之间的逻辑关系
4.1 给人用的 CLI ──► 4.2 给程序用的 API ──► 4.3 给生态用的 SDK
三者是同一语义契约在不同媒介上的投影：CLI 的命令可等价翻译成 curl 请求，curl 请求可等价翻译成 SDK 调用。先学 CLI 建立直觉，再看 API 理解契约本质，最后用 SDK 落地产物。
这一章解决的真实问题
模型跑起来了，但要"接进自己的系统"才是多数人用 Ollama 的真实目的：写个脚本批量处理文档、给网页加个 AI 对话框、在微信机器人里调模型、让 CI 流程自动生成代码注释。这些场景的共同点是：你不能坐在终端前手动输入，必须让程序自己去调用。本章就是教你这一层：先讲 CLI——因为它是理解 API 的最佳入口，你敲的每条命令背后都对应一个接口调用；再讲 REST API——程序直接发 HTTP 请求就能对话，不依赖任何语言 SDK；最后讲官方 SDK——它把接口封装成 Python/JavaScript/Go 等语言的自然写法，省去手拼 JSON 的麻烦。三条路殊途同归，背后都是同一套语义契约。
一个容易误判的点
新手常纠结"用 CLI 还是用 API"，其实不是二选一。CLI 适合你亲手调试、快速验证；API 适合程序接入；SDK 适合写正式代码。同一个模型，三种方式都能访问，区别只在"谁在调用"。一个实用的心智是：CLI 命令就是 API 的教程——遇到不懂的接口，先在终端用 ollama run 试出感觉，再照着请求结构写代码，基本不会错。这也是本章把 CLI 放在最前面的原因。
为什么要搞懂"无状态"设计
第 4.2 节反复强调"会话状态在客户端，服务端不保存"。这个设计初看反直觉——为什么不把对话历史存在服务端？但想通后你会认可它的好处：服务器重启不丢对话（历史在你这）；多台机器可以共享同一份上下文（把 messages 传过去就行）；做 RAG 时可以在请求前动态注入检索结果。理解了这个设计，你写代码时就不会犯"以为服务端记得上一轮"的错误——每轮对话都要自己带上完整历史。
动手实验建议
读完本章，请完成一个"最小闭环"：用 curl 调一次 /api/chat 拿到响应；再用你熟悉的语言写一个 20 行内的程序，用 SDK 实现同样的对话；最后把输入改成流式，看看逐 token 输出的效果。这个闭环做完，你就真正拥有了"把本地模型接进任何程序"的能力，后面第 6 章的 RAG 和 Agent 都建立在这个基础上。
三种交互方式速查
| 方式 | 适合谁 | 特点 | 学习建议 |
|---|---|---|---|
| CLI | 人工调试 | 有状态、有斜杠命令 | 先学，建立直觉 |
| REST API | 程序接入 | 无状态、语言无关 | 理解契约本质 |
| SDK | 正式开发 | 语言原生、类型安全 | 落地生产 |
⚠️ 常见误区：以为必须二选一。同一套服务三种方式都能用——调试用 CLI，验证用 curl，上线用 SDK。它们不是竞争关系，是同一契约的三副面孔。
💡 关键直觉：记住"无状态"这三个字。服务端不记住任何对话，所以你的程序要负责把完整上下文带来带去。这看似麻烦，却换来服务可重启、可多机共享上下文的弹性。
前置知识与后续延伸
- 前置知识：第 3 章建好的本地模型；对 HTTP 与 JSON 有基本认识
- 后续延伸：第 6 章 RAG 和 Agent 都建立在 API 与 SDK 之上；第 7 章网络配置保护的就是这套 API 暴露的端口
读完本章的验收标准
四件事。第一，你能不看文档写出一条正确的 /api/chat 请求（含 model、messages、stream 三个字段）。第二，你能说清 stream 为 true 和 false 的区别以及各自适用场景。第三，你能用你熟悉的语言调用本地模型并拿到结构化结果。第四，你知道 CLI、API、SDK 三者的关系——它们共享同一套语义契约，只是媒介不同。做到这四点，交互层就真正拿下了。
一些提个醒的事
本地模型的接口和云端 API 有个重要差异：没有速率限制和账号体系，所以你的程序要自己控制并发——一次性发几十个并发请求可能把显存打爆。另一个细节是 token 计数：本地推理不按 token 收费，但上下文长度受模型限制，超长输入会被截断，写代码时要注意控制 messages 的长度，必要时做摘要或截断。