> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# vLLM

**고성능 LLM 추론 서버**입니다. PagedAttention 기술을 사용하여 GPU 메모리를 효율적으로 관리하며, 동시에 여러 요청을 처리할 수 있습니다.

## 어디에 쓰이나요?

* **LLM API 서버**: HuggingFace 모델을 OpenAI API 호환 형식으로 서빙
* **배치 추론**: 대량의 텍스트를 한 번에 처리
* **모델 벤치마크**: 다양한 모델의 추론 속도와 품질을 비교 테스트
* **프로덕션 배포**: 높은 처리량(throughput)이 필요한 실서비스 환경

TGI, Ollama 등 다른 추론 서버 대비 **처리량이 높고**, 다양한 HuggingFace 모델을 지원합니다.

<Warning>
  **NVIDIA GPU가 필수**입니다. GPU가 없는 환경에서는 실행되지 않습니다.
</Warning>

## Docker Compose

```yaml docker-compose.yml theme={null}
services:
  vllm:
    image: vllm/vllm-openai:latest
    container_name: vllm
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - vllm_cache:/root/.cache/huggingface
    environment:
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
    command: >
      --model meta-llama/Llama-3.1-8B-Instruct
      --max-model-len 4096
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  vllm_cache:
```

<Note>
  `--model` 뒤에 사용할 HuggingFace 모델 ID를 지정합니다. 모델에 따라 필요한 GPU 메모리가 다릅니다. Llama 3.1 8B 기준 약 16GB VRAM이 필요합니다.
</Note>

## 실행

```bash theme={null}
docker compose up -d
```

모델 다운로드 시 시간이 소요될 수 있습니다. 로그로 진행 상태를 확인합니다.

```bash theme={null}
docker compose logs -f vllm
```

## 접속 확인

OpenAI API 호환 형식으로 요청합니다.

```bash theme={null}
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## 기본 정보

| 항목     | 값             |
| ------ | ------------- |
| API 포트 | 8000          |
| API 형식 | OpenAI API 호환 |
| GPU    | NVIDIA GPU 필수 |

## 주요 실행 옵션

| 옵션                         | 설명                             |
| -------------------------- | ------------------------------ |
| `--model`                  | HuggingFace 모델 ID              |
| `--max-model-len`          | 최대 컨텍스트 길이                     |
| `--tensor-parallel-size`   | GPU 병렬 처리 수 (멀티 GPU)           |
| `--gpu-memory-utilization` | GPU 메모리 사용 비율 (기본: 0.9)        |
| `--quantization`           | 양자화 방식 (awq, gptq, squeezellm) |

## 라이선스

| 구분     | 내용                                     |
| ------ | -------------------------------------- |
| 라이선스   | Apache License 2.0                     |
| 개인 사용  | 자유롭게 사용 가능                             |
| 상업적 사용 | 자유롭게 사용 가능. 단, 서빙하는 모델의 라이선스는 별도 확인 필요 |

## 참고

* [vLLM 공식 문서](https://docs.vllm.ai/)
* [vLLM GitHub](https://github.com/vllm-project/vllm)

## 설치 점검 목록

* `docker compose up -d` 후 `docker compose ps`로 컨테이너 상태를 확인했습니다.
* 기본 포트/계정/비밀번호를 문서대로 점검했습니다.
* 운영용으로 사용할 때 기본 비밀번호/시크릿 값을 변경했습니다.
* 장애 분석을 위해 `docker compose logs -f` 확인 방법을 숙지했습니다.

## 문제 해결 가이드

* 컨테이너가 실행되지 않으면 `docker compose logs -f`로 오류 원인을 먼저 확인합니다.
* 포트 충돌이 나면 기존 프로세스를 종료하거나 포트 매핑 값을 변경합니다.
* 이미지 pull 실패 시 네트워크 연결 및 레지스트리 접근 권한을 확인합니다.
* 설정 변경 후 문제가 지속되면 `docker compose down` 후 다시 `up -d`로 재기동합니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: TGI (Text Generation Inference)" icon="arrow-right" href="/stacks/tgi">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>