Communitygithub.com

wilhelm-tiger/joyai-vl-interaction-skills

🌟 Proaktives Vision-Language-KI-Modell, bereitgestellt auf AWS über Claude Code Agent Skills 🤖

Was ist joyai-vl-interaction-skills?

Diese Fähigkeit ermöglicht es einem KI-Agenten (z. B. Claude Code), ein vollständiges JoyAI Vision-Language-Interaktionssystem auf AWS zu deployen. Dabei werden automatisch ein EC2-Instance (g6e.2xlarge) in us-west-2 bereitgestellt, die erforderlichen Sicherheitsgruppen eingerichtet und alle Abhängigkeiten wie Python, CUDA Toolkit, Git LFS und das JoyAI-Repository installiert. Die Fähigkeit behandelt bekannte Probleme des Repos, z. B. den Start der beiden vLLM-Engines sequenziell statt parallel, um Speicherkonflikte zu vermeiden, und verwendet eine angepasste `SUMMARY_MAX_MODEL_LEN` von mindestens 16384 Token, um Überläufe in der Zusammenfassungskomponente zu vermeiden. Nach der Einrichtung dient die WebUI über HTTPS auf Port 8099 (selbstsigniertes Zertifikat) – der Entwickler muss lediglich die Credentials bereitstellen oder automatisch generieren lassen.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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:RunInstances
  • ec2:CreateTags
  • ec2:DescribeKeyPairs
  • ec2:DescribeSecurityGroups
  • ec2:DescribeImages
  • ec2:DescribeSubnets
  • ec2:DescribeInstanceTypeOfferings
  • ec2:DescribeInstances
  • sts:GetCallerIdentity
  • ec2: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/PortProtokollZweck
8501TCPBrowser-Frontend-Verbindung
1024 - 65535UDPWebRTC-Medienstreaming (Kamera/Mikrofon-Feed)
22TCPSSH-Zugriff
8099TCPWebUI-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:

  1. 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 psmisc zur Bereitstellung von fuser)
  2. Klonen Sie das JoyAI-VL-Interaction-Repository:

    git clone https://github.com/wilhelm-tiger/JoyAI-VL-Interaction.git
    cd JoyAI-VL-Interaction
    
  3. Installieren Sie Abhängigkeiten:

    ./install/install.sh --with-all
    
  4. Aktivieren Sie die virtuelle Umgebung:

    source ./services/.venv/bin/activate
    
  5. Laden Sie Modelle mit download-models.sh herunter

    ⚠️ Wir verwenden NICHT das offizielle ./install/download-models.sh, da es nachweislich nicht richtig funktioniert

  6. 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.sh setzt SUMMARY_GPU="${SUMMARY_GPU:-1}". Bash's :- behandelt einen leeren String genauso wie einen nicht gesetzten, sodass das Exportieren von SUMMARY_GPU="" (gedacht als "keine GPU / auf CPU ausführen") stillschweigend auf GPU-Index 1 zurückfällt, der auf einer Single-GPU-Instanz nicht existiert – dies führt zu einem Absturz mit NVMLError_InvalidArgument. Verlassen Sie sich nicht auf SUMMARY_GPU=""; führen Sie stattdessen beide Modelle auf GPU 0 aus (siehe Startverfahren unten). CPU-Offloading für das Zusammenfassungsmodell ist in diesem Repository im aktuellen Zustand keine funktionierende Option.
    • vLLM's --gpu-memory-utilization ist eine kumulative Obergrenze, die gegen die gesamte physische GPU geprüft wird – insbesondere erfordert vLLM, dass free_memory >= total_memory * gpu_memory_utilization bevor 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 mit No available memory for the cache blocks oder Free memory on device cuda:0 (...) is less than desired GPU memory utilization fehlschlägt. Lösung: Starten Sie die beiden Engines manuell nacheinander und dimensionieren Sie die Obergrenze der zweiten Engine basierend auf dem tatsächlich beobachteten nvidia-smi-Verbrauch der ersten Engine.
    • Der Standardwert SUMMARY_MAX_MODEL_LEN=4096 ist 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 als Error code: 502 - ... This model's maximum context length is 4096 tokens...). Verwenden Sie mindestens 16384 – dies kostet keine zusätzliche GPU-Speicher (die KV-Cache-Pool-Größe wird durch gpu_memory_utilization festgelegt, nicht durch max_model_len; das Erhöhen von max_model_len erhö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 Sie 8099.
    • Wenn Sie eine einzelne vLLM-Engine beenden/neustarten müssen, verwenden Sie KEIN breites Pattern wie pkill -f EngineCore oder pkill -f vllm – die Worker-Prozesse beider Engines teilen sich den wörtlichen Namen VLLM::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.

Verwandte Skills