허깅페이스 cli 설치 & vllm 설치 테스트

허깅페이스 cli 설치

* 준비물

- Python 3.10+ & pip

- NVIDIA 드라이버 설치

1) 가상 환경

python3 -m venv ~/venvs/llm

source ~/venvs/llm/bin/activate

# 최신 pip로 업데이트

python -m pip install -U pip

# 1. rustup 설치 (공식 툴체인 관리자)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

source $HOME/.cargo/env

2) Hugging Face CLI & 라이브러리 설치

# (venv가 켜져 있다고 가정)

export RUSTFLAGS="-A invalid_reference_casting"

pip install -U "huggingface_hub[cli]" transformers accelerate

(선택) 로그인 – Private 모델 쓸 때

hf auth login

# 토큰 입력 (https://huggingface.co/settings/tokens 에서 발급)

3) 캐시 저장 경로를 대용량 디스크로 변경

한 번만 설정해두면 편한 HF_HOME을 추천합니다. (모델/데이터셋/설정이 전부 이 경로 아래로 이동)

# 3-1) 디렉터리 준비

mkdir -p /data/huggingface/hf_cache

# 3-2) 현재 쉘 세션에 적용

export HF_HOME=/data/huggingface/hf_cache

# 3-3) 영구 반영 (zsh 예시: ~/.zshrc / bash면 ~/.bashrc)

echo 'export HF_HOME=/data/huggingface/hf_cache' >> ~/.bashrc

# 새 터미널에서 자동 적용되며, 현 세션엔 아래로 즉시 적용:

source ~/.bashrc

(빠른 확인)

python - << 'PY'

import os; print("HF_HOME =", os.environ.get("HF_HOME"))

PY

4) (선택) 모델을 미리 내려받아 캐시 확인

용량 작은 모델로 빠르게 손에 익히기:

# 아주 가벼운 채팅용: TinyLlama (≈1.1B)

hf download TinyLlama/TinyLlama-1.1B-Chat-v1.0

# 또는 3B급: Qwen2.5 3B Instruct (조금 무거움)

hf download Qwen/Qwen2.5-3B-Instruct

다운로드 후 캐시 위치가 바뀌었는지 확인:

du -sh /data/huggingface/hf_cache/hub

5) vLLM 설치

pip install -U vllm

주의: 최초 설치 시 CUDA/컴파일 관련 의존성 때문에 시간이 걸릴 수 있어요.

6) vLLM으로 로컬 OpenAI 호환 서버 띄우기

첫 기동은 작은 모델로 확인하세요. (VRAM 16GB 기준: 1~3B는 매우 안전)

# 예: TinyLlama (1.1B) – 가장 안전한 첫 기동

# --max-model-len 옵션 제거(기본이 2048이므로 동일 효과)

vllm serve TinyLlama/TinyLlama-1.1B-Chat-v1.0 \

  --dtype auto \

  --port 9000 \

  --gpu-memory-utilization 0.85 \

  --max-model-len 2048 \

  --max-num-batched-tokens 1024 \

  --max-num-seqs 16 \

  --enforce-eager

# 또는 Qwen2.5 3B Instruct (조금 무거움)

vllm serve Qwen/Qwen2.5-3B-Instruct \

  --port 9000 --dtype auto \

  --gpu-memory-utilization 0.85 \

  --max-model-len 8192 \

  --max-num-batched-tokens 1024 \

  --max-num-seqs 16

기본 주소/엔드포인트: http://127.0.0.1:9000/v1

외부 접속도 필요하면 --host 0.0.0.0 추가 (집/사내망 노출 시 방화벽 유의)

7) cURL로 Chat Completions 테스트

curl http://127.0.0.1:9000/v1/chat/completions \

  -H "Content-Type: application/json" \

  -d '{

    "model": "Qwen/Qwen2.5-3B-Instruct",

    "messages": [

      {"role": "system", "content": "You are a helpful assistant."},

      {"role": "user", "content": "안녕하세요, 자기소개 해주세요."}

    ],

    "max_tokens": 128,

    "temperature": 0.7

  }'

curl http://127.0.0.1:9000/v1/chat/completions \

  -H "Content-Type: application/json" \

  -d '{

    "model": "TinyLlama/TinyLlama-1.1B-Chat-v1.0",

    "messages": [

      {"role": "system", "content": "You are a helpful Korean assistant."},

      {"role": "user", "content": "안녕! 자기소개해줘"}

    ],

    "temperature": 0.7

  }'

모델 이름은 serve 때 지정한 모델 문자열과 동일해야 합니다.

(위 예시는 TinyLlama 기준. Qwen2.5 3B로 띄웠다면 그 이름으로 바꿔서 호출하세요.)

8) 자주 쓰는 운영 팁

포트 변경: --port 8000 등

호스트 변경: --host 0.0.0.0 (외부 접근 허용)

컨텍스트 길이 제한: --max-model-len 2048 (메모리 아끼기)

GPU 메모리 활용도: --gpu-memory-utilization 0.92 (기본 0.9 근처, 상황에 맞게 조정)

중단: 실행 터미널에서 Ctrl + C

9) (선택) 로컬 폴더에서 바로 서빙

모델을 특정 폴더에 미리 내려받아 두고 그 경로를 직접 지정할 수 있어요.

# 미리 받아두기 (예: /data/huggingface/models/qwen2_5_3b)

hf download Qwen/Qwen2.5-3B-Instruct \

  --local-dir /data/huggingface/models/qwen2_5_3b --local-dir-use-symlinks False

# 로컬 경로로 바로 기동

vllm serve /data/huggingface/models/qwen2_5_3b \

  --port 9000 --dtype auto \

  --gpu-memory-utilization 0.85 \

  --max-model-len 8192 \

  --max-num-batched-tokens 1024 \

  --max-num-seqs 16

/* 백그라운 기동 */

- 날짜별로 로그파일 생성하기 위해서 cronolog 설치

sudo apt-get update

sudo apt-get install cronolog -y

nohup vllm serve /data/huggingface/models/qwen2_5_3b \

  --port 9000 \

  --dtype auto \

  --gpu-memory-utilization 0.85 \

  --max-model-len 8192 \

  --max-num-batched-tokens 1024 \

  --max-num-seqs 16 \

  2>&1 | cronolog vllm_%Y-%m-%d.log &

/* 프로세스 확인 */

ps aux | grep vllm

/* 종료 */

pkill -f "vllm serve"

/* 테스트 */

curl http://127.0.0.1:9000/v1/chat/completions   -H "Content-Type: application/json"   -d '{

    "model": "/data/huggingface/models/qwen2_5_3b",

    "messages": [

      {"role": "system", "content": "You are a helpful assistant."},

      {"role": "user", "content": "안녕하세요, 자기소개 해주세요."}

    ],

    "max_tokens": 128,

    "temperature": 0.7

  }'

이렇게 하면 vLLM이 허깅페이스 Hub에서 다시 받지 않고 로컬 디렉터리를 그대로 사용합니다.

OpenAI SDK로도 쉽게 호출

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:9000/v1", api_key="EMPTY")

resp = client.chat.completions.create(

    model="TinyLlama/TinyLlama-1.1B-Chat-v1.0",

    messages=[

        {"role": "system", "content": "You are a helpful Korean assistant."},

        {"role": "user", "content": "서울 가을 날씨 느낌으로 삼행시 해줘"}

    ],

    temperature=0.7,

)

print(resp.choices[0].message.content)

vLLM은 기본적으로 인증을 요구하지 않아서 api_key에는 임의 문자열을 넣어도 됩니다(빈 값은 안 되는 SDK도 있어 “EMPTY” 추천).

가상환경 진입 불편함 줄이기

파이션 버전에 따라서 다양한 라이브러리 의존성 충돌 오류가 많이 발생해서 가상환경 설치는 옵션이 아닌 필수

개발할때 마다 가상환경 진입 불편하니 환경변수에 alias로 단축키 등록후 가상환경 활성화후

작업하면 해당 가상환경에 설치된 파이션 버전에 라이브러리 로 사용

 alias로 단축

~/.bashrc나 ~/.zshrc에:

alias llm='source ~/venvs/llm/bin/activate'

저장후에 아무 터미널이나 열고

llm 만 치면 바로 가상환경 진입.

/* 간단 테스트 */

llm         # alias로 가상환경 진입

huggingface-cli whoami

python -c "import transformers; print(transformers.__version__)"

CUDA /PyTorch 버전호환 설치

내가 사용하는 파이션 기준 : Python 3.12.3 버전으로 설정

GPU를 쓰려면 PyTorch가 Python 3.12 + CUDA에 맞게 설치되어야 합니다.

보통 vLLM 설치 시 PyTorch가 자동 설치되지만, 혹시 충돌 나면 공식 PyTorch 설치 명령으로 재설치하면 됩니다.

cuda 버전 확인 방법

