本地大模型部署这件事从去年到现在我身边至少有二十来个朋友问过同一个问题模型跑起来了然后呢命令行里聊两句挺新鲜可真正想把它塞进自己的工具链里做个小助手、做个批处理脚本、做个内部知识库问答就卡在“怎么让程序跟模型对话”这一步。Ollama 装完、模型拉完ollama run一敲界面是能聊但那是个交互式终端不是给代码用的接口。真正要把模型变成自己应用里的一个零件绕不开的就是它的原生 API。这篇东西就是聊这个的。标题里挂着“从入门到入土”我理解这个系列的意思——入门是能跑起来入土是能把它埋进生产环境里干活。进阶篇的核心就是把 Ollama 当成一个本地服务来用通过它的 HTTP 接口做应用开发。我会从接口设计讲起把几个核心端点拆开揉碎给出可直接抄的调用代码再聊聊流式输出、结构化输出、并发、上下文管理这些实际开发里躲不掉的问题。适合已经装好 Ollama、能跑通一个模型但还没搞明白怎么用代码调它的朋友也适合已经会调、但总在流式解析和并发上翻车的朋友对照看看。1. 先搞清楚 Ollama 到底暴露了什么很多人第一次接触 Ollama 的 API是在浏览器里敲http://localhost:11434看到一行“Ollama is running”然后就没了。这行字其实是个信号11434 端口上跑着一个 HTTP 服务你的程序只要会发 HTTP 请求就能跟模型对话。它不依赖任何 SDK不挑语言Python、Node、Go、甚至 shell 里的 curl 都能用。这一点很关键——意味着你不需要为了调模型去学一套新的客户端库现有的 HTTP 工具链直接复用。1.1 原生 API 与 OpenAI 兼容层的关系Ollama 其实提供了两套接口。一套是它自己的原生 API路径以/api/开头比如/api/generate、/api/chat、/api/embed另一套是 OpenAI 兼容层路径以/v1/开头比如/v1/chat/completions。这两套东西并存各有各的用处。原生 API 是 Ollama 自己的“母语”功能最全模型管理的那些操作拉取、删除、列出、查看详情只有原生 API 有。OpenAI 兼容层是为了让那些已经写死了 OpenAI 客户端的项目能低成本迁移过来接口形状对齐但功能是原生 API 的子集。我的建议很直接新项目用原生 API老项目迁移用兼容层。原因在于原生 API 的返回结构更贴合 Ollama 自己的模型管理逻辑字段命名也更直白调试的时候一眼能看懂兼容层为了对齐外部规范做了一些字段映射出问题时排查链路更长。这里有个容易踩的坑两套接口的默认端口是同一个 11434但路径前缀不同写代码时如果混用很容易出现“请求发出去了但 404”的情况。我见过有人把/api/chat和/v1/chat/completions的请求体搞混把 OpenAI 格式的messages直接丢给原生接口结果模型返回一堆莫名其妙的补全。所以第一件事先把你要用的那套接口的请求体结构记牢。1.2 服务地址与跨域配置的实操细节默认情况下Ollama 只监听127.0.0.1:11434也就是只有本机能访问。这在开发阶段没问题但如果你想让同一局域网里的另一台机器、或者容器里的服务调它就得改监听地址。通过环境变量OLLAMA_HOST控制比如设成0.0.0.0:11434就能对外监听。注意把监听地址放开到0.0.0.0意味着同网段内任何设备都能访问你的模型服务如果机器上还有别的敏感服务务必配合防火墙规则限制来源别图省事直接全开。跨域是另一个高频问题。如果你在浏览器里直接写前端代码调 Ollama会遇到 CORS 拦截。Ollama 提供了OLLAMA_ORIGINS环境变量来配置允许的来源多个来源用逗号分隔支持通配符。开发阶段图方便可以设成*但上线前一定要收窄到具体域名。我个人的习惯是开发机上也只放行http://localhost:3000这类明确的前端地址避免养成“反正本地无所谓”的坏习惯等部署时忘了改。配置改完记得重启服务环境变量是在进程启动时读取的改完不重启等于没改。这一点看起来是常识但我确实见过有人改完环境变量对着旧进程调试半小时。2. 核心端点逐个拆generate、chat、embed原生 API 的端点不多但每个的定位差别很大用错了不仅浪费算力还会让代码逻辑变复杂。这一节把最常用的三个端点讲透顺带把请求体和响应体的关键字段过一遍。2.1 /api/generate单轮补全的正确打开方式/api/generate是最基础的端点定位是“给一段提示返回一段补全”。它适合的场景是单轮任务文本改写、摘要、翻译、代码补全、分类打标。请求体里最核心的字段是model和prompt前者指定模型名必须是你本地已经拉下来的后者是输入文本。一个最小的请求长这样curl http://localhost:11434/api/generate -d { model: qwen2.5:7b, prompt: 用一句话解释什么是向量数据库, stream: false }注意stream这个字段。它默认是true也就是流式返回响应是一行一行的 JSON每行包含一个片段。如果你在脚本里直接拿响应体当整体解析会得到一堆拼接不完整的 JSON解析必然报错。做非交互式任务时第一件事就是把stream设成false这样返回的是一个完整的 JSON 对象字段包括response模型输出、done是否结束、context对话上下文可用于后续续写、以及若干耗时统计字段。context这个字段值得单独说。它是模型对当前输入的内部编码把它原样带回下一次请求的context字段就能实现“续写”效果而不需要把历史文本重新拼进 prompt。这在做长文本分段处理时很有用——比如你有一篇长文要逐段摘要每段处理完把 context 传下去模型对前文的记忆会更连贯。不过要注意context 是模型相关的换模型后不能混用。2.2 /api/chat多轮对话的状态管理/api/chat是为多轮对话设计的请求体里的messages是一个数组每个元素有role和content两个字段role 取system、user、assistant三种。跟 generate 最大的区别在于chat 端点本身是无状态的对话历史需要你自己维护并每次全量传进去。这一点是新手最容易误解的地方。很多人以为调了 chat 接口服务端就记住了上下文下一轮只传新消息就行。实际上不是Ollama 不会替你保存会话每次请求你都得把完整的 messages 数组带上。这既是负担也是自由——负担在于你要自己管历史自由在于你可以精确控制哪些历史进上下文、哪些丢掉做上下文裁剪时非常灵活。一个典型的多轮请求import requests messages [ {role: system, content: 你是一个简洁的技术助手回答不超过三句话。}, {role: user, content: Ollama 的默认端口是多少} ] resp requests.post(http://localhost:11434/api/chat, json{ model: qwen2.5:7b, messages: messages, stream: False }) data resp.json() assistant_reply data[message][content] messages.append({role: assistant, content: assistant_reply})看到没拿到回复后要手动 append 进 messages下一轮再整体发出去。这个模式在写代码时建议封装成一个会话类内部维护 messages 列表对外只暴露ask(text)方法避免每处调用都手动拼数组。system 消息的位置也有讲究。放在数组最前面是标准做法但有些模型对 system 的遵循程度不一样实测下来 7B 级别的模型对 system 的敏感度不如更大参数量的模型如果你的 system 提示词很长很复杂小模型可能会“选择性忽略”。这时候可以把关键约束同时写进第一条 user 消息里双保险。2.3 /api/embed把文本变成向量/api/embed是做检索增强、语义搜索、聚类的基础。请求体传model和inputinput 可以是单个字符串也可以是字符串数组批量。返回的embeddings是一个二维数组每个元素对应一条输入的向量。curl http://localhost:11434/api/embed -d { model: nomic-embed-text, input: [第一段文本, 第二段文本] }这里有个实操要点embedding 模型和生成模型是两套东西别拿生成模型去做 embed。生成模型虽然也能返回向量但它的向量不是为相似度计算优化的拿来算余弦相似度效果会很差。专门拉一个 embedding 模型比如 nomic-embed-text 或者 bge 系列体积小、速度快专门干这活。批量输入时注意单次请求的条数。虽然接口支持数组但一次塞几百条进去显存和内存都会吃紧实测下来单次 32 到 64 条是比较稳的区间具体看你的机器配置和文本长度。超长文本还要注意模型的上下文窗口限制超出部分会被截断截断是静默的不会报错所以入库前最好自己先做长度检查。2.4 模型管理端点/api/tags、/api/pull、/api/delete应用开发里这几个端点用得不多但在做部署脚本、健康检查、模型预热时会用到。/api/tags列出本地所有模型返回每个模型的名字、大小、修改时间适合做启动时的依赖检查——程序启动先查一下需要的模型在不在不在就提示用户拉取比运行到一半报错友好得多。/api/pull是拉取模型支持流式返回进度做安装向导时可以把进度透传给前端。/api/delete删除模型慎用删了要重新拉。/api/show查看模型详情包括参数规模、量化方式、模板格式排查“为什么这个模型输出格式怪怪的”时很有用——很多时候是模型的 prompt 模板跟你的预期不一致。3. 流式输出从能用到好用的关键一跃流式输出是提升交互体验的核心。用户敲完问题如果等三五秒才看到整段回复体感很差如果字是一个一个蹦出来的哪怕总耗时一样用户也觉得“它在思考”。Ollama 的流式返回是 NDJSON 格式也就是每行一个独立的 JSON 对象行与行之间用换行符分隔。3.1 NDJSON 流的解析姿势流式响应的每一行长这样{model:qwen2.5:7b,created_at:...,message:{role:assistant,content:你},done:false} {model:qwen2.5:7b,created_at:...,message:{role:assistant,content:好},done:false} ... {model:qwen2.5:7b,created_at:...,message:{role:assistant,content:},done:true,total_duration:...}解析的关键是逐行读取、逐行 json 解析取message.content拼接直到done为 true。Python 里用 requests 的iter_lines最省事import requests, json def stream_chat(model, messages): with requests.post(http://localhost:11434/api/chat, json{model: model, messages: messages, stream: True}, streamTrue) as resp: for line in resp.iter_lines(): if not line: continue chunk json.loads(line) if chunk.get(done): break piece chunk.get(message, {}).get(content, ) if piece: yield piece这段代码有几个细节值得说。streamTrue是 requests 的参数不加的话响应体会被整体缓冲流式就失效了。iter_lines按行切分但要注意它可能把一行拆成多次返回所以不能假设每次拿到的都是完整 JSON——不过 requests 的 iter_lines 在大多数情况下会处理好边界稳妥起见还是加个空行跳过。done为 true 的那一行 content 通常是空字符串直接 break 即可。提示流式解析时不要用resp.text或resp.json()这两个都会等响应完全结束才返回等于把流式退化成非流式白白浪费了体验优势。3.2 流式场景下的错误处理流式接口的错误处理比非流式麻烦。非流式时HTTP 状态码不对直接抛异常就行流式时连接建立成功、状态码 200但流到一半模型出错错误信息会以一行 JSON 的形式混在流里字段可能是error。所以解析循环里要判断chunk.get(error)有错误就中断并上报别傻乎乎地继续拼。另一个坑是客户端主动断开。用户点了“停止生成”前端断开连接服务端会感知到并停止推理但你的代码里如果没处理ConnectionError或GeneratorExit可能会抛一堆异常日志。在生成器函数里用 try/finally 包住确保断开时能清理资源日志也干净。还有超时设置。流式请求的总时长可能很长生成长文本时几十秒很正常但单次读取的间隔不应该太长。给 requests 设timeout(连接超时, 读取超时)读取超时设成 30 秒左右比较合理——如果 30 秒一个字节都没来基本可以判定卡死了。3.3 把流式接到前端SSE 还是 WebSocket如果你的应用有前端后端拿到 Ollama 的流之后还要再转发给浏览器。这时候有两个选择SSEServer-Sent Events和 WebSocket。我的经验是优先 SSE因为它是单向的、基于 HTTP 的实现简单浏览器原生支持 EventSource断线重连也是内置的。WebSocket 适合双向通信场景但单纯做“后端推流给前端”有点杀鸡用牛刀还要自己处理心跳和重连。后端转发时把 Ollama 的 NDJSON 逐块转成 SSE 的data:格式推出去就行。注意设置响应头Content-Type: text/event-stream、Cache-Control: no-cache以及关闭 Nginx 之类的反向代理缓冲X-Accel-Buffering: no否则流会被代理攒着一起发前端看到的还是“一次性蹦出来”。4. 结构化输出与参数调优模型输出是自然语言但程序要的是结构化数据。让模型稳定输出 JSON是做应用开发绕不过去的一关。Ollama 原生 API 提供了format参数传json就能约束模型输出合法 JSON这是最省事的方式。4.1 formatjson 的用法与边界请求体里加format: json模型会被引导只输出 JSON 对象不带 markdown 代码块包裹也不带解释性文字。配合明确的 prompt命中率很高resp requests.post(http://localhost:11434/api/generate, json{ model: qwen2.5:7b, prompt: 从下面这句话里抽取人名和城市输出 JSON字段为 name 和 city张三上周去了杭州。, format: json, stream: False }) result json.loads(resp.json()[response])但要清楚它的边界formatjson保证的是“语法上是合法 JSON”不保证“字段符合你的 schema”。模型可能给你{name: 张三, city: 杭州}也可能给你{人名: 张三, 地点: 杭州}字段名对不对得看你 prompt 写得够不够明确。想要更强的约束可以在 prompt 里直接给出 JSON schema 示例甚至把示例的字段顺序、类型都写死实测能显著提升字段一致性。还有一个细节formatjson对模型的“听话程度”有要求。参数量太小的模型比如 1B 级别即使加了约束偶尔还是会输出不合法 JSON这时候要么换大一点的模型要么在代码里加一层容错——解析失败时重试一次或者用正则从文本里抠出第一个{...}块再解析。4.2 temperature、top_p 这些参数怎么调生成质量调优绕不开采样参数。Ollama 的请求体支持options字段里面可以放temperature、top_p、top_k、num_predict、repeat_penalty等。这些参数不是玄学每个都有明确的作用参数作用常用取值适用场景temperature控制随机性越高越发散0~0.3 严谨0.7~1.0 创意抽取任务用低值文案生成用高值top_p核采样控制候选词范围0.9~0.95一般保持默认配合 temperature 微调top_k只从概率最高的 k 个词里采样40 左右想进一步收敛输出时调低num_predict最大生成 token 数按任务定摘要类设小长文生成设大repeat_penalty重复惩罚1.1~1.3模型爱复读时调高调参的顺序建议是先定 temperature再动 top_p最后才碰 top_k。因为 temperature 对输出的影响最直接top_p 和 top_k 是在 temperature 基础上的进一步约束。做信息抽取、分类这种要稳定结果的任务temperature 直接拉到 0 到 0.2基本每次输出都一致做头脑风暴、文案润色temperature 放到 0.8 以上让模型多给几个不同角度。num_predict这个参数容易被忽略但它直接影响响应时间和资源占用。默认值可能很大模型会一直生成到自然结束如果你的任务只需要一句话设成 100 左右能明显缩短响应。反过来做长文生成时如果发现输出被截断先检查是不是 num_predict 设小了。4.3 用 system 提示词稳住输出格式除了 format 参数system 提示词是控制输出格式的第二道保险。我的习惯是把格式要求写进 system把具体任务写进 user职责分离。比如system: 你是一个数据抽取器。只输出 JSON不要输出任何解释。JSON 必须包含 name字符串和 city字符串两个字段。 user: 张三上周去了杭州。这种写法比把所有要求堆在 user 里更稳定因为 system 在对话中的权重通常更高模型对它的遵循更持久。多轮对话里system 只在开头出现一次后续轮次模型依然会参考它这也是为什么 system 适合放“全局约束”。5. 并发、上下文与工程化实践单次调用跑通只是起点真正做应用时并发、上下文长度、错误重试这些工程问题才是决定能不能上生产的关键。5.1 并发请求的坑与限流策略Ollama 默认对并发请求的处理能力有限具体取决于你的硬件和模型大小。同一时刻发太多请求要么排队等待要么直接失败。我实测过在一台普通开发机上7B 模型同时发 5 个请求响应时间会明显拉长发到 10 个以上就开始有请求超时。所以并发控制是必须的。最直接的办法是在客户端加信号量限流比如用 Python 的threading.Semaphore或asyncio.Semaphore控制同时进行的请求数。限流值设多少取决于你的机器显存 8G 左右跑 7B 模型建议并发控制在 2 到 3显存 16G 以上可以放到 4 到 6。这个数字不是拍脑袋是看模型加载后剩余显存能容纳几个推理上下文。另一个思路是队列化。把请求丢进队列后台 worker 按顺序消费前端拿任务 ID 轮询结果。这种方式牺牲了实时性但稳定性最好适合批处理场景比如批量给几千条文本打标。队列化还能顺带做优先级调度重要的任务插队。注意并发调高之前先确认模型是否支持并行。有些模型在 Ollama 里加载时默认单实例并发请求会串行处理看起来像“并发没生效”其实是模型层面的限制。可以在启动时通过OLLAMA_NUM_PARALLEL环境变量调整并行数但调高会成倍占用显存量力而行。5.2 上下文窗口管理与历史裁剪多轮对话跑久了messages 数组会越来越长最终超出模型的上下文窗口。超出后 Ollama 的行为是截断但截断策略不一定符合你的预期可能把最早的系统提示词给截掉导致模型“失忆”。所以历史裁剪要自己做。常见的裁剪策略有三种。第一种是滑动窗口只保留最近 N 轮对话简单粗暴但有效适合闲聊类应用。第二种是保留 system 加最近 N 轮确保全局约束不丢适合任务型对话。第三种是摘要压缩把早期对话用模型总结成一段话替换掉原始消息适合长会话但会增加额外调用成本。我一般用第二种实现上就是维护 messages 时system 单独存user 和 assistant 的配对存进一个列表超过阈值就从头部丢弃最老的配对。阈值怎么定粗略估算一轮对话大约几百 token7B 模型的上下文窗口常见是 8K 到 32K留出生成用的空间历史部分控制在窗口的一半左右比较安全。5.3 超时、重试与降级网络请求没有百分百可靠的本地服务也一样——模型加载慢、显存不足、进程崩溃都会导致请求失败。工程化代码里超时和重试是标配。超时设置分两段连接超时和读取超时。连接超时短一点3 到 5 秒连不上就是连不上等再久也没用读取超时长一点非流式请求给 60 到 120 秒流式请求给 30 秒的间隔超时。重试策略上只对“可重试错误”重试比如连接超时、5xx 错误对 4xx 错误比如模型名写错重试没意义只会浪费时间。重试次数 2 到 3 次足够每次重试之间加个退避比如 1 秒、2 秒、4 秒。降级策略看场景。如果主模型调用失败可以降级到一个小一点的备用模型虽然质量差些但至少能用或者降级到缓存结果返回上一次的答案并标注“可能不是最新”。做内部工具时降级到“提示用户稍后重试”也是可接受的关键是别让整个应用卡死在一个失败的请求上。5.4 一个可直接复用的封装思路把上面这些揉在一起我通常会封装一个客户端类职责包括维护会话历史、处理流式与非流式、做超时重试、限流。对外暴露的方法不多chat(text)返回完整回复chat_stream(text)返回生成器embed(texts)返回向量。内部把 messages 管理、参数默认值、错误处理都收拢业务代码调用时只关心“问什么”和“拿结果”不关心底层细节。这种封装的好处是将来如果要换模型、换端点、加缓存改动都集中在一个地方业务代码不用动。我见过不少项目把 requests 调用散落在各处后来想加个重试或者换个模型得改几十个文件非常痛苦。前期多花半小时封装后期省几十小时维护。6. 常见问题速查与避坑清单这一节把实际开发中高频遇到的问题整理成表方便对照排查。这些问题大多不是文档里会写的是踩出来的。现象可能原因排查与解决请求返回 404路径写错混用了 /api 和 /v1确认端点前缀原生 API 是 /api/xxx响应解析报 JSON 错误stream 默认为 true拿到的是 NDJSON非流式场景显式设 streamfalse模型输出被截断num_predict 太小或上下文超限调大 num_predict检查历史长度流式输出前端一次性显示反向代理缓冲了响应关闭代理缓冲设 X-Accel-Buffering: no并发时大量超时并发超过硬件承载加信号量限流或改队列化formatjson 仍输出非 JSON模型太小或 prompt 不明确换大模型prompt 里给 schema 示例多轮对话模型“失忆”历史被截断或未传全量 messages检查 messages 是否完整做历史裁剪局域网其他机器连不上默认只监听 127.0.0.1设 OLLAMA_HOST0.0.0.0:11434浏览器调用被 CORS 拦截未配置允许来源设 OLLAMA_ORIGINS 为具体前端地址embedding 相似度不准用了生成模型做 embed换专用 embedding 模型除了表里的再补几个零散但重要的点。第一模型名要写全包括 tag比如qwen2.5:7b而不是qwen2.5虽然有时省略 tag 也能跑但明确写出来能避免拉到非预期版本。第二首次调用某个模型会触发加载耗时明显长于后续调用做健康检查或预热时要把这个考虑进去别把首次加载的慢当成故障。第三日志里别打印完整的 prompt 和响应尤其是涉及用户数据时脱敏后再记录这是基本的安全习惯。我个人在实际操作中的体会是Ollama 的原生 API 设计得相当克制端点少、字段直白学习成本低但“能用”和“用好”之间的差距全在工程细节上——流式解析、并发限流、上下文管理、错误重试这些才是决定一个 AI 应用能不能稳定跑起来的东西。接口本身半小时就能看完把这些细节磨顺往往要花上几天。建议上手时先用 curl 把每个端点手动敲一遍感受一下请求和响应的形状再写代码封装比直接抄示例代码理解得深。后续如果要扩展可以在这个封装基础上加缓存层相同 prompt 直接返回结果、加可观测性记录每次调用的耗时和 token 数这些都是在原生 API 之上做加法不影响底层逻辑。
