ollama python怎么用

你已经在本机跑起了 Ollama，模型也能在命令行里聊，但一换到 Python 就卡住：库装哪个、地址填什么、流式怎么接、报错从哪查。这篇按「先跑通、再跑顺」的顺序，把官方 Python 库调本地模型的完整动作走一遍，最后给一份按现象排错的对照清单。

你已经在本机把 Ollama 跑起来了，命令行里也能正常聊，结果一换到 Python 就卡住：库装哪个、地址填什么、流式怎么接、报错从哪查。这篇按「先跑通、再跑顺」的顺序，把官方 Python 库调本地模型的完整动作走一遍，最后给一份按现象排错的对照清单。全程只讲判断标准和可执行动作，具体参数默认值以你本地安装版本的文档为准。

读之前先明确一件事：Python 侧所有问题，几乎都能在命令行侧复现或排除。命令行能出的结果，Python 才有前提。所以下面每个环节都先给一个「在命令行能验证」的动作，再去写代码，这样出错时你能立刻判断是环境问题还是代码问题。

先把环境和连接确认清楚

1. 确认服务在跑在终端执行一次本地模型列表查询，能正常返回模型名就说明服务进程和端口都活着。返回空列表也算活着，只是还没拉模型。
2. 装官方 Python 库用 pip 装官方包，装完在 Python 里导入一次，导入不报错说明版本和解释器匹配。如果是虚拟环境，确认你装库和跑脚本用的是同一个环境。
3. 对齐地址与端口客户端默认指向本机默认端口。如果你改过启动环境变量、换过端口，或者服务跑在容器里、脚本跑在宿主机，就必须显式指定地址。跨容器还要确认端口有没有映射出来。
4. 写最小连通请求先用一个「列出本地已有模型」的调用把链路跑通，再写业务代码。这个最小请求能过，说明网络、库版本、地址三件事都没问题。

服务端

真正加载模型、跑推理的那个进程，Python 只是通过 HTTP 找它说话

客户端地址

Python 库要连的 host 与端口，默认值和你的启动方式不一定一致

最小连通请求

不涉及生成、只做一次列表查询的调用，用来把连接问题和代码问题分开

对话接口怎么调：参数与返回结构

官方库提供两种调用形态，先分清再用。一种是「对话」，入参是一串带角色的消息，天然支持多轮；另一种是「生成补全」，入参是一段提示词，适合单次改写、摘要这类场景。选错了不会立刻报错，但多轮上下文会自己乱掉，表现为模型答非所问、把系统指令当用户输入。

• 消息列表里的角色顺序要固定：系统在前、用户与助手交替在后，顺序错了模型表现会明显变差
• 历史消息直接塞进去最省事，但长会话要配合条数上限，否则迟早撞上上下文长度限制
• 把每次请求的结束原因记进日志，截断和正常结束要能一眼区分
• 温度、输出长度这类参数先在默认值下跑通，再改；一次改多个，出问题无法归因

一个最小对话骨架

# 伪代码，字段名以你本地库版本为准
client = Client(host="http://本机地址:端口")
resp = client.chat(
    model="本地已有模型名",
    messages=[
        {"role": "system", "content": "你是简洁的助手"},
        {"role": "user", "content": "用一句话解释什么是向量"},
    ],
)
print(resp["message"]["content"])

流式输出怎么接，卡顿怎么定位

把流式开关打开后，返回的不再是一个完整对象，而是一段段增量。你需要自己在循环里拼接，并识别结束标志。流式的好处是首字快、体感好，但它不改变总耗时——如果模型本身就慢，流式只会让你更早看到「它在慢」。

1. 开开关在对话调用里加上流式参数，确认返回对象变成可迭代的分片，而不是等待后才拿到完整结果。
2. 循环拼接遍历分片，把每片里的文本取出来累加到一个缓冲区。注意结束标志出现后要停止追加，别把空片也算进去。
3. 打两个时间点记录第一个分片到达的时刻和最后一个分片到达的时刻。前者反映排队与加载，后者反映生成总时长，两条曲线分开看才有意义。
4. 量基线去 /tools/speed-test 跑一条延迟基线，把「Python 侧观测到的分片时间」和基线对照，能快速判断慢在模型、网络还是你的循环。

• 首字慢但后续稳：多半是模型加载或排队，查显存是否够、是否需要常驻
• 首字快但每片间隔长：模型在 CPU 上跑的概率大，去 /ollama-gpu-selection 与 /local-inference-speed-tuning 对一下加载逻辑
• 偶发卡住不动：先看是不是长上下文把显存吃满，缩短历史再复现一次
• 前端乱码：先怀疑分片边界，改成先累积再解码，多数能直接消掉

出错了按这个顺序排

下面这张表按「从外到内」的顺序排：先排环境，再排模型，最后才怀疑代码。按顺序走的原因很简单——越靠外的问题越常见，也越好验证。跳过前面直接改代码，通常是在浪费时间。

• 连接类问题一律先在命令行复现，命令行不通就别动 Python 代码
• 模型名一律从列表接口复制，不要手打，标签写法很容易差一个字符
• 慢的问题先区分「冷启动慢」和「一直慢」，前者是加载策略，后者是硬件或参数
• 报错信息里带路径或端点的，直接把那段贴出来对照站内端点说明，通常能定位到配置项

先让命令行能出结果，再让 Python 能出结果，最后才谈流式和调参——顺序反了，每步都要重新猜一遍。