Rihpig

Posted on Apr 24 • Originally published at apidog.com

DeepSeek V4 로컬 실행 방법

2026년 4월 23일, MIT 라이선스가 적용된 DeepSeek V4 가중치가 Hugging Face에 공개되었습니다. 이 단일 라이선스 선택은 자체 하드웨어에서 최첨단 AI를 원하는 모든 팀의 계산 방식을 바꿉니다. V4-Flash (총 284B, 활성 13B)는 FP8에서 H100 2대에 적합합니다. V4-Pro (총 1.6T, 활성 49B)는 클러스터가 필요하지만, 코드 및 추론에서 GPT-5.5 및 Claude Opus 4.6과 경쟁력 있게 작동합니다.

지금 Apidog을 사용해보세요

이 가이드는 로컬 배포를 위한 실전 가이드입니다. 하드웨어 요구 사항, 양자화 옵션, vLLM 및 SGLang 설정, 도구 사용 구성, 그리고 프로덕션 트래픽을 연결하기 전에 Apidog으로 로컬 서버를 검증하는 테스트 워크플로를 다룹니다.

제품 개요는 DeepSeek V4란 무엇인가를 참조하세요. 호스팅된 API 경로는 DeepSeek V4 API 사용 방법을 참조하세요. 비용 비교는 DeepSeek V4 API 가격을 참고하세요.

요약

V4-Flash: FP8에서 2 × H100 80GB 또는 INT4에서 1 × H100에서 실행. 가중치는 FP8에서 약 500GB.
V4-Pro: 프로덕션 처리량을 위해 FP8에서 16개 이상의 H100 필요. 노트북 모델 아님.
vLLM: OpenAI 호환 서버로 가장 빠르게 배포 가능. vllm>=0.9.0에서 V4 지원.
SGLang: 더 나은 도구 사용 및 구조화된 출력이 필요한 팀에 적합.
AWQ INT4/GPTQ INT4 양자화: V4-Flash를 단일 80GB 카드에서 약 5% 품질 손실로 실행 가능.
Apidog으로 http://localhost:8000/v1를 테스트하고, 호스팅 API에서 사용한 컬렉션을 그대로 재사용.

자가 호스팅이 필요한 경우

V4 자가 호스팅은 다음과 같은 팀에 적합합니다.

규제 준수: 네트워크 밖으로 데이터가 나갈 수 없는 의료, 금융, 법률, 국방 등.
대규모·안정적 워크로드: 월 2천억 토큰 이상 워크로드면 전용 하드웨어가 API 대비 경제적.
미세 조정 및 연구: MIT 라이선스는 결과물의 상업적 재배포까지 허용.

하지 말아야 할 경우: 프로토타입, GPU 운영 경험 부족, 월 $200 미만 API 사용량. 이 경우 운영 오버헤드가 비용 절감을 상쇄합니다.

하드웨어 요구 사항

DeepSeek V4는 FP4 + FP8 혼합 정밀도를 기본 사용합니다. 메모리 요구 사항은 다음과 같습니다.

변형	총 매개변수	활성 매개변수	FP8 VRAM	INT4 VRAM	최소 카드
V4-Flash	284B	13B	~500GB	~140GB	2 × H100 80GB (FP8) 또는 1 × H100 (INT4)
V4-Pro	1.6T	49B	~2.4TB	~700GB	16 × H100 80GB (FP8) 또는 8 × H100 (INT4)

설명:

MoE 메모리는 활성 매개변수가 아닌 전체 전문가 수에 맞춰야 합니다.
H200/MI300X: 더 높은 VRAM 카드(141/192GB)는 카드 수를 줄여줍니다.
소비자 GPU: 24GB RTX 5090도 INT4 V4-Flash 실행 불가.
Apple Silicon: 128GB M3/M4 Max에서 느리게 구동 가능(개발/테스트용).

1단계: 가중치 다운로드

공식 저장소:

deepseek-ai/DeepSeek-V4-Flash
deepseek-ai/DeepSeek-V4-Pro
미세 조정: deepseek-ai/DeepSeek-V4-Flash-Base, DeepSeek-V4-Pro-Base

pip install -U "huggingface_hub[cli]"
huggingface-cli login

huggingface-cli download deepseek-ai/DeepSeek-V4-Flash \
  --local-dir ./models/deepseek-v4-flash \
  --local-dir-use-symlinks False

V4-Flash: 약 500GB, V4-Pro: 수 TB 디스크 필요.
중국 사용자는 ModelScope 미러링 활용.

2단계: 서빙 엔진 선택

vLLM: 최고의 처리량, OpenAI 호환, 기본값.
SGLang: 도구 사용·구조화 출력에 강점. 함수 호출 중심 워크로드에 권장.

최신 버전은 V4를 기본 지원합니다.

3단계: vLLM으로 V4-Flash 서빙

pip install "vllm>=0.9.0"

vllm serve deepseek-ai/DeepSeek-V4-Flash \
  --tensor-parallel-size 2 \
  --max-model-len 1048576 \
  --dtype auto \
  --enable-prefix-caching \
  --port 8000

--tensor-parallel-size 2: 2개 H100 분산. 카드 수에 맞게 조절.
--max-model-len 1048576: 1M 토큰 컨텍스트. 필요시 131072로 축소.
--enable-prefix-caching: 반복 접두사 캐싱 활성화.
--dtype auto: FP8 혼합 정밀도 자동 적용.

서버가 뜨면 모든 OpenAI 호환 클라이언트가 http://localhost:8000/v1에 접속할 수 있습니다.

4단계: vLLM으로 V4-Pro 서빙

클러스터 환경 필요. 명령어 예시:

vllm serve deepseek-ai/DeepSeek-V4-Pro \
  --tensor-parallel-size 8 \
  --pipeline-parallel-size 2 \
  --max-model-len 524288 \
  --enable-prefix-caching \
  --port 8000

