如何通过 Ollama 与 Python 集成本地大语言模型

原文链接https://realpython.com/ollama-python/

将本地大语言模型（LLM）通过Ollama集成到Python项目中，是提升隐私性、降低成本并构建支持离线运行的AI应用的优质方案。Ollama是一款开源平台，能让你在本地设备上轻松运行主流大语言模型，搭配其Python SDK即可实现Python代码与本地模型的联动。

本文将带你完成Ollama的搭建、本地模型的拉取，以及通过Python代码实现模型的对话交互、文本生成和工具调用，掌握这些技能后，你就能开发出完全本地运行的AI应用。

前提条件

学习本教程需满足以下环境和资源要求：

1. 安装并运行Ollama：后续章节会讲解具体安装步骤；
2. Python 3.8及以上版本：Ollama的Python SDK对Python版本有此要求；
3. 可用的模型：本教程将使用llama3.2:latest和codellama:latest，后续会介绍下载方法；
4. 性能足够的硬件：本地运行大语言模型需要一定的内存、磁盘和CPU资源，无GPU也可运行，但GPU能大幅提升运行速度。

第一步：搭建Ollama、拉取模型并安装Python SDK

要在Python中调用本地模型，需先启动Ollama服务并下载至少一个模型，本步骤将完成Ollama安装、服务启动、模型拉取和Python SDK安装的全流程。

启动Ollama服务

1. Windows/macOS：访问Ollama官方下载页，下载对应系统的安装包（Windows需10及以上、macOS需14 Sonoma及以上），运行安装包并按提示操作即可；安装后Ollama会在后台运行，若未自动启动，可在开始菜单/启动台搜索并打开Ollama。
2. Linux：通过以下命令安装：

curl -fsSL https://ollama.com/install.sh | sh

3. 验证安装：执行以下命令，若能正常输出版本信息则安装成功：

ollama -v

4. 启动Ollama服务（Linux）：

ollama serve

注：部分Linux发行版（如Ubuntu）安装后会自动启动服务，此时执行上述命令会报错，属正常现象。

拉取所需模型

Ollama安装并启动后，即可拉取模型，拉取前需保证设备有足够的磁盘空间（llama3.2:latest约2.0GB，codellama:latest约3.8GB），执行以下命令拉取本教程所需模型：

ollama pull llama3.2:latest
ollama pull codellama:latest

模型下载需要一定时间，完成后可通过命令行测试模型：

ollama run llama3.2:latest
>>> 用一句话解释Python是什么
Python是一种高级解释型编程语言，以简洁、易读和多功能著称，广泛应用于Web开发、数据分析、机器学习、自动化等领域。

测试成功后，按Ctrl + D即可退出对话，接下来就能在Python中调用该模型。

注：Ollama的CLI用法与Docker类似，通过pull拉取模型，再通过run本地运行。

安装Ollama的Python SDK

Ollama提供了官方Python库，可通过PyPI安装到虚拟环境中，这是Python项目集成Ollama的推荐方式：

(venv) $ python -m pip install ollama

第二步：通过Python实现文本与代码生成

Ollama Python库提供了两个核心接口实现与本地模型的交互，分别适用于不同的使用场景：

• ollama.chat()：用于基于角色的多轮对话，适合构建需要上下文的智能助手；
• ollama.generate()：用于一次性提示词调用，适合文本起草、改写、总结和代码生成。

与Ollama的对话接口交互

以下是一个极简的Python对话示例，效果与前文的命令行测试一致：

from ollama import chat

messages = [
    {
        "role": "user",
        "content": "用一句话解释Python是什么。",
    },
]

response = chat(model="llama3.2:latest", messages=messages)
print(response.message.content)

关键说明：

1. messages是字典列表，专为多轮对话设计；
2. 每个字典包含role（角色）和content（内容）两个核心键；
3. chat()方法返回ChatResponse对象，通过response.message.content可获取模型的回复内容。

保留对话上下文实现跟进提问

若需要继续基于上一轮的对话内容提问，只需将模型的回复追加到messages列表中即可，以下是关于Python列表推导式的多轮对话示例：

messages = [
    {"role": "system", "content": "你是一名Python资深讲师。"},
    {
        "role": "user",
        "content": "用一句话定义列表推导式。"
    },
]
response = chat(model="llama3.2:latest", messages=messages)
print(response.message.content)

# 保留上下文，追加跟进问题
messages.append(response.message)
messages.append(
    {
        "role": "user",
        "content": "提供一个简短的实用示例。"
    }
)
response = chat(model="llama3.2:latest", messages=messages)
print(response.message.content)

运行后模型会先定义列表推导式，再基于该定义提供对应的代码示例，实现上下文关联的多轮交互。

流式输出对话结果

流式输出能让模型的回复逐段显示，提升交互体验，适合开发命令行或聊天应用，只需在chat()中设置stream=True即可：

# streams.py
from ollama import chat

stream = chat(
    model="llama3.2:latest",
    messages=[
        {
            "role": "user",
            "content": "结合示例解释Python的数据类（dataclasses）。"
        }
    ],
    stream=True,
)

for chunk in stream:
    print(chunk.message.content, end="", flush=True)

stream=True时，chat()会返回一个迭代器，逐一生成模型的回复片段，实现“打字机式”的输出效果。

使用Ollama的文本生成接口

若无需保留对话上下文，generate()是更合适的选择，该方法适用于一次性的提示词调用，用法如下：

from ollama import generate

response = generate(
    model="llama3.2:latest",
    prompt="用一句话解释Python是什么。"
)

print(response.response)

生成Python代码

generate()也可用于代码生成，推荐使用专门的代码模型codellama:latest，以下是生成FizzBuzz挑战实现代码的示例：

