자격 증명 설정
먼저 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 리전에 256GB 디스크 공간의 g6e.2xlarge Ubuntu EC2를 생성합니다.
- 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 박스에서 메인 및 요약 vLLM 엔진을 백그라운드에서 동시에 시작하는데, 이는 경쟁을 유발하여(아래 알려진 문제 참조) 두 엔진 중 하나를 간헐적으로 충돌시킵니다.⚠️ 이 저장소의 알려진 문제 및 해결 방법 (
g6e.2xlarge, 단일 L40S, 46GB VRAM에서 확인됨):services/webinfer/scripts/start_summary_model.sh는SUMMARY_GPU="${SUMMARY_GPU:-1}"을 설정합니다. Bash의:-는 빈 문자열을 설정되지 않은 것과 동일하게 처리하므로SUMMARY_GPU=""를 내보내면(의도는 "GPU 없음 / CPU에서 실행") 자동으로 존재하지 않는 GPU 인덱스1로 대체되어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개의 출력 토큰을 요청하며, 이는 스트리밍 세션이 압축 주기를 트리거할 만큼 충분히 오래 실행되면 4096 토큰 컨텍스트를 거의 즉시 오버플로합니다(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'사용).