mcpField
O
ollama

ollama

github.com/balloob開発466 回インストール40 週間前に更新
リポジトリ

ollama について

ローカルで動作する Ollama の LLM を Python や Node.js のプロジェクトに組み込む開発者向けスキルです。セットアップ、接続確認、モデル管理、API利用に加え、クラウドに依存しないアプリ向けのストリーミングや埋め込みも扱います。

主な機能

  1. 01Ollama のセットアップと接続確認
  2. 02モデルの一覧表示・取得・削除
  3. 03Python と Node.js の API ガイド
  4. 04ストリーミング生成とチャット
  5. 05埋め込みと RAG の実装
  6. 06トラブルシューティングと統合の指針

活用シーン

  1. 01ローカルのテキスト生成・チャットアプリの構築
  2. 02アプリへのストリーミング応答の追加
  3. 03セマンティック検索や RAG システムの作成
  4. 04Ollama サーバーとモデルの確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/balloob/llm-skills --skill ollama

インストール後、Claude Code で/ollamaを入力して読み込まれたか確認します。

同梱ファイルreferences/nodejs_api.mdreferences/python_api.md

詳細

Ollama

概要

このスキルは、ユーザーが Ollama をプロジェクトに統合し、大規模言語モデルをローカルで実行できるよう支援します。セットアップ、接続の検証、モデル管理、Python および Node.js アプリケーション向けの API 統合について案内します。Ollama を使用すると、クラウドに依存せず、Llama、Mistral、Gemma などのモデルをローカルで実行するためのシンプルな API を利用できます。

このスキルを使用するタイミング

次のことをユーザーが希望する場合に、このスキルを使用します。

  • 自分のマシンで大規模言語モデルをローカル実行する
  • クラウドに依存しない AI 搭載アプリケーションを構築する
  • テキスト生成、チャット、または埋め込み機能を実装する
  • LLM の応答をリアルタイムでストリーミングする
  • RAG（検索拡張生成）システムを作成する
  • Python または Node.js プロジェクトにローカル AI 機能を統合する
  • Ollama モデルを管理する（取得、一覧表示、削除）
  • Ollama への接続を検証し、接続の問題をトラブルシューティングする

インストールとセットアップ

ステップ 1：Ollama の URL を確認する

重要：必ず Ollama の URL をユーザーに確認してください。ローカルで実行されていると決めつけないでください。

ユーザーに「Ollama サーバーの URL は何ですか？」と尋ねます。

よくあるケース：

  • ローカルインストール：http://localhost:11434（デフォルト）
  • リモートサーバー：http://192.168.1.100:11434
  • カスタムポート：http://localhost:8080
  • Docker：http://localhost:11434（ポートが 11434 にマッピングされている場合）

Ollama をローカルで実行しているとユーザーが言った場合や、URL がわからない場合は、http://localhost:11434 を試すよう提案します。

ステップ 2：Ollama がインストールされているか確認する

先に進む前に、指定された URL で Ollama がインストールされ、実行中であることを確認します。ユーザーはブラウザーで URL にアクセスするか、次のコマンドを実行して確認できます。

curl <OLLAMA_URL>/api/version

Ollama がインストールされていない場合は、インストール方法を案内します。

macOS/Linux：

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

Windows： https://ollama.com/download からダウンロードしてください

Docker：

docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama
ステップ 3：Ollama サービスを起動する

Ollama が実行中であることを確認します。

macOS/Linux：

ollama serve

Docker：

docker start ollama

通常、サービスはデフォルトで http://localhost:11434 で実行されます。

ステップ 4：接続を検証する

検証スクリプトを使って接続をテストし、利用可能なモデルを一覧表示します。

重要：スクリプトのパスはスキルのディレクトリからの相対パスです。スクリプトを実行するときは、次のいずれかを行ってください。

  1. スキルのディレクトリからのフルパスを使用する（例：/path/to/ollama/scripts/validate_connection.py）
  2. 先にスキルのディレクトリに移動してから、python scripts/validate_connection.py を実行する