nvidia-smi 로 확인하면 상단에 cuda 버전 확인 가능

내 pc cuda 버전 

NVIDIA-SMI 580.76.05 Driver Version: 580.76.05 CUDA Version: 13.0 

현재 NVIDIA 드라이버 버전은 580.76.05, 그리고 nvidia-smi가 보고하는 CUDA Version: 13.0 

1. CUDA 13.0 의미

• nvidia-smi에서 나오는 CUDA Version은 “최대 지원 버전”을 의미합니다.

• 즉, GPU 드라이버가 CUDA 13.0을 지원한다는 뜻이고, 실제 파이썬 라이브러리(PyTorch, vLLM 등)는 그보다 낮은 버전(CUDA 12.x, 11.x) 를 설치해도 정상 동작합니다.

• 중요한 건 드라이버 ≥ CUDA 런타임만 만족하면 된다는 점이에요.

2. vLLM & PyTorch 호환성

• 현재 vLLM은 PyTorch + CUDA 12.x 빌드와 가장 안정적으로 동작합니다.

• Python 3.12.3 + CUDA 13 드라이버 환경에서라면, PyTorch의 cu121(12.1) wheel을 설치하는 게 안전합니다:

pip install torch --index-url https://download.pytorch.org/whl/cu121

-  설치 순서 (추천)

# 가상환경 진입 후

pip install -U pip

# PyTorch (CUDA 12.1 빌드)

pip install torch --index-url https://download.pytorch.org/whl/cu121

# Hugging Face & vLLM

pip install -U "huggingface_hub[cli]" transformers accelerate

pip install -U vllm

- 확인

python - <<'PY'

import torch

print("Torch CUDA available:", torch.cuda.is_available())

print("Torch CUDA version:", torch.version.cuda)

print("GPU:", torch.cuda.get_device_name(0))

PY

torch.version.cuda 가 12.1 로 나오고, GPU 이름이 뜨면 정상입니다.

vllm 기동시에 에러가 발생하면 gpu 메모리(부족) 확인

/* 아래의 옵션으로 메모리 옵션 설정후 다시 실행 */

vllm serve TinyLlama/TinyLlama-1.1B-Chat-v1.0 \

  --dtype auto \

  --port 9000 \

  --gpu-memory-utilization 0.85 \

  --max-model-len 8192 \

  --max-num-batched-tokens 1024 \

  --max-num-seqs 16

vllm serve Qwen/Qwen2.5-3B-Instruct \

  --port 9000 --dtype auto \

  --gpu-memory-utilization 0.85 \

  --max-model-len 8192 \

  --max-num-batched-tokens 1024 \

  --max-num-seqs 16

/* 참고 사항 */

vllm serve <모델>: 해당 모델을 OpenAI 호환 REST 서버로 띄웁니다. (기본 엔드포인트: /v1/completions, /v1/chat/completions 등)

모델 Qwen/Qwen2.5-3B-Instruct: Hugging Face의 체크포인트를 사용합니다.

옵션별 상세 설명

1) --port 9000

API 서버가 바인딩될 포트.

예: http://localhost:9000/v1/chat/completions 로 요청.

이미 다른 프로세스가 9000을 점유 중이면 충돌하므로, 그런 경우 포트를 바꾸면 됩니다.

2) --dtype auto

모델과 GPU 능력에 맞춰 가중치·연산 정밀도를 자동 선택.

보통 최신 NVIDIA GPU(암페어↑)면 bfloat16(bf16), 그 외엔 fp16으로 잡힙니다.

의미: 메모리 절약(+속도 개선)과 수치 안정성의 밸런스. bf16은 fp16보다 overflow에 좀 더 안정적입니다.

3) --gpu-memory-utilization 0.85

vLLM이 시작 시점에 목표로 하는 VRAM 점유 비율(가중치+KV 캐시+런타임 버퍼의 계획치).

16GB급 GPU에서 0.85면 약 13.1GiB 정도를 목표로 잡습니다.

시작 직전 실제 여유 VRAM이 이 목표치보다 적으면 초기화가 실패합니다(방금 보신 에러의 원인).

튜닝 가이드

안정: 0.80~0.88

다른 프로세스가 VRAM을 조금 쓰고 있으면 더 낮춰야 합니다.

서버 실행 후 OOM이 난다면 이 값만으로 해결되지 않을 수 있고, 아래 배치/길이 옵션도 함께 보정해야 합니다.

4) --max-model-len 8192

한 시퀀스(한 요청)의 최대 컨텍스트 길이(토큰) 상한입니다.

