local-ai-use

ローカル AI の利用（画像、TTS、STT を Lemonade 経由にする）

これはメタスキルです。一度実行すれば、以降、画像生成、テキスト読み上げ、音声テキスト変換が必要なリクエストでは、クラウド API の代わりにローカルの Lemonade Server が使われます。エージェント自身の LLM は引き続きテキストを処理し、高コストなマルチモーダル呼び出しだけがデバイス上で実行されます。

このスキルでは、次の 3 つを行います。

1. ローカルの Lemonade がインストールされ、実行中であることを確認します。 最新の lemonade CLI が見つからない場合、セットアップスクリプトがユーザーに代わって最新バージョンの Lemonade をインストールします。最新の Lemonade には serve コマンドがありません。Lemonade サービス（lemond デーモン）はインストール時に自動起動し、OS によって管理されます。そのため、セットアップスクリプトはサービスが起動するまで待機し、停止したままの場合は、起動に使う OS 固有のコマンド（例：Linux では sudo systemctl start lemond）を正確に表示します。
2. lemonade status が報告するポートでローカルの Lemonade に接続できることを確認します。これにより、デフォルト以外のポートですでに実行中のサーバーも、未検出として報告されず、そのまま使用されます（13305 はフォールバックにすぎません）。
3. ワークスペースの AGENTS.md に Local AI Use ブロックを追加し、以降のすべてのターンで、Cursor、Claude Code、Codex、Gemini CLI、および AGENTS.md に対応するその他のエージェントがルーティングルールを読み込むようにします。

最新の Lemonade（v10.1.0 以降）が必要です。 最新の Lemonade では、常時稼働する lemond サービスを制御する単一の lemonade CLI（lemonade status、lemonade pull など）にすべてが統合されています。有効な CLI は lemonade のみです。このスキルでは、ステップ 1a に記載された公式のインストール方法からのみ Lemonade をインストールします。古い lemonade がすでに PATH 上にある場合、最新の CLI の実行を妨げます。このスキルを実行する前にアンインストールしてください（ステップ 1a の削除コマンドを参照）。

セットアップ中にモデルはダウンロードされません。デフォルトの各モデルは、ルーティングルールによって初回使用時に遅延ダウンロードされます（例：初めて画像をリクエストしたときに画像モデルをダウンロードします）。これにより、セットアップを速くし、ユーザーが必要としない可能性のある数ギガバイトものダウンロードを避けられます。

このスキルを使う場合

次の条件をすべて満たす場合に、このスキルを使います。

• ユーザーがローカルの Lemonade を希望していること。まだインストールされていない場合、セットアップスクリプトがユーザーに代わって最新バージョンを自動インストールします。
• ユーザーが、このマシン上の Lemonade エンドポイントを受け入れること。ポートはサービスが報告するものを使います（変更されたことがなければ http://localhost:13305）。
• ユーザーが、今後のターンやエージェントの再起動後も変更を永続化することを希望していること（ルールはディスクに書き込まれます）。

ユーザーがアプリのインストーラー内に Lemonade をプライベートなサブプロセスとして組み込む場合は、このスキルを使わず、代わりに local-ai-app-integration を使います。

前提条件

• OS： Windows 11 x64、Ubuntu/Debian x64、または macOS（ベータ版）。
• Lemonade： Lemonade が見つからない場合、セットアップスクリプトが最新バージョンをインストールします。Windows では winget、Ubuntu/Debian では ppa:lemonade-team/stable PPA、macOS では Homebrew cask を使用します（代替手段についてはステップ 1a を参照）。インストール後、lemond サービスは自動起動します。スクリプトはサービスを起動せず、起動を待機します。Linux でのインストールには sudo が必要です。ユーザー自身でインストールする場合は、--no-install を渡してください。
• ディスク容量： デフォルトの 3 つのモデル（SD-Turbo + Whisper-Tiny
  • kokoro-v1）用に約 8 GB、インストーラー本体用に約 0.1 GB の空き容量が必要です。最初の画像リクエスト時には、SD-Turbo がまだキャッシュされていない場合、約 5 GB のダウンロードも発生します。従量制または低速なネットワーク接続では、セットアップ後にモデルをあらかじめダウンロードすることを検討してください（reference.md の lemonade pull を参照）。
