摘要

前面几篇文章里，我们已经完成了 Ollama 的基础入门、Windows 安装、显卡和模型选择，以及常用命令管理。

到这里，Ollama 已经可以在终端里正常聊天了。
但是如果只停留在终端聊天，其实还没有真正发挥 Ollama 的价值。

Ollama 最有意思的地方之一是：它不只是一个命令行聊天工具，还可以作为一个本地 AI 后端，让 Python、JavaScript、网页项目、Electron 桌面应用等程序调用本地大模型。

这一篇文章就开始进入开发实战：如何通过 Ollama API，让自己的程序调用本地 AI。

---

一、为什么要用 Ollama API？

很多人第一次使用 Ollama，都是这样运行模型：

ollama run qwen2.5:7b

然后在终端里和模型对话。

这种方式适合体验模型，但不适合做项目。

如果你想做这些东西：

本地 AI 聊天网页
Python 自动总结工具
AI 写作助手
代码解释工具
本地知识库
Electron 桌面 AI 助手
浏览器插件
学习辅助工具

那就不能只靠终端对话，而是需要让程序向 Ollama 发送请求。

这时候就要用到 Ollama API。

简单说：

终端使用：人直接和模型聊天
API 使用：程序向模型发送请求，再拿到模型回答

有了 API，Ollama 就从一个“本地聊天工具”变成了一个“本地 AI 服务”。

---

二、Ollama 的本地服务地址

Ollama 安装后，会在本地启动一个 HTTP 服务。
默认地址通常是：

http://localhost:11434

其中：

localhost 表示本机
11434 是 Ollama 默认端口

所以当我们用程序访问：

http://localhost:11434/api/generate

其实就是在向自己电脑上的 Ollama 服务发送请求。

这个逻辑很重要。

你可以把 Ollama 理解成：

你的程序 → 本地 Ollama API → 本地模型 → 返回回答

而不是：

你的程序 → 云端服务器 → 在线模型 → 返回回答

这也是为什么 Ollama 适合做本地开发和低成本测试。

---

三、使用 API 前的准备

在调用 API 之前，要先确认几件事。

1. Ollama 已经安装成功

打开终端，输入：

ollama --version

如果能看到版本号，说明安装成功。

2. 本地已经有模型

查看本地模型：

ollama list

如果没有模型，可以先下载一个：

ollama pull qwen2.5:7b

或者直接运行：

ollama run qwen2.5:7b

3. Ollama 服务正在运行

一般情况下，安装 Ollama 后它会在后台自动运行。

也可以用下面方式测试本地服务是否正常：

curl http://localhost:11434/api/tags

如果返回本地模型列表，说明 API 服务可以访问。

---

四、最简单的 API：/api/generate

Ollama 里最基础的文本生成接口是：

POST /api/generate

它适合完成一次性文本生成任务，比如：

解释一个概念
总结一段内容
改写一句话
生成标题
写一段代码

curl 示例

curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "请用一句话解释什么是 Ollama。",
  "stream": false
}'

这里有三个关键字段：

model：要调用的模型名称
prompt：输入给模型的问题
stream：是否流式输出

如果设置：

"stream": false

Ollama 会一次性返回完整结果。

如果不设置，或者使用流式模式，返回可能会是一段一段的 JSON 数据。

新手刚开始建议先用：

"stream": false

因为这样更容易处理返回结果。

---

五、/api/generate 返回结果怎么看？

上面的请求成功后，返回结果大概会包含：

{
  "model": "qwen2.5:7b",
  "created_at": "2026-01-01T00:00:00Z",
  "response": "Ollama 是一个可以在本地运行大语言模型的工具。",
  "done": true
}

最重要的是这个字段：

"response"

它就是模型生成的回答。

所以程序调用 Ollama 时，核心流程就是：

发送 prompt
等待 Ollama 生成
读取 response 字段
把 response 显示给用户

---

六、用 Python 调用 Ollama

Python 调用 Ollama 非常简单，可以使用 requests 库。

如果没有安装 requests，可以先安装：

pip install requests

然后写一个 Python 文件，例如：

ask_ollama.py

代码如下：

import requests

url = "http://localhost:11434/api/generate"

