企业官网建设流程全解析

Ollama 装好了、模型也拉下来了，但如果你只是停留在终端里/bye退出，或者盯着命令行里的光标来回聊天，那这玩意儿对你来说还只是个"高级玩具"。真正让它产生价值的，是把它接入你自己的代码、脚本、业务流程里。这篇是这个系列的第 5 篇，核心就一件事：在 PyCharm 里用 Python 调用本地大模型，把 Ollama 变成一个可以由你任意调用的"智能函数"。全文会覆盖 requests、openai 两条调用路线，以及流式输出、多轮对话、工程化封装和我在实际调试中踩过的坑，适合已经把 Ollama 跑通、想继续做应用开发的朋友。

1. 为什么非得用 Python 调 Ollama，而不是继续敲命令行

1.1 命令行解决了"能跑"，解决不了"能用"

很多人第一次体验本地大模型，都是下载 Ollama 之后在终端敲ollama run qwen2.5:7b，然后像跟 ChatGPT 聊天一样一问一答。这个体验确实很惊艳，但你很快就会遇到瓶颈：一批文本想总结，你得一条一条复制粘贴；想让它每天定时生成报告，命令行帮不了你；想让 Web 后端接一个大模型接口，更不是敲命令能解决的。

换句话说，命令行证明了"模型能跑"，但生产和开发场景需要的是"能用"——批量、自动、可编程、可嵌入。Python 就是连接这两者的桥。你只需要让 Python 脚本往 Ollama 发一个 HTTP 请求，就能拿到模型的回答，剩下的逻辑（文件读取、结果落库、定时任务、Web 响应）全都可以用你熟悉的方式继续写。

我见过不少新手在这一步卡住，不是因为代码难，而是没搞清楚 Ollama 的定位。Ollama 不只是个"聊天工具"，它本质是一个本地模型服务端，自带 HTTP API。你在终端里聊天，背后走的也是同一套接口。搞懂这一点，后面的路就顺了。

1.2 调用链路全景：从 PyCharm 到模型只隔一个 HTTP 端口

先把这个链路看清楚，你写代码的时候心里就有地图了：

• PyCharm 里运行你的 Python 脚本
• 脚本通过 HTTP 发送 JSON 格式的请求到http://localhost:11434
• Ollama 服务端接收请求，把 prompt 交给指定模型
• 模型推理完成，Ollama 把结果以 JSON 返回
• Python 脚本解析响应，得到文本

整个过程不需要公网，不需要云服务，数据和请求都留在本机。Ollama 安装完成后，默认监听127.0.0.1:11434，这个端口就是你的"入口"。你不光可以用 Python 调，理论上任何能发 HTTP 请求的语言和工具都能调，只是 Python 生态最成熟，做 AI 应用最顺手。

这里有个简单的验证方法：浏览器打开http://localhost:11434，如果 Ollama 服务在运行，页面会显示一行Ollama is running。看到这行字，就说明服务端是健康的，问题只会出在 Python 脚本这一侧。我习惯把它当成"开胃检查"，比直接写一堆代码再去排查要高效得多。

1.3 环境准备：PyCharm 社区版就够，别在这步卡住

在开始写代码之前，把环境准备好。很多人在 PyCharm 配置这一步折腾半天，其实完全没必要。

• PyCharm：用 Community 版就够，免费，功能完全覆盖我们这篇文章的需求。
• Python 解释器：建议在 PyCharm 里新建项目时选择venv，也就是虚拟环境，每个项目单独一套依赖，不会污染全局环境。
• 第三方库：本篇文章主要用requests，进阶部分会用openai。在 PyCharm 底部 Terminal 里执行pip install requests openai就行。
• Ollama 服务：保证它已经在后台运行。可以打开一个终端执行ollama list，能列出你已下载的模型就说明没问题。另外记得你已经拉取了至少一个模型，比如qwen2.5:7b或llama3.1:8b，没有就先跑ollama pull qwen2.5:7b。

有一个细节很容易被忽略：PyCharm 里跑的是客户端代码，Ollama 是独立的后台服务。你在 PyCharm 里启动脚本前，必须先确保 Ollama 本身在运行。很多人把 Ollama 装在另一个机器上，或者用 WSL 装的，那localhost的指向就不一样了，这个后面踩坑部分再展开。

