로컬 LLM

지도 위치 : 3일차 · ③추론 엔진 층 · vLLM 설치와 첫 추론 | 이전: 17차시 LLM Serving 아키텍처 | 다음: 19차시 vLLM 서버 구축 키워드 : vLLM 설치, GPU 환경 설정, 모델 로딩 및 기본 추론

이 차시를 다 읽으면

1. vLLM을 유와 종차로 정의하고, Transformers · Ollama와 무엇으로 갈리는지 말할 수 있다.
2. vLLM을 반드시 전용 가상환경 에 설치해야 하는 이유를 전역 ↔ 격리 축으로 설명할 수 있다.
3. 설치 전에 확인할 것(OS · GPU · 드라이버 · 디스크)을 명령과 함께 댈 수 있다.
4. 오프라인 추론 코드에서 LLM · SamplingParams · llm.chat 세 줄 을 알아보고 첫 실행 성공을 판정할 수 있다.
5. Ollama가 이미 GPU를 쓰고 있을 때의 충돌 을 nvidia-smi로 진단할 수 있다.

---

0. 이 차시의 판별 축

축 1은 앞에서 배운 가상환경(3차시 3.1) 을 다시 꺼내는 자리입니다. 짧게 되짚으면, 가상환경 은 [격리 장치]인데 [ 프로젝트마다 파이썬과 패키지 묶음을 별도의 폴더에 따로 둔다 ]는 점에서 컴퓨터 전체가 패키지 한 벌을 같이 쓰는 전역 설치와 구별됩니다. 따로 두는 이유는 의존성 지옥 때문입니다. 프로젝트 A와 B가 같은 패키지의 다른 버전 을 원하면, 한 곳에 같이 깔았을 때 둘 중 하나는 깨집니다. 가상환경은 이 고장이 다른 프로젝트로 번지지 않게 막는 장애 격리 장치 이고, vLLM에서 그 역할이 가장 절실해집니다(3절).

---

1. vLLM은 무엇인가

1.1 정의

vLLM — [LLM 추론 엔진 겸 서빙 프레임워크]인데, [ KV 캐시를 블록 단위로 관리하고(PagedAttention) 여러 요청을 생성 스텝마다 섞어 계산해(연속 배칭) 동시 처리량을 높이는 데 특화되었다 ]는 점에서 1인 실행의 간편함에 맞춘 Ollama, 범용 모델 라이브러리인 Transformers와 구별된다.

종차에 나온 두 기술(PagedAttention, 연속 배칭)은 21차시에서 풉니다. 지금은 "여럿이 동시에 쓸 때 강한 엔진" 이라는 위치만 잡으면 됩니다.

1.2 반례 — 이건 vLLM이 아닙니다

---

2. 설치 전 확인 — 요구사항

vLLM은 Linux + NVIDIA GPU(CUDA) 가 기본 대상입니다(README 8장). 설치를 맡기기 전에 아래 표를 먼저 채웁니다.

⚠️ nvidia-smi의 CUDA Version 은 "설치된 CUDA 툴킷 버전"이 아니라 드라이버가 지원하는 최대 CUDA 버전 입니다. pip로 받는 vLLM은 필요한 CUDA 런타임을 함께 가져오는 경우가 많아 툴킷을 따로 깔 필요가 없을 수 있습니다. 정확한 조건은 설치 페이지 에서 확인합니다.

⚠️ 드라이버 · CUDA 재설치는 시스템 전체에 영향을 줍니다. README 9장의 표대로 실행 전 설명을 받고 사람이 승인 합니다.

---

3. ⚠️ 전용 가상환경 — 왜 반드시 따로인가

3.1 vLLM은 PyTorch 버전을 고정한다

vLLM은 특정 PyTorch 버전에 맞춰 빌드되어 설치할 때 그 버전의 torch를 함께 깝니다. 11차시에 bitsandbytes · Transformers를 깔아 둔 환경에 vLLM을 얹으면 torch가 바뀌면서 그 환경이 깨질 수 있습니다.

원래도 파이썬 · PyTorch · CUDA 세 개는 따로 고를 수 없습니다. PyTorch는 특정 CUDA 버전에 맞춰 빌드되어 배포되고, PyTorch 버전마다 지원하는 파이썬 버전 범위가 있기 때문입니다(3차시 1절의 사슬). vLLM은 여기에 한 층을 더 얹습니다. vLLM · torch · CUDA 가 한 묶음입니다.

