Python 中的本地 LLM：使用 Ollama 和 LiteLLM 快速入门

# Python 本地大模型快速上手：Ollama + LiteLLM 开发者指南

许多开发者初次接触大语言模型（LLM）时，常遇到注册云服务、管理 API 密钥以及持续产生 token 费用的障碍。虽然这种方式可行，但并不适合初期实验和本地开发。本文介绍一种高效替代方案：在你的电脑上直接部署和集成 LLM。我们将一步步指导你使用 Ollama 搭建本地环境运行模型，并通过 LiteLLM 将其接入 Python 应用，让你无需依赖外部服务，就能从自家 LLM 获取首个有意义回复。

本地 LLM 开发的显著优势

本地部署 LLM 具有诸多无可否认的优势，尤其适合学习和原型开发。首先，完全免除 API 密钥和相关费用，支持无限实验。其次，无需每次请求都依赖网络连接，这对离线开发或网络不稳的环境至关重要。第三，这种方式让 LLM 交互过程高度透明：你能清楚看到 Python 代码如何与 LiteLLM 通信，后者再转发请求给 Ollama，最终抵达本地模型。这不是“AI 魔法”，而是清晰可追踪的软件逻辑，大大简化调试和架构理解。对于希望深入掌握 LLM 集成机制的开发者，本地方式是完美起点。

Ollama 和 LiteLLM：核心架构组件

在安装前，先了解我们将使用的两大工具的功能区别：Ollama 和 LiteLLM。

Ollama 是一款强大的本地运行大语言模型工具。它充当服务器，负责在你的电脑上下载、存储和执行 LLM，并提供统一 API 接口访问。本质上，Ollama 是本地 LLM 的运行时，让你轻松处理 Llama、Mistral、Qwen 等多种模型。
LiteLLM 是一个轻量级 Python 库，专为统一不同 LLM 提供商的 API 请求而设计。其核心亮点是提供单一接口，同时支持云服务（如 OpenAI、Anthropic、Google Gemini）和本地方案如 Ollama。这意味着，通过 LiteLLM 编写本地模型代码，只需微调即可切换到云端提供商。

简而言之，Ollama “启动”本地模型，LiteLLM 提供标准化 Python 交互方式，你的代码则在此基础上构建完整应用。

安装 Ollama 并下载本地模型

开始本地 LLM 工作，只需按顺序执行几步。

安装 Ollama

首先，从官网（ollama.com）下载适合你操作系统的 Ollama（Windows、macOS、Linux）并安装。安装后，在终端运行以下命令验证：

ollama --version

成功输出版本号即表示 Ollama 就绪。Windows 用户请确认系统托盘有 Ollama 图标（🦙），表明后台服务已激活。

下载本地 LLM 模型

Ollama 本身不是模型，而是运行它们的平台。现在下载具体大语言模型。对于我们的示例，qwen2.5:3b 是绝佳选择——体积小巧、性能强劲，适合大多数笔记本，还支持俄语。在终端执行：

ollama run qwen2.5:3b

首次运行会开始下载并本地保存。下载完成后，你将进入 Ollama 交互聊天界面。用俄语测试模型，例如：Hello! Tell me in two sentences, what is Python.（你好！用两句话告诉我 Python 是什么。）模型若回复，即主关卡通过。退出聊天用 /bye。

注意： 若 qwen2.5:3b 性能不足以适配你的硬件，可试更轻量版：ollama run qwen2.5:1.5b。Python 代码逻辑不变。

准备 Python 环境

为隔离项目依赖，推荐使用虚拟环境。

创建项目文件夹并进入：

```bash

mkdir llm-chat

cd llm-chat

```

初始化虚拟环境：

```bash

python -m venv venv

```

激活环境。

* Windows： venv\Scripts\activate

* macOS / Linux： source venv/bin/activate

激活成功后，命令行前会出现 (venv) 前缀。

安装 LiteLLM 库：

```bash

pip install litellm

```

现在，所有组件就绪，可开始编码。

Python 中集成 LLM：首个请求

在项目根目录创建 main.py 文件，添加以下代码：

from litellm import completion
 
MODEL = "ollama_chat/qwen2.5:3b"
API_BASE = "http://localhost:11434"
 

def ask(question: str) -> str:
    response = completion(
        model=MODEL,
        messages=[
            {"role": "user", "content": question}
        ],
        api_base=API_BASE,
        request_timeout=120,
    )
    return response.choices[0].message.content
 
answer = ask("Hello! Write one short sentence about Python.")
print(answer)

在激活的虚拟环境中运行脚本：

python main.py

若控制台出现模型的有意义回复，即表示你已成功将本地 LLM 集成进 Python 代码。这是关键时刻，抽象模型转为应用功能组件。

`main.py` 代码解析

剖析这个简洁却实用的脚本核心元素：

from litellm import completion：从 LiteLLM 导入核心 completion 函数，用于向 LLM 发送请求。
MODEL = "ollama_chat/qwen2.5:3b"：定义使用的模型。ollama_chat/ 前缀指示 LiteLLM 将请求导向本地 Ollama 服务。这里需填入你下载的模型名（如 qwen2.5:1.5b）。
API_BASE = "http://localhost:11434"：指定本地 Ollama API 服务器地址，默认端口 11434。
messages=[{"role": "user", "content": question}]：这是大多数现代 LLM API 的基础结构。请求以消息列表形式传递，每条消息含 role（如 "user"、"assistant"、"system"）和 content（文本）。即使单问，也用此结构，为后续对话历史和上下文打基础。
request_timeout=120：设置模型响应最大等待时间（秒）。本地模型初次启动或处理复杂请求可能需更长时间。
response.choices[0].message.content：从模型返回的完整响应对象中提取生成文本。response 对象还含丰富其他信息，后续可深入探索。

常见启动问题排查

设置过程中可能遇阻，以下是最常见问题及解决办法：

问题 1：Connection refused 或 Failed to connect

* 原因： Ollama 服务未运行或不可达。

* 解决： 确认 Ollama 活跃。检查系统托盘 🦙 图标（Windows/macOS），或终端运行 ollama list。命令响应即服务正常。

问题 2：Model not found

* 原因： 代码指定模型未下载，或名称不匹配。

* 解决： 运行 ollama list 查看可用本地模型，然后修正 main.py 中 MODEL 变量。

问题 3：响应慢或性能低

* 原因： 模型首次加载入内存较慢，或硬件负担过重。

* 解决： 多等一会儿。关闭资源占用大的应用。试用更轻模型，如 qwen2.5:1.5b。

问题 4：ModuleNotFoundError: No module named 'litellm'

* 原因： 脚本在未激活虚拟环境（无 LiteLLM）下运行。

* 解决： 确认激活虚拟环境（终端有 (venv) 前缀）后再运行。

问题 5：PowerShell 编码问题（乱码）

* 原因： 终端编码不匹配。

* 解决： PowerShell 中执行 $OutputEncoding = [System.Text.Encoding]::UTF8，再运行脚本。

核心要点总结

使用 Ollama + LiteLLM 本地部署 LLM，避免 API 费用和网络依赖，全程掌控。
Ollama 充当本地模型运行时，LiteLLM 统一 Python 交互 API。
第一步：安装 Ollama，下载合适模型如 qwen2.5:3b。
Python 脚本用 litellm.completion 发送请求，MODEL 以 ollama_chat/ 指向本地模型，API_BASE 指定 Ollama 地址。
LLM 请求以带 role 和 content 的消息列表传递，为构建对话系统奠基。