关于下载慢的问题，简单提一句：Ollama 安装包如果下载慢，可以找可信的国内镜像站拉取，本质就是个普通安装程序；模型下载慢的话，我更建议选小一点的量化版本，或者干脆耐心等官方源，镜像源质量参差不齐，反而容易出问题。

2. 先搞清楚 Ollama 的 HTTP API：这是代码调用的地基

2.1 不写代码先验证：浏览器和 curl 都能试

我强烈建议，在写 Python 之前，先用手里的现成工具把 API 通一通。这样后面代码出问题时，你能快速判断是代码问题还是服务问题。

打开一个终端，执行：

curl http://localhost:11434/api/generate -d '{ "model": "qwen2.5:7b", "prompt": "你好，用一句话介绍你自己", "stream": false }'

正常情况下，你会看到一大段 JSON 返回，里面核心字段是response，那是模型真正回答的内容。如果返回的是连接失败或者model not found，那就先别急着写 Python，先解决服务和模型的问题。

这一步的价值在于：它把"模型推理"和"代码调用"拆开了。我调试时永远是先用 curl 验证，再写 Python 脚本。curl 验证通过，Python 代码出错，那问题 99% 出在代码语法、参数格式或者环境上；curl 都过不了，那就先查 Ollama 服务和模型。

2.2 /api/generate 和 /api/chat，两个接口怎么选

Ollama 提供了两个常用的文本生成接口，很多人一开始分不清。

/api/generate是补全型接口，你给一段 prompt，它接着往下生成。它适合文本续写、翻译、摘要这类单轮任务，请求体简单直接，只要model和prompt两个字段就能跑。

/api/chat是对话型接口，采用messages数组传参，每条消息带role（system、user、assistant），和 OpenAI 的 Chat Completions 风格一致。它天然支持多轮对话，也是我更推荐日常使用的接口，因为以后切换到 OpenAI 或者其他兼容服务时，代码改动最小。

简单说：做聊天机器人、Agent 应用，直接用/api/chat；做文本批处理，/api/generate更轻。我这篇的主体部分两种都会用到。

2.3 必须认识的返回字段和常用参数

调用成功之后，返回的 JSON 里信息很多，但真正要关注的没几个。

以/api/generate为例，重点看这几个字段：

• response：模型的生成文本，这是你最关心的
• done：布尔值，true表示生成完成
• eval_count：生成了多少个 token
• eval_duration：推理耗时（纳秒）
• total_duration：整个请求的总耗时

/api/chat的响应结构不同，模型的回答在message.content里，注意别取错字段。

常用参数方面，options对象里可以配置：

• temperature：控制随机性，0 到 1 之间，写代码类任务建议 0.2 左右，创意类任务 0.7 以上
• num_predict：限制生成的最大 token 数，防止模型无限写下去
• top_p：核采样参数，一般保持默认就行

一个容易被忽略的参数是keep_alive，它控制模型在内存中的驻留时间。默认模型会在闲置 5 分钟后释放显存，如果你频繁调用，建议把它设大一点，比如"keep_alive": "30m"甚至-1表示一直驻留，能显著减少每次调用的冷启动时间。

3. 在 PyCharm 里把第一个本地大模型调用跑起来

3.1 用 requests 实现最简问答

现在进入正题。在 PyCharm 里新建一个 Python 文件，敲下这段代码：

import requests url = "http://localhost:11434/api/generate" payload = { "model": "qwen2.5:7b", "prompt": "用三句话解释什么是大语言模型", "stream": False } resp = requests.post(url, json=payload, timeout=120) data = resp.json() print(data["response"])

这段代码做了什么？requests.post把payload这个字典自动序列化成 JSON，发给 Ollama 的接口，timeout=120表示最多等 120 秒，然后resp.json()把返回的 JSON 解析成 Python 字典，最后取出response字段打印。

这里有几个细节值得说。stream: False意味着 Ollama 会等整个回答生成完再一次性返回，代码最简单，适合第一次跑通。timeout一定要设，不设的话一旦模型推理卡住，程序会一直挂在那里。7B 模型生成几句话一般几秒到十几秒，但第一次加载模型会慢，所以 120 秒是个比较安全的阈值。

运行之后，如果一切正常，控制台会直接打印模型生成的文本。看到文字的那一刻，你就已经用 Python 在调本地大模型了。

