Ollama Python SDK活用ガイド:ローカルLLMを実践的なアプリケーションに統合する

Python tutorial - IT technology blog
Python tutorial - IT technology blog

クラウドAPIに依存せず社内でローカルLLMをセルフホストすべき理由

エンタープライズのインフラ環境において、データセキュリティは常に最大の課題です。内部IPアドレス、アクセストークン、データベースダンプなどを含むログファイルをクラウドAPIに送信することは、極めて高い情報漏洩リスクを伴います。また、コンプライアンス上の懸念だけでなく、毎日数万行規模のログを解析する場合にはトークンコストも急激に増大します。

Ollamaを用いてオープンソースモデルをセルフホストすることで、これら2つの課題を根本から解決できます。データがサーバー外部へ送信されることはなく、APIコストもゼロになります。さらに、公式ライブラリであるOllama Python SDKと組み合わせれば、使い慣れたわずか数行のコードで自動化スクリプトにAIを直接組み込むことが可能です。

環境構築

まず、Ollamaサービスがインストールされ、デフォルトポートである11434で正常にリッスンしていることを確認します。

1. Ollamaサーバーのインストール

UbuntuまたはmacOSサーバーで以下のコマンドを実行し、最新バージョンをインストールします:

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

続いて、テスト用に軽量なモデルをプルします。llama3.2:3bモデルはサイズが約2.0GB、VRAM消費量も2.5GB未満と軽量ながら、英語やベトナム語の推論も非常に安定しています:

ollama pull llama3.2:3b
ollama list

2. Python SDKのインストール

依存関係の衝突を防ぐため、独立した仮想環境(virtualenv)の作成を推奨します:

python3 -m venv .venv
source .venv/bin/activate
pip install ollama

Ollama Python SDKの実践:基本から応用まで

SDKは主に2つのインターフェースを提供しています。シンプルなタスク向けの同期(synchronous)インターフェースと、高負荷なバックエンド向けの非同期(async)インターフェースです。

1. テキスト生成とリアルタイムストリーミング

プロンプトに対して長い回答を求める場合、モデルがテキスト全体を生成し終えるまで待つとレスポンスの遅延(もたつき)を感じやすくなります。パラメータstream=Trueを有効にすると、Time-To-First-Token(TTFT)を300ms未満に短縮し、生成されたテキストからリアルタイムに順次表示できます。

import ollama

# ストリーミング形式でモデルを呼び出す
stream = ollama.generate(
    model='llama3.2:3b',
    prompt='セキュアなDockerfileを作成するための3つの原則を簡潔に述べてください:',
    stream=True
)

print("ローカルLLMからの応答:")
for chunk in stream:
    print(chunk['response'], end='', flush=True)
print()

2. マルチターン会話の管理(Chat API)

生のプロンプトのみを受け取るgenerateとは異なり、chat関数はロール(system、user、assistant)が割り当てられたメッセージリストを介して会話のコンテキストを維持します。

from ollama import Client

# 社内Ollamaインスタンスへのクライアントを初期化
client = Client(host='http://localhost:11434')

messages = [
    {
        'role': 'system',
        'content': 'あなたはDevOpsエンジニアです。技術的な解決策に絞って簡潔に回答してください。'
    },
    {
        'role': 'user',
        'content': 'PythonアプリケーションのDockerイメージサイズを削減するにはどうすればよいですか?'
    }
]

# 1回目の対話
response = client.chat(model='llama3.2:3b', messages=messages)
print(response['message']['content'])

# コンテキストを維持するためにモデルの応答を会話履歴に追加
messages.append(response['message'])
messages.append({
    'role': 'user',
    'content': 'alpine以外に、さらに効果的な手法はありますか?'
})

# 2回目の対話
follow_up = client.chat(model='llama3.2:3b', messages=messages)
print(follow_up['message']['content'])

注意:Ollamaのコンテキストウィンドウ(num_ctx)はデフォルトで2048トークンに設定されています。長い会話や大量のドキュメントを投入する場合は、辞書指定options={'num_ctx': 4096}でこのパラメータを増やすことをおすすめします。

3. 構造化JSONデータの出力強制(Structured Output)

