用 API 调用本地模型：让程序连上你的 AI

用 API 调用本地模型：让程序连上你的 AI

从「人用」到「程序用」

到目前为止，我们用的都是「人机交互」:在命令行或界面里输入问题，看模型回答。但本地 AI 更大的价值在于「程序调用」——让脚本、应用、自动化流程直接调用模型能力。比如：让定时任务自动总结新闻，让脚本批量翻译文档，让个人网站接入一个问答助手。这一切都靠 API 实现。

Ollama 内置了完整的 HTTP API，和其他任何 HTTP 接口一样，用标准请求就能调用。好消息是，Ollama 的 API 兼容 OpenAI 的接口规范，这意味着几乎所有为 OpenAI 写的程序，改一下地址就能连到本地模型。本文带你走通「第一次 API 调用」,并给出几个可以直接套用的例子。

理解 API 的基本形态

API(应用程序接口)的本质是「约定好的通信方式」:你的程序按规定的格式发一个请求，模型服务按格式返回结果。Ollama 的 API 默认监听 11434 端口，通过 HTTP 协议通信，请求和返回都是 JSON 格式。

最基本的对话接口是 /api/chat，它接收你发的消息列表，返回模型的回答。一次最简单的调用长这样：

curl http://localhost:11434/api/chat \
  -d '{"model": "qwen2.5:7b", "messages": [{"role": "user", "content": "用一句话介绍你自己"}]}'

返回结果是一个 JSON，里面有模型生成的回答内容。curl 只是演示，真实使用中，你用任何编程语言的 HTTP 库都能做同样的事：Python 用 requests、JavaScript 用 fetch，本质上都是「发 JSON、收 JSON」。

核心接口：聊天与补全

Ollama API 最常用的有两个接口：/api/chat(对话)和 /api/generate(补全)。前者适合多轮对话(传整个消息历史)，后者适合单次生成(给提示词、拿结果)。日常自动化场景，九成用 /api/chat 就够了。

/api/chat 的请求体包含两个核心字段：model(模型名)和 messages(消息数组)。消息数组里的每条消息有 role(角色)和 content(内容)两个字段，role 有三个取值：system(系统指令)、user(用户)、assistant(模型)。多轮对话就是不断往数组里追加消息。

{
  "model": "qwen2.5:7b",
  "messages": [
    {"role": "system", "content": "你是一个严谨的中文编辑"},
    {"role": "user", "content": "请修改这句话的语病"}
  ]
}

system 角色很有用：它是给模型的「人设」或「规则」,告诉模型以什么身份、按什么风格回答。固定工作流(翻译、润色、摘要)都可以通过 system 指令固化行为，让输出更稳定。

一个可直接用的 Python 例子

下面给一个完整可运行的 Python 例子，演示「读文件、调用模型、保存结果」的完整流程。假设你有一个文本文件 input.txt，想让它翻译成英文：

import requests

def call_model(prompt, model="qwen2.5:7b"):
    resp = requests.post("http://localhost:11434/api/chat", json={
        "model": model,
        "messages": [{"role": "user", "content": prompt}],
        "stream": False
    })
    return resp.json()["message"]["content"]

text = open("input.txt", encoding="utf-8").read()
result = call_model("把下面的内容翻译成英文:\n" + text)
open("output.txt", "w", encoding="utf-8").write(result)
print("done,", len(result), "chars")

这个例子虽然简单，但已经展示了自动化调用的完整骨架：构造请求、调用接口、解析结果、写回文件。你可以在此基础上扩展：批量处理(循环多个文件)、加入延迟(避免请求过密)、错误重试(接口偶发失败时重试)。

参数	作用	示例
model	指定模型	qwen2.5:7b
messages	对话内容	系统+用户消息
stream	是否流式返回	false 等完整结果
temperature	随机性	0.3 更稳定

用 Python 之外的调用方式

Python 是最常用的调用方式，但不是唯一选择，了解其他方式能帮你更灵活地接入模型。

命令行 curl 是最轻量的验证方式：一条命令发请求、看返回，适合测试和调试，前面已经演示过。JavaScript/Node.js 适合网页应用：前端或后端用 fetch 调 API，把模型能力嵌进网站。还有 Ollama 的官方客户端库(Python、JavaScript 等)，封装了流式、并发等细节，写起来更省心。另外，很多应用框架(如 Open WebUI 的 API、各类聊天机器人框架)已经内置了 Ollama 适配，直接配置地址即可。