3.2 流式输出：让回答像真正的对话一样逐字出现

一次性返回虽然简单，但体验不好。尤其是模型要生成几百字时，用户会面对一个毫无反应的黑框，容易让人以为程序死了。真实对话应该像 ChatGPT 那样，一个字一个字往外蹦。

Ollama 对流的支持很优雅，只需要把stream改成true，返回的数据会变成多行 JSON，每一行是模型当前生成的片段：

import requests import json url = "http://localhost:11434/api/generate" payload = { "model": "qwen2.5:7b", "prompt": "以'本地大模型'为主题写一段200字的介绍", "stream": True } with requests.post(url, json=payload, stream=True, timeout=300) as resp: for line in resp.iter_lines(): if line: chunk = json.loads(line) print(chunk.get("response", ""), end="", flush=True)

核心是iter_lines()逐行读取响应，每读到一行就解析一段 JSON，取出response字段立即打印。flush=True很关键，它强制刷新输出缓冲区，否则文字还是会在程序结束后一次性蹦出来，流式效果就没了。

流式输出的意义不只是好看。对大模型应用来说，它还能让你尽早发现问题——比如模型开始胡说八道，你马上就能看到，直接中断请求，而不是等它把一整篇错误内容写完。

3.3 多轮对话：上下文列表是这样维护的

单轮问答很容易，但真实应用里用户经常会追问。比如你问"介绍一下 Python"，然后追问"它的 GIL 是什么"，模型如果不知道前面聊了什么，就答非所问。多轮对话的核心是把历史消息一起发给模型。

import requests messages = [ {"role": "system", "content": "你是一位熟悉 Python 的编程导师，回答要简洁。"}, ] while True: user_input = input("你：") if user_input.lower() in ("exit", "quit"): break messages.append({"role": "user", "content": user_input}) payload = { "model": "qwen2.5:7b", "messages": messages, "stream": False } resp = requests.post("http://localhost:11434/api/chat", json=payload, timeout=120) reply = resp.json()["message"]["content"] print("AI：" + reply) messages.append({"role": "assistant", "content": reply})

看到了吗？每次用户提问，我都把用户消息追加到messages，拿到模型回复后再追加一条 assistant 消息。下一次请求时，整个列表都发给模型，它就有了"记忆"。

这里要注意两点。第一，system消息是可选的，但强烈建议加，它相当于给模型设定人设和行为边界。第二，messages不能无限增长，上下文太长会拖慢推理速度，还会占用大量显存。实际项目中，当地址超过一定长度时要裁剪，只保留最近几轮对话，或者做摘要压缩。我一般保留最近 10 轮左右，超过就把最早的对话扔掉。

4. 工程化改造：超时、重试、并发，一个都不能少

4.1 我遇到过的三类异常：连接拒绝、读超时、模型加载失败

写脚本玩和写能用的程序是两码事。你在 PyCharm 里碰到最多的，是下面这三类问题，我一个个说。

第一类，连接被拒绝。报错长这样：requests.exceptions.ConnectionError。原因基本是 Ollama 服务没启动，或者你访问的地址不对。处理方式很简单：确认 Ollama 在后台运行，确认地址是http://localhost:11434。

第二类，读超时。requests.exceptions.ReadTimeout，指服务器接收请求后，在规定时间内没返回完整响应。这通常是模型推理时间超过了 timeout 阈值，也可能是模型还没加载完。处理办法是调大 timeout，或者显式设置keep_alive让模型常驻内存。

第三类，模型加载失败。请求能到 Ollama，但返回的 HTTP 状态码是 500，响应体里可能写no space left on device之类。这通常是显存或者内存不足，模型放不进去。处理方法是换更小的模型，或者调整OLLAMA_MAX_LOADED_MODELS等环境变量，减少同时加载的模型数量。

我把常见的现象、原因和处理方案整理成一张表，方便你对照：

4.2 把调用封装成可复用的 ask_ollama 函数

每写一个功能就复制一遍 requests 代码，迟早会乱。我建议一开始就封装成一个函数，参数暴露出来，调用方只需要关心传什么、拿什么。

