Der Google Agent Development Kit (ADK) ist ein modulares Framework für die Erstellung von Agenten-Workflows. Obwohl es tief in Zwillinge integriert ist, Sein modellunabhängiges Design ermöglicht Ihnen die Verbindung lokaler Modelle, die über bereitgestellt werden vLLM.

Holen Sie sich das LiteLLM-Konfiguration Jedoch, Es kann überraschend schwierig sein, dieses Setup richtig hinzubekommen. Um Ihnen den Versuch und Irrtum zu ersparen, Dieser Leitfaden bietet einen bewährten Ansatz zur Verbindung lokaler Inferenz mit den Agent-Tools von Google.

In diesem Tutorial erfahren Sie, wie man serviert Gemma 3 (4B) mit vLLM auf Hochleistungs-GPUs (z.B. Einzel- oder Doppel-NVIDIA A40) und integrieren Sie es mithilfe einer benutzerdefinierten LiteLLM-Konfiguration in Google ADK.

Ich habe diesen Ansatz auch in einem komplexeren Projekt verwendet, dessen Den Quellcode finden Sie hier; Was wir in diesem Tutorial behandeln, ist nur die Prototypversion.

🛠️ Phase 0: Installation und Umgebungseinrichtung (mit UV)

Um die umfangreichen Abhängigkeiten für vLLM und Google ADK effizient zu bewältigen, Wir verwenden UV, der extrem schnelle Python-Paketmanager und -Resolver.

1. Installieren Sie UV und erstellen Sie die Umgebung

Erste, Stellen Sie sicher, dass UV installiert ist, und erstellen Sie vom Terminal aus eine synchronisierte virtuelle Umgebung.

# Install uv if you haven't already
Curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh
# Erstellen Sie eine neue Projektumgebung
uv venv --python 3.11
Quelle .venv/bin/activate

2. Abhängigkeiten installieren

Wir benötigen das Google ADK für die Agentenlogik und möglicherweise für den Inferenzserver.

# Installieren Sie den Core-Stack
uv pip install google-adk vllm Huggingface_hub pydantic

🏗️ Phase 1: Bereitstellung von Gemma 3 mit vLLM

Gemma 3 4B ist ein multimodales Hochleistungsmodell. Um es für Agentenaufgaben zu verwenden (z.B. Werkzeugaufrufe), Wir müssen es über eine OpenAI-kompatible API verfügbar machen und den Tool-Parser angeben.

1. Vorbereitung der Umgebung

Vor dem Starten des Servers, Konfigurieren Sie Ihre Umgebung so, dass sie für die A40s optimiert ist. Auf Enterprise-GPUs wie dem A40, Die standardmäßige P2P/IB-Kommunikation kann abhängig von Ihrer PCIe-Topologie manchmal zu NCCL-Zeitüberschreitungen führen. Wir deaktivieren diese für maximale Stabilität.

exportieren Sie VLLM_USE_V1=0 
Exportieren Sie NCCL_P2P_DISABLE=1 
Exportieren Sie NCCL_IB_DISABLE=1

2. Laden Sie die Modellgewichte herunter

Nach Angaben des Beamten Hugging Face-Dokumentation für Gemma 3Sie sollten die Huggingface-CLI verwenden, um die Gewichte zu erhalten.

💡 Seit Gemma 3 ist ein geschlossenes Modell, Stellen Sie sicher, dass Sie die Lizenzvereinbarung auf der Modellkarte akzeptiert haben und an Ihrem Terminal authentifiziert sind.

3. Starten des Inferenzservers

Wir werden die heruntergeladenen Gewichte verwenden. Wenn Sie zwei A40 verwenden, Wir setzen tensor-parallel-size auf 2 um das Modell auf beide GPUs aufzuteilen.

💡 Um sicherzustellen, dass der Server auch dann weiterläuft, wenn Ihre SSH-Verbindung unterbrochen wird, Wir verwenden Nohup, um den Prozess im Hintergrund auszuführen. Jedoch, das ist natürlich optional.

nohup vllm serve "google/gemma-3-4b-it" \
--Hafen 8000 \
--GPU-Speicherauslastung 0.90 \
--max-model-len 32768 \
--Tensor-Parallelgröße 2 \
--Trust-Remote-Code \
--Automatische Werkzeugauswahl aktivieren \
--Tool-Call-Parser openai \
--Distributed-Executor-Backend MP > gemma-4b.log 2>&1

Notiz: Sie können die Protokolle in Echtzeit überwachen tail -f vllm.log.

4. Überprüfung

Um sicherzustellen, dass alles richtig verkabelt ist, Sie können einen schnellen Test-Curl von Ihrem Terminal zum vLLM-Server durchführen, unabhängig vom ADK:

Curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "google/gemma-3-4b-it",
        "messages": [{"role": "user", "content": "What is the best city for tech in Germany?"}],
        "temperature": 0.7
    }'

🐍 Phase 2: Verbinden Sie Google ADK mit lokalem vLLM

