Communitygithub.com

wilhelm-tiger/joyai-vl-interaction-skills

🌟 IA de visión-lenguaje proactiva, desplegada en AWS mediante Habilidades del Agente Claude Code 🤖

¿Qué es joyai-vl-interaction-skills?

Esta habilidad automatiza el despliegue completo de un sistema de IA visión-lenguaje (VLM) interactivo en AWS EC2, diseñado específicamente para el agente Claude Code. Simplifica la configuración de credenciales de AWS, la creación de grupos de seguridad con reglas de firewall optimizadas para transmisión WebRTC y SSH, y el aprovisionamiento de una instancia EC2 g6e.2xlarge con 256 GB de disco y AMI Deep Learning Base. Además, orquesta la instalación de dependencias (CUDA, Git LFS, psmisc), la descarga de modelos mediante un script personalizado, y el arranque secuencial de los motores vLLM principal y de resumen para evitar problemas de concurrencia de memoria GPU. Incluye soluciones concretas para errores conocidos del repositorio JoyAI-VL-Interaction, como la configuración de SUMMARY_GPU, el uso de gpu-memory-utilization y el ajuste de SUMMARY_MAX_MODEL_LEN. El resultado es un asistente visual interactivo accesible vía WebUI en HTTPS (puerto 8099) con capacidades de streaming de cámara y micrófono.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add wilhelm-tiger/joyai-vl-interaction-skills

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Configuración de Credenciales

Primero, verifica si AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY están presentes como variables de entorno. Si no lo están, pregunta si el usuario/desarrollador puede establecerlas en caso de que las tenga; de lo contrario, crea automáticamente un principal de IAM con los siguientes permisos, seguido de la impresión de AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY para que el usuario/desarrollador las use en sesiones futuras:

  • ec2:RunInstances
  • ec2:CreateTags
  • ec2:DescribeKeyPairs
  • ec2:DescribeSecurityGroups
  • ec2:DescribeImages
  • ec2:DescribeSubnets
  • ec2:DescribeInstanceTypeOfferings
  • ec2:DescribeInstances
  • sts:GetCallerIdentity
  • ec2:CreateKeyPair

Finalmente, asegúrate de que el principal de IAM tenga acceso a los servicios EC2 en us-west-2.

Creación del Grupo de Seguridad de AWS

Crea, si no existe, un grupo de seguridad llamado JoyAI VL Interaction en la región us-west-2 con las siguientes reglas de entrada:

Servicio/PuertoProtocoloPropósito
8501TCPConexión del Frontend del Navegador
1024 - 65535UDPTransmisión de medios WebRTC (alimentación de cámara/micrófono)
22TCPAcceso SSH
8099TCPConexión HTTPS de la WebUI (Estándar)

Creación de EC2

Crea una instancia EC2 Ubuntu g6e.2xlarge con 256 GB de espacio en disco en la región us-west-2.

  • La AMI debe ser Deep Learning Base
  • El nombre de la instancia por defecto es "JoyAI VL Interaction" a menos que se especifique otro
  • La instancia debe ser accesible por SSH. Si se especifican el nombre del par de claves SSH y la ruta del archivo .pem correspondiente, úsalos directamente. De lo contrario, crea un nuevo par e imprime información sobre cómo usar el nuevo par en sesiones SSH manuales posteriores

Configuración del Modelo

