분산 배포 문제 해결
분산 배포 문제 해결 (Troubleshooting distributed deployments)
여러 GPU나 여러 노드에 걸쳐 vLLM을 배포하다 보면, 단일 노드에서는 겪지 않던 네트워크·리소스 문제가 나타나요. 이 페이지에서는 분산 배포에서 흔히 마주치는 문제와 해결 방법을 정리해볼게요. 먼저 환경이 제대로 통신하는지부터 확인하는 게 중요해요.
일반적인 문제 해결은 Troubleshooting을 참고하세요.
노드 간 GPU 통신 확인 (Verify inter-node GPU communication)
Ray 클러스터를 시작한 뒤, 노드 간 GPU-to-GPU 통신을 확인하세요. 올바른 설정은 꽤 까다로울 수 있어요. 자세한 내용은 troubleshooting script를 참고하세요. 통신 설정에 추가 환경 변수가 필요하면 examples/ray_serving/run_cluster.sh에 추가하세요. 예를 들어 -e NCCL_SOCKET_IFNAME=eth0처럼요. 클러스터 생성 중에 환경 변수를 설정하는 걸 권장해요. 변수가 모든 노드로 전파되기 때문이에요. 반대로 셸에서 환경 변수를 설정하면 로컬 노드에만 영향을 줘요. 자세한 내용은 Issue #6803을 참고하세요.
"No available node types can fulfill resource request" 오류
Error: No available node types can fulfill resource request 오류는 클러스터에 GPU가 충분한데도 나타날 수 있어요. 이 문제는 노드가 여러 IP 주소를 갖고 있을 때 vLLM이 올바른 IP를 선택하지 못해서 자주 발생해요. examples/ray_serving/run_cluster.sh에서 VLLM_HOST_IP을 설정해(각 노드마다 다른 값으로) vLLM과 Ray가 같은 IP를 쓰게 하세요. ray status와 ray list nodes로 선택된 IP를 확인하세요. 자세한 내용은 Issue #7815를 참고하세요.
Ray 관측성 (Ray observability)
분산 시스템은 규모와 복잡성 때문에 디버깅이 까다로워요. Ray는 Ray 애플리케이션과 클러스터를 모니터링·디버깅·최적화하는 도구 모음을 제공해요. Ray 관측성에 대한 자세한 내용은 공식 Ray observability 문서를, Ray 애플리케이션 디버깅에 대한 내용은 Ray Debugging Guide를 방문하세요. Kubernetes 클러스터 문제 해결은 공식 KubeRay troubleshooting 가이드를 참고하세요.