16개 H100에 맞춰 컨텍스트 길이와 병렬 처리 분할.
VRAM 허용 시 1M 토큰까지 확장 가능.

5단계: SGLang으로 서빙 (도구 사용 대안)

pip install "sglang[all]>=0.4.0"

python -m sglang.launch_server \
  --model-path deepseek-ai/DeepSeek-V4-Flash \
  --tp 2 \
  --context-length 1048576 \
  --port 30000

SGLang은 http://localhost:30000/v1에서 OpenAI 호환 엔드포인트 제공.
SGLang의 DSL(lang)로 함수 호출/JSON 모드 등 확장 가능.

6단계: 단일 GPU 상자를 위한 양자화

INT4 양자화로 V4-Flash를 단일 80GB 카드에서 실행(5% 품질 손실).

AWQ (권장)

pip install autoawq

python -c "
from awq import AutoAWQForCausalLM
from transformers import AutoTokenizer

model_path = './models/deepseek-v4-flash'
out_path = './models/deepseek-v4-flash-awq'
model = AutoAWQForCausalLM.from_pretrained(model_path)
tokenizer = AutoTokenizer.from_pretrained(model_path)
model.quantize(tokenizer, quant_config={'w_bit': 4, 'q_group_size': 128})
model.save_quantized(out_path)
tokenizer.save_pretrained(out_path)
"

GPTQ

pip install auto-gptq
# GPTQ 양자화 레시피 참고. AWQ와 유사한 사용법.

vLLM 실행 시 --quantization awq 또는 --quantization gptq 옵션 추가.

7단계: Apidog로 테스트

프로덕션 트래픽 투입 전, 로컬 서버를 반드시 검증하세요.

Apidog 설치
http://localhost:8000/v1/chat/completions로 연결되는 컬렉션 생성
호스팅 API에 사용한 테스트 프롬프트 붙여넣기. 결과 비교
500K 토큰 컨텍스트 테스트로 KV 캐시 확인
에이전트 루프 연결 전, 도구 호출 흐름 처음부터 끝까지 실행

동일한 컬렉션을 호스팅 API와 로컬 서버 모두에 사용할 수 있습니다. OpenAI 호환 엔드포인트의 장점입니다.

관측 가능성 및 모니터링

초기부터 다음 4가지 지표를 추적하세요.

초당 토큰 수: vLLM의 /metrics(Prometheus 포맷)에서 확인
GPU 활용률: nvidia-smi 또는 DCGM. 70% 미만이면 배치 크기 조정
KV 캐시 히트율: --enable-prefix-caching 사용 시 vLLM이 제공. 히트율 하락 시 프롬프트 변동성 높음
요청 지연 p50/p95/p99: 표준 트레이싱 도구 사용. p99가 높으면 특정 요청이 큐를 정체

모든 지표를 Grafana 등 관측 스택에 연동하세요.

V4 기본 체크포인트 미세 조정

기본 체크포인트는 지속적 사전학습 및 SFT 용도로 설계됨. 표준 SFT 파이프라인:

pip install "torch>=2.6" transformers accelerate peft trl

# LoRA를 이용한 V4-Flash-Base SFT 예시
python -m trl sft \
  --model_name_or_path deepseek-ai/DeepSeek-V4-Flash-Base \
  --dataset_name your-org/your-sft-set \
  --output_dir ./models/v4-flash-custom \
  --per_device_train_batch_size 1 \
  --gradient_accumulation_steps 16 \
  --learning_rate 2e-5 \
  --bf16 true \
  --use_peft true \
  --lora_r 64 \
  --lora_alpha 128

V4-Pro 전체 매개변수 미세 조정은 연구용 과제.
대부분의 팀은 V4-Flash-Base의 LoRA 어댑터로 충분.

일반적인 문제점

시작 시 OOM(메모리 부족): --max-model-len이 너무 크거나 --tensor-parallel-size가 낮음. 컨텍스트 줄이거나 병렬수 늘리기.
느린 첫 요청: vLLM 커널 지연 컴파일. 더미 요청으로 워밍업.
도구 사용 파싱 오류: DeepSeek 인코딩 스키마가 다름. 최신 SDK/버전 고정.
FP8 오류(A100 등): A100은 FP8 미지원. BF16 사용, VRAM 2배 필요.

자가 호스팅 이득 시점

호스팅 DeepSeek V4 가격 기반 손익분기점:

V4-Flash, 월 2000억 입력/20억 출력 토큰: API $33.6K, 8×H100 임대 $20K (자가 호스팅 40% 절감)
V4-Pro, 월 5000억 입력/50억 출력 토큰: API $1.04M, 16×H100 클러스터 $35K (자가 호스팅 95% 절감)

V4-Flash 손익분기점: 월 약 1000억 토큰. 그 이하라면 호스팅 API가 더 저렴.

자주 묻는 질문

단일 A100에서 V4-Flash 구동?: 고양자화/짧은 컨텍스트에서 가능하나 느림(80GB, INT4: 5~15 tok/s). H100 권장.
LoRA 미세조정 지원?: 예. 기본 체크포인트 + 표준 TRL/Axolotl 파이프라인 사용.
로컬 서버 OpenAI 호환?: 예. vLLM/SGLang 모두 /v1/chat/completions, /v1/completions 지원. API 가이드 참고.
로컬 사고 모드 활성화?: body에 thinking_mode: "thinking" 또는 "thinking_max" 전달.
로컬 V4 서버 스트리밍?: 예. stream: true 설정.
가장 저렴한 실험법?: RunPod/Lambda에서 H100 임대, INT4 V4-Flash로 실제 프롬프트 처리량 측정($10~$30).

DEV Community