ログパーサーのスクリプトを作成する際、PostgreSQLに保存したりElasticsearchに転送したりするために、標準化されたスキーマのデータが必要になります。format='json'を渡すことで、モデルに対して余分な解説文を含めず、有効なJSONのみを返すよう強制できます。

import json
from ollama import chat

prompt = """
以下のログから status、error_code、service_name のフィールドを抽出してください:
[2026-11-20 09:12:01] [payment-service] ERROR 504: Gateway Timeout when contacting bank gateway
"""

response = chat(
    model='llama3.2:3b',
    messages=[{'role': 'user', 'content': prompt}],
    format='json'
)

# マークダウン(```json)混入を心配することなくPython辞書に直接パース可能
data = json.loads(response['message']['content'])
print(f"サービス名: {data.get('service_name')} | エラーコード: {data.get('error_code')}")

4. AsyncClientによる並行処理

FastAPIなどの非同期Webフレームワークでは、同期クライアントを使用しないでください。2〜5秒かかる推論処理がイベントループ全体をブロックし、サーバーの応答が停止してしまいます。このような場合は、AsyncClientとasyncio.gatherを組み合わせて使用します。

import asyncio
from ollama import AsyncClient

async def analyze_task(client, task_id, prompt):
    res = await client.generate(model='llama3.2:3b', prompt=prompt)
    return task_id, res['response'][:60].strip()

async def main():
    client = AsyncClient(host='http://localhost:11434')
    tasks_data = [
        ("task_1", "Kubernetes Ingressの概念を一文で説明してください"),
        ("task_2", "Gitのmergeとrebaseの違いを説明してください"),
    ]
    coros = [analyze_task(client, t_id, p) for t_id, p in tasks_data]
    results = await asyncio.gather(*coros)
    
    for t_id, summary in results:
        print(f"[{t_id}] -> {summary}...")

if __name__ == '__main__':
    asyncio.run(main())

運用上のヒント:複数のリクエストをスムーズに並列処理したい場合は、Ollamaサーバーを起動する前に環境変数OLLAMA_NUM_PARALLEL=4を設定してください。

実環境でのリソース監視とパフォーマンス測定

ローカル環境でAIモデルを実行する際は、VRAM消費量とトークン生成速度を常に監視する必要があります。十分なリソース計算を行わないと、GPUメモリ枯渇によるOut Of Memory(OOM)エラーが発生し、プロセスがクラッシュする原因となります。

1. VRAMとGPUオフロード状況の監視

モデルがGPUに完全にロードされているか、あるいはシステムRAMへ溢れてしまっているかを確認するには、ターミナルで以下のコマンドを実行します:

# NVIDIA GPUの実際のVRAM消費量を確認
watch -n 1 nvidia-smi

# Ollamaのモデルロード状態を確認
ollama ps

ollama psの実行結果にあるPROCESSORカラムが100% GPUと表示されている必要があります。もし60% GPU / 40% CPUのような比率になっている場合、PCIeの帯域幅がボトルネックとなり、トークン生成速度が4〜5分の1に低下してしまいます。

2. 推論速度の測定(Tokens Per Second)

SDKはリクエストごとに詳細なメタデータを返します。これらのフィールドを抽出することで、メトリクスをPrometheusやGrafanaに出力できます:

import ollama

res = ollama.generate(model='llama3.2:3b', prompt='Ping test')

# eval_durationはナノ秒単位で返される
eval_count = res.get('eval_count', 0)
eval_duration_sec = res.get('eval_duration', 1) / 1e9
tokens_per_sec = eval_count / eval_duration_sec if eval_duration_sec > 0 else 0

print(f"生成トークン数: {eval_count}")
print(f"推論速度: {tokens_per_sec:.2f} tokens/s")

通常、RTX 4060(8GB VRAM)のようなミドルレンジGPU環境下で、llama3.2:3bを使用した場合、45〜65 tokens/sの速度に達します。バッチ処理スクリプトの実行完了後すぐにVRAMを解放したい場合は、リクエストにkeep_alive=0パラメータを追加することで、Ollamaにメモリ上のモデルを自動的にアンロードさせることができます。

Share: