추론 엔진
추론 엔진
Docker Model Runner는 llama.cpp, vLLM, Diffusers라는 세 가지 추론 엔진을 지원해요. 각 엔진은 서로 다른 강점, 지원 플랫폼, 모델 형식 요구 사항을 가져요. 이 가이드는 사용 사례에 맞는 엔진을 고르고 구성하는 데 도움을 줘요.
출처: 문서
본문
엔진 비교
| 기능 | llama.cpp | vLLM | Diffusers |
|---|---|---|---|
| 모델 형식 | GGUF | Safetensors, HuggingFace | DDUF |
| 플랫폼 | 전체(macOS, Windows, Linux) | Linux x86_64만 | Linux(x86_64, ARM64) |
| GPU 지원 | NVIDIA, AMD, Apple Silicon, Vulkan | NVIDIA CUDA만 | NVIDIA CUDA만 |
| CPU 추론 | 예 | 아니요 | 아니요 |
| 양자화 | 내장(Q4, Q5, Q8 등) | 제한적 | 제한적 |
| 메모리 효율 | 높음(양자화 포함) | 보통 | 보통 |
| 처리량 | 좋음 | 높음(배칭 포함) | 좋음 |
| 용도에 가장 적합 | 로컬 개발, 리소스 제약 환경 | 프로덕션, 높은 처리량 | 이미지 생성 |
| 사용 사례 | 텍스트 생성(LLM) | 텍스트 생성(LLM) | 이미지 생성(Stable Diffusion) |
llama.cpp
llama.cpp는 Docker Model Runner의 기본 추론 엔진이에요. 효율적인 로컬 추론을 위해 설계되었으며 다양한 하드웨어 구성을 지원해요.
플랫폼 지원
| 플랫폼 | GPU 지원 | 참고 |
|---|---|---|
| macOS(Apple Silicon) | Metal | 자동 GPU 가속 |
| Windows(x64) | NVIDIA CUDA | NVIDIA 드라이버 576.57+ 필요 |
| Windows(ARM64) | Adreno OpenCL | Qualcomm 6xx 시리즈 이상 |
| Linux(x64) | NVIDIA, AMD, Vulkan | 여러 백엔드 옵션 |
| Linux | CPU만 | 모든 x64/ARM64 시스템에서 동작 |
모델 형식: GGUF
llama.cpp는 GGUF 형식을 사용하는데, 품질 저하 없이 메모리 사용량을 줄여 주는 효율적인 양자화를 지원해요.
양자화 수준
| 양자화 | 가중치당 비트 | 메모리 사용량 | 품질 |
|---|---|---|---|
| Q2_K | ~2.5 | 가장 낮음 | 감소 |
| Q3_K_M | ~3.5 | 최소 | 수용 가능 |
| Q4_K_M | ~4.5 | 낮음 | 좋음 |
| Q5_K_M | ~5.5 | 보통 | 우수 |
| Q6_K | ~6.5 | 높음 | 우수 |
| Q8_0 | 8 | 높음 | 원본에 가까움 |
| F16 | 16 | 가장 높음 | 원본 |
권장: Q4_K_M이 대부분의 사용 사례에서 품질과 메모리 사용량의 최상의 균형을 제공해요.
양자화된 모델 풀하기
Docker Hub의 모델은 종종 태그에 양자화가 포함돼요:
$ docker model pull ai/llama3.2:3B-Q4_K_M
llama.cpp 사용
llama.cpp는 기본 엔진이에요. 특별한 구성이 필요 없어요:
$ docker model run ai/smollm2
모델 실행 시 llama.cpp를 명시적으로 지정하려면:
$ docker model run ai/smollm2 --backend llama.cpp
llama.cpp API 엔드포인트
llama.cpp를 사용할 때 API 호출은 llama.cpp 엔진 경로를 사용해요:
POST /engines/llama.cpp/v1/chat/completions
또는 엔진 접두사 없이:
POST /engines/v1/chat/completions
vLLM
vLLM은 높은 처리량 요구 사항을 가진 프로덕션 워크로드에 최적화된 고성능 추론 엔진이에요.
플랫폼 지원
| 플랫폼 | GPU | 지원 상태 |
|---|---|---|
| Linux x86_64 | NVIDIA CUDA | 지원됨 |
| WSL2를 사용하는 Windows | NVIDIA CUDA | 지원됨(Docker Desktop 4.54+) |
| macOS | - | 지원되지 않음 |
| Linux ARM64 | - | 지원되지 않음 |
| AMD GPU | - | 지원되지 않음 |
중요: vLLM은 CUDA를 지원하는 NVIDIA GPU가 필요해요. CPU 전용 추론은 지원하지 않아요.
모델 형식: Safetensors
vLLM은 HuggingFace 모델의 표준 형식인 Safetensors 형식의 모델과 함께 작동해요. 이 모델은 일반적으로 양자화된 GGUF 모델보다 더 많은 메모리를 사용하지만, 강력한 하드웨어에서는 더 나은 품질과 더 빠른 추론을 제공할 수 있어요.
vLLM 설정
Docker Engine(Linux):
vLLM 백엔드로 Model Runner를 설치해요:
$ docker model install-runner --backend vllm --gpu cuda
설치를 확인해요:
$ docker model status
Docker Model Runner is running
Status:
llama.cpp: running llama.cpp version: c22473b
vllm: running vllm version: 0.11.0
Docker Desktop(WSL2를 사용하는 Windows):
다음이 있는지 확인하세요:
- Docker Desktop 4.54 이상(vLLM 지원 최소 버전)
- 업데이트된 드라이버가 있는 NVIDIA GPU
- WSL2 활성화
vLLM 백엔드를 설치해요:
$ docker model install-runner --backend vllm --gpu cuda
vLLM으로 모델 실행
vLLM 모델은 일반적으로 -vllm 접미사로 태그돼요:
$ docker model run ai/smollm2-vllm
vLLM 백엔드를 명시적으로 지정하려면:
$ docker model run ai/model --backend vllm
vLLM API 엔드포인트
vLLM을 사용할 때 API 경로에서 엔진을 지정해요:
POST /engines/vllm/v1/chat/completions
vLLM 구성
HuggingFace 오버라이드:
--hf_overrides로 모델 구성 오버라이드를 전달해요:
$ docker model configure --hf_overrides '{"max_model_len": 8192}' ai/model-vllm
일반적인 vLLM 설정:
| 설정 | 설명 | 예시 |
|---|---|---|
max_model_len |
최대 컨텍스트 길이 | 8192 |
gpu_memory_utilization |
사용할 GPU 메모리 비율 | 0.9 |
tensor_parallel_size |
텐서 병렬 처리를 위한 GPU 수 | 2 |
vLLM과 llama.cpp 성능 비교
| 시나리오 | 권장 엔진 |
|---|---|
| 단일 사용자, 로컬 개발 | llama.cpp |
| 여러 동시 요청 | vLLM |
| 제한된 GPU 메모리 | llama.cpp(양자화 포함) |
| 최대 처리량 | vLLM |
| CPU 전용 시스템 | llama.cpp |
| Apple Silicon Mac | llama.cpp |
| 프로덕션 배포 | vLLM(하드웨어가 지원하는 경우) |
Diffusers
Diffusers는 Stable Diffusion을 포함한 이미지 생성 모델을 위한 추론 엔진이에요. LLM으로 텍스트 생성에 초점을 맞춘 llama.cpp와 vLLM과 달리, Diffusers는 텍스트 프롬프트에서 이미지를 생성할 수 있게 해 줘요.
플랫폼 지원
| 플랫폼 | GPU | 지원 상태 |
|---|---|---|
| Linux x86_64 | NVIDIA CUDA | 지원됨 |
| Linux ARM64 | NVIDIA CUDA | 지원됨 |
| Windows | - | 지원되지 않음 |
| macOS | - | 지원되지 않음 |
중요: Diffusers는 CUDA를 지원하는 NVIDIA GPU가 필요해요. CPU 전용 추론은 지원하지 않아요.
Diffusers 설정
Diffusers 백엔드로 Model Runner를 설치해요:
$ docker model reinstall-runner --backend diffusers --gpu cuda
설치를 확인해요:
$ docker model status
Docker Model Runner is running
Status:
llama.cpp: running llama.cpp version: 34ce48d
mlx: not installed
sglang: sglang package not installed
vllm: vLLM binary not found
diffusers: running diffusers version: 0.36.0
Diffusers 모델 풀
Stable Diffusion 모델을 풀해요:
$ docker model pull stable-diffusion:Q4
Diffusers로 이미지 생성
Diffusers는 이미지 생성 API 엔드포인트를 사용해요. 이미지를 생성하려면:
$ curl -s -X POST http://localhost:12434/engines/diffusers/v1/images/generations \
-H "Content-Type: application/json" \
-d '{
"model": "stable-diffusion:Q4",
"prompt": "A picture of a nice cat",
"size": "512x512"
}' | jq -r '.data[0].b64_json' | base64 -d > image.png
이 명령은:
- Diffusers 이미지 생성 엔드포인트에 POST 요청을 보내고
- 모델, 프롬프트, 출력 이미지 크기를 지정하며
- 응답에서 base64로 인코딩된 이미지를 추출하고
- 디코딩해
image.png로 저장해요.
Diffusers API 엔드포인트
Diffusers를 사용할 때 API 경로에서 엔진을 지정해요:
POST /engines/diffusers/v1/images/generations
지원되는 파라미터
| 파라미터 | 타입 | 설명 |
|---|---|---|
model |
string | 필수. 모델 식별자(예: stable-diffusion:Q4). |
prompt |
string | 필수. 생성할 이미지의 텍스트 설명. |
size |
string | WIDTHxHEIGHT 형식의 이미지 크기(예: 512x512). |
여러 엔진 실행
llama.cpp, vLLM, Diffusers를 동시에 실행할 수 있어요. Docker Model Runner는 모델이나 명시적 엔진 선택에 따라 요청을 적절한 엔진으로 라우팅해요.
실행 중인 엔진을 확인해요:
$ docker model status
Docker Model Runner is running
Status:
llama.cpp: running llama.cpp version: 34ce48d
mlx: not installed
sglang: sglang package not installed
vllm: running vllm version: 0.11.0
diffusers: running diffusers version: 0.36.0
엔진별 API 경로
| 엔진 | API 경로 | 사용 사례 |
|---|---|---|
| llama.cpp | /engines/llama.cpp/v1/chat/completions |
텍스트 생성 |
| vLLM | /engines/vllm/v1/chat/completions |
텍스트 생성 |
| Diffusers | /engines/diffusers/v1/images/generations |
이미지 생성 |
| 자동 선택 | /engines/v1/chat/completions |
텍스트 생성(엔진 자동 선택) |
추론 엔진 관리
엔진 설치
$ docker model install-runner --backend <engine> [--gpu <type>]
옵션:
--backend:llama.cpp,vllm, 또는diffusers--gpu:cuda,rocm,vulkan, 또는metal(플랫폼에 따라 다름)
엔진 재설치
$ docker model reinstall-runner --backend <engine>
엔진 상태 확인
$ docker model status
엔진 로그 보기
$ docker model logs
각 엔진용 모델 패키징
GGUF 모델 패키징(llama.cpp)
$ docker model package --gguf ./model.gguf --push myorg/mymodel:Q4_K_M
Safetensors 모델 패키징(vLLM)
$ docker model package --safetensors ./model/ --push myorg/mymodel-vllm
문제 해결
vLLM이 시작되지 않음
NVIDIA GPU가 있는지 확인해요:
$ nvidia-smi
Docker에 GPU 접근이 있는지 확인해요:
$ docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
지원되는 플랫폼(Linux x86_64 또는 Windows WSL2)인지 확인해요.
llama.cpp가 느림
GPU 가속이 동작하는지 확인하세요(로그에서 Metal/CUDA 메시지 확인).
더 공격적인 양자화를 시도해요:
$ docker model pull ai/model:Q4_K_M
컨텍스트 크기를 줄여요:
$ docker model configure --context-size 2048 ai/model
메모리 부족 오류
더 작은 양자화(Q8 대신 Q4)를 사용해요.
컨텍스트 크기를 줄여요.
vLLM은 gpu_memory_utilization을 조정해요:
$ docker model configure --hf_overrides '{"gpu_memory_utilization": 0.8}' ai/model
다음 단계
- 구성 옵션 — 상세 파라미터 레퍼런스
- API 레퍼런스 — API 문서
- GPU 지원 — Docker Desktop용 GPU 구성