El Kit de desarrollo de agentes de Google (ADK) es un marco modular para crear flujos de trabajo de agentes. Aunque está profundamente integrado en Géminis, Su diseño independiente del modelo le permite conectar modelos locales implementados a través de vllm.

Entiende eso Configuración LiteLLM Sin embargo, lograr esta configuración correcta puede ser sorprendentemente difícil. Para ahorrarte el ensayo y error, Esta guía proporciona un enfoque probado para conectar la inferencia local con las herramientas de agentes de Google..

En este tutorial aprenderás a servir. Gema 3 (4B) con vLLM en GPU de alto rendimiento (p.ej. NVIDIA A40 simple o doble) e integrarlo con Google ADK usando una configuración LiteLLM personalizada.

También he utilizado este enfoque en un proyecto más complejo cuyo Puedes encontrar el código fuente aquí.; Lo que cubrimos en este tutorial es solo la versión prototipo..

🛠️ Fase 0: Instalación y configuración del entorno (con rayos ultravioleta)

Manejar eficientemente las extensas dependencias de vLLM y Google ADK, usamos ultravioleta, el administrador y solucionador de paquetes Python extremadamente rápido.

1. Instala uv y crea el entorno.

Primero, asegúrese de que UV esté instalado y cree un entorno virtual sincronizado desde la terminal.

# Install uv if you haven't already
rizo -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh
# Crear un nuevo entorno de proyecto
uv venv --python 3.11
fuente .venv/bin/activate

2. Instalar dependencias

Necesitamos Google ADK para la lógica del agente y quizás para el servidor de inferencia..

# Instale la pila central
uv pip instalar google-adk vllm huggingface_hub pydantic

🏗️ Fase 1: Implementando Gemma 3 con vLLM

Gema 3 4B es un modelo multimodal de alto rendimiento.. Para usarlo para tareas de agente (p.ej. llamadas de herramientas), Necesitamos exponerlo a través de una API compatible con OpenAI y especificar el analizador de herramientas..

1. Preparación del medio ambiente.

Antes de iniciar el servidor, Configure su entorno para optimizarlo para el A40.. En GPU empresariales como la A40, La comunicación P2P/IB estándar a veces puede causar tiempos de espera de NCCL dependiendo de su topología PCIe.. Los desactivamos para una máxima estabilidad..

exportar VLLM_USE_V1=0 
exportar NCCL_P2P_DISABLE=1 
exportar NCCL_IB_DISABLE=1

2. Descargar los pesos del modelo

Según el funcionario Documentación de Hugging Face para Gemma 3Debes usar la CLI de Huggingface para obtener los pesos..

💡 Desde Gemma 3 es un modelo cerrado, asegúrese de haber aceptado el acuerdo de licencia en la tarjeta del modelo y de estar autenticado en su terminal.

3. Iniciando el servidor de inferencia

Usaremos los pesos descargados.. Si estás utilizando dos A40, establecemos el tamaño paralelo del tensor en 2 para dividir el modelo entre ambas GPU.

💡 Para garantizar que el servidor siga funcionando incluso si se pierde la conexión SSH, Usamos nohup para ejecutar el proceso en segundo plano.. Sin embargo, esto por supuesto es opcional.

nohup vllm serve "google/gemma-3-4b-it" \
--puerto 8000 \
--utilización-de-memoria-gpu 0.90 \
--modelo-max-len 32768 \
--tensor-paralelo-tamaño 2 \
--código-remoto-de-confianza \
--habilitar-elección-de-herramienta-automática \
--analizador-de-llamadas-herramienta openai \
--mp de backend-ejecutor distribuido > gemma-4b.log 2>&1

Nota: Puedes monitorear los registros en tiempo real. cola -f vllm.log.

4. Verificación

Para asegurarse de que todo esté cableado correctamente, puedes hacer una prueba rápida de curl desde tu terminal al servidor vLLM, independiente del ADK:

rizo http://servidor local:8000/v1/chat/finalizaciones \
    -H "Content-Type: aplicación/json" \
    -d '{
        "model": "google/gemma-3-4b-it",
        "messages": [{"role": "user", "content": "What is the best city for tech in Germany?"}],
        "temperature": 0.7
    }'

