Ollama Python 库：在本地开启 LLM 之旅

云端 LLM API 功能强大，但也伴随取舍：按量计费、速率限制，以及数据究竟在哪里被处理的持续不确定性。对于处理敏感数据或高频试验的开发者来说，这些约束很快就会造成阻力。

这正是本地优先方法的优势所在。Ollama Python 库让您在本地运行大型语言模型，并用简洁、原生的 Python 代码与之交互，从而消除阻力。这样您就能完全掌控性能、成本与隐私。

本文将带您完整了解 Ollama Python 库 API，从使用 generate() 进行简单文本生成，到工具调用与视觉模型。

也推荐您查看我们其他最新的 Ollama 教程：

• Gemma 4 教程：用 Gradio 和 Ollama 构建本地 AI 编码代理
• Qwen 3.5 小模型教程：用 Ollama 构建视频到游戏生成器
• 在 Ollama 中使用 OpenClaw：打造本地数据分析师
• 将 Claude Code 与 Ollama 本地模型配合使用

用 Python 运行 Ollama 的先决条件

在开始前，请确保您的设备完成以下设置：

• Python 3.8 或更高版本

• 从其官网下载、安装并运行 Ollama（ollama serve）

• 至少拉取一个模型（例如 ollama pull llama3.2）

之所以需要这些先决条件，是因为 Python SDK 只是客户端；实际推理发生在 Ollama 运行时中。如果运行时不可用或没有合适的模型，请求将失败。

您也可以考虑将 Docker 与 Ollama 搭配使用以保持版本一致性。

什么是 Ollama Python 库？

Ollama Python 库是官方 SDK，将 Ollama 的 REST API 封装为简洁、Python 化的接口。换句话说，它把底层的 HTTP 请求与 JSON 负载转换为高级的Python 函数，让您专注意图而非传输细节。

随着应用规模增长，这种抽象能消除重复的请求构造，统一响应处理方式，并将错误处理集中到一处。

对比之下，原始请求可能如下所示：

import requests

response = requests.post(
    "http://localhost:11434/api/generate",
    json={
        "model": "llama3.2",
        "prompt": "Explain recursion"
    }
)

这当然可行，但很快会变得冗长且容易出错。使用 SDK，同样的任务可以这样实现：

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Explain recursion'
)

库如何与 Ollama 服务器通信

在底层，每个 SDK 调用都会转化为发往 http://localhost:11434 的 HTTP 请求。您的 Python 脚本充当客户端，而 Ollama 运行时则作为托管并执行模型的服务器。

这种分离很重要，因为它允许将模型作为专用服务运行，更高效地管理资源（CPU/GPU），并使多个应用共享同一模型实例。

如果需要连接到其他机器，您可以配置自定义客户端：

from ollama import Client

client = Client(host='http://remote-server:11434')
response = client.generate(model='llama3.2', prompt='Hello')

安装与配置库

安装非常简单，且只需极少依赖：

pip install ollama

安装完成后，建议通过列出可用模型来验证连通性。

这有助于确认您的 Python 环境、SDK 与 Ollama 运行时均已正确连接。

为此，请运行以下代码：

import ollama

print(ollama.list())

使用 generate() 生成文本

generate() 适用于无状态任务，即每个请求独立处理，不记忆先前交互。这非常适合摘要、改写或代码生成等任务。

由于不保留上下文，输出质量完全取决于提示词是否清晰。

基础文本生成

下面的示例展示了最简单的流程：发送提示词、接收响应，并提取生成的文本。

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Write a Python docstring for a function that calculates factorial'
)

print(response['response'])

响应中还包含元数据，如执行时间和 token 计数，这些在优化性能时很有用。

通过参数自定义输出

可以通过采样参数调整生成行为，从而控制模型如何选择 token。

较低的 temperature 值会产生更确定性的输出，而较高的值会带来更多变化。您还可以使用 top_p 和 num_predict 等参数进一步控制输出的多样性与长度。

以下是一些重要参数：

以下是一个使用 top_p、temperature 与 num_predict 的示例：

response = ollama.generate(
    model='llama3.2',
    prompt='Explain machine learning in one paragraph',
    options={
        'temperature': 0.2,
        'top_p': 0.9,
        'num_predict': 100
    }
)

使用 chat() 构建对话

与 generate() 不同，chat() API 通过一系列消息实现有状态交互，使模型能够在多轮对话中保持上下文。

每条消息都包含一个角色，例如 user、assistant 或 system，用于组织对话结构。

单轮对话请求

即使是单轮交互，也会使用消息格式，这为更复杂的对话奠定基础。

response = ollama.chat(
    model='llama3.2',
    messages=[
        {'role': 'user', 'content': 'Explain Python decorators'}
    ]
)

print(response['message']['content'])

维持多轮上下文

要维持上下文，您需要显式存储并在每次请求时重发完整的对话历史。这样您可以完全控制模型“记住”什么。

messages = [
    {'role': 'user', 'content': 'What is recursion?'}
]

response = ollama.chat(model='llama3.2', messages=messages)
messages.append(response['message'])

messages.append({'role': 'user', 'content': 'Give an example in Python'})
response = ollama.chat(model='llama3.2', messages=messages)

用系统提示塑造行为

系统提示用于预先定义模型的行为，例如语气、约束或角色。