⭐ 가상환경은 결국 폴더 하나 라서 지우고 다시 만들면 됩니다. 다른 환경에는 아무 영향이 없습니다. 설치가 꼬이면 고치려 애쓰지 말고 .venv-vllm을 지우고 새로 만드는 것이 가장 빠릅니다.

3.2 uv로 만들기

uv — [파이썬 패키지 · 환경 관리자]인데, [ 가상환경 만들기와 패키지 설치를 한 도구로, 빠르게 한다 ]는 점에서 pip · venv · conda와 구별된다.

# uv 설치 (처음 한 번)
curl -LsSf https://astral.sh/uv/install.sh | sh

# vLLM 전용 환경
mkdir -p ~/vllm-lab && cd ~/vllm-lab
uv venv --python 3.12 .venv-vllm
source .venv-vllm/bin/activate
uv pip install vllm --torch-backend=auto   # ⚠️ 옵션은 공식 설치 페이지의 현재 명령을 따를 것

🔍 읽는 포인트

• .venv-vllm — 환경 이름. 기존 .venv와 이름부터 갈라 둡니다.
• source ... activate 뒤에는 터미널 프롬프트 앞에 (.venv-vllm)이 붙어야 합니다. 안 붙으면 엉뚱한 곳에 설치됩니다.
• 마지막 줄의 옵션(--torch-backend=auto)은 버전에 따라 다릅니다. AI가 기억으로 쓴 명령 대신 공식 문서(docs.vllm.ai의 Installation → GPU)의 명령을 씁니다.

3.3 설치 확인 한 줄

python -c "import vllm, torch; print(vllm.__version__, torch.__version__, torch.cuda.is_available())"

---

4. 모델 로딩과 기본 추론 — 오프라인 추론

4.1 첫 코드

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen3-8B", max_model_len=8192)          # ① 모델 로딩
params = SamplingParams(temperature=0.2, max_tokens=256)       # ② 생성 설정

messages = [
    {"role": "system", "content": "너는 쇼핑몰 고객센터 문의를 3줄로 요약하는 도우미다."},
    {"role": "user", "content": "주문한 운동화가 일주일째 안 와요. 주문번호 20261128-001입니다. 빨리 확인 부탁드려요."},
]
outputs = llm.chat(messages, params)                            # ③ 채팅 형식 추론
print(outputs[0].outputs[0].text)

🔍 읽는 포인트

• ① LLM(...) — 이 한 줄에서 다운로드(처음만) → VRAM 로딩 → KV 캐시 자리 확보 까지 전부 일어납니다. 가장 오래 걸리는 줄입니다. max_model_len은 2차시의 컨텍스트 길이 설정값 입니다.
• ② SamplingParams — 6 · 13차시의 추론 파라미터 입니다. max_tokens는 이번에 생성할 최대 토큰 수.
• ③ llm.chat — messages를 모델에 맞는 채팅 템플릿 으로 바꿔 넣어 줍니다. 날 문자열을 넣는 llm.generate도 있습니다.

4.2 Ollama에서 배운 것과의 대응

⚠️ Qwen3 계열은 출력에 <think> 생각 과정 이 붙을 수 있습니다. 끄는 방법(채팅 템플릿 옵션 enable_thinking 등)은 모델 카드와 vLLM 버전에 따라 다르니 확인 후 씁니다.

4.3 ⚠️ 이건 아직 서빙이 아닙니다

LLM 클래스는 내 스크립트 안에서 모델을 돌리는 방식입니다. 17차시 3.1의 "앱 안에 모델"과 같은 자리입니다. 스크립트가 끝나면 모델도 내려갑니다.

그래도 쓸모가 있습니다. llm.chat에 대화 여러 개를 리스트로 넘기면 엔진이 알아서 묶어 계산합니다. 밤새 문의 1,000통을 요약하는 오프라인 배치 (17차시 1.2)에는 이쪽이 단순합니다. 여러 사람에게 계속 제공하려면 19차시의 vllm serve로 갑니다.

---

5. 자주 만나는 걸림돌

5.1 ⚠️ Ollama가 이미 GPU를 쓰고 있을 때

