ollama-python 教程

你已经用命令行跑通了本地模型，想把调用写进 Python 脚本或自己的小工具里，结果卡在第一步：库装完连不上服务、返回的字段看不懂、流式输出接不上、换模型不知道改哪一行。这篇按「装好—连通—发出第一句话—接进自己的代码」的顺序走一遍，只讲动手的部分，参数取值和模型清单到站内对应页面核对。

命令行里 ollama run 已经能聊了，下一步自然是把调用搬进 Python 脚本或自己的小工具。很多人卡的地方其实不是代码难，而是没分清「库」和「服务」：pip 装的那个包只是客户端，真正跑模型的是本机常驻的 Ollama 服务，两者没接通就会一直报连接错误。

这篇按「装好—连通—发出第一句话—接进自己的代码」的顺序走一遍，只讲动手部分。参数具体取什么值、本地适合上哪些模型，这些跟机器配置强相关，到站内对应页面核对当时的数字，别照抄别人的配置。

先把库装上，再把服务连起来

1. 装库并确认解释器用 pip 安装官方客户端库，装完在 Python 里 import 一次。如果报模块找不到，多半是装到了另一个解释器或虚拟环境里，用 which python 和 pip -V 对着看路径是否一致。
2. 确认本机服务在跑另开一个终端跑 ollama serve（有的安装方式会做成后台服务）。服务没起，客户端怎么调都是连接被拒，这一步不要跳。
3. 跑通最小连通测试写三行代码：建客户端、查一下本地模型列表、打印结果。能打印出列表就说明网络这一层通了，再去写对话逻辑。

默认地址是本地回环，如果端口被别的程序占了，或者你把服务跑在另一台机器、容器里，就必须显式传 host 参数。地址到底写成什么形态，不同场景不一样，可以先到 /ollama-local-api-address 对照一下再改。

客户端库

只负责按协议发请求、把返回整理成对象，本身不含模型

Ollama 服务

常驻进程，负责加载模型、推理、把结果吐回给客户端

host

客户端往哪个地址发请求，本机、局域网、容器各不一样

发出第一句话：对话与生成两种写法

客户端主要两种调用方式：chat 收的是消息列表，适合多轮；generate 收的是单段提示词，适合一次性补全或改写。选哪种取决于你的场景，不要因为 chat 看起来更「高级」就一律用它，单次任务用 generate 往往更直观。

返回体字段不少，但业务里真正要用的通常只有两个：生成出来的文本，以及表示结束的标记。其它状态字段看一眼确认没有报错就行，别把它们全塞进业务逻辑，否则换模型或升级库的时候会一地鸡毛。

模型名不是随便写的，得是本地已经拉过的那个。先用命令行列一遍本地模型确认名字，再去 /models 看该模型的资料和适用场景，别把线上 API 的模型名直接搬过来用。

流式输出、多轮上下文与常用参数

• 打开流式后返回的是可迭代对象，要逐块取文本再拼接，拼完的那份才是完整回答；直接打印每一块会看到字一个个蹦出来。
• 交给前端或写日志时，建议边收边追加到一个字符串里，最后统一处理，别在循环里反复做重活。
• 多轮对话的历史要自己维护：把上一轮的用户消息和模型回复都追加进消息列表，下次调用一起传回去。
• 列表越来越长会拖慢速度、吃显存，常见做法是只保留最近若干轮，或者把早期内容压成一段摘要再带上。

温度、输出长度这类参数决定回答是「稳」还是「活」。需要确定答案的场景把随机性压低，需要发散创意的场景调高一点，没有通用最优值，按任务试几次就有手感。不同量化档位的模型表现差异，可以到 /quantization-tier-choice 一类页面看判断口径，别只看体积。

连不上、没输出、结果怪：按顺序排查

排查最怕跳步。按下面的顺序从下往上查，每过一层再往下走，比同时怀疑三四个地方快得多。

1. 服务是否在跑终端里能不能正常用命令行跟模型对话？能，说明服务没问题，问题在客户端这一侧。
2. host 与端口打印一下客户端实际用的地址，和你想连的地址对一遍；换过端口或跑在容器里时最容易错在这。
3. 模型名是否存在用命令行列出本地模型，确认脚本里写的名字在同一份清单里，大小写和分隔符都要对上。
4. 库与服务端兼容性前面都对还报协议类错误，再考虑库版本和服务端版本是否差得太远，对照站内资料决定要不要动。

如果调用不报错但长时间没结果，或者返回空内容，先看本机资源占用：模型太大、显存不够时会一直在换入换出，看起来就像卡死。这时换个小一点的模型或调低输出长度，往往比改代码有效。

最后做一件收尾的事：把调用封成一个小函数，host、模型名、常用参数全部抽成变量放在顶部。以后换模型、换机器、调参数都只改一处，不用在脚本里到处翻。