# Run from the skill directory
cd /path/to/ollama
python scripts/validate_connection.py <OLLAMA_URL>

ユーザーの Ollama URL を使用した例：

cd /path/to/ollama
python scripts/validate_connection.py http://192.168.1.100:11434

スクリプトは次の処理を行います。

  • URL を正規化する（パス部分をすべて削除する）
  • Ollama にアクセスできるか確認する
  • Ollama のバージョンを表示する
  • インストール済みのすべてのモデルとサイズを一覧表示する
  • 接続に失敗した場合に、トラブルシューティングの方法を提示する

成功時の出力：

✓ Connection successful!
  URL: http://localhost:11434
  Version: Ollama 0.1.0
  Models available: 2

Installed models:
  - llama3.2 (4.7 GB)
  - mistral (7.2 GB)

失敗時の出力：

✗ Connection failed: Connection refused
  URL: http://localhost:11434

Troubleshooting:
  1. Ensure Ollama is installed and running
  2. Check that the URL is correct
  3. Verify Ollama is accessible at the specified URL
  4. Try: curl http://localhost:11434/api/version

モデル管理

モデルの取得

Ollama ライブラリからモデルをダウンロードするようユーザーに案内します。よく使われるモデルは次のとおりです。

  • llama3.2 - Meta の Llama 3.2（さまざまなサイズ：1B、3B）
  • llama3.1 - Meta の Llama 3.1（8B、70B、405B）
  • mistral - Mistral 7B
  • phi3 - Microsoft Phi-3
  • gemma2 - Google Gemma 2

ユーザーは次の方法でモデルを取得できます。

ollama pull llama3.2

または、API を使ってプログラムから取得できます（例はリファレンスドキュメントを参照）。

モデルの一覧表示

インストール済みモデルを一覧表示する方法をユーザーに案内します。

ollama list

または、検証スクリプトを使って詳細情報とともにモデルを確認できます。

モデルの削除

空き容量を確保するためにモデルを削除する方法をユーザーに案内します。

ollama rm llama3.2
モデル選択のガイダンス

ニーズに応じた適切なモデルの選び方をユーザーに案内します。

  • 小規模モデル（1～3B）：高速で、単純なタスクに適しており、必要なリソースも少なめです
  • 中規模モデル（7～13B）：性能と品質のバランスが取れています
  • 大規模モデル（70B 以上）：最高品質ですが、多くのリソースが必要です

実装ガイダンス

Python プロジェクト

Python ベースのプロジェクトについては、Python API リファレンスを参照してください。

  • ファイル：references/python_api.md
  • 用途：Python 統合を実装する際に、このリファレンスを読み込んでください
  • 内容：
    • 標準ライブラリの urllib.request を使用した REST API の例
    • Generate API を使用したテキスト生成
    • Chat API を使用した会話型インターフェース
    • リアルタイム出力のためのストリーミング応答（推奨）
    • セマンティック検索用の埋め込み
    • RAG システムの完全な例
    • エラー処理のパターン
    • 依存関係用の PEP 723 インラインスクリプトメタデータ
  • 依存関係は不要：Python 標準ライブラリのみを使用します

重要：ユーザー向けの Python スクリプトを作成する際は、依存関係を宣言するために PEP 723 インラインスクリプトメタデータを含めてください。例についてはリファレンスドキュメントを参照してください。

ストリーミングをデフォルトにする：テキスト生成またはチャットを実装する際は、ユーザーが明示的に非ストリーミングを希望しない限り、ストリーミング応答を使用してください。

Python の一般的なユースケース：

# Streaming text generation (RECOMMENDED)
for token in generate_stream("Explain quantum computing"):
    print(token, end="", flush=True)

# Streaming chat conversation (RECOMMENDED)
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"}
]
for token in chat_stream(messages):
    print(token, end="", flush=True)

# Non-streaming (use only when needed)
response = generate("Explain quantum computing")

# Embeddings for semantic search
embedding = get_embeddings("Hello, world!")
Node.js プロジェクト