调用方式	适合场景	特点
curl	测试调试	最轻量
Python	脚本自动化	生态全
JavaScript	网页应用	前端友好
框架内置	聊天机器人	开箱即用

选择建议：验证用 curl，写脚本用 Python，做网页用 JavaScript，搭聊天机器人用现成框架。工具选熟了，「调用模型」这件事就没有门槛，剩下的就是业务逻辑。

错误处理：调用失败的常见原因

API 调用不会总是一帆风顺，把常见错误和处理方法提前列出来，遇到不慌。

最常见的几类：连接失败——服务没启动或端口不对，先确认 ollama serve 在运行；模型不存在——模型名写错或没拉取，用 ollama list 核对；请求格式错误——JSON 结构不对，对照文档检查字段；资源不足——并发太多或上下文太大，降低负载或换小模型；超时——生成时间过长，流式处理或调整参数。

错误	原因	处理
连接失败	服务未启动	启动服务
模型不存在	名称写错	核对列表
格式错误	JSON 不对	检查字段
资源不足	负载过高	降负载
超时	生成过久	流式/调参

调用失败时，先读错误信息(通常是英文，但关键词清晰)，再按表定位。写自动化脚本时，建议加一层重试逻辑：偶发失败自动重试，能显著提升稳定性。

流式输出与参数控制

上面的例子用了 stream: false，意思是等模型生成完再一次性返回。但模型生成需要时间，长回答可能要等几十秒，体验上像是卡住了。更好的做法是用流式输出(stream: true)，让内容边生成边返回，程序逐段接收，像聊天一样实时。

流式输出在交互场景(聊天机器人、实时字幕)中几乎是必须的。实现方式：请求里加 stream: true，返回的每一行都是一个 JSON 片段，程序逐个解析、拼接，直到收到结束标记。Python 里用 requests 的迭代器即可实现，代码量也不大。

参数控制方面，API 调用可以传 temperature、num_ctx 等，和命令行一致。实际项目中，建议把常用的参数组合封装成一个函数，固定模型名、固定温度，只暴露「提示词」一个入参——这样调用方不用关心底层细节，代码也更清晰。

安全要点：API 别裸奔

调用 API 很方便，但有一个必须牢记的安全原则：不要让 API 在公网裸奔。Ollama 的 API 本身没有完善的认证机制，默认只应该监听本机或内网。如果把它暴露到公网，任何知道地址的人都能调用你的模型，消耗你的资源，还可能被滥用。

正确的做法：第一，保持默认监听本地(127.0.0.1)，只有本机程序能访问；第二，如果确实需要跨设备访问，让它监听内网 IP，同时用防火墙限制来源；第三，如果需要公网访问，必须加一层带认证的反向代理或 VPN，不要直接暴露。安全细节第四章还会展开，这里先记住原则。

还有一个小细节：调用频率要克制。脚本批量调用时，建议在请求之间加一点延迟，避免瞬间大量请求把服务打满。这既是保护服务稳定，也是良好的使用习惯。

从一次调用到自动化工作流

学会了 API 调用，你就拥有了把本地 AI 嵌入任何流程的能力。举几个实际例子：定时脚本每天早上总结最新文档；文件监控工具自动给新上传的图片写说明；个人网站接入问答机器人；知识库系统通过 API 完成检索问答。这些都不需要多高深的技术，核心就是「发请求、拿结果」。

本书第四章会带你做最典型的两个应用：私有知识库(RAG)和代码助手。到那时你会发现，API 调用只是起点，组合起来才是真正的生产力。

调用策略：如何优雅地批量使用

批量调用本地模型时，策略比单次调用的写法更重要，这里讲三个实用策略。

第一个，串行加延迟。批量任务按顺序一个个调，请求之间留一点间隔，避免瞬间打满服务，也让输出更可控。第二个，错误重试。网络波动、瞬时过载都可能让单次调用失败，写一个「失败自动重试 2~3 次」的逻辑，稳定性立刻提升。第三个，结果落盘。每次调用把结果保存到文件，即使中途失败，已完成的成果也不丢，重跑时还能跳过已处理的部分。

策略	做法	收益
串行延迟	逐个调用留间隔	稳定
错误重试	失败自动重试	鲁棒
结果落盘	保存已完成	可续跑

这三个策略让批量调用从「能用」变成「可靠」。写自动化脚本时把这些考虑进去，你的 AI 工作流就能长期稳定运行，而不是跑一次坏一次。

用 API 调用本地模型:让程序连上你的 AI