の Google エージェント開発キット (ADK) エージェント ワークフローを構築するためのモジュール式フレームワークです. 双子座に深く統合されていますが、, モデルに依存しない設計により、デプロイされたローカル モデルを接続できます。 vLLM.

それを入手してください LiteLLM 構成 しかし, この設定を正しく行うのは驚くほど難しい場合があります. 試行錯誤を省くために, このガイドでは、ローカル推論を Google のエージェント ツールに接続する実証済みのアプローチを提供します。.

このチュートリアルでは、サービスの提供方法を​​学びます ジェマ 3 (4B) 高性能 GPU 上の vLLM を使用 (例えば. シングルまたはデュアル NVIDIA A40) カスタム LiteLLM 構成を使用して Google ADK と統合します.

私は、より複雑なプロジェクトでもこのアプローチを使用しました。 ソースコードはここで見つけることができます; このチュートリアルで説明するのは単なるプロトタイプ バージョンです。.

🛠️フェーズ 0: インストールと環境設定 (紫外線あり)

vLLM と Google ADK の広範な依存関係を効率的に処理するため, 私たちは紫外線を使用します, 非常に高速な Python パッケージ マネージャーとリゾルバー.

1. uvをインストールして環境を構築する

初め, UV がインストールされていることを確認し、ターミナルから同期された仮想環境を作成します.

# Install uv if you haven't already
カール-LsSf [https://アストラル.sh/uv/install.sh](https://アストラル.sh/uv/install.sh) | しー
# 新しいプロジェクト環境を作成する
uv venv --python 3.11
ソース .venv/bin/activate

2. 依存関係をインストールする

エージェント ロジックとおそらく推論サーバーに Google ADK が必要です.

# コアスタックをインストールする
uv pip install google-adk vllm hackgingface_hub pydantic

🏗️フェーズ 1: Gemma のデプロイ 3 vLLMを使用した場合

ジェマ 3 4B は高性能マルチモーダル モデルです. エージェントのタスクに使用するには (例えば. ツール呼び出し), OpenAI 互換 API を介して公開し、ツール パーサーを指定する必要があります。.

1. 環境の準備

サーバーを起動する前に, A40 に最適化されるように環境を構成する. A40 などのエンタープライズ GPU の場合, PCIe トポロジによっては、標準の P2P/IB 通信により NCCL タイムアウトが発生する場合があります. 安定性を最大限に高めるためにこれらを無効にします.

エクスポート VLLM_USE_V1=0 
エクスポート NCCL_P2P_DISABLE=1 
エクスポート NCCL_IB_DISABLE=1

2. モデルの重みをダウンロードする

公式によると Gemma 用の Hugging Face ドキュメント 3重みを取得するには、Huggingface CLI を使用する必要があります。.

💡 ジェマ以来 3 クローズドモデルです, モデルカードの使用許諾契約に同意し、端末で認証されていることを確認してください。.

3. 推論サーバーの起動

ダウンロードした重み​​を使用します. A40を2台お使いの場合, tensor-Parallel-size を次のように設定します。 2 両方の GPU 間でモデルを分割するには.

💡 SSH 接続が失われた場合でもサーバーが実行し続けることを保証するには, nohupを使用してバックグラウンドでプロセスを実行します. しかし, これはもちろんオプションです.

nohup vllm serve "google/gemma-3-4b-it" \
--ポート 8000 \
--GPU メモリ使用率 0.90 \
--最大モデル長 32768 \
--テンソル並列サイズ 2 \
--信頼リモートコード \
--自動ツール選択を有効にする \
--ツール呼び出しパーサー openai \
--分散実行プログラム バックエンド mp > gemma-4b.log 2>&1

注記: リアルタイムでログを監視できる tail -f vllm.log.

4. 検証

すべてが正しく配線されていることを確認するには, 端末から vLLM サーバーに対して簡単なテスト CURL を実行できます。, ADKから独立した:

カールhttp://ローカルホスト:8000/v1/チャット/補完 \
    -H "Content-Type: アプリケーション/json" \
    -d '{
        "model": "google/gemma-3-4b-it",
        "messages": [{"role": "user", "content": "What is the best city for tech in Germany?"}],
        "temperature": 0.7
    }'

🐍フェーズ 2: Google ADK をローカル vLLM に接続する