payload = {
    "model": "qwen2.5:7b",
    "prompt": "请用简单的话解释什么是本地大模型。",
    "stream": False
}

try:
    response = requests.post(url, json=payload, timeout=120)
    response.raise_for_status()

    data = response.json()
    print(data["response"])

except requests.exceptions.RequestException as e:
    print("请求 Ollama 失败：", e)
except KeyError:
    print("返回结果中没有 response 字段。")

运行：

python ask_ollama.py

如果一切正常，终端会输出模型回答。

---

七、Python 代码解释

上面的代码逻辑其实很简单。

1. 设置接口地址

url = "http://localhost:11434/api/generate"

这表示我们要访问本机 Ollama 的生成接口。

2. 准备请求数据

payload = {
    "model": "qwen2.5:7b",
    "prompt": "请用简单的话解释什么是本地大模型。",
    "stream": False
}

这里告诉 Ollama：

用 qwen2.5:7b 这个模型
回答 prompt 里的问题
不要流式返回，一次性返回完整结果

3. 发送 POST 请求

response = requests.post(url, json=payload, timeout=120)

json=payload 会把 Python 字典自动转换成 JSON 请求体。

4. 读取回答

data = response.json()
print(data["response"])

Ollama 的回答在 response 字段里，所以直接打印出来即可。

---

八、做一个简单的 Python 交互聊天

上面的代码只能问一次。
如果想做一个简单的连续问答，可以写成循环：

import requests

MODEL = "qwen2.5:7b"
URL = "http://localhost:11434/api/generate"

print("本地 Ollama 聊天程序已启动，输入 exit 退出。")

while True:
    user_input = input("\n你：")

    if user_input.lower() in ["exit", "quit", "q"]:
        print("已退出。")
        break

    payload = {
        "model": MODEL,
        "prompt": user_input,
        "stream": False
    }

    try:
        response = requests.post(URL, json=payload, timeout=120)
        response.raise_for_status()
        data = response.json()

        print("\nAI：", data.get("response", ""))

    except requests.exceptions.RequestException as e:
        print("请求失败：", e)

这个程序已经具备一个最基础的本地 AI 聊天功能。

不过要注意：
这种写法每次只把当前问题发给模型，没有保存上下文。
也就是说，模型不一定记得你前面问过什么。

如果想做真正的多轮聊天，更推荐使用 /api/chat。

---

九、多轮对话接口：/api/chat

/api/generate 更适合一次性生成。
如果你想做聊天机器人，更适合使用：

POST /api/chat

它的请求结构更像常见聊天模型：

{
  "model": "qwen2.5:7b",
  "messages": [
    {
      "role": "system",
      "content": "你是一个严谨的中文技术助手。"
    },
    {
      "role": "user",
      "content": "请解释什么是 Ollama API。"
    }
  ],
  "stream": false
}

其中 messages 是对话历史。

常见 role 有：

system：系统设定
user：用户输入
assistant：模型回答

---

十、用 curl 调用 /api/chat

示例：

curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [
    {
      "role": "system",
      "content": "你是一个中文技术博客助手，回答要清晰、有步骤。"
    },
    {
      "role": "user",
      "content": "请解释 Ollama API 的作用。"
    }
  ],
  "stream": false
}'

返回结果中，模型回答一般在：

{
  "message": {
    "role": "assistant",
    "content": "Ollama API 的作用是..."
  }
}

所以程序里要读取：

message.content

而不是 /api/generate 里的 response 字段。

---

十一、用 Python 写一个带上下文的聊天程序

下面是一个简单的多轮聊天示例：

import requests

MODEL = "qwen2.5:7b"
URL = "http://localhost:11434/api/chat"

messages = [
    {
        "role": "system",
        "content": "你是一个清晰、耐心的中文技术助手。"
    }
]

print("Ollama 多轮聊天已启动，输入 exit 退出。")

while True:
    user_input = input("\n你：")

    if user_input.lower() in ["exit", "quit", "q"]:
        print("已退出。")
        break

    messages.append({
        "role": "user",
        "content": user_input
    })

    payload = {
        "model": MODEL,
        "messages": messages,
        "stream": False
    }

    try:
        response = requests.post(URL, json=payload, timeout=120)
        response.raise_for_status()

        data = response.json()
        answer = data["message"]["content"]

        print("\nAI：", answer)

        messages.append({
            "role": "assistant",
            "content": answer
        })

    except requests.exceptions.RequestException as e:
        print("请求失败：", e)
    except KeyError:
        print("返回格式异常：", response.text)

