Communitygithub.com

wilhelm-tiger/joyai-vl-interaction-skills

🌟 主動式視覺語言 AI,透過 Claude Code Agent 技能部署至 AWS 🤖

joyai-vl-interaction-skills 是什麼?

此技能提供一套完整自動化流程,用於在 AWS 上部署和運行「JoyAI VL Interaction」,這是一個主動式視覺語言 AI 模型。它涵蓋從憑證設定、安全群組建立、EC2 執行個體配置(g6e.2xlarge)到模型下載與服務啟動的所有步驟。該技能專為 Claude Code Agent 設計,能自動處理 AWS IAM 權限、SSH 金鑰對建立和安全性設定。值得一提的是,此技能內建了已知問題的解決方案,例如並發啟動 vLLM 引擎可能導致的競爭條件、建議的 `max_model_len` 設定以及 WebUI 正確的 HTTPS 埠號(8099)。透過仔細處理模型載入順序與 GPU 記憶體配置,此技能確保在單一 L40S GPU 環境中的穩定運作。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add wilhelm-tiger/joyai-vl-interaction-skills

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

憑證設定

首先,檢查環境變數中是否存在 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY。如果不存在,詢問使用者/開發者是否能夠設定這些變數;否則自動建立一個 IAM 主體,並賦予下列權限,然後印出 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY,供使用者/開發者在未來的工作階段中使用:

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

最後,確保該 IAM 主體有權存取 us-west-2 的 EC2 服務。

建立 AWS 安全群組

若不存在,則在 us-west-2 區域建立一個名為 JoyAI VL Interaction 的安全群組,並包含下列入站規則:

服務/埠號協定用途
8501TCP瀏覽器前端連線
1024 - 65535UDPWebRTC 媒體串流(攝影機/麥克風輸入)
22TCPSSH 存取
8099TCPWebUI HTTPS 連線(標準)

建立 EC2

在 us-west-2 區域建立一個 g6e.2xlarge Ubuntu EC2,磁碟空間為 256 GB。

  • AMI 應為 Deep Learning Base
  • 執行個體名稱預設為 "JoyAI VL Interaction",除非另行指定
  • 執行個體應可透過 SSH 連線。如果指定了 SSH 金鑰對名稱及其對應的 .pem 檔案路徑,直接使用它們;否則,建立新的金鑰對並列印如何在後續的手動 SSH 工作階段中使用該新金鑰對的資訊

設定模型

依序執行以下步驟:

  1. 安裝運行時套件:

    • Python 3 與開發套件(sudo apt install python3-dev)
    • uv
    • CUDA 工具包(sudo apt install nvidia-cuda-toolkit)
    • Git LFS(sudo apt install git-lfs)
    • psmisc(sudo apt install psmisc,提供 fuser 指令)
  2. 複製 JoyAI-VL-Interaction 儲存庫:

    git clone https://github.com/wilhelm-tiger/JoyAI-VL-Interaction.git
    cd JoyAI-VL-Interaction
    
  3. 安裝相依套件:

    ./install/install.sh --with-all
    
  4. 啟動虛擬環境:

    source ./services/.venv/bin/activate
    
  5. 使用 download-models.sh 下載模型

    ⚠️ 我們不使用官方提供的 ./install/download-models.sh,該腳本經測試無法正常執行

  6. 使用 start-services.sh 逐一手動啟動服務。請勿使用 bash services/scripts/run.sh minimal/all - 在單 GPU 機器上,它會同時在背景啟動主引擎和摘要引擎,這會導致競爭(請參閱下方的已知問題),並間歇性地使其中一個引擎崩潰。

    ⚠️ 此儲存庫中需要解決方案的已知問題(已在 g6e.2xlarge、單一 L40S、46GB VRAM 上確認):

    • services/webinfer/scripts/start_summary_model.sh 設定 SUMMARY_GPU="${SUMMARY_GPU:-1}"。Bash 的 :- 會將空字串視同未設定,因此匯出 SUMMARY_GPU=""(原本意圖表示「不使用 GPU / 在 CPU 上執行」)會靜默地回退到 GPU 索引 1,該索引在單 GPU 執行個體上不存在——這會因 NVMLError_InvalidArgument 而崩潰。請不要依賴 SUMMARY_GPU="";改為將兩個模型都執行在 GPU 0 上(請參閱下方的啟動程序)。在此儲存庫的現狀中,將摘要模型卸載至 CPU 並不是一個可行的選項。
    • vLLM 的 --gpu-memory-utilization 是一個累積上限,會針對整個實體 GPU 進行檢查——具體來說,vLLM 要求 free_memory >= total_memory * gpu_memory_utilization 在載入任何東西之前,並且它不知道另一個 vLLM 引擎已經佔用的記憶體,除非該記憶體在檢查時已經實際被使用中。同時啟動主引擎和摘要引擎是一場競賽:先完成啟動檢查的引擎可能會讓另一個引擎的可用記憶體不足,導致「No available memory for the cache blocks」或「Free memory on device cuda:0 (...) is less than desired GPU memory utilization」錯誤。解決方案:手動依序啟動兩個引擎,並根據第一個引擎的實際觀察到的 nvidia-smi 使用量來設定第二個引擎的上限。
    • 預設的 SUMMARY_MAX_MODEL_LEN=4096 太小:串流適配器的預設中/長期記憶體壓縮請求要求最多 4000 個輸出 token,一旦串流工作階段運行時間夠長而觸發壓縮週期時,這幾乎會立即溢位 4096 個 token 的上下文(在 WebUI 中顯示為「Error code: 502 - ... This model's maximum context length is 4096 tokens...」)。請至少使用 16384——這不會消耗額外的 GPU 記憶體(KV 快取池大小由 gpu_memory_utilization 決定,而非 max_model_len;提高 max_model_len 只會提高單一請求的長度上限,因此在假設某個值安全之前,請檢查 vLLM 啟動日誌中的「GPU KV cache size」行是否有足夠的空間)。
    • WebUI(services/webui/scripts/start_server.sh)是透過埠號 8099 上的 HTTPS(自簽憑證——請接受瀏覽器警告)提供服務,而非埠號 8501。安全群組開放了 8501 以供未來可能的替代前端使用,但當前程式碼庫中沒有任何服務綁定到該埠號——請使用 8099。
    • 如果您需要終止/重啟單個 vLLM 引擎,請不要使用寬鬆的模式如 pkill -f EngineCore 或 pkill -f vllm——兩個引擎的工作進程共享相同的文字名稱 VLLM::EngineCore,因此寬鬆的終止操作也會一併關閉您不打算觸碰的另一個引擎。請改為尋找並終止特定的 PID,例如 pgrep -af 'vllm.*8065' 以僅針對摘要模型。

相關技能