Node.js ベースのプロジェクトについては、Node.js API リファレンスを参照してください。

  • ファイル：references/nodejs_api.md
  • 用途：Node.js 統合を実装する際に、このリファレンスを読み込んでください
  • 内容：
    • 公式の ollama npm パッケージの例
    • Fetch API を使用する代替例（Node.js 18 以降）
    • テキスト生成 API とチャット API
    • 非同期イテレーターを使用したストリーミング（推奨）
    • 埋め込みとセマンティック類似度
    • RAG システムの完全な例
    • エラー処理と再試行ロジック
    • TypeScript のサポート例

インストール：

npm install ollama

ストリーミングをデフォルトにする：テキスト生成またはチャットを実装する際は、ユーザーが明示的に非ストリーミングを希望しない限り、ストリーミング応答を使用してください。

Node.js の一般的なユースケース：

import { Ollama } from 'ollama';
const ollama = new Ollama();

// Streaming text generation (RECOMMENDED)
const stream = await ollama.generate({
  model: 'llama3.2',
  prompt: 'Explain quantum computing',
  stream: true
});

for await (const chunk of stream) {
  process.stdout.write(chunk.response);
}

// Streaming chat conversation (RECOMMENDED)
const chatStream = await ollama.chat({
  model: 'llama3.2',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is the capital of France?' }
  ],
  stream: true
});

for await (const chunk of chatStream) {
  process.stdout.write(chunk.message.content);
}

// Non-streaming (use only when needed)
const response = await ollama.generate({
  model: 'llama3.2',
  prompt: 'Explain quantum computing'
});

// Embeddings
const embedding = await ollama.embeddings({
  model: 'llama3.2',
  prompt: 'Hello, world!'
});

一般的な統合パターン

テキスト生成

プロンプトからテキストの補完を生成します。ユースケース：

  • コンテンツ生成
  • コード補完
  • 質問への回答
  • 要約

ユースケースに応じた適切なパラメーター（temperature、top_p など）を指定して Generate API を使用するよう、ユーザーを案内してください。

会話型インターフェース

会話履歴を含むチャットアプリケーションを構築します。ユースケース：

  • チャットボット
  • バーチャルアシスタント
  • カスタマーサポート
  • インタラクティブチュートリアル

メッセージ履歴を管理しながら Chat API を使用するよう、ユーザーを案内してください。動作を制御するうえでシステムプロンプトが重要であることを説明してください。

埋め込みとセマンティック検索

テキストのベクトル埋め込みを生成します。ユースケース：

  • セマンティック検索
  • ドキュメントの類似度
  • RAG システム
  • レコメンデーションシステム

Embeddings API を使用し、埋め込みを比較するためにコサイン類似度を実装するよう、ユーザーを案内してください。

ストリーミング応答

推奨される方法：ユーザー体験を向上させるため、常にストリーミングを優先してください。

LLM の出力をトークン単位でストリーミングします。ユースケース：

  • リアルタイムのチャットインターフェース
  • 段階的なコンテンツ生成
  • 長い出力におけるユーザー体験の向上
  • ユーザーへの即時フィードバック

ユーザー向けのコードを作成する際は、非ストリーミング応答を明示的に希望された場合を除き、ストリーミング API をデフォルトにしてください。

次のようにユーザーを案内してください：

  • API 呼び出しで stream: true を有効にする
  • 非同期イテレーション（Node.js）またはジェネレーター（Python）を処理する
  • トークンの到着に合わせて表示し、リアルタイムのフィードバックを提供する
  • 生成中に進行状況インジケーターを表示する
RAG（検索拡張生成）

ドキュメント検索と生成を組み合わせます。ユースケース：

  • ドキュメントに関する質問への回答
  • ナレッジベースのチャットボット
  • コンテキストを考慮した支援

ユーザーを次の手順に案内してください：

  1. ドキュメントの埋め込みを生成する
  2. 関連するテキストとともに埋め込みを保存する
  3. クエリの埋め込みを使用して関連ドキュメントを検索する
  4. 検索したコンテキストをプロンプトに挿入する
  5. コンテキストを用いて回答を生成する

