摘要：一份从零把本地大模型接进 Python 项目的实战手册。覆盖安装拉模型、requests 直连 /api/generate、/api/chat 多轮对话、OpenAI 兼容端点（改两行就能把云端代码跑本地）、response_format 结构化 JSON 抽取、批量打标签带重试超时、Embedding 余弦相似度，最后把「端口暴露公网、冷启动超时、模型名 typo」这些生产坑讲透。基于 Ollama 0.5+ 与 Python 3.12 实测。
引子：我为什么从云端 API 转投本地大模型
三个月前我还在用某家云端大模型 API 写脚本。一个月下来账单 200 多块，关键是数据得出境——我把内部日志、用户反馈喂进去做分析，心里一直发毛：这些算不算敏感数据？万一哪天合规找上来，我拿什么解释「我把公司数据传到了第三方」？
后来试了 Ollama，彻底回头。本地跑开源模型，零调用成本、数据不出本机、断网也能用。我现在日常的代码注释生成、文本批量分类、日志语义检索，全在本地完成，电费忽略不计。算笔账：我那台老笔记本 24 小时开着，一个月电费撑死二十块，换来的是无限次调用和绝对的数据主权——这笔买卖太划算。
更早的触发点是一次安全审计。公司要求所有对外调用的第三方 API 必须登记数据流向，我那个云端大模型调用因为「可能传送敏感日志」被卡了两周流程。从那以后我就下定决心：凡是涉及内部数据的文本处理，一律本地化。Ollama 恰好在这个时间点成熟，7B 级别的开源模型在代码、抽取、分类任务上已经够用，门槛低到装个软件、敲条命令就能跑。
本文把我的接入套路完整写出来。Ollama 的 API 设计得很干净，REST 风格，本地默认跑在 http://localhost:11434。Python 3.12.4 + Ollama 0.5+ 实测，低版本在 JSON 模式等特性上有差异，下面会标注。不管你是想省 API 钱、护数据合规，还是单纯想断网也能用 AI，这套都能直接搬。
一、5 分钟装好：安装与拉模型
Ollama 支持 macOS、Linux、Windows。装完会顺带起一个本地 API 服务。我三台不同系统的机器都装过，过程基本一致，唯一要注意的是 Windows 上安装包会顺便把服务注册成开机自启，不想开机就跑的记得去任务管理器关掉。
# macOS / Linux 一键装
curl -fsSL https://ollama.com/install.sh | sh
# 拉一个常用模型（以 llama3.1 为例，约 4.7GB）
ollama pull llama3.1
# 验证服务在跑、模型已就绪
curl http://localhost:11434/api/tags
Windows 用户直接去 ollama.com 下安装包，装完在 PowerShell 里同样用 ollama pull llama3.1。模型名必须和 ollama list 输出一字不差，拼错不会报错，只会静默返回空——这是后面最常见的坑。我第一次拉模型时把 llama3.1 写成 llama-3.1（多了个横杠），对着空响应排查了十分钟，最后才发现是名字不对。
想跑轻量模型，可以用 llama3.2（3B，约 2GB），老笔记本也能带动。做嵌入检索用 nomic-embed-text（274MB，768 维向量），下面会用到。模型选择上有个经验：本地机器内存小于 8G 就老老实实用 3B，7B 在 CPU 推理时首字延迟能到十几秒，体验比较劝退；有独立显卡（哪怕入门级）7B 会很流畅。
二、最低成本调用：requests 直连 /api/generate
Ollama 暴露的 REST API 非常直白。最朴素的调用，用 requests 发个 POST 就行。我之所以推荐 requests 直连而不是官方 ollama Python 库，是因为生产环境里少一个依赖少一个出问题的点，而且直连让你对每个请求的参数、超时、异常处理都清清楚楚。
import requests
OLLAMA_BASE = \”http://localhost:11434\”
def generate(prompt: str, model: str = \”llama3.1\”) -> str:
resp = requests.post(
f\”{OLLAMA_BASE}/api/generate\”,
json={\”model\”: model, \”prompt\”: prompt, \”stream\”: False},
timeout=120, # 冷启动首次推理 CPU 上可能 30-60s，timeout 给足
)
resp.raise_for_status()
return resp.json()[\”response\”]
print(generate(\”用一句话解释什么是闭包\”))
两个关键点：stream: False 必须显式写。Ollama 0.1.0+ 默认流式返回 NDJSON（每行一个 JSON），不关流直接 response.json() 会抛 JSONDecodeError。