Ollama는 설치하면 systemd 서비스로 상주 하고(5차시), 마지막 요청 뒤에도 모델을 기본 5분간 VRAM에 남겨 둡니다 (OLLAMA_KEEP_ALIVE). 그런데 vLLM은 뜰 때 GPU 메모리의 정해진 비율(기본 0.9)을 미리 확보 하려 합니다(19차시). 자리가 없으면 메모리 부족 에러로 로딩이 실패 합니다.

nvidia-smi                    # 아래 Processes 표에 ollama 가 있는가, 몇 MiB를 쓰는가
ollama ps                     # 메모리에 올라가 있는 모델
ollama stop qwen3:8b          # 그 모델만 내리기
sudo systemctl stop ollama    # 서비스째 멈추기 (실습 끝나면 start)

🔍 읽는 포인트 — nvidia-smi 아래쪽 Processes 표가 "누가 VRAM을 쥐고 있나"의 답입니다. 11차시에 쓰던 Jupyter 커널 이 모델을 쥐고 있는 경우도 같습니다(커널 재시작).

5.2 모델은 어디에 받아지나 — Hugging Face 캐시

4차시에서 본 그대로, vLLM은 모델을 Hugging Face 캐시 (기본 ~/.cache/huggingface/hub, HF_HOME으로 변경)에 받습니다. 폴더 이름은 models--Qwen--Qwen3-8B 모양입니다.

⚠️ 그래서 같은 Qwen3-8B라도 디스크에 두 벌 이 생깁니다. 형식도 다릅니다. 이 차이가 24차시 "공정한 비교"의 함정이 됩니다.

💡 폐쇄망이라면 4차시대로 인터넷 되는 곳에서 받아 반입하고 오프라인 모드(HF_HUB_OFFLINE=1)로 실행합니다. 접근 승인이 필요한 모델은 Hugging Face 로그인 토큰이 필요합니다.

5.3 첫 실행이 느린 이유

LLM(...) 한 줄 안에서 다운로드 → 디스크에서 VRAM으로 로딩 → 엔진 준비(KV 캐시 확보, 내부 최적화 단계) 가 일어납니다. 두 번째부터는 다운로드가 빠지지만 로딩과 준비는 매번 합니다. 앞에서 배운 축 ① 디스크 ↔ 메모리 의 비용입니다. 그래서 운영에서는 한 번 띄워 계속 떠 있게 합니다(19차시).

---

6. 실습 — 맡기고 검수하기

지시

Linux + NVIDIA GPU 서버에 vLLM 전용 가상환경을 만들고 첫 추론까지 해줘.
맥락: vLLM 공식 문서 설치 페이지(docs.vllm.ai, Installation → GPU)를 먼저 읽고 현재 명령을 따를 것.
     기억하고 있는 명령을 쓰지 마.
제약:
- 시스템 파이썬과 기존 가상환경에는 아무것도 설치하지 마. 새 환경 이름은 .venv-vllm.
- 드라이버 · CUDA 재설치가 필요해 보이면 실행하지 말고 이유를 먼저 보고해.
- 시작 전에 nvidia-smi로 GPU를 쓰는 다른 프로세스(특히 ollama, jupyter)가 있는지 확인하고,
  있으면 멈추기 전에 나에게 보고하고 승인을 받아.
할 일:
1. 요구사항 확인(OS, nvidia-smi, 파이썬 버전, 디스크 여유)
2. 설치 후 버전 확인 한 줄 실행
3. LLM(model="Qwen/Qwen3-8B", max_model_len=8192) + llm.chat으로 문의 요약 1건
보고 형식: [단계 | 실행한 명령 | 결과 요약 | 출력 원문] 표.
추측하지 말고 실행 출력 원문을 붙여.

받을 증거

• 설치 전후 nvidia-smi 출력 원문
• 버전 확인 한 줄의 출력 (vllm 버전, torch 버전, True)
• 로딩 로그 중 모델 가중치가 차지한 메모리 줄과 KV 캐시 관련 줄 (19차시에서 읽는 법을 배웁니다)
• 요약 결과 텍스트

내가 직접 볼 것 — 첫 실행 확인 표

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 18차시 노트만 근거로 5문제를 내줘. 비전공자 기준으로.
"vLLM을 전용 가상환경에 설치하는 이유", "LLM·SamplingParams·llm.chat 세 줄의 역할", "Ollama와 GPU 충돌 진단"은 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.