import requests import time def ask_ollama( prompt: str, model: str = "qwen2.5:7b", system_prompt: str = "", temperature: float = 0.7, timeout: int = 120, max_retries: int = 3, ) -> str: messages = [] if system_prompt: messages.append({"role": "system", "content": system_prompt}) messages.append({"role": "user", "content": prompt}) payload = { "model": model, "messages": messages, "stream": False, "options": {"temperature": temperature}, } for attempt in range(max_retries): try: resp = requests.post( "http://localhost:11434/api/chat", json=payload, timeout=timeout, ) resp.raise_for_status() return resp.json()["message"]["content"] except requests.exceptions.ConnectionError: if attempt == max_retries - 1: raise RuntimeError("无法连接 Ollama，请确认服务已启动") time.sleep(2) except requests.exceptions.Timeout: if attempt == max_retries - 1: raise RuntimeError(f"请求超时（>{timeout}s），可适当调大 timeout") time.sleep(1)

这样一个函数，重试了 3 次，超时保护也有了，错误信息也清晰。项目里其他地方只需要：

answer = ask_ollama("帮我写一封请假邮件", system_prompt="你是行政助理。")

把大模型调用收敛到一个函数里，最大的好处是后续如果要换模型、换接口、加缓存，只需要改这一个地方。我在真实项目里就是这么组织的，维护成本低很多。

4.3 并发调用要克制：本地显卡不是无限资源

很多人跑通单次调用后，马上想上并发——同时来 10 个请求，是不是能快 10 倍？想法很好，现实很骨感。本地大模型的瓶颈通常在显存和算力，并发高了以后，请求会排队甚至互相抢占显存，单个请求的延迟反而飙升。

Ollama 本身支持一定程度的并发，通过环境变量OLLAMA_NUM_PARALLEL可以控制同时处理的请求数，默认是 1，也就是串行处理。如果你用 24GB 显存的卡跑 7B 模型，可以试试设为 2 或 3，但建议实测一下整体吞吐，不要盲目调大。

另外，并发请求时要对每个请求设置合理的超时，否则一个卡住的请求会把进程池占满。如果你用的是 FastAPI 这类框架，记得把大模型调用放到线程池里，避免阻塞事件循环。实在需要高并发，又只有一块消费级显卡，那就老老实实排队，或者考虑把请求做合并批处理，减少模型切换次数。

5. 进阶：用 openai 库一行代码切换 Ollama

5.1 为什么大家都喜欢 OpenAI 兼容格式

Ollama 从某个版本开始提供了 OpenAI 兼容接口，地址是http://localhost:11434/v1。这意味着你不需要改业务代码，只需要把 OpenAI SDK 的base_url指到本地，就能用本地模型。

这个设计非常聪明。现在几乎所有主流框架——LangChain、LlamaIndex、Dify、FastGPT——都默认对接 OpenAI 格式。Ollama 兼容了这个格式，就能无缝接入这些生态。更实际的好处是，你开发的代码以后想切换回 GPT 或者其他云厂商的模型，只需要改一个 base_url 和 api_key，逻辑完全不用动。

这相当于给本地大模型装了一个"标准插座"。你在 PyCharm 里开发阶段用本地模型，零成本验证思路，等真要上生产再切换到更强大的云端模型，迁移成本几乎为零。

5.2 用 openai SDK 跑通本地对话

先安装 openai 库：

pip install openai

然后写代码：

