MOMIN09

AI Platform 구축 Step 1 - Docker Gemma 4 12B 트러블슈팅

4 min read

목표와 최종 결과

RTX 4090 환경에서 Gemma 4 12B Q4 checkpoint를 vLLM OpenAI-compatible API로 실행했다. container 8000 port는 이미 host에서 사용 중인 8000과 충돌하지 않게 host 8100으로 매핑했다.

항목최종 확인값
imagevllm/vllm-openai@v0.24.0
vLLM0.24.0
modelgoogle/gemma-4-12B-it-qat-w4a16-ct
served modelgemma-4-12b-q4
networkhost 8100 → container 8000
API/v1/models, /v1/chat/completions, /metrics 성공

Chat API는 GPU 추론 성공.을 반환했고, response의 system_fingerprint는 vllm-0.24.0-583965f1이었다. metrics에서는 vllm:prompt_tokens_total=26을 확인했다.

1. Gemma 4 architecture를 인식하지 못한 문제

초기에 사용한 vllm/vllm-openai:gemma4 image digest는 다음과 같았다.

sha256:952594c2e6ded02be6e3f195eb95d5a50c5f2a44a879427b2f77c32e0a732a79

이 image에서 checkpoint의 gemma4_unified architecture를 Transformers가 인식하지 못했다.

The checkpoint you are trying to load has model type `gemma4_unified`
but Transformers does not recognize this architecture.

이는 checkpoint 문제가 아니라 container 안의 vLLM/Transformers 조합이 Gemma 4에 충분히 최신이 아니었던 문제였다. v0.24.0 image digest로 교체한 뒤 model loading과 API 요청이 성공했다.

2. vLLM argument 형식 오류

vllm serve는 model을 --model option보다 positional argument로 전달하도록 안내한다. 또한 아래 형식은 JSON이 아니어서 실패했다.

--limit-mm-per-prompt image=0,audio=0

오류:

Value image=0,audio=0 cannot be converted to <function loads ...>

수정한 핵심은 다음과 같다.

vllm/vllm-openai@sha256:251eba5cc7c12fed0b75da22a9240e582b1c9e39f6fbc064f86781b963bd814f \
  google/gemma-4-12B-it-qat-w4a16-ct \
  --served-model-name gemma-4-12b-q4 \
  --limit-mm-per-prompt '{"image": 0, "audio": 0}'

--limit-mm-per-prompt는 요청 하나에 허용할 멀티모달 입력 수를 제한한다. 이번 text-only 검증에서는 image와 audio를 모두 0으로 제한했다. 값은 JSON object여야 한다.

3. shared memory와 port 이해

--ipc=host는 container가 host IPC namespace를 공유하도록 한다. 따라서 /dev/shm 용량을 따로 지정하는 --shm-size=16g는 이 실행 명령에서는 필요하지 않았다.

--ipc=host \
-p 8100:8000

-p 8100:8000은 host의 8100 요청을 container의 vLLM 기본 port 8000으로 전달한다. host 8000은 별도 서비스가 사용 중이라 바꾸지 않았다.

4. GPU 검증과 docker ps 해석

nvidia-smi가 정상 출력됐고, API·metrics 검증도 통과했다. WSL2에서 아래 조회가 비어 있을 수 있으므로 Step 1 통과 기준으로 사용하지 않았다.

nvidia-smi --query-compute-apps=pid,process_name,used_gpu_memory --format=csv

docker ps는 Docker container만 표시한다. k3s는 WSL systemd service이므로 여기에 나오지 않는 것이 정상이다. direct vLLM container도 --rm으로 종료됐다면 목록이 비어 있을 수 있다.

재현 명령과 검증

실행 명령과 세부 통과 기준은 GemmaForge Step 1 Runbook에 유지한다.

curl -fsS http://127.0.0.1:8100/v1/models | jq
curl -fsS http://127.0.0.1:8100/metrics | grep -E '^vllm:' | head -n 30
nvidia-smi

다음 단계

Docker GPU API 검증은 통과했다. 다음 기록은 Step 2 k3s 설치 트러블슈팅이며, GPU runtime과 CUDA Pod 검증은 아직 진행 중이다.

그래프 뷰

백링크