这个版本比 /api/generate 更像真正的聊天机器人。
因为它会把历史消息保存在 messages 数组里，然后每次一起发给模型。

不过也要注意：
历史消息越多，上下文越长，占用资源越高，回答速度也可能变慢。
实际项目里通常需要控制历史长度，比如只保留最近 10 轮对话。

---

十二、用 JavaScript 调用 Ollama

如果你做网页或前端项目，可以用 JavaScript 的 fetch 调用 Ollama。

示例：

async function askOllama(prompt) {
  const response = await fetch("http://localhost:11434/api/generate", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "qwen2.5:7b",
      prompt: prompt,
      stream: false
    })
  });

  if (!response.ok) {
    throw new Error("请求失败：" + response.status);
  }

  const data = await response.json();
  return data.response;
}

askOllama("请解释什么是 Ollama API。")
  .then(answer => {
    console.log(answer);
  })
  .catch(error => {
    console.error(error);
  });

这段代码可以直接放在前端项目里测试。

逻辑是：

用户输入 prompt
fetch 发送 POST 请求
Ollama 返回 JSON
读取 data.response
显示到页面

---

十三、做一个最简单的网页 AI 助手

下面是一个完整的 HTML 示例。
保存为：

index.html

代码如下：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>本地 Ollama AI 助手</title>
  <style>
    body {
      font-family: Arial, sans-serif;
      max-width: 800px;
      margin: 40px auto;
      padding: 0 20px;
      background: #f6f7f9;
    }

    h1 {
      text-align: center;
    }

    textarea {
      width: 100%;
      height: 120px;
      padding: 12px;
      font-size: 16px;
      box-sizing: border-box;
    }

    button {
      margin-top: 12px;
      padding: 10px 18px;
      font-size: 16px;
      cursor: pointer;
    }

    #answer {
      margin-top: 20px;
      padding: 16px;
      background: white;
      border-radius: 8px;
      min-height: 100px;
      white-space: pre-wrap;
      line-height: 1.6;
    }
  </style>
</head>
<body>
  <h1>本地 Ollama AI 助手</h1>

  <textarea id="prompt" placeholder="请输入你的问题..."></textarea>
  <br>
  <button onclick="ask()">发送</button>

  <div id="answer">AI 回答会显示在这里。</div>

  <script>
    async function ask() {
      const prompt = document.getElementById("prompt").value.trim();
      const answerBox = document.getElementById("answer");

      if (!prompt) {
        answerBox.textContent = "请输入问题。";
        return;
      }

      answerBox.textContent = "正在思考中...";

      try {
        const response = await fetch("http://localhost:11434/api/generate", {
          method: "POST",
          headers: {
            "Content-Type": "application/json"
          },
          body: JSON.stringify({
            model: "qwen2.5:7b",
            prompt: prompt,
            stream: false
          })
        });

        if (!response.ok) {
          throw new Error("HTTP 错误：" + response.status);
        }

        const data = await response.json();
        answerBox.textContent = data.response || "没有返回内容。";

      } catch (error) {
        answerBox.textContent = "请求失败：" + error.message;
      }
    }
  </script>
</body>
</html>

运行前确保：

ollama run qwen2.5:7b

或者至少本地已经下载了这个模型：

ollama pull qwen2.5:7b

然后打开 HTML 文件，输入问题，点击发送。
如果 Ollama 服务正常，就可以看到本地模型的回答。

---

十四、网页调用可能遇到跨域问题

如果你把网页放在某些开发服务器、浏览器插件或特殊环境里，可能会遇到跨域访问问题。

常见报错类似：

Access to fetch at 'http://localhost:11434/...' has been blocked by CORS policy

这说明浏览器不允许当前网页直接访问 Ollama 服务。

解决思路有几个：

1. 本地开发时尽量使用 localhost

例如用 Vite、Live Server、Node 服务启动本地网页。

2. 设置 Ollama 允许的来源

