ollama/ollama-python

Ollama Python 库 – 快速概览

它是什么 – 一个围绕 Ollama REST API 的轻量级 Python 封装。它让您只需几行代码，即可从任何 Python 3.8+ 项目中调用本地运行或云端托管的 LLM。

为什么重要 – Ollama 提供了一个自托管模型服务器（以及云端层级），可以运行多种开源 LLM（例如 Gemma、DeepSeek、Qwen）。此 Python 包消除了 HTTP 请求的样板代码，并为您处理流式传输、异步调用和模型管理。

核心功能 (如 README 所述)

功能	您将获得什么
简单聊天 API	`ollama.chat(model, messages)` 返回一个包含模型回复的 `ChatResponse` 对象。
流式输出	传入 `stream=True` 以在接收到部分 Token 时即时获取，支持同步 (可迭代) 或异步 (异步生成器)。
异步客户端	`AsyncClient` 镜像了同步的 `Client`，但适用于 `await`/`asyncio` 以实现非阻塞程序。
完整模型生命周期	用于 `list`、`show`、`create`、`copy`、`delete`、`pull`、`push` 和 `ps` (处理状态) 的辅助函数。
嵌入支持	`ollama.embed` 为单个字符串或字符串列表返回向量嵌入。
System One	用于决策风格提示 (选择、评分、布尔值) 的结构化问答端点 (`systemone`)。
可自定义 HTTP 客户端	使用自定义 `host`、`headers` 或任何 `httpx.Client` 选项来实例化 `Client` 或 `AsyncClient`。
云端模型访问	将 host 设置为 `https://ollama.com` 并提供 API 密钥，即可针对 Ollama 的托管模型调用相同函数 (例如 `gpt-oss:120b-cloud`)。

典型使用案例

原型化 LLM 驱动的功能 – 快速将聊天、生成或嵌入调用加入脚本、Web 服务或笔记本中。
混合本地/云端工作流程 – 在本地运行小型模型以进行快速迭代，并在需要时切换到云端托管的大型模型。
异步管线 – 使用 AsyncClient 将 LLM 调用整合到异步 Web 框架 (FastAPI, Starlette) 中，而不阻塞事件循环。
结构化决策支持 – 利用 systemone 端点进行简单的分类、评分或多选任务。
模型管理 – 在 Python 代码中自动化拉取、推送或删除模型。

开始使用 (来自 README)

# 安装包
pip install ollama

# 同步聊天示例
from ollama import chat

response = chat(
    model='gemma4',
    messages=[{'role': 'user', 'content': 'Why is the sky blue?'}]
)
print(response.message.content)   # → 来自模型的回答

流式示例

stream = chat(model='gemma4', messages=[{'role': 'user', 'content': 'Why is the sky blue?'}], stream=True)
for chunk in stream:
    print(chunk.message.content, end='', flush=True)

异步使用

import asyncio
from ollama import AsyncClient

async def ask():
    resp = await AsyncClient().chat(model='gemma4', messages=[{'role': 'user', 'content': 'Why?'}])
    print(resp.message.content)

asyncio.run(ask())

云端模型访问

在 ollama.com 创建 API 密钥并导出：

export OLLAMA_API_KEY=your_api_key

将客户端指向云端主机：

from ollama import Client
client = Client(host='https://ollama.com', headers={'Authorization': f'Bearer {os.getenv("OLLAMA_API_KEY")}'})
for part in client.chat('gpt-oss:120b-cloud', messages=[{'role': 'user', 'content': 'Explain quantum entanglement.'}], stream=True):
    print(part.message.content, end='')

错误处理

所有请求层级的错误都会引发 ollama.ResponseError。异常包含：

e.error – 来自服务器的可读消息。
e.status_code – HTTP 状态码 (例如 404 表示模型缺失)。

典型模式：

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