どちらのリファレンスドキュメントにも、RAG システムの完全な例が含まれています。

ベストプラクティス

セキュリティ
  • 機密情報をハードコードしないでください
  • 設定には環境変数を使用してください
  • LLM に送信する前に、ユーザー入力を検証してサニタイズしてください
パフォーマンス
  • 長い応答ではストリーミングを使用し、体感パフォーマンスを向上させます
  • 変更されないドキュメントの埋め込みをキャッシュします
  • 用途に合った適切なサイズのモデルを選択します
  • モデルを選択する際は、応答時間の要件を考慮します
エラー処理
  • ネットワーク障害に対する適切なエラー処理を必ず実装します
  • リクエストを送信する前に、モデルが利用可能か確認します
  • ユーザーにわかりやすいエラーメッセージを提示します
  • 一時的な障害に対するリトライ処理を実装します
接続管理
  • 実装に進む前に、接続を検証します
  • 接続タイムアウトを適切に処理します
  • リモートの Ollama インスタンスでは、ネットワークにアクセスできることを確認します
  • 開発中は検証スクリプトを使用します
モデル管理
  • サイズの大きいモデルをダウンロードする前に、利用可能なディスク容量を確認します
  • 実際に使用しているモデルのみを保持します
  • モデルのダウンロードサイズをユーザーに知らせます
  • 要件に基づいたモデルの選択方法を案内します
コンテキスト管理
  • チャットアプリケーションでは、トークン数の上限を超えないように会話履歴を管理します
  • 会話が長くなりすぎた場合は、古いメッセージを削除します
  • 長い会話履歴には要約の利用を検討します

トラブルシューティング

接続の問題

接続に失敗する場合：

  1. Ollama がインストールされていることを確認します：ollama --version
  2. Ollama が実行中か確認します：curl http://localhost:11434/api/version
  3. Ollama サービスを再起動します：ollama serve
  4. リモート接続用のファイアウォール設定を確認します
  5. URL の形式が正しいことを確認します（パスを含めず、http://host:port の形式にします）
モデルが見つからない

モデルが利用できない場合：

  1. インストール済みモデルを一覧表示します：ollama list
  2. 必要なモデルをダウンロードします：ollama pull model-name
  3. モデル名の綴りを確認します（大文字と小文字は区別されます）
メモリ不足

メモリが不足する場合：

  1. より小さいモデルのバリアントを使用します
  2. 他のアプリケーションを終了します
  3. システムのスワップ領域を増やします
  4. RAM 容量の大きいマシンの使用を検討します
パフォーマンスが遅い

応答が遅い場合：

  1. より小さいモデルを使用します
  2. num_predict パラメーターを小さくします
  3. CPU／GPU の使用状況を確認します
  4. 利用可能な場合は、Ollama が GPU を使用していることを確認します
  5. リソースを大量に消費する他のアプリケーションを終了します

リソース

scripts/validate_connection.py

Ollama への接続を検証し、利用可能なモデルを一覧表示する Python スクリプトです。URL の正規化、接続テスト、バージョン情報の表示、トラブルシューティングの案内を行います。

references/python_api.md

次の例を含む、包括的な Python API リファレンスです：

  • インストールとセットアップ
  • 接続の確認
  • モデル管理（一覧表示、ダウンロード、削除）
  • テキスト補完用の Generate API
  • 会話用の Chat API
  • ストリーミング応答
  • 埋め込みとセマンティック検索
  • RAG システムの完全な実装
  • エラー処理のパターン
  • ベストプラクティス
references/nodejs_api.md

次の例を含む、包括的な Node.js API リファレンスです：

  • npm を使用したインストール
  • 公式 ollama パッケージの使用
  • Fetch API を使用した代替例
  • モデル管理
  • Generate API と Chat API
  • 非同期イテレーターによるストリーミング
  • 埋め込みとセマンティック類似度
  • RAG システムの完全な実装
  • エラー処理とリトライ処理
  • TypeScript のサポート
  • ベストプラクティス

コメント

Markdown 対応