(시스템/유저/어시스턴트 메시지 포함 전체 프롬프트 + 생성 토큰 합산 관점으로 생각하면 됩니다.)

메모리 영향이 큼: 길이가 길수록 토큰당 KV 캐시가 커져서 VRAM을 많이 먹습니다.

효과: 32K → 8K로 낮추면 KV 캐시가 대폭 줄어, 시작 실패/런타임 OOM 위험이 크게 감소합니다.

튜닝 팁

긴 문서 요약/롱컨텍스트가 필요 없을 때는 4K~8K로 제한하면 효율적.

매우 긴 컨텍스트가 필요한 경우엔 이 값을 올리되, 아래 두 옵션(--max-num-batched-tokens, --max-num-seqs)을 더 보수적으로 잡아 VRAM을 맞춰주세요.

5) --max-num-batched-tokens 1024

동시에 전개(prefill 또는 decode)되는 “총 토큰 수” 상한입니다.

예) 프리필 단계에서 8개의 요청이 각각 128토큰이라면 8×128=1024 → 한 번에 처리 가능.

영향

값을 낮추면: 한 라운드에 다루는 토큰이 줄어 피크 VRAM 사용량 감소(안정↑), 대신 스루풋↓.

값을 높이면: 스루풋↑, VRAM 피크↑.

언제 줄이나요?

“긴 프롬프트 여러 개를 동시에” 넣는 사용 패턴에서 자주 OOM이 난다면 먼저 이 값을 낮춰보세요(1024→768→512…).

6) --max-num-seqs 16

동시 처리(동시 추론) 가능한 시퀀스(요청) 개수 상한입니다.

영향

값을 낮추면: 동시성↓ → KV 캐시 및 배치 메모리 부담 감소(안정↑), 하지만 여러 요청이 대기 큐에 쌓여 대기 지연↑.

값을 높이면: 동시성↑ → 스루풋↑, VRAM 부담↑.

권장

16GB VRAM에서 3B 모델은 8~32 사이에서 워크로드에 맞게 조절하는 편.

사용자 수가 적고 지연 중요하면 8~16, 스루풋이 더 중요하면 16~32 시도(메모리 여유 필수).

옵션 간 상호작용 & 튜닝 흐름

부팅 실패(시작 시 메모리 부족)

→ --gpu-memory-utilization을 먼저 낮추고, 그래도 부족하면 --max-model-len을 더 낮춥니다.

(이 두 가지가 “고정 비용”에 가장 큰 영향)

런타임 중 OOM(특히 긴 프롬프트/동시 다수 요청 때)

→ --max-num-batched-tokens ↓, --max-num-seqs ↓ 순서로 조정해 피크를 낮춥니다.

처리량(스루풋)이 부족

→ VRAM 여유가 있다면 --max-num-batched-tokens ↑ 또는 --max-num-seqs ↑.

(단, 둘 다 올리면 피크가 급격히 커지니 한 단계씩)

지연 시간(Latency)이 길다

단일 요청 지연이 길면 배치가 과도하게 합쳐지지 않도록 --max-num-batched-tokens 과도 상승을 피합니다.

동시성으로 인해 대기 시간이 길면 --max-num-seqs를 약간 올리되, 메모리 여유 체크는 필수.

실전 추천값(16GB급 GPU, 3B 모델 기준)

안정 시작 지점:

--gpu-memory-utilization 0.82~0.86, --max-model-len 4K~8K,

--max-num-batched-tokens 512~1024, --max-num-seqs 8~16

트래픽이 늘면:

메모리 여유 확인 후 --max-num-seqs → --max-num-batched-tokens 순으로 소폭↑

자주 묻는 질문(FAQ)

Q. --max-model-len을 낮추면 응답 품질이 떨어지나요?

→ 길게 기억해야 하는 작업(롱컨텍스트) 외에는 직접적인 품질 저하는 거의 없습니다. 다만 너무 긴 프롬프트/히스토리를 넣을 수 없게 되니 사용 패턴에 맞춰 잡으세요.

Q. --gpu-memory-utilization만 낮추면 충분한가요?

→ 시작은 가능해지지만, 런타임 피크(긴 프롬프트/동시성)에서 OOM이 날 수 있습니다. 그땐 배치·동시성 옵션까지 만지세요.

Q. 어떤 값부터 손대야 하나요?

→ (부팅 실패) gpu-memory-utilization → max-model-len → (런타임 OOM) max-num-batched-tokens → max-num-seqs 순서가 안전합니다.