허깅페이스 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

2) Hugging Face CLI & 라이브러리 설치
pip install -U "huggingface_hub[cli]" transformers accelerate

(선택) 로그인 – Private 모델 쓸 때
huggingface-cli 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)
huggingface-cli download TinyLlama/TinyLlama-1.1B-Chat-v1.0

# 또는 3B급: Qwen2.5 3B Instruct (조금 무거움)
huggingface-cli 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 순서가 안전합니다.



댓글

댓글 쓰기

이 블로그의 인기 게시물

아파치 보안관련 기본설정

-
 🔧 기본 설정 항목들 1. ServerTokens & ServerSignature 설명 : Apache가 클라이언트에게 서버 정보를 얼마나 제공할지 결정함. 보안 권장 설정 : ServerTokens Prod ServerSignature Off Prod : 버전 정보 없이 "Apache"만 반환. Off : 에러 페이지나 디렉토리 목록에 서버 정보 숨김. 2. Timeout 설명 : 클라이언트와의 연결에 대해 Apache가 기다리는 시간. 권장 설정 (성능 및 DoS 방지): Timeout 30 기본값 60초 → 30초로 줄이면 유휴 연결을 빠르게 정리 가능. 3. KeepAlive & MaxKeepAliveRequests 설명 : 하나의 TCP 연결로 여러 요청을 처리할 수 있게 함. 권장 설정 : KeepAlive On MaxKeepAliveRequests 100 KeepAliveTimeout 5 KeepAliveTimeout 은 너무 길면 자원 낭비. 일반적으로 2~5초 권장. 4. 디렉토리 보호 설정 <Directory /var/www/html>     Options -Indexes     AllowOverride None     Require all granted </Directory> -Indexes : 디렉토리 인덱싱 비활성화. -  AllowOverride None : .htaccess 비활성화하여 보안 강화. Apache에서 HttpOnly 쿠키 설정하기 ✅ 방법 1: Apache에서 Set-Cookie 에 HttpOnly 추가하기 <IfModule mod_headers.c> Header edit Set-Cookie ^(.*)$ "$1;HttpOnly;Secure" </IfModule> 🔎 설명: mod_headers 모듈을 사용하여 모든 Set...
자세한 내용 보기

티베로 이관 작업 절차

-
티베로 이관 작업 절차 /* 기존 DB 환경 파악 신규 DB설치시 NLS_CHARACTERSET, DB_BLOCK_SIZE 기존과 동일해야 데이터 import 시 오류없이 import 된다. */ /*1.  터미널에서 기존 db 접속후 환경 파악 */ /* 티베로 db 접속 */ /* tbsql 사용자/패스워드@sid */ tbsql sys/tibero@SID /* DB_BLOCK_SIZE 확인 */ SHOW PARAMETER DB_BLOCK_SIZE SQL> SHOW PARAMETER DB_BLOCK_SIZE NAME                         TYPE     VALUE ---------------------------- -------- ---------------------------------------- DB_BLOCK_SIZE                INT32    8192 /* CHARACTER_SET 확인 */ SQL>  SELECT * FROM SYS._VT_NLS_CHARACTER_SET; CHARACTERSET_NAME NCHAR_CHARACTERSET_NAME ----------------- ----------------------- MSWIN949          UTF16 /*2. 테이블 스페이스 생성 스크립트 실제테이블 스크립트 용량 계산 추출 */ set linesize 1000 set pagesize 50000 set trimspool on spool create_tablespace.sql SELECT 'create tablespace ' || TABLESPACE_NAME || ' datafile ''' || ...
자세한 내용 보기

윈도우 네트워크 리소스 사용권한 오류

-
이미지
윈도우에서 네트워크 공유 오류 처리 이 네트워크 리소스를 사용할 권한이 없는 것 같습니다. 이 서버의 관리자에게 문의하여 액세스 권한이 있는지 확인하십시시오. 이렇게 메세지 뜨고 공유가 안될경우 cmd 콘솔창을 띄워서 기존에 등록되어 있는 연결정보를 다 삭제 하고 다시 접속하면 연결이 된다. 연결된 정보 확인 cmd 창에서  net use C:\Windows\System32>net use 새 연결 정보가 저장됩니다. 상태         로컬      원격                      네트워크 ------------------------------------------------------------------------------- OK                     \\192.168.6.20\IPC$       Microsoft Windows Network 명령을 잘 실행했습니다. 확인후 연결 끊기 net use /delete * 실행후 y를 눌러서 계속하면 현재 연결을 끊어 버립니다. 연결을 끊고 다시 네트워크 접속을 하면 정상적으로 접속이 됩니다. 전체가 아니고 해당 연결만 삭제 하는 방법은 net use /delete \\공유폴더명 위와 같이 하여도 해결이 안 될 경우 자경증명 관리자에서 저장된 자격증명 삭제하기 윈도우 키를 누른후 자격 증명 관리자 실행   자격증명 관리자 메뉴에 들어가서 Windows 자격증명 메뉴를 클릭하여 오류가 나는 아이피를 선택하여 제거 하고 다시 접속합니다.
자세한 내용 보기