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` を渡すことで、同期（イテラブル）または非同期（非同期ジェネレーター）でトークンを逐次受け取れます。
非同期クライアント	`AsyncClient` は同期版 `Client` と同様のインターフェースを持ち、`await`/`asyncio` を使用した非ブロッキングプログラムに対応しています。
モデルのライフサイクル管理	`list`、`show`、`create`、`copy`、`delete`、`pull`、`push`、`ps` (プロセス状態) のヘルパー関数を提供します。
埋め込みサポート	`ollama.embed` は、単一の文字列または文字列リストに対してベクトル埋め込みを返します。
System One	意思決定スタイルのプロンプト（選択、スコア、ブール値）のための構造化された Q&A エンドポイント (`systemone`)。
カスタマイズ可能な HTTP クライアント	`Client` または `AsyncClient` をインスタンス化する際に、カスタム `host`、`headers`、または任意の `httpx.Client` オプションを指定可能です。
クラウドモデルへのアクセス	ホストを `https://ollama.com` に設定し、API キーを提供することで、Ollama のホスト型モデル（例：`gpt-oss:120b-cloud`）に対して同じ関数を呼び出せます。

一般的なユースケース

LLM 搭載機能のプロトタイプ作成 – チャット、生成、埋め込み呼び出しをスクリプト、Web サービス、ノートブックに素早く追加できます。
ローカル/クラウドのハイブリッドワークフロー – 小規模モデルをローカルで実行して高速に反復し、必要に応じてクラウドホスト型の大型モデルに切り替えます。
非同期パイプライン – AsyncClient を使用して、イベントループをブロックすることなく、非同期 Web フレームワーク (FastAPI, Starlette) に LLM 呼び出しを統合します。
構造化された意思決定サポート – 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')

詳細情報

API リファレンス – ライブラリは公式の Ollama REST API (docs/api.md) を反映しています。
型定義 – レスポンスオブジェクトの正確な構造については ollama/_types.py を参照してください。
サンプル – リポジトリには、構造化 Q&A エンドポイントを実演する examples/systemone.py スクリプトが含まれています。

結論 – Ollama Python ライブラリは、開発者がローカルおよびクラウドの Ollama LLM と慣用的な Python で対話できるように設計された、目的特化型の軽量クライアントです。ストリーミング、非同期処理、埋め込みや構造化プロンプトなどの高度な操作をサポートしています。