messages = [
    {'role': 'system', 'content': 'You are a strict Python code reviewer.'},
    {'role': 'user', 'content': 'Review this code: def add(a,b): return a+b'}
]

Ollama Python 库的流式与异步支持

对于交互式应用，响应速度与正确性同样重要。Ollama 支持流式与异步执行，以提升性能和用户体验。

实时流式响应

流式传输允许您在生成过程中按增量处理输出，而无需等待完整响应。

for chunk in ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Write a story'}],
    stream=True
):
    print(chunk['message']['content'], end='', flush=True)

在异步应用中使用 AsyncClient

异步执行让您的应用能够并发处理多个请求而不阻塞。您需要使用 Python 的 asyncio 库来实现这一点。

下面看一个示例：

import asyncio
from ollama import AsyncClient

async def main():
    client = AsyncClient()
    async for chunk in await client.chat(
        model='llama3.2',
        messages=[{'role': 'user', 'content': 'Explain async programming'}],
        stream=True
    ):
        print(chunk['message']['content'], end='')

asyncio.run(main())

在 Python 中管理 Ollama 模型

Ollama SDK 还提供以编程方式管理模型的工具，这在自动化环境中特别有用。

列出并查看本地模型

您可以获取可用模型列表并查看其属性，如大小和配置。

models = ollama.list()
print(models)

info = ollama.show('llama3.2')
print(info)

以编程方式拉取与删除模型

可以直接在 Python 中下载或移除模型，更便于动态管理依赖。

ollama.pull('llama3.2')
ollama.delete('llama3.2')

使用 Ollama Python 库生成与使用向量嵌入

向量嵌入将文本表示为捕捉语义含义的数值向量，从而可以基于相似度而非字面一致性来比较文本。

创建文本嵌入

下面的示例会将文本转换为可用于搜索或聚类的向量表示。

response = ollama.embed(
    model='nomic-embed-text',
    input='Ollama is a local LLM runtime'
)

embedding = response['embeddings'][0]

构建基础相似度搜索

一旦生成嵌入，就可以使用余弦相似度来度量相似性，它比较向量之间的夹角。

这是一个简单的搜索函数示例：

import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

Ollama Python 库中的工具调用与结构化输出

在构建更高级的应用时，模型往往需要与外部函数交互或返回结构化数据。

用 Python 函数实现工具调用

工具调用允许模型基于用户意图调用预定义的 Python 函数。

让我们创建一个使用此类工具的函数：

def get_weather(city: str) -> str:
    """Get current weather for a city"""
    return f"Weather in {city} is sunny"
response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'What is the weather in Paris?'}],
    tools=[get_weather]
)

获取结构化 JSON 响应

结构化输出确保响应以一致、机器可读的格式（如 JSON）返回。

response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Review: Great product, 5 stars!'}],
    format='json'
)

进阶：Python 中的视觉模型与 Ollama Cloud

Ollama 支持多模态模型与基于云的推理，以满足更高级的用例。

向视觉模型发送图像

视觉模型可同时处理文本与图像，支持图像描述与视觉分析等任务。

response = ollama.chat(
    model='llama3.2-vision',
    messages=[{
        'role': 'user',
        'content': 'Describe this image',
        'images': ['image.jpg']
    }]
)

从 Python 运行云端模型

对于无法在本地运行的更大模型，Ollama Cloud 提供托管推理。您需要登录 Ollama Cloud。

ollama signin

登录后，您可以像这样与云托管模型对话：

from ollama import Client
import os

ollama.chat(model='deepseek-v3.1:671b-cloud', messages=[...])

client = Client(
    host='https://ollama.com',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

最常见 Ollama Python 问题的错误处理

在构建真实应用时，显式处理错误有助于避免静默失败并提升可靠性。

处理 ResponseError 异常

Ollama SDK 会针对服务器端错误抛出结构化异常，便于您检查问题原因。

import ollama

try:
    ollama.generate(model='unknown', prompt='test')
except ollama.ResponseError as e:
    print(e.status_code, e.error)

调试连接与模型问题

常见问题包括服务器未运行、缺少模型、内存不足或超过上下文限制。

• 服务器未运行：用 ollama serve 启动

• 找不到模型：运行 ollama pull

• 内存不足：使用更小的模型或量化

• 上下文问题：调整 num_ctx

num_ctx 控制模型一次能“看到”的最大 token 数，包括：

• 您的提示词
• 系统指令
• 对话历史
• 检索到的文档（RAG）
• 以及模型自身生成的 token

管理好该参数可避免 LLM 截断较早内容（通常从开头开始），或在不经意间丢失重要指令或数据。

结语

Ollama Python 库为使用本地与云端 LLM 提供了完整接口，从简单的文本生成到嵌入、工具调用、多模态输入等高级能力。LLM 成为一种本地服务，您可以像对待技术栈中的其他组件一样对其进行脚本化、测试与扩展。

根据我使用 Ollama 的体验，我觉得它作为无需使用云端 LLM 的可选方案相当不错。例如，我可以更自由地使用开源模型。如果您也希望在模型之间有更多切换空间，Ollama 是通往这些能力的良好入口。

如果您想进一步提升技能，推荐学习我们的 Developing LLM Applications with LangChain 课程，或获取 Associate AI Engineer for Developers 认证。