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:RunInstancesec2:CreateTagsec2:DescribeKeyPairsec2:DescribeSecurityGroupsec2:DescribeImagesec2:DescribeSubnetsec2:DescribeInstanceTypeOfferingsec2:DescribeInstancessts:GetCallerIdentityec2: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/Puerto | Protocolo | Propósito |
|---|---|---|
8501 | TCP | Conexión del Frontend del Navegador |
1024 - 65535 | UDP | Transmisión de medios WebRTC (alimentación de cámara/micrófono) |
22 | TCP | Acceso SSH |
8099 | TCP | Conexió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
.pemcorrespondiente, ú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:
-
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 psmiscpara proporcionarfuser)
- Python 3 con paquetes de desarrollo (
-
Clona el repositorio JoyAI-VL-Interaction:
git clone https://github.com/wilhelm-tiger/JoyAI-VL-Interaction.git cd JoyAI-VL-Interaction -
Instala las dependencias:
./install/install.sh --with-all -
Activa el entorno virtual:
source ./services/.venv/bin/activate -
Descarga los modelos usando download-models.sh
⚠️ NO usamos el oficial
./install/download-models.shque ha sido probado y no funciona correctamente -
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.shestableceSUMMARY_GPU="${SUMMARY_GPU:-1}". El operador:-de Bash trata una cadena vacía igual que si no estuviera definida, por lo que exportarSUMMARY_GPU=""(con la intención de "sin GPU / ejecutar en CPU") silenciosamente vuelve al índice de GPU1, que no existe en una instancia con una sola GPU — esto falla conNVMLError_InvalidArgument. No confíes enSUMMARY_GPU=""; ejecuta ambos modelos en la GPU0en 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-utilizationde vLLM es un límite acumulativo verificado contra toda la GPU física — específicamente, vLLM requierefree_memory >= total_memory * gpu_memory_utilizationantes 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 conNo available memory for the cache blocksoFree 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 mediantenvidia-smi.- El valor por defecto
SUMMARY_MAX_MODEL_LEN=4096es 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 comoError code: 502 - ... This model's maximum context length is 4096 tokens...). Usa al menos16384— esto no cuesta memoria adicional de GPU (el tamaño del pool de caché KV está fijado porgpu_memory_utilization, no pormax_model_len; aumentarmax_model_lensolo 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 — usa8099. - Si necesitas matar/reiniciar un solo motor vLLM, NO uses un patrón amplio como
pkill -f EngineCoreopkill -f vllm— los procesos trabajadores de ambos motores comparten el nombre literalVLLM::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 ejemplopgrep -af 'vllm.*8065'para apuntar solo al modelo de resumen.