from openai import OpenAI client = OpenAI( base_url="http://localhost:11434/v1", api_key="ollama", # 本地服务不需要真实 key，随便填 ) resp = client.chat.completions.create( model="qwen2.5:7b", messages=[ {"role": "system", "content": "你是一个严谨的助手。"}, {"role": "user", "content": "解释一下递归算法"}, ], stream=False, ) print(resp.choices[0].message.content)

注意几点：api_key随便填，Ollama 本地服务不会校验，但 OpenAI SDK 要求这个字段非空；model填你实际拉取的模型名；流式输出时用stream=True，然后遍历resp，每个 chunk 里取delta.content，和官方 OpenAI SDK 用法一致。

我会在你本地模型工作时用这套方式，因为它意味着你跑通本地模型的同时，也学会了标准的 OpenAI 接口调用，一举两得。

5.3 顺着这条路接入 LangChain

一旦走上 OpenAI 兼容路线，LangChain 这类框架就变得非常友好。你可以直接用ChatOllama，它内部帮你封装好了所有细节：

from langchain_community.chat_models import ChatOllama from langchain_core.messages import HumanMessage llm = ChatOllama( model="qwen2.5:7b", base_url="http://localhost:11434", temperature=0.7, ) resp = llm.invoke([HumanMessage(content="给我三个Python学习建议")]) print(resp.content)

也可以使用标准的ChatOpenAI类，把 base_url 指向 Ollama 的/v1。两种方式各有优劣：ChatOllama对 Ollama 特性支持更完整，ChatOpenAI则完全模拟云端环境，切换厂商时几乎不用改代码。

我的建议是：如果只是玩 Ollama，用ChatOllama；如果是为了做项目、准备将来接云端模型，直接用ChatOpenAI配置本地地址，养成标准接口的习惯。LangChain 的好处是链式调用、工具调用、记忆管理这些能力都现成，不用自己从零写，后续做 Agent 应用会省很多事。

6. 实测踩坑记录：PyCharm 里最容易翻车的几个瞬间

6.1 端口占用和 Ollama 服务起不来的排查链路

有一次我打开 PyCharm 准备演示代码，结果脚本一直报连接错误。我第一反应是 Ollama 崩了，打开终端敲ollama list，居然也卡住。后来一查，是之前另一个程序占用了 11434 端口，Ollama 服务其实没起来。

排查端口是否被占用，Windows 上用：

netstat -ano | findstr 11434

macOS / Linux 上用：

lsof -i :11434

如果发现端口被其他进程占用，要么关掉那个进程，要么给 Ollama 换端口。Ollama 支持通过环境变量OLLAMA_HOST修改监听地址和端口，比如：

OLLAMA_HOST=127.0.0.1:11435 ollama serve

换端口后，Python 代码里的base_url也要跟着改，这是最容易漏掉的地方。另外，如果 Ollama 是用图形界面安装的（Windows/macOS），注意系统托盘里有没有它的图标，有的话基本说明服务在跑；图标不见了，去应用程序里重新启动一下。

6.2 第一次请求特别慢：冷启动和 keep_alive

很多人的第一个坑是：第一次跑代码，等了半天没反应，还以为程序死了。并不是。模型第一次被调用时，Ollama 需要把权重从硬盘加载到显存，这个冷启动过程可能是十几秒甚至几十秒，取决于你的硬盘速度和模型大小。

解决思路有三个。第一，把 timeout 设置大一点，至少 120 秒，别一超时就误判。第二，设置keep_alive让模型在内存里驻留。比如：

payload = { "model": "qwen2.5:7b", "messages": [...], "stream": False, "keep_alive": "30m" }

这样 30 分钟内模型不会从内存卸载，后续请求都是"热启动"，速度快很多。第三，如果你明知接下来要用某个模型，可以先在终端执行ollama run qwen2.5:7b随便聊一句再退出，相当于预热，之后 Python 调用就快了。

我实测下来，同样的 7B 模型，冷启动可能 20 多秒，预热后首 token 只要一两秒。这个差距在交互式应用里是决定性的。

6.3 Windows 下中文乱码的根治办法

很多人第一次跑通代码，看到控制台输出的中文全是乱码，或者直接报 UnicodeEncodeError。这多半是 Windows 控制台默认编码 GBK 导致的，而 Ollama 返回的是 UTF-8 文本。

最简单的根治办法，在 Python 文件最开头加两行：

import sys sys.stdout.reconfigure(encoding="utf-8")

或者设置环境变量PYTHONIOENCODING=utf-8再启动 PyCharm。如果是 PyCharm 自带的运行窗口，还可以在 Help -> Edit Custom VM Options 里加上-Dfile.encoding=UTF-8，重启后生效。不过我更推荐直接在代码里 recconfigure，这样换机器、换环境也不受影响。

另外，requests 解析 JSON 时本身就能正确处理 UTF-8，问题只出现在打印环节。所以排查思路就是：别怀疑模型返回的数据坏了，先怀疑控制台输出编码。

说实话，PyCharm 调用 Ollama 这件事本身不复杂，难点全在细节。把这几个常见问题提前预防好，整个流程会顺畅很多。我每次在新环境配置这套东西，已经养成固定习惯：先 curl 验证接口，再跑最小 Python 脚本，最后才封装函数和做业务逻辑。这个顺序能帮你把"环境问题"和"代码问题"彻底隔离开。你按这个节奏来，基本半小时内就能在 PyCharm 里看到大模型的回答。