ollama/ollama-python

Ollama Python 库 – 快速概览

它是什么：一个轻量级 Python 封装（适用于 Python 3.8+），让你从代码中调用 Ollama AI 推理服务器。它镜像了 Ollama REST API，处理聊天、生成、模型管理、嵌入以及更新的“System One”决策端点。

主要功能

聊天与生成 – ollama.chat() 和 ollama.generate() 将提示发送到本地或云端托管的模型，并返回结构化响应对象。
流式 – 设置 stream=True 以接收一个生成器，该生成器在响应到达时产生部分响应。
模型管理 – 直接从 Python 拉取、推送、列出、显示、创建、复制、删除模型。
嵌入 – ollama.embed() 返回单个字符串或批次的向量嵌入。
System One – 用于决策类型查询（选择、是/否、评分）的专用端点，支持可选图像输入。
异步支持 – AsyncClient 使用 async/await 和异步生成器提供相同的 API。
可定制客户端 – 底层使用 httpx；你可以将其指向任何主机（例如，本地 Ollama 服务器 http://localhost:11434 或云端 https://ollama.com）并添加自定义标头。

安装

pip install ollama

基本用法示例

from ollama import chat

response = chat(
    model='gemma4',
    messages=[{'role': 'user', 'content': 'Why is the sky blue?'}]
)
print(response.message.content)   # 或 response['message']['content']

流式示例

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

直接使用客户端（例如，用于云端模型）

from ollama import Client
import os

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':'Why is the sky blue?'}], stream=True):
    print(part.message.content, end='')

异步用法

import asyncio
from ollama import AsyncClient

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

asyncio.run(main())

System One 示例

import ollama
resp = ollama.systemone(
    model='nimble',
    state='Our checkout has returned 500 errors since 9am.',
    questions={
        'team': {
            'type': 'choice',
            'instructions': 'Which team should handle this ticket?',
            'criteria': {'billing':'Payments and refunds','technical':'Software errors'}
        }
    }
)
print(resp.answers['team'])

错误处理

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

何时使用

你已经在本地运行 Ollama 或拥有 Ollama 云订阅，并希望以 Pythonic 方式与之交互。
你需要流式响应或异步调用用于 UI 或服务器端应用程序。
你想在不离开 Python 环境的情况下管理模型（拉取、推送、删除）。
你需要 System One 决策 API 用于结构化、多问题工作流。

它不提供什么

它本身不包含任何 AI 模型；你必须安装 Ollama 并拉取所需的模型。
训练或微调能力不在其范围内。

以上所有细节均直接取自仓库的 README。

ollama/ollama-python

Ollama Python 库 – 快速概览

相关