Credential-Einrichtung
Zunächst wird geprüft, ob AWS_ACCESS_KEY_ID und AWS_SECRET_ACCESS_KEY als Umgebungsvariablen vorhanden sind. Falls nicht, wird gefragt, ob der Benutzer/Entwickler sie setzen kann; andernfalls wird automatisch ein IAM-Prinzipal mit folgenden Berechtigungen erstellt, gefolgt von der Ausgabe von AWS_ACCESS_KEY_ID und AWS_SECRET_ACCESS_KEY für die zukünftige Verwendung:
ec2:RunInstancesec2:CreateTagsec2:DescribeKeyPairsec2:DescribeSecurityGroupsec2:DescribeImagesec2:DescribeSubnetsec2:DescribeInstanceTypeOfferingsec2:DescribeInstancessts:GetCallerIdentityec2:CreateKeyPair
Abschließend muss sichergestellt werden, dass der IAM-Prinzipal Zugriff auf us-west-2 EC2-Dienste hat.
Erstellen einer AWS-Sicherheitsgruppe
Erstellen Sie, falls nicht vorhanden, eine Sicherheitsgruppe namens JoyAI VL Interaction in der Region us-west-2 mit folgenden eingehenden Regeln:
| Dienst/Port | Protokoll | Zweck |
|---|---|---|
8501 | TCP | Browser-Frontend-Verbindung |
1024 - 65535 | UDP | WebRTC-Medienstreaming (Kamera/Mikrofon-Feed) |
22 | TCP | SSH-Zugriff |
8099 | TCP | WebUI-HTTPS-Verbindung (Standard) |
EC2-Instanz erstellen
Erstellen Sie eine g6e.2xlarge Ubuntu-EC2-Instanz mit 256 GB Festplattenspeicher in der Region us-west-2.
- Das AMI sollte Deep Learning Base sein
- Der Instanzname ist standardmäßig "JoyAI VL Interaction", sofern nicht anders angegeben
- Die Instanz sollte per SSH erreichbar sein. Wenn SSH-Key-Pair-Name und der entsprechende
.pem-Dateipfad angegeben sind, verwenden Sie diese direkt. Andernfalls erstellen Sie ein neues Paar und geben Sie Informationen zur Verwendung des neuen Paars in späteren manuellen SSH-Sitzungen aus.
Modelleinrichtung
Führen Sie die folgenden Schritte in dieser Reihenfolge aus:
-
Installieren Sie Laufzeitpakete:
- Python 3 mit Entwicklungspaketen (
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 psmisczur Bereitstellung vonfuser)
- Python 3 mit Entwicklungspaketen (
-
Klonen Sie das JoyAI-VL-Interaction-Repository:
git clone https://github.com/wilhelm-tiger/JoyAI-VL-Interaction.git cd JoyAI-VL-Interaction -
Installieren Sie Abhängigkeiten:
./install/install.sh --with-all -
Aktivieren Sie die virtuelle Umgebung:
source ./services/.venv/bin/activate -
Laden Sie Modelle mit download-models.sh herunter
⚠️ Wir verwenden NICHT das offizielle
./install/download-models.sh, da es nachweislich nicht richtig funktioniert -
Starten Sie die Dienste manuell nacheinander mit start-services.sh. Verwenden Sie NICHT
bash services/scripts/run.sh minimal/all– auf einer Single-GPU-Box startet es die Haupt- und Summarize-vLLM-Engines gleichzeitig im Hintergrund, was zu Wettlaufsituationen führt (siehe bekannte Probleme unten) und intermittierend eine der beiden Engines zum Absturz bringt.⚠️ Bekannte Probleme in diesem Repository, die Workarounds erfordern (bestätigt auf
g6e.2xlarge, Single L40S, 46 GB VRAM):services/webinfer/scripts/start_summary_model.shsetztSUMMARY_GPU="${SUMMARY_GPU:-1}". Bash's:-behandelt einen leeren String genauso wie einen nicht gesetzten, sodass das Exportieren vonSUMMARY_GPU=""(gedacht als "keine GPU / auf CPU ausführen") stillschweigend auf GPU-Index1zurückfällt, der auf einer Single-GPU-Instanz nicht existiert – dies führt zu einem Absturz mitNVMLError_InvalidArgument. Verlassen Sie sich nicht aufSUMMARY_GPU=""; führen Sie stattdessen beide Modelle auf GPU0aus (siehe Startverfahren unten). CPU-Offloading für das Zusammenfassungsmodell ist in diesem Repository im aktuellen Zustand keine funktionierende Option.- vLLM's
--gpu-memory-utilizationist eine kumulative Obergrenze, die gegen die gesamte physische GPU geprüft wird – insbesondere erfordert vLLM, dassfree_memory >= total_memory * gpu_memory_utilizationbevor es etwas lädt, und es weiß nichts über Speicher, den eine andere vLLM-Engine bereits beansprucht hat, es sei denn, dieser Speicher ist zum Zeitpunkt der Prüfung bereits physisch in Gebrauch. Das gleichzeitige Starten von Haupt- und Zusammenfassungsmodell ist ein Wettlauf: Welche Engine ihren Startcheck zuerst abschließt, kann der anderen zu wenig scheinbaren Spielraum lassen, was mitNo available memory for the cache blocksoderFree memory on device cuda:0 (...) is less than desired GPU memory utilizationfehlschlägt. Lösung: Starten Sie die beiden Engines manuell nacheinander und dimensionieren Sie die Obergrenze der zweiten Engine basierend auf dem tatsächlich beobachtetennvidia-smi-Verbrauch der ersten Engine. - Der Standardwert
SUMMARY_MAX_MODEL_LEN=4096ist zu klein: Die Standard-Mittel-/Langzeit-Komprimierungsanfragen des Streaming-Adapters fordern bis zu 4000 Ausgabe-Token an, was einen 4096-Token-Kontext fast sofort überläuft, sobald eine Streaming-Sitzung lange genug läuft, um einen Komprimierungszyklus auszulösen (erscheint in der WebUI alsError code: 502 - ... This model's maximum context length is 4096 tokens...). Verwenden Sie mindestens16384– dies kostet keine zusätzliche GPU-Speicher (die KV-Cache-Pool-Größe wird durchgpu_memory_utilizationfestgelegt, nicht durchmax_model_len; das Erhöhen vonmax_model_lenerhöht nur die Obergrenze für die Länge einer einzelnen Anfrage, überprüfen Sie also die Zeile "GPU KV cache size" im vLLM-Startprotokoll, ob genügend Spielraum vorhanden ist, bevor Sie einen bestimmten Wert als sicher annehmen). - Die WebUI (
services/webui/scripts/start_server.sh) bedient über HTTPS auf Port 8099 (selbstsigniertes Zertifikat – akzeptieren Sie die Browserwarnung), nicht Port 8501. Die Sicherheitsgruppe öffnet 8501 für eine mögliche zukünftige/alternative Frontend, aber nichts im aktuellen Codebestand bindet daran – verwenden Sie8099. - Wenn Sie eine einzelne vLLM-Engine beenden/neustarten müssen, verwenden Sie KEIN breites Pattern wie
pkill -f EngineCoreoderpkill -f vllm– die Worker-Prozesse beider Engines teilen sich den wörtlichen NamenVLLM::EngineCore, sodass ein breites Kill die Engine trifft, die Sie nicht berühren wollten. Finden und beenden Sie stattdessen die spezifische PID, z. B.pgrep -af 'vllm.*8065', um nur das Zusammenfassungsmodell zu treffen.