Ollama Python 库

Ollama Python 库为将 Python 3.8 及以上版本的项目与 Ollama 集成提供了最简便的方式。

先决条件

• 已安装并运行 Ollama
• 拉取一个模型以供库使用：ollama pull <model>，例如 ollama pull gemma3
  • 更多可用模型信息，请参阅 Ollama.com。

安装

pip install ollama

使用方法

from ollama import chat
from ollama import ChatResponse

response: ChatResponse = chat(model='gemma3', messages=[
  {
    'role': 'user',
    'content': '为什么天空是蓝色的？',
  },
])
print(response['message']['content'])
# 或直接从响应对象访问字段
print(response.message.content)

有关响应类型的更多信息，请参阅 _types.py。

流式响应

通过设置 stream=True 可启用流式响应。

from ollama import chat

stream = chat(
    model='gemma3',
    messages=[{'role': 'user', 'content': '为什么天空是蓝色的？'}],
    stream=True,
)

for chunk in stream:
  print(chunk['message']['content'], end='', flush=True)

云端模型

通过将计算任务卸载到 Ollama 的云端，您可以在保持本地工作流程的同时运行更大的模型。

• 支持的模型：deepseek-v3.1:671b-cloud、gpt-oss:20b-cloud、gpt-oss:120b-cloud、kimi-k2:1t-cloud、qwen3-coder:480b-cloud、kimi-k2-thinking。更多信息请参阅 Ollama Models - Cloud。

通过本地 Ollama 运行

1. 登录（仅需一次）：

ollama signin

2. 拉取云端模型：

ollama pull gpt-oss:120b-cloud

3. 发起请求：

from ollama import Client

client = Client()

messages = [
  {
    'role': 'user',
    'content': '为什么天空是蓝色的？',
  },
]

for part in client.chat('gpt-oss:120b-cloud', messages=messages, stream=True):
  print(part.message.content, end='', flush=True)

云端 API (ollama.com)

通过将客户端指向 https://ollama.com，您可以直接访问云端模型。

1. 从 ollama.com 创建 API 密钥，然后设置：

export OLLAMA_API_KEY=your_api_key

2. （可选）列出可通过 API 使用的模型：

curl https://ollama.com/api/tags

3. 通过云端 API 生成响应：

import os
from ollama import Client

client = Client(
    host='https://ollama.com',
    headers={'Authorization': 'Bearer ' + os.environ.get('OLLAMA_API_KEY')}
)

messages = [
  {
    'role': 'user',
    'content': '为什么天空是蓝色的？',
  },
]

for part in client.chat('gpt-oss:120b', messages=messages, stream=True):
  print(part.message.content, end='', flush=True)

自定义客户端

可以通过实例化 ollama 中的 Client 或 AsyncClient 来创建自定义客户端。

所有额外的关键字参数都会传递给 httpx.Client。

from ollama import Client
client = Client(
  host='http://localhost:11434',
  headers={'x-some-header': 'some-value'}
)
response = client.chat(model='gemma3', messages=[
  {
    'role': 'user',
    'content': '为什么天空是蓝色的？',
  },
])

异步客户端

AsyncClient 类用于发出异步请求。它可以使用与 Client 类相同的配置项进行配置。

import asyncio
from ollama import AsyncClient

async def chat():
  message = {'role': 'user', 'content': '为什么天空是蓝色的？'}
  response = await AsyncClient().chat(model='gemma3', messages=[message])

asyncio.run(chat())

设置 stream=True 会将函数修改为返回 Python 异步生成器：

import asyncio
from ollama import AsyncClient

async def chat():
  message = {'role': 'user', 'content': '为什么天空是蓝色的？'}
  async for part in await AsyncClient().chat(model='gemma3', messages=[message], stream=True):
    print(part['message']['content'], end='', flush=True)

asyncio.run(chat())

API

Ollama Python 库的 API 是围绕 Ollama REST API 设计的。

聊天

ollama.chat(model='gemma3', messages=[{'role': 'user', 'content': '为什么天空是蓝色的？'}])

生成

ollama.generate(model='gemma3', prompt='为什么天空是蓝色的？')

列表

ollama.list()

显示

ollama.show('gemma3')

创建

ollama.create(model='example', from_='gemma3', system="你就是超级马里奥中的马里奥。")

复制

ollama.copy('gemma3', 'user/gemma3')

删除

ollama.delete('gemma3')

拉取

ollama.pull('gemma3')

推送

ollama.push('user/gemma3')

嵌入

ollama.embed(model='gemma3', input='天空之所以是蓝色的，是因为瑞利散射。')

批量嵌入

ollama.embed(model='gemma3', input=['天空之所以是蓝色的，是因为瑞利散射。', '草地之所以是绿色的，是因为叶绿素。'])

进程列表

ollama.ps()

错误处理

如果请求返回错误状态码，或者在流式传输过程中检测到错误，将会抛出异常。

model = '不存在的模型'

try:
  ollama.chat(model)
except ollama.ResponseError as e:
  print('错误:', e.error)
  if e.status_code == 404:
    ollama.pull(model)

Ollama Python 快速上手指南

环境准备

在开始之前，请确保满足以下前置条件：

1. 安装并运行 Ollama

   • 访问 Ollama 官网 下载并安装对应系统的 Ollama 服务。
   • 确保 Ollama 服务已在后台运行。

2. 拉取模型

   • 在使用库之前，需先通过命令行拉取一个模型（例如 gemma3）：

     ollama pull gemma3
     

   • 更多可用模型请访问 Ollama 模型搜索页。

3. Python 版本

   • 需要 Python 3.8 或更高版本。

安装步骤

使用 pip 安装官方 Python 库：

pip install ollama

国内加速建议：如果下载速度较慢，可使用国内镜像源安装：

pip install ollama -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是最简单的对话示例，展示如何调用本地模型进行问答：

from ollama import chat

response = chat(model='gemma3', messages=[
  {
    'role': 'user',
    'content': 'Why is the sky blue?',
  },
])

# 打印回复内容
print(response['message']['content'])
# 或者直接访问对象属性
print(response.message.content)

流式输出（可选）

如果需要实时打印生成的内容（类似打字机效果），可开启流式模式：

from ollama import chat

stream = chat(
    model='gemma3',
    messages=[{'role': 'user', 'content': 'Why is the sky blue?'}],
    stream=True,
)

for chunk in stream:
  print(chunk['message']['content'], end='', flush=True)