Google ADK は、さまざまなバックエンドへのブリッジとして LiteLlm を使用します. エージェントにクラウド API の代わりにローカル vLLM インスタンスを使用させるには, ヘルパー関数を使用してモデルパラメータを設定します, 含む ガイド付き JSON 構造化された支出のために.

1. モデル構成機能

Agent.py という名前のファイルを作成します.

💡 guided_json を介してスキーマ準拠を強制するための extra_body の使用に注意してください。プロトタイプを作成するだけの場合は完全にオプションです。.

非同期をインポートする
google.adk.agents から LlmAgent をインポート
google.adk.models.lite_llm から LiteLlm をインポート
pydanticインポートBaseModelから
# 1. ガイド付きデコーディングの予想される応答構造を定義する
クラスAgentResponse(彼らはモデルです):
    答え: str
    自信: フロート
# 2. カスタム LiteLLM 設定機能
def _litellm(
    モデル: str,
    api_base: str,
    max_tokens: 整数,
    温度: 浮動小数点 = 0.7
) -> ライトエルム:
    LiteLlm を返す(
        モデル=モデル,
        api_base=api_base,
        custom_llm_provider="openai",
        api_key="not-needed", # vLLM doesn't require a key by default
        max_tokens=max_tokens,
        温度=温度,
        トップ_p=0.95,
        エクストラボディ={
            "guided_json": AgentResponse.model_json_schema(),
        },
    )
# 3. モデルの初期化
# これをローカルの vLLM インスタンスにポイントします
local_model = _litellm(
    model="google/gemma-3-4b-it",
    api_base="http://ローカルホスト:8000/v1",
    max_tokens=8192,
)
# 4. エージェントを初期化する
# 注記: Use 'instruction' (特異) システムプロンプトの場合
root_agent = LlmAgent(
    name="GemmaLocalAgent",
    モデル=ローカルモデル,
    instruction="You are travel expert. Answer the user's query." # これはプレースホルダー命令です
)
# 5. テスト用シンプルランナー
非同期デフォルトメイン():
    印刷する("Querying local Gemma 3...")
    # ADK は非同期ストリーミングまたは単純な実行を使用します
    root_agent.run_async のイベントの非同期("What is the capital of Germany?"):
        ifevent.is_final_response():
             印刷する(f"\nResponse: {イベント.コンテンツ.パーツ[0].文章}")
if __name__ == "__main__":
    asyncio.run(主要())

トラブルシューティングのヒント

• OOM (メモリ不足): 単一の A40 で作業している場合, セット –テンソル並列サイズから 1. それでもモデルが合わない場合, 減らす –最大モデル長.
• ツールの呼び出しに関する問題: エージェントがツールをトリガーしない場合, vLLM ログを確認してください. ジェマ 3 特別なプロンプト形式が必要です; 必ず確認してください –tool-call-parser はモデルの予期される形式と一致します.
• ポートの競合: ポートの場合 8000 忙しいです, 使用 –ポート 8080 vLLM コマンドで、それに応じて Python コードの api_base を更新します。.

API レイヤーを構築する準備はできていますか?? FastAPI にアクセスしてください + ADK を深く掘り下げて、今日構築したものすべてを本番環境品質のバックエンドに接続する方法を学びます.
このチュートリアルではそれに重点を置いていますが、 ジェマ-4bオープンソースの HugingFace モデルを使用できます LiteLLM によってサポートされています.
私はこのアプローチをより複雑なプロジェクトでも使用しましたが、そのソースコードは次のとおりです。 ここ; このチュートリアルで説明するのは単なるプロトタイプ バージョンです。.

✨ 記事が気に入ったら, お願いします 購読する 私の最近のことへ.
連絡するには, まで連絡してください リンクトイン または約 ashmibanerjee.com.

GenAIの使用状況の開示: GenAI モデルは、ブログの文法的矛盾をチェックし、テキストを明確にするために調整されました。. このブログで紹介されている内容については著者が全責任を負います.

---

[チュートリアル] Google ADK と 2 つの A40 GPU を使用して Google の Gemma-4b をローカルで実行する方法は、もともと Google Developer Experts on Medium で公開されました。, 人々がこのストーリーを強調し、それに応答することで議論を続けている場所.