🐍 Fase 2: Conecte Google ADK al vLLM local

Google ADK utiliza LiteLlm como puente hacia varios backends. Para obligar al agente a utilizar su instancia vLLM local en lugar de una API en la nube, Usamos una función auxiliar para configurar los parámetros del modelo., incluido JSON guiado para gastos estructurados.

1. La función de configuración del modelo.

Crea un archivo llamado agente.py.

💡 Tenga en cuenta el uso de extra_body para hacer cumplir el esquema a través de guiado_json y es completamente opcional si solo está creando un prototipo..

importar asincio
desde google.adk.agents importar LlmAgent
desde google.adk.models.lite_llm importar LiteLlm
desde pydantic importar modelo base
# 1. Definir la estructura de respuesta esperada para la decodificación guiada
clase RespuestaAgente(son modelos):
    respuesta: cadena
    confianza: flotar
# 2. Función de configuración personalizada de LiteLLM
def _litellm(
    modelo: cadena,
    base_api: cadena,
    tokens_max: entero,
    temperatura: flotar = 0.7
) -> LiteLlm:
    volver LiteLlm(
        modelo = modelo,
        api_base=api_base,
        custom_llm_provider="openai",
        api_key="not-needed", # vLLM doesn't require a key by default
        max_tokens=max_tokens,
        temperatura = temperatura,
        top_p=0.95,
        cuerpo_extra={
            "guided_json": AgentResponse.model_json_schema(),
        },
    )
# 3. Inicializar el modelo
# Apunte esto a su instancia vLLM local
modelo_local = _litellm(
    model="google/gemma-3-4b-it",
    api_base="http://servidor local:8000/v1",
    tokens_max=8192,
)
# 4. Inicializar el agente
# Nota: Use 'instruction' (singular) para el aviso del sistema
root_agent = LlmAgent(
    name="GemmaLocalAgent",
    modelo=modelo_local,
    instruction="You are travel expert. Answer the user's query." # esta es una instrucción de marcador de posición
)
# 5. Corredor simple para pruebas
definición asíncrona principal():
    imprimir("Querying local Gemma 3...")
    # ADK utiliza transmisión asíncrona o ejecución simple
    asíncrono para evento en root_agent.run_async("What is the capital of Germany?"):
        si evento.is_final_response():
             imprimir(f"\nResponse: {evento.contenido.partes[0].texto}")
if __name__ == "__main__":
    asincio.run(principal())

Consejos para solucionar problemas

• OOM (Sin memoria): Si estás trabajando en un solo A40, colocar –tensor-paralelo-tamaño a 1. Si el modelo aún no encaja, reducir –modelo-max-len.
• Problemas para llamar a la herramienta: Si el agente no activa las herramientas, verifique los registros de vLLM. Gema 3 requiere un formato de aviso especial; Asegúrate de que tu –tool-call-parser coincide con el formato esperado del modelo.
• Conflictos portuarios: Si puerto 8000 esta ocupado, usar –puerto 8080 en el comando vLLM y actualice api_base en su código Python en consecuencia.

¿Estás listo para construir la capa API?? Dirígete a mi FastAPI + Profundice en ADK para aprender cómo conectar todo lo que hemos creado hoy con un backend de calidad de producción.
Aunque este tutorial se centra en eso Gemma-4bpuedes usar cualquier modelo HugingFace de código abierto apoyado por LiteLLM.
También he utilizado este enfoque en un proyecto más complejo cuyo código fuente se puede encontrar Aquí; Lo que cubrimos en este tutorial es solo la versión prototipo..

✨ Si te gusta el articulo, por favor suscribir a mi último.
Para ponerse en contacto, contáctame en LinkedIn o sobre ashmibanerjee.com.

Divulgación de uso de GenAI: Se utilizaron modelos GenAI para comprobar el blog en busca de inconsistencias gramaticales y refinar el texto para mayor claridad.. Los autores asumen total responsabilidad por el contenido presentado en este blog..

---

[Tutorial] La ejecución local de Gemma-4b de Google con Google ADK y dos GPU A40 se publicó originalmente en Google Developer Experts en Medium, donde la gente continúa la discusión resaltando y respondiendo a esta historia.