• ネットワーク： インストールのダウンロードと各モデルの初回 lemonade pull に必要です。その後は、すべてのモダリティがオフラインで動作します。
• バージョン： v10.1.0 以降が必要です（このスキルが対象とする統合版の lemonade CLI）。モデル ID と system-info フィールドはリリースごとに変わる場合があります。このドキュメントが最新だと思い込まず、実際にインストールされたバージョンの lemonade status と GET /api/v1/models で確認してください。

推奨手順

このチェックリストを上から順に実行してください。進捗を記録し、各ステップの確認が済むまで先に進まないでください。

[ ] 1. Ensure Lemonade Server is installed and running (auto-install if missing)
[ ] 2. Install the routing rule into the workspace AGENTS.md

管理対象または共有マシンで、エージェントに sudo apt-get install を実行させてはいけない場合は、セットアップスクリプトに --no-install を渡し、続行する前に Lemonade がすでにインストールされていることを確認してください。

両方のステップを一度に実行するコマンドは次のとおりです。

python scripts/setup_local_ai.py

Lemonade がすでにインストールされ、サーバーがすでに実行中であっても、また画像を 1 枚生成する前であっても、必ず最初にこのスクリプトを実行してください。 AGENTS.md にルーティングルールを書き込むことで、このスキルが完全なものになります。「Lemonade はすでに起動している」という理由で省略すると、今後のターンに向けてワークスペースが設定されないままになります。その場合でも、スクリプトの実行に問題はありません。実行中のサービスを検出し、インストールをスキップしてルールを書き込みます。

最新の lemonade CLI が見つからない場合は、最新バージョンの Lemonade を自動インストールして、自動起動した lemond サービスを待機した後、ルールを書き込みます。スクリプトは冪等です。設定済みのワークスペースで再実行しても、ヘルスチェック以外は何も行いません。各ステップが失敗した場合の対処方法については、以下のセクションを参照してください。

---

ステップ 1：Lemonade Server がインストールされ、実行中であることを確認する

scripts/setup_local_ai.py が一連の処理をすべて行いますが、手動で実行したりデバッグしたりできるよう、処理内容を以下に説明します。Lemonade がすでに別の方法で管理されていて、エージェントがパッケージのインストールを試みてはいけない場合は、--no-install を渡してください。

1a. 最新版の lemonade CLI がインストールされていますか？ lemonade status を実行します。判定基準は名前ではなく、機能です。最新の Lemonade は Server is running... または Server is not running と表示します。「invalid choice」や使用方法に関するエラーが表示される場合、PATH 上の lemonade は統合版 CLI（v10.1.0）より前の古いビルドです。使用しないでください。 削除してから、このスキルを再実行してください。

OS	古いビルドのアンインストール方法
Windows	winget uninstall -e --id AMD.LemonadeServer、または「設定」>「アプリ」>「インストールされているアプリ」>「Lemonade Server」>「アンインストール」
Ubuntu/Debian	sudo apt remove lemonade-server
macOS	brew uninstall --cask lemonade-server、またはインストール済みの Lemonade.app とその .pkg レシートを削除

ユーザーに代わってアンインストールしたり、自動で削除したりしないでください。

lemonade がまったく見つからない場合は、ユーザーに代わって最新バージョンをインストールしてください。まずパッケージマネージャーを使用し、パッケージマネージャーがない場合はダウンロードを代替手段として使用してください。Arch、Fedora、Debian、Snap、Docker を含む全対応環境については、インストールのドキュメント を参照してください。

OS	インストール	代替手段
Windows	winget install -e --id AMD.LemonadeServer	lemonade.msi をダウンロードし、msiexec /i lemonade.msi /qn を実行します（サイレント、ユーザーごと、管理者権限不要）。
Ubuntu	sudo add-apt-repository -y ppa:lemonade-team/stable && sudo apt-get update && sudo apt-get install -y lemonade-server	sudo snap install lemonade-server
macOS	brew install --cask lemonade-server	最新リリースから Lemonade-<ver>-Darwin.pkg をダウンロードし、sudo installer -pkg Lemonade-<ver>-Darwin.pkg -target / を実行します。

Ubuntu の apt パッケージ名は lemonade-server ですが、インストールされる CLI は lemonade です。ブラウザー UI は追加パッケージなしで http://localhost:13305 で 提供されます。デスクトップフロントエンドが必要な場合に限り、 sudo apt install lemonade-desktop を追加します。

