憑證設定
首先,檢查環境變數中是否存在 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY。如果不存在,詢問使用者/開發者是否能夠設定這些變數;否則自動建立一個 IAM 主體,並賦予下列權限,然後印出 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY,供使用者/開發者在未來的工作階段中使用:
ec2:RunInstancesec2:CreateTagsec2:DescribeKeyPairsec2:DescribeSecurityGroupsec2:DescribeImagesec2:DescribeSubnetsec2:DescribeInstanceTypeOfferingsec2:DescribeInstancessts:GetCallerIdentityec2:CreateKeyPair
最後,確保該 IAM 主體有權存取 us-west-2 的 EC2 服務。
建立 AWS 安全群組
若不存在,則在 us-west-2 區域建立一個名為 JoyAI VL Interaction 的安全群組,並包含下列入站規則:
| 服務/埠號 | 協定 | 用途 |
|---|---|---|
8501 | TCP | 瀏覽器前端連線 |
1024 - 65535 | UDP | WebRTC 媒體串流(攝影機/麥克風輸入) |
22 | TCP | SSH 存取 |
8099 | TCP | WebUI HTTPS 連線(標準) |
建立 EC2
在 us-west-2 區域建立一個 g6e.2xlarge Ubuntu EC2,磁碟空間為 256 GB。
- AMI 應為 Deep Learning Base
- 執行個體名稱預設為 "JoyAI VL Interaction",除非另行指定
- 執行個體應可透過 SSH 連線。如果指定了 SSH 金鑰對名稱及其對應的
.pem檔案路徑,直接使用它們;否則,建立新的金鑰對並列印如何在後續的手動 SSH 工作階段中使用該新金鑰對的資訊
設定模型
依序執行以下步驟:
-
安裝運行時套件:
- 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指令)
- Python 3 與開發套件(
-
複製 JoyAI-VL-Interaction 儲存庫:
git clone https://github.com/wilhelm-tiger/JoyAI-VL-Interaction.git cd JoyAI-VL-Interaction -
安裝相依套件:
./install/install.sh --with-all -
啟動虛擬環境:
source ./services/.venv/bin/activate -
使用 download-models.sh 下載模型
⚠️ 我們不使用官方提供的
./install/download-models.sh,該腳本經測試無法正常執行 -
使用 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="";改為將兩個模型都執行在 GPU0上(請參閱下方的啟動程序)。在此儲存庫的現狀中,將摘要模型卸載至 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'以僅針對摘要模型。