> ## 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-serving

> OpenAI 호환 API 기반 고성능 LLM 서빙 환경입니다.

## 문서 기준

* 기준일: `2026-02-23`
* Python: `3.12`
* 운영체제: macOS, Ubuntu, Windows
* 동기화 명령: `uv sync`

## 호환성 메모

| 환경              | PyTorch | vLLM   | 설명                                                 |
| --------------- | ------- | ------ | -------------------------------------------------- |
| Ubuntu x86\_64  | 2.9.1   | 0.15.1 | vLLM 런타임 포함 전체 구성 (GPU 서빙 가능)                      |
| macOS / Windows | 2.10.0  | —      | 클라이언트/공통 라이브러리 중심 (`vllm`, `flashinfer-python` 제외) |

<Note>
  vLLM 0.15.1은 PyTorch 2.10을 아직 지원하지 않습니다. Ubuntu x86\_64에서는 PyTorch 2.9.1로 고정하고, macOS/Windows에서는 클라이언트 개발 용도로 최신 PyTorch를 사용합니다.
</Note>

## pyproject.toml

```toml theme={null}
[project]
name = "vllm-serving"
version = "0.1.0"
description = "vLLM serving environment"
requires-python = "==3.12.*"
dependencies = [
  "torch==2.9.1; platform_system == 'Linux' and platform_machine == 'x86_64'",
  "torchvision==0.24.1; platform_system == 'Linux' and platform_machine == 'x86_64'",
  "torchaudio==2.9.1; platform_system == 'Linux' and platform_machine == 'x86_64'",
  "torch==2.10.0; platform_system != 'Linux' or platform_machine != 'x86_64'",
  "torchvision==0.25.0; platform_system != 'Linux' or platform_machine != 'x86_64'",
  "torchaudio==2.10.0; platform_system != 'Linux' or platform_machine != 'x86_64'",
  "vllm==0.15.1; platform_system == 'Linux' and platform_machine == 'x86_64'",
  "flashinfer-python==0.6.1; platform_system == 'Linux' and platform_machine == 'x86_64'",
  "xgrammar==0.1.29",
  "transformers==4.57.6",
  "openai==2.21.0",
  "ray==2.54.0",
  "ipykernel==7.2.0",
  "pytest==9.0.2",
  "ruff==0.15.2",
]

[tool.uv]
package = false
```

## 설치

<Steps>
  <Step title="프로젝트 생성">
    ```bash theme={null}
    uv init vllm-serving
    cd vllm-serving
    ```
  </Step>

  <Step title="의존성 락 및 동기화">
    ```bash theme={null}
    uv lock
    uv sync
    ```
  </Step>

  <Step title="Jupyter 커널 등록">
    ```bash theme={null}
    uv run python -m ipykernel install --user --name vllm-serving --display-name "UV vllm-serving"
    ```
  </Step>
</Steps>

## 설치 확인

모든 OS 공통 확인:

```bash theme={null}
uv run python -c "import torch, transformers, openai, xgrammar; print('torch', torch.__version__); print('transformers', transformers.__version__); print('xgrammar', xgrammar.__version__)"
```

Ubuntu x86\_64 추가 확인:

```bash theme={null}
uv run python -c "import vllm; print('vllm', vllm.__version__)"
```

## 서빙 시작 (Ubuntu x86\_64)

### 기본 서빙

```bash theme={null}
uv run python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --max-model-len 4096
```

### 주요 서빙 옵션

| 옵션                         | 설명                                   | 기본값    |
| -------------------------- | ------------------------------------ | ------ |
| `--model`                  | HuggingFace 모델 ID 또는 로컬 경로           | (필수)   |
| `--tensor-parallel-size`   | GPU 병렬 수                             | 1      |
| `--max-model-len`          | 최대 시퀀스 길이                            | 모델 기본값 |
| `--gpu-memory-utilization` | GPU 메모리 사용 비율                        | 0.9    |
| `--dtype`                  | 연산 정밀도 (`auto`, `half`, `bfloat16`)  | auto   |
| `--quantization`           | 양자화 방식 (`awq`, `gptq`, `squeezellm`) | None   |

### 클라이언트 호출 예시

```python theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="token-not-needed"  # vLLM 자체 서빙 시 인증 불필요
)

response = client.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=[{"role": "user", "content": "한국의 수도는?"}],
    max_tokens=256
)
print(response.choices[0].message.content)
```

## 트러블슈팅

| 증상               | 원인                          | 해결                                             |
| ---------------- | --------------------------- | ---------------------------------------------- |
| `vllm` import 실패 | Linux x86\_64 + CUDA 환경이 아님 | `uname -m`, `nvidia-smi` 확인                    |
| `uv sync` 의존성 충돌 | 기존 락 파일과 버전 불일치             | `uv lock --refresh` 사용                         |
| CUDA OOM         | `max-model-len`이 VRAM 초과    | `--max-model-len` 줄이거나 `--quantization awq` 적용 |
| 느린 첫 응답          | 모델 로딩 + KV 캐시 초기화           | 정상 동작, warm-up 요청으로 대응                         |
| `ray` 관련 오류      | 멀티 GPU 설정 불일치               | `--tensor-parallel-size`와 실제 GPU 수 일치 확인       |

## 설치 점검 목록

* 관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다.
* 설치 후 버전 확인 명령어(`--version`)를 실행해 정상 설치를 검증했습니다.
* PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다.
* 문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다.

## 관련 문서

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