Windows にインストールすると、CLI は %LOCALAPPDATA%\lemonade_server に配置され、 ユーザー PATH に追加されます（新しいシェルでのみ有効）。セットアップスクリプトは このディレクトリを確認するため、同じ実行中でも動作します。

1b. サービスは実行中ですか？ 実行場所はどこですか？ lemonade status --json を 確認します。バインドされているポート（{"port": 13305}）が出力され、両方を一度に 確認できます。lemond サービスはインストール時に自動起動します。最新の Lemonade に lemonade serve はありません。

lemonade status の表示	対応
Server is running on port <N>	後続のすべてのリクエストとルールには、13305 以外の場合もポート <N> を使います。ステップ 2 に進みます。
Server is not running	自動起動したサービスが起動するまで数秒待ちます（スクリプトは /api/v1/health をポーリングし、サービスが別のポートで起動した場合に備えて status を再確認します）。停止したままの場合は、OS のサービスマネージャーから起動します。Linux のシステムインストールでは sudo systemctl start lemond、ユーザーごとのインストールでは systemctl --user start lemond、macOS では launchctl load /Library/LaunchDaemons/com.lemonade.server.plist、Windows では Lemonade トレイアプリまたは Start-Service lemond を使います。

13305 を「実行中」の定義として扱わないでください。ポートは設定値 （lemonade config set port）であり、既存の設定、別のインストール方法、または ポートの競合によって変更されるため、デフォルトのポートだけを確認すると正常な サーバーが見つからないと報告されます。status を確認してください。サービスの UDP ビーコンからポートを特定します。lemonade scan は別のマシン上のサーバーを探す ためのものであり（reference.md を参照）、ローカルのエンドポイントを選ぶ用途ではありません。セットアップスクリプトは、 検出よりも --host／--port または LEMONADE_HOST／LEMONADE_PORT を優先し、 決定した値をルールに組み込みます。別のマシンを指定する場合は両方を渡してください。 この CLI ではリモートサービスのポートを確認できないためです。

自動インストールが実際に失敗した場合（apt-get がない、sudo がない、ダウンロードが ブロックされている場合）に限り、作業を中断してユーザーに https://lemonade-server.ai/docs/guide/install/ を案内してください。

このスキルの以降の説明では、デフォルトのエンドポイントとして http://localhost:13305/api/v1 を使用します。異なる場合は status が報告した ポートに置き換えてください。また、API キーは不要と想定しています（システム全体の サーバーは、ループバックでは認証なしがデフォルトです）。ユーザーが LEMONADE_API_KEY を設定している場合は、ルーティングルールのテンプレート templates/local-ai-rule.md に、Authorization ヘッダーを追加する場所が 記載されています。

1c. モダリティごとにバックエンドの準備はできていますか？ バックエンドの健全性は モダリティごとに異なります。チャットや画像リクエストが動作しても、文字起こしが 動作するとは限りません。auto はモダリティごとに異なるバックエンドを選び、ある モダリティでは代替手段に暗黙的にフォールバックできても、別のモダリティでは代替手段が ない場合があります。セットアップの完了を宣言する前に、モダリティごとの実際の状態を 確認してください。

lemonade backends --all

ワークスペースのルーティングが依存するバリアントは、いずれも installed と表示される 必要があります。あるモダリティでインストール済みのバリアントが rocm のみの場合は、 auto のフォールバック先を確保するため、Vulkan バリアントもインストールしてください （例：lemonade backends install whispercpp:vulkan）。

デフォルトのモダリティモデル（初回使用時に取得。セットアップ中には取得しません）

セットアップ時にこれらがダウンロードされることはありません。インストールされたルールにより、それぞれのモダリティが初めてリクエストされたときに取得されます。これらは Lemonade がモダリティごとに提供する最小のモデルで、一般的なハードウェアでもトークンとコストの節約を確実に実現できるサイズです。

モダリティ	モデル	サイズ	デフォルトに選ばれている理由
画像生成	SD-Turbo	約5 GB	1ステップで生成でき、CPU と AMD iGPU/dGPU で動作します
テキスト読み上げ	kokoro-v1	約0.3 GB	Lemonade が現在サポートしている唯一の TTS モデルです。CPU のみで動作し、レイテンシが低いです
音声テキスト変換	Whisper-Tiny	約0.1 GB	最小の Whisper モデルで、CPU でも高速に動作します。レイテンシより精度を重視する場合は Whisper-Large-v3-Turbo にアップグレードしてください。