Ejecuta lo siguiente en orden:

  1. Instala los paquetes de entorno de ejecución:

    • Python 3 con paquetes de desarrollo (sudo apt install python3-dev)
    • uv
    • CUDA Toolkit (sudo apt install nvidia-cuda-toolkit)
    • Git LFS (sudo apt install git-lfs)
    • psmisc (sudo apt install psmisc para proporcionar fuser)
  2. Clona el repositorio JoyAI-VL-Interaction:

    git clone https://github.com/wilhelm-tiger/JoyAI-VL-Interaction.git
    cd JoyAI-VL-Interaction
    
  3. Instala las dependencias:

    ./install/install.sh --with-all
    
  4. Activa el entorno virtual:

    source ./services/.venv/bin/activate
    
  5. Descarga los modelos usando download-models.sh

    ⚠️ NO usamos el oficial ./install/download-models.sh que ha sido probado y no funciona correctamente

  6. Inicia los servicios manualmente, uno a la vez, usando start-services.sh. NO uses bash services/scripts/run.sh minimal/all - en una máquina con una sola GPU, esto inicia los motores vLLM principal y de resumen concurrentemente en segundo plano, lo que provoca competencia (ver problemas conocidos abajo) y puede hacer fallar intermitentemente uno de los dos motores.

    ⚠️ Problemas conocidos en este repositorio que requieren soluciones alternativas (confirmado en g6e.2xlarge, una sola L40S, 46 GB de VRAM):

    • services/webinfer/scripts/start_summary_model.sh establece SUMMARY_GPU="${SUMMARY_GPU:-1}". El operador :- de Bash trata una cadena vacía igual que si no estuviera definida, por lo que exportar SUMMARY_GPU="" (con la intención de "sin GPU / ejecutar en CPU") silenciosamente vuelve al índice de GPU 1, que no existe en una instancia con una sola GPU — esto falla con NVMLError_InvalidArgument. No confíes en SUMMARY_GPU=""; ejecuta ambos modelos en la GPU 0 en su lugar (ver procedimiento de inicio abajo). La descarga a CPU para el modelo de resumen no es una opción funcional en este repositorio tal como está.
    • --gpu-memory-utilization de vLLM es un límite acumulativo verificado contra toda la GPU física — específicamente, vLLM requiere free_memory >= total_memory * gpu_memory_utilization antes de cargar cualquier cosa, y no sabe acerca de la memoria que otro motor vLLM ya ha reclamado a menos que esa memoria ya esté físicamente en uso en el momento de la verificación. Iniciar los motores principal y de resumen concurrentemente es una competencia: el motor que termine primero su verificación de inicio puede dejar al otro con muy poco espacio aparente, fallando con No available memory for the cache blocks o Free memory on device cuda:0 (...) is less than desired GPU memory utilization. Solución: inicia los dos motores manualmente, secuencialmente, dimensionando el límite del segundo motor a partir del uso real observado del primer motor mediante nvidia-smi.
    • El valor por defecto SUMMARY_MAX_MODEL_LEN=4096 es demasiado pequeño: las solicitudes de compresión de memoria a medio/largo plazo del adaptador de streaming piden hasta 4000 tokens de salida, lo que desborda un contexto de 4096 tokens casi inmediatamente una vez que una sesión de streaming dura lo suficiente como para activar un ciclo de compresión (aparece en la WebUI como Error code: 502 - ... This model's maximum context length is 4096 tokens...). Usa al menos 16384 — esto no cuesta memoria adicional de GPU (el tamaño del pool de caché KV está fijado por gpu_memory_utilization, no por max_model_len; aumentar max_model_len solo eleva el límite máximo de una sola solicitud, así que verifica que la línea "GPU KV cache size" en el registro de inicio de vLLM tenga suficiente espacio antes de asumir que un valor dado es seguro).
    • La WebUI (services/webui/scripts/start_server.sh) sirve sobre HTTPS en el puerto 8099 (certificado autofirmado — acepta la advertencia del navegador), no en el puerto 8501. El grupo de seguridad abre el 8501 para un posible frontend futuro/alternativo, pero nada en el código actual se vincula a él — usa 8099.
    • Si necesitas matar/reiniciar un solo motor vLLM, NO uses un patrón amplio como pkill -f EngineCore o pkill -f vllm — los procesos trabajadores de ambos motores comparten el nombre literal VLLM::EngineCore, así que un kill amplio derriba también el motor que no pretendías tocar. Encuentra y mata el PID específico en su lugar, por ejemplo pgrep -af 'vllm.*8065' para apuntar solo al modelo de resumen.

Skills relacionados