可以通过环境变量配置允许访问的 origin。

例如允许某个本地开发地址：

set OLLAMA_ORIGINS=http://localhost:5173

然后重启 Ollama。

如果是 PowerShell，可以使用：

$env:OLLAMA_ORIGINS="http://localhost:5173"
ollama serve

3. 用后端代理

更正式的做法是：

前端网页 → 自己的后端服务 → Ollama API

这样前端不直接请求 Ollama，而是请求自己的后端。
后端再去访问 localhost:11434。

这个结构更适合正式项目，也更方便做权限控制、日志记录、请求限制和模型切换。

---

十五、什么时候用 /api/generate，什么时候用 /api/chat？

这两个接口很容易混。

简单判断：

1. 使用 /api/generate 的场景

适合一次性任务：

总结一段文本
生成一篇文章标题
解释一个概念
改写一段文字
生成一段代码

特点：

输入 prompt
输出 response
结构简单
适合工具类任务

2. 使用 /api/chat 的场景

适合多轮对话：

聊天机器人
学习助手
客服机器人
AI 角色助手
带上下文的问答系统

特点：

输入 messages
输出 message.content
可以保留历史对话
更适合聊天类项目

如果你只是写一个“文本生成工具”，用 /api/generate 就够了。
如果你要做“聊天助手”，优先用 /api/chat。

---

十六、流式输出是什么？

前面的示例都用了：

"stream": false

这样 Ollama 会等模型生成完，再一次性返回结果。

但真实聊天软件通常不是这样。
它会一边生成，一边显示，就像 ChatGPT 那样逐字输出。

这就是流式输出。

如果设置：

"stream": true

或者不关闭流式输出，Ollama 可能会持续返回多行 JSON，每一行包含一部分内容。

流式输出的优点：

用户等待感更低
聊天体验更自然
适合网页聊天框

缺点：

代码处理更复杂
需要逐块读取响应
新手不容易调试

所以建议学习路线是：

第一步：先用 stream:false 跑通
第二步：再做流式输出
第三步：最后优化前端体验

---

十七、控制模型加载时间：keep_alive

调用 API 时，还有一个常见参数：

"keep_alive": "10m"

它的意思是：模型在请求结束后继续保留在内存里的时间。

例如：

curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "你好",
  "stream": false,
  "keep_alive": "10m"
}'

这样模型在请求结束后，还会保留一段时间。
下次再请求时，可能会更快。

如果想让模型生成后立刻释放资源，可以设置：

"keep_alive": 0

如果你电脑显存比较小，建议不要让模型长期占用资源。
如果你正在开发一个频繁请求的项目，可以适当延长 keep_alive。

---

十八、控制上下文长度：num_ctx

本地模型处理长文本时会占用更多资源。
如果你想控制上下文窗口，可以在 options 里设置：

"options": {
  "num_ctx": 4096
}

示例：

curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "请解释什么是上下文窗口。",
  "stream": false,
  "options": {
    "num_ctx": 4096
  }
}'

上下文不是越大越好。

上下文变大后，可能带来：

显存占用上升
内存占用上升
响应速度下降
多轮对话变慢

所以本地模型要根据电脑配置合理设置上下文长度。

---

十九、查看本地模型列表 API：/api/tags

除了命令行的：

ollama list

API 里也可以查看本地模型列表：

curl http://localhost:11434/api/tags

这个接口适合做“模型选择器”。

比如你做一个网页 AI 助手，可以先请求 /api/tags，拿到本地模型列表，然后让用户在下拉框里选择模型。

这样用户不需要手动输入模型名。

---

二十、Embedding 接口：/api/embed

如果后面想做本地知识库，就会用到 embedding。

Embedding 可以把文本转换成向量，用来做语义搜索。
比如用户问：

Ollama 怎么切换模型？

系统可以先把问题转成向量，再从文档库里找最相关的内容，然后交给大模型回答。

Ollama 的 embedding 接口是：

POST /api/embed

示例：

curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
  "input": "Ollama 是一个本地大模型运行工具。"
}'

这会返回一组数字向量。

对于新手来说，embedding 的概念可以先简单理解成：

把文字变成一串数字，让电脑可以判断语义相似度。

下一篇如果写本地知识库，embedding 就会非常重要。