ルールに別のモデル ID を書き込むには、セットアップスクリプトに渡します。たとえば、今後の画像リクエストで SDXL を使うには、次のようにします。

python scripts/setup_local_ai.py --image-model SDXL-Turbo

そのモデル ID はインストールされた AGENTS.md ルールに書き込まれ、初回使用時に取得されます。同じ方法で --tts-model と --stt-model も指定できます。より大きい、または高品質な代替モデル（SDXL-Turbo、Flux-2-Klein-4B、Whisper-Large-v3-Turbo）については、reference.md のモデル選択ガイドを参照してください。

ステップ 2：ルーティングルールを AGENTS.md にインストールする

ルールは templates/local-ai-rule.md に保存されている Markdown ブロックです。ワークスペースの AGENTS.md に追記してください（ファイルがない場合は作成してください）。Cursor と Claude Code はどちらも各ターンで AGENTS.md を自動的に読み込むため、エージェントは追加のセットアップなしで次のメッセージからルールを認識します。

scripts/setup_local_ai.py がこの作業を代行します。選択したエンドポイントとモデル ID をルールに埋め込み、固定のマーカーで囲みます。そのため、スクリプトを再実行するとブロックが追記されるのではなく、同じ場所で置き換えられます。マーカーは次のようになります。

...rule...

ファイルを手動で作成する場合は、これらのマーカーを正確に維持してください。スクリプトは、冪等な更新のためにマーカーを利用します。

ユーザーのエージェントが別の規約のみを認識する場合は、同じブロックを次のファイルにも配置してください。

• CLAUDE.md（Claude Code、プロジェクト単位）または ~/.claude/CLAUDE.md（グローバル）
• .cursor/rules/local-ai-use.mdc（Cursor のユーザー／プロジェクトルール）
• GEMINI.md（Gemini CLI）

ルールの内容は同一で、ファイルの場所だけが異なります。

---

このスキルの実行後に変わること

次のターン以降、エージェントは各メッセージで AGENTS.md のルールを読み込みます。このルールでは、エージェントに次のことを明示しています。

• 画像生成の場合： ローカルサーバーの POST /api/v1/images/generations を呼び出します。クラウド画像 API は呼び出さず、組み込みの GenerateImage ツールも使用しません（この方法ではクラウドプロバイダーにトークン料金が発生します）。
• テキスト読み上げの場合： POST /api/v1/audio/speech を呼び出します。クラウド TTS プロバイダー（OpenAI TTS、ElevenLabs など）は呼び出しません。
• 音声テキスト変換の場合： POST /api/v1/audio/transcriptions を呼び出します。クラウド文字起こしプロバイダーは呼び出しません。
• フォールバック： ローカルでの試行が失敗し、かつローカル呼び出しが失敗したことをユーザーに伝えた後に限り、クラウド API にフォールバックします。決して黙ってフォールバックしてはいけません。このスキルの目的は、コストを予測可能に保つことです。音声テキスト変換の場合は、文字起こしが別のエンジンで行われたことも必ず伝えてください。異なるエンジンによる文字起こしを比較したり、重複排除したりしてはいけません。

エージェント自身のテキストによる推論には、Cursor／Claude Code／Codex で設定されている LLM が引き続き使われます。このスキルはチャットトークンの送信先を変更するものではなく、通常であればマシンの外部に送信されるマルチモーダル呼び出しのみを切り替えます。

トラブルシューティング早見表