from ollama import generate

prompt = """
编写一个Python函数fizzbuzz(n: int) -> List[str]，要求：
- 返回1到n的字符串列表；
- 3的倍数替换为"Fizz"；
- 5的倍数替换为"Buzz"；
- 同时是3和5的倍数替换为"FizzBuzz"；
- 其他数字直接转为字符串；
- 若n < 1则抛出ValueError异常；
- 包含兼容Python 3.8的类型注解。
"""

response = generate(model="codellama:latest", prompt=prompt)
print(response.response)

模型会生成符合要求的代码，将代码复制到Python解释器中即可测试：

from typing import List

def fizzbuzz(n: int) -> List[str]:
    if n < 1:
        raise ValueError("n must be greater than or equal to 1")
    result = []
    for i in range(1, n+1):
        if i % 3 == 0 and i % 5 == 0:
            result.append("FizzBuzz")
        elif i % 3 == 0:
            result.append("Fizz")
        elif i % 5 == 0:
            result.append("Buzz")
        else:
            result.append(str(i))
    return result

# 测试
fizzbuzz(16)
# 输出：['1', '2', 'Fizz', '4', 'Buzz', 'Fizz', '7', '8', 'Fizz', 'Buzz', '11', 'Fizz', '13', '14', 'FizzBuzz', '16']

第三步：使用工具调用来获取增强型答案

工具调用（也叫函数调用）能让模型调用Python自定义函数，并将函数执行结果作为上下文，生成更准确、更贴合需求的回复，该技术也可用于检索增强生成（RAG），提升回复的时效性和相关性。

理解工具调用的工作流程

工具调用的功能依赖于模型本身的支持，本教程使用的llama3.2:latest已支持该功能，其核心流程如下：

1. 定义相关的Python工具函数；
2. 将工具函数与提示词一起传入模型；
3. 在代码中执行模型选择的工具函数；
4. 将函数执行结果以role="tool"的消息追加到上下文；
5. 模型基于工具执行结果生成最终回复。

在Python中实现工具调用

以下以平方根计算函数为例，演示工具调用的完整实现过程，模型会自动调用该函数计算平方根，并基于计算结果给出回复：

# tool_calling.py
import math

from ollama import chat

# 定义工具函数：计算平方根
def square_root(number: float) -> float:
    """计算一个数的平方根。
    参数：
        number: 要计算平方根的数值
    返回：
        该数的平方根
    """
    return math.sqrt(number)

messages = [
    {
        "role": "user",
        "content": "36的平方根是多少？",
    }
]

# 传入工具函数并调用模型
response = chat(
    model="llama3.2:latest",
    messages=messages,
    tools=[square_root]
)

# 将模型的回复追加到上下文
messages.append(response.message)

# 判断模型是否触发了工具调用
if response.message.tool_calls:
    tool = response.message.tool_calls[0]
    # 执行工具函数
    result = square_root(float(tool.function.arguments["number"]))

    # 将工具执行结果追加到上下文
    messages.append(
        {
            "role": "tool",
            "tool_name": tool.function.name,
            "content": str(result),
        }
    )

    # 获取模型基于工具结果的最终回复
    final_response = chat(model="llama3.2:latest", messages=messages)
    print(final_response.message.content)

关键说明：

1. 定义工具函数时，清晰的文档字符串（docstring）和类型注解能帮助模型判断是否调用该函数及如何传参；
2. 通过tools参数将自定义函数传入chat()方法；
3. 模型的工具调用信息存储在response.message.tool_calls中；
4. 工具执行结果需以role="tool"追加到messages，供模型生成最终回复。

运行上述代码，输出结果为：36的平方根是6。。

注：若未输出结果，可能是模型直接给出了答案而非调用工具，或工具调用信息未写入tool_calls属性，可尝试使用更大的模型（如llama3.1:8b）或修改提示词鼓励模型调用工具。

总结

通过本教程，你已完成Ollama的安装与启动、本地模型的拉取，以及Ollama Python SDK的集成，掌握了以下核心技能：

1. 安装并运行Ollama，拉取本地运行的大语言模型；
2. 使用chat()实现基于角色和上下文的多轮对话，支持流式输出；
3. 使用generate()实现一次性的文本和代码生成；
4. 利用工具调用，让模型基于自定义函数的执行结果生成有依据的回复。

本地运行大语言模型的核心优势在于提升隐私性、控制成本、支持离线运行，无需依赖外部云服务即可开发和部署AI应用。你可以继续尝试不同的提示词、流式回复和自定义工具，让本地大语言模型的工作流更好地适配你的Python项目。

常见问题解答

能否将Ollama与Python一起使用？

可以。从PyPI安装ollama包，保持Ollama服务运行，即可在Python代码中通过chat()和generate()调用本地模型。

Ollama是免费的吗？

Ollama是开源的，可免费下载和本地运行。需注意模型本身的许可证要求，以及本地计算和存储的硬件成本，但本地运行无云服务的按令牌计费成本。

使用Ollama的优缺点分别是什么？

优点：本地运行提升隐私性、降低长期云服务开销、支持离线工作；
缺点：对硬件性能要求较高，模型文件体积大，无GPU时运行速度较慢。

运行Ollama模型需要GPU吗？

不需要。模型可在CPU上运行，但GPU能大幅提升运行速度，也能让更大的模型顺利运行。

何时使用ollama.chat()，何时使用ollama.generate()？

• chat()：适用于多轮、基于角色的对话，需要保留上下文，也可选择流式输出；
• generate()：适用于一次性提示词调用，无需上下文，如文本起草、总结、快速代码生成等场景。