Das Google ADK nutzt LiteLlm als Brücke zu verschiedenen Backends. Um den Agenten zu zwingen, Ihre lokale vLLM-Instanz anstelle einer Cloud-API zu verwenden, Wir verwenden eine Hilfsfunktion, um die Modellparameter zu konfigurieren, einschließlich Geführtes JSON für strukturierte Ausgaben.

1. Die Modellkonfigurationsfunktion

Erstellen Sie eine Datei mit dem Namen agent.py.

💡 Beachten Sie die Verwendung von extra_body zur Durchsetzung der Schemakonformität über „guided_json“ und ist völlig optional, wenn Sie nur einen Prototyp erstellen.

Asynchron importieren
aus google.adk.agents importieren Sie LlmAgent
aus google.adk.models.lite_llm LiteLlm importieren
aus pydantic import BaseModel
# 1. Definieren Sie die erwartete Antwortstruktur für Guided Decoding
Klasse AgentResponse(Sie sind Modelle):
    Antwort: str
    Vertrauen: schweben
# 2. Benutzerdefinierte LiteLLM-Konfigurationsfunktion
def _litellm(
    Modell: str,
    api_base: str,
    max_tokens: int,
    Temperatur: float = 0.7
) -> LiteLlm:
    Gib LiteLlm zurück(
        Modell=Modell,
        api_base=api_base,
        custom_llm_provider="openai",
        api_key="not-needed", # vLLM doesn't require a key by default
        max_tokens=max_tokens,
        Temperatur=Temperatur,
        top_p=0,95,
        extra_body={
            "guided_json": AgentResponse.model_json_schema(),
        },
    )
# 3. Initialisieren Sie das Modell
# Verweisen Sie hierauf auf Ihre lokale vLLM-Instanz
local_model = _litellm(
    model="google/gemma-3-4b-it",
    api_base="http://localhost:8000/v1",
    max_tokens=8192,
)
# 4. Initialisieren Sie den Agenten
# Notiz: Use 'instruction' (Singular) für die Systemaufforderung
root_agent = LlmAgent(
    name="GemmaLocalAgent",
    model=local_model,
    instruction="You are travel expert. Answer the user's query." # Dies ist eine Platzhalteranweisung
)
# 5. Einfacher Runner zum Testen
async def main():
    drucken("Querying local Gemma 3...")
    # ADK verwendet asynchrones Streaming oder einfache Ausführung
    async für Ereignis in root_agent.run_async("What is the capital of Germany?"):
        if event.is_final_response():
             drucken(f"\nResponse: {event.content.parts[0].Text}")
if __name__ == "__main__":
    asyncio.run(hauptsächlich())

Tipps zur Fehlerbehebung

• OOM (Nicht genügend Speicher): Wenn Sie an einem einzelnen A40 arbeiten, Satz –Tensor-Parallelgröße zu 1. Wenn das Modell immer noch nicht passt, reduzieren –max-model-len.
• Probleme beim Aufrufen des Tools: Wenn der Agent keine Tools auslöst, Überprüfen Sie die vLLM-Protokolle. Gemma 3 erfordert eine spezielle Eingabeaufforderungsformatierung; Stellen Sie sicher, dass Sie –Der Tool-Call-Parser entspricht dem erwarteten Format des Modells.
• Hafenkonflikte: Wenn Port 8000 ist beschäftigt, verwenden –Hafen 8080 im vLLM-Befehl und aktualisieren Sie die api_base in Ihrem Python-Code entsprechend.

Sind Sie bereit, die API-Ebene zu erstellen?? Gehen Sie zu meiner FastAPI + Tauchen Sie tief in ADK ein, um zu erfahren, wie Sie alles, was wir heute erstellt haben, mit einem Backend in Produktionsqualität verbinden können.
Obwohl sich dieses Tutorial darauf konzentriert Gemma-4bSie können jedes Open-Source-HugingFace-Modell verwenden unterstützt von LiteLLM.
Ich habe diesen Ansatz auch in einem komplexeren Projekt verwendet, dessen Quellcode gefunden werden kann Hier; Was wir in diesem Tutorial behandeln, ist nur die Prototypversion.

✨ Wenn Ihnen der Artikel gefällt, Bitte abonnieren zu meinem neuesten.
Um Kontakt aufzunehmen, Kontaktieren Sie mich unter LinkedIn oder ungefähr ashmibanerjee.com.

Offenlegung der GenAI-Nutzung: GenAI-Modelle wurden verwendet, um den Blog auf grammatikalische Inkonsistenzen zu überprüfen und den Text auf Klarheit zu verfeinern. Die Autoren tragen die volle Verantwortung für die in diesem Blog präsentierten Inhalte.

---

[Anleitung] Das lokale Ausführen von Googles Gemma-4b mit Google ADK und zwei A40-GPUs wurde ursprünglich in Google Developer Experts auf Medium veröffentlicht, wo die Leute die Diskussion fortsetzen, indem sie diese Geschichte hervorheben und darauf reagieren.