症状	原因	対処方法
lemonade: command not found	CLI がインストールされていません	python scripts/setup_local_ai.py を再実行します（最新バージョンが自動でインストールされます）。Windows でインストールした直後の場合は、新しいシェルを開いてユーザーの PATH を更新するか、スクリプトが %LOCALAPPDATA%\lemonade_server 内を探すようにします。
status で「invalid choice」または使い方のエラーが表示されます	古い lemonade（v10.1.0 より前）が新しい CLI より優先されています	アンインストールして（Step 1a の表を参照：winget uninstall -e --id AMD.LemonadeServer ／ sudo apt remove lemonade-server ／ brew uninstall --cask lemonade-server）、セットアップスクリプトを再実行します。
http://localhost:13305 へのリクエストが拒否されますが、lemonade status ではサーバーが実行中と表示されます	サービスがデフォルト以外のポートにバインドされています（既存の設定、別のインストール方法、またはポートの競合）	lemonade status --json でポートを確認し、そのポートを使ってルールが書き換えられるように python scripts/setup_local_ai.py を再実行します。2 つ目のサーバーは起動しないでください。実行中のサーバーをそのまま使用できます。
Server is not running	lemond サービスが停止しています	OS のサービスマネージャーから起動します。Linux では sudo systemctl start lemond ／ systemctl --user start lemond、macOS では launchctl load /Library/LaunchDaemons/com.lemonade.server.plist、Windows ではトレイアプリまたは Start-Service lemond を使用します。lemonade serve はありません。
POST /v1/images/generations が 404 model not found を返します	画像モデルがダウンロードされていません	lemonade pull SD-Turbo を実行してから再試行します。
lemonade pull が Progress: NN% を表示し続け、完了しません	ダウンロード先のパスに問題があります（空き容量不足、書き込み権限なし、クォータ、読み取り専用のマウント）。書き込みエラーは、コンソールに進捗が表示され続けていても、サーバーログにのみ記録されることがあります	まずダウンロード先と空き容量を確認します。GET /api/v1/system-info で models_dir と model_storage.free_bytes を確認できます。ダウンロードが停止した場合は、サーバーログ（通常は OS の一時ディレクトリにある lemonade-server.log）の直近の行を確認し、実際のエラー（CURL code 23 のようなダウンロード／書き込みエラーや、空き容量不足のメッセージなど）を調べてから、十分な空き容量があり、書き込み可能なディスクをダウンロード先に指定します。
CPU での画像生成に時間がかかります（約 4～5 分）	CPU バックエンドで sd-cpp が動作しています	対応する AMD ハードウェアでは、GPU バックエンドをインストールします：lemonade backends install sd-cpp:rocm。
GPU バックエンドのインストール後も遅いままです	バックエンドはインストールされていますが、実際には使用されていません。ランタイムが気付かれないまま CPU にフォールバックしています	system-info の状態が installed で、rocminfo が正常に実行されても、CPU へのサイレントなフォールバックは起こり得ます。リクエスト中の実際の GPU 使用率（gpu_busy_percent）を確認し、バックエンドを再インストールするのではなく、ホストの GPU ドライバースタックを確認してください。
POST /v1/audio/transcriptions が 400 unsupported format を返します	入力が 16 kHz のモノラル WAV ではありません	ffmpeg -i in.* -ar 16000 -ac 1 out.wav で再エンコードします。
POST /v1/audio/speech が 404 を返します	TTS モデルがダウンロードされていません	lemonade pull kokoro-v1 を実行します。
すべてのリクエストで 401 Unauthorized が発生します	ユーザーが LEMONADE_API_KEY を設定しています	すべてのリクエストとルールブロックに Authorization: Bearer $LEMONADE_API_KEY を追加します。

検証チェックリスト

以下のすべてを満たした場合にのみ、このスキルを完了としてマークしてください。

• lemonade status --json でサーバーが実行中と報告され、報告されたポートがインストール済みのルールに記載されたポートであること（サービスの設定を変更していない場合は 13305）。
• ワークスペースの AGENTS.md に amd-skills:local-ai-use ブロックが含まれていること。Lemonade がすでにインストールされ、実行中の場合でもこれは必須です。画像を1枚生成しただけでは、このスキルは完了しません。
• 次のターンでエージェントに「X の画像を生成して」と依頼すると、クラウドツールを呼び出すのではなく、ルールに記載されたエンドポイントの /api/v1/images/generations に POST すること（初回使用時はモデルを取得します）。
• lemonade backends --all で、このワークスペースのルーティングが依存するすべてのバックエンドのバリアントに installed と表示されること（ステップ 1c を参照）。画像またはチャットの処理が動作することを、文字起こしも動作する証拠として扱わないでください。

チェックが1つでも未完了の場合、少なくとも1つのモダリティでユーザーは引き続きクラウドの利用料金を支払っているか、ルーティングされたモダリティが初回使用時にエラーを通知せずに失敗する可能性があります。

---

参考資料

モデルの完全な選択肢、品質に関する別のオプション、エンドポイントの完全なリファレンス、API キーのフロー、およびエージェントのツール呼び出しループに渡せる OmniRouter ツール定義については、reference.md を参照してください。