---

二十一、Ollama 兼容 OpenAI API 有什么用？

Ollama 还有一个很实用的能力：兼容部分 OpenAI API。

这意味着一些原本调用 OpenAI 的工具，可以通过修改地址和模型名，改成调用本地 Ollama。

例如，在一些 SDK 或项目里，原本可能是：

base_url = "https://api.openai.com/v1"

如果改成本地 Ollama 兼容地址，就可能变成：

base_url = "http://localhost:11434/v1"

然后模型名写成本地模型：

qwen2.5:7b

这个能力非常适合已有项目迁移。

比如你原来写了一个调用 OpenAI API 的聊天程序，现在想先用本地模型测试，就可以尝试改成本地 Ollama。

不过要注意：
兼容不等于所有功能完全一样。不同模型、不同参数、不同工具调用能力，实际表现可能会有差异。

---

二十二、一个简单项目结构建议

如果你真的要做项目，我不建议直接把所有逻辑写在 HTML 里。

更推荐这样的结构：

project/
  frontend/
    index.html
    script.js
    style.css

  backend/
    server.js
    ollama.js

  README.md

调用流程：

前端输入问题
↓
发送给自己的后端
↓
后端调用 Ollama API
↓
后端把回答返回前端
↓
前端显示回答

这样做的好处是：

前端代码更干净
更容易处理跨域
可以统一管理模型名
可以限制请求频率
可以记录日志
可以后期切换云端 API

如果只是学习，直接前端 fetch 没问题。
如果是正式项目，最好加一层后端。

---

二十三、常见问题整理

问题 1：请求失败，连接不上 Ollama

检查：

Ollama 是否安装
Ollama 是否正在运行
地址是否写错
端口是否是 11434
模型是否已经下载

可以先测试：

curl http://localhost:11434/api/tags

如果这个都不通，说明不是代码问题，而是 Ollama 服务没有正常访问。

---

问题 2：返回很慢

可能原因：

模型太大
显存不足
第一次加载模型
上下文太长
电脑后台程序太多

解决方法：

换小模型
先预加载模型
减少上下文长度
关闭其他占显存的软件
设置合适的 keep_alive

---

问题 3：Python 报 timeout

可能是模型第一次加载太慢。
可以把 timeout 设置长一点：

response = requests.post(url, json=payload, timeout=300)

或者先手动运行：

ollama run qwen2.5:7b

让模型提前加载。

---

问题 4：返回 JSON 解析失败

如果使用流式输出，返回可能不是一个完整 JSON，而是多行 JSON。
新手建议先设置：

"stream": false

等功能跑通后，再研究流式处理。

---

问题 5：网页请求被浏览器拦截

可能是跨域问题。
可以尝试：

使用 localhost 启动网页
设置 OLLAMA_ORIGINS
使用后端代理

正式项目里更推荐后端代理。

---

二十四、这一篇的完整学习路线

如果你是第一次用 Ollama API，建议按这个顺序：

第一步：curl 调用 /api/tags
第二步：curl 调用 /api/generate
第三步：Python 调用 /api/generate
第四步：Python 调用 /api/chat
第五步：JavaScript fetch 调用
第六步：做一个简单网页
第七步：处理跨域、上下文、流式输出
第八步：再考虑知识库和 embedding

不要一开始就做复杂项目。

先把最小链路跑通：

程序 → Ollama API → 本地模型 → 返回结果

这个链路跑通后，后面不管做网页、桌面助手还是知识库，本质上都是在这个基础上扩展。

---

二十五、总结

这一篇主要讲了如何通过 API 调用 Ollama。

核心内容可以总结成几句话：

Ollama 默认提供本地 HTTP API
/api/generate 适合一次性文本生成
/api/chat 适合多轮聊天
/api/tags 可以获取本地模型列表
/api/embed 可以生成文本向量
Python 可以用 requests 调用
JavaScript 可以用 fetch 调用
正式项目建议加一层后端代理

到这里，Ollama 已经不只是一个终端工具了。
它可以变成你本地项目里的 AI 后端。

下一篇文章，我会继续写 Ollama 的进阶实战：如何结合 embedding、文档切分和检索，搭建一个简单的本地知识库问答系统。