본문으로 건너뛰기

로컬에서 DeepSeek-V4 실행하는 방법: Pro 및 Flash 설치 가이드

AIDeepSeek-V4LLMLocal AI약 3 분

로컬에서 DeepSeek-V4 실행하는 방법: Pro 및 Flash 설치 가이드

DeepSeek-V4는 지금까지 DeepSeek에서 공개한 가장 야심찬 오픈 웨이트 모델 중 하나입니다. 이 시리즈에는 49B 활성화 파라미터를 가진 1.6T 파라미터 Mixture-of-Experts 모델인 DeepSeek-V4-Pro와 13B 활성화 파라미터를 가진 더 작은 284B 파라미터 MoE 모델인 DeepSeek-V4-Flash가 포함되어 있습니다. 두 모델 모두 최대 백만 토큰의 컨텍스트 길이를 지원합니다.

이 조합은 매우 흥미롭지만, 실질적인 질문이 생깁니다: 실제로 DeepSeek-V4를 로컬에서 실행할 수 있을까요?

답은 예지만 중요한 단서가 있습니다. DeepSeek-V4는 노트북 크기의 모델이 아닙니다. Flash 버전조차도 다중 GPU 배포가 필요한 심각한 모델입니다. 이 가이드는 Hugging Face의 공식 DeepSeek 모델 저장소를 사용한 로컬 설정 경로를 안내하고, 계획해야 할 하드웨어를 설명하며, 공식 추론 및 인코딩 파일을 올바르게 사용하는 방법을 보여줍니다.

참고 모델 페이지:

DeepSeek-V4-Pro vs DeepSeek-V4-Flash

무엇이든 다운로드하기 전에 올바른 모델 변형을 선택하세요.

모델전체 파라미터 수활성화 파라미터 수컨텍스트 길이정밀도적합 용도
DeepSeek-V4-Flash284B13B1MFP4 + FP8 혼합빠른 로컬 실험, 저비용 서비스, 코딩 어시스턴트, 장기 컨텍스트 테스트
DeepSeek-V4-Pro1.6T49B1MFP4 + FP8 혼합최고 품질, 연구실, 대규모 GPU 클러스터, 심도 있는 추론 및 에이전트 작업

가장 중요한 점은 DeepSeek-V4가 Mixture-of-Experts (MoE) 아키텍처를 사용한다는 것입니다. 각 토큰마다 모델의 일부만 활성화되어 계산 비용을 줄입니다. 하지만 모델 가중치를 저장하고 로드해야 하므로 GPU 메모리와 저장 공간 요구량은 여전히 매우 높습니다.

대부분 개발자에게는 DeepSeek-V4-Flash가 현실적인 출발점입니다. DeepSeek-V4-Pro는 클러스터 규모 배포로 간주하는 것이 좋습니다.

DeepSeek-V4가 특별한 이유는?

DeepSeek의 모델 카드에 따르면 V4 시리즈는 다음과 같은 주요 업그레이드를 도입했습니다:

  1. 하이브리드 어텐션 아키텍처: DeepSeek는 Compressed Sparse Attention (CSA)와 Heavily Compressed Attention (HCA)를 결합하여 장기 컨텍스트 효율성을 향상시켰습니다. 백만 토큰 설정에서 DeepSeek-V4-Pro는 DeepSeek-V3.2보다 훨씬 적은 KV 캐시를 사용한다고 합니다.
  2. Manifold-Constrained Hyper-Connections (mHC): 매우 깊은 네트워크에서 안정성을 개선하면서 모델 용량을 유지합니다.
  3. Muon Optimizer: DeepSeek는 훈련 중 더 나은 수렴과 안정성을 위해 Muon을 사용합니다.
  4. 장기 컨텍스트: Pro와 Flash 모두 최대 1M 토큰을 지원하며, DeepSeek는 Think Max 모드에 최소 384K 컨텍스트를 권장합니다.
  5. 다중 추론 모드: DeepSeek-V4는 Non-think, Think High, Think Max 스타일 사용을 지원합니다.

로컬 배포에서 가장 중요한 실용적 변화는 혼합 FP4/FP8 정밀도와 맞춤형 채팅 인코딩 포맷입니다.

하드웨어 요구사항

DeepSeek-V4는 RTX 4090 같은 소비자용 GPU를 위해 설계되지 않았습니다(향후 커뮤니티 양자화 수정본으로 실험하는 경우 제외). 공식 가중치를 사용할 경우 서버용 GPU를 계획하세요.

실용적 하드웨어 계획

사용 사례권장 하드웨어비고
DeepSeek-V4-Flash 테스트 배포4-8개의 고메모리 NVIDIA GPUH100/H200/A100급 GPU가 실용적 목표
DeepSeek-V4-Flash 프로덕션 서비스8개 이상의 고메모리 GPU더 많은 GPU가 처리량과 장기 컨텍스트 작업에 도움
DeepSeek-V4-Pro 연구 배포대규모 다중 노드 GPU 클러스터단일 워크스테이션 모델이 아닌 클러스터 인프라로 취급
Think Max 장기 컨텍스트추가 GPU 메모리 및 KV 캐시 예산Think Max에 최소 384K 컨텍스트 권장

저장 공간 요구사항

다운로드 전에 충분한 로컬 저장 공간을 확보하세요:

  • 가능하면 NVMe SSD 저장소 사용
  • 변환된 가중치 저장을 위한 여유 공간 확보
  • 작은 시스템 디스크에 직접 다운로드하지 말 것
  • Pro 모델은 Flash보다 훨씬 더 많은 저장 공간 필요 예상

안전한 디렉터리 구조 예시:

/data/models/deepseek-v4-flash-hf      # 원본 Hugging Face 파일
/data/models/deepseek-v4-flash-infer   # 변환된 추론 가중치
/data/cache/huggingface                # HF 캐시

클라우드 GPU 서버를 임대하는 경우, 로컬 NVMe가 있거나 대용량 고처리량 볼륨을 연결할 수 있는 인스턴스를 선택하세요. VPS 스타일 배포 계획 시 LightNode 같은 공급자를 통해 GPU 또는 고메모리 서버를 비교할 수 있지만, 해당 인스턴스가 이 클래스 모델에 필요한 GPU 메모리를 실제로 갖추었는지 반드시 확인하세요.

소프트웨어 요구사항

최신 NVIDIA 드라이버와 CUDA가 설치된 Linux 환경이 필요합니다.

권장 기본 환경:

구성 요소권장 사항
OSUbuntu 22.04 이상
Python3.10 이상
GPU 드라이버최신 NVIDIA 데이터센터 드라이버
CUDACUDA 12.x 권장
PyTorchCUDA 지원 빌드
Git LFS모델 파일 다운로드에 필요
Hugging Face CLI안정적인 다운로드에 필요

기본 도구 설치:

sudo apt update
sudo apt install -y git git-lfs python3 python3-venv python3-pip

git lfs install
pip install -U huggingface_hub

Python 가상환경 사용 시:

python3 -m venv dsv4-env
source dsv4-env/bin/activate
pip install -U pip wheel setuptools
pip install -U huggingface_hub torch transformers safetensors

1단계: DeepSeek-V4-Flash 다운로드

대부분 사용자에게는 Flash부터 시작하세요:

mkdir -p /data/models
cd /data/models

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

Pro 모델을 원하면:

huggingface-cli download deepseek-ai/DeepSeek-V4-Pro \
  --local-dir DeepSeek-V4-Pro \
  --local-dir-use-symlinks False

다운로드가 중단되면 같은 명령어를 다시 실행하세요. Hugging Face가 다운로드를 이어서 진행합니다.

2단계: 공식 저장소 구조 확인

다운로드 후 모델 폴더를 확인하세요:

cd /data/models/DeepSeek-V4-Flash
ls

모델 카드에는 두 개의 중요한 폴더가 있습니다:

  • inference/ - 공식 로컬 추론 코드, 가중치 변환 및 생성 스크립트 포함
  • encoding/ - DeepSeek-V4용 프롬프트 인코딩 및 출력 파싱 유틸리티

이 점이 중요한 이유는 DeepSeek-V4가 일반적인 Jinja 형식의 채팅 템플릿을 제공하지 않기 때문입니다. 모든 일반 OpenAI 호환 채팅 래퍼가 기본적으로 프롬프트를 올바르게 포맷한다고 가정하면 안 됩니다.

3단계: 공식 추론용 가중치 변환

공식 추론 README는 생성 실행 전에 변환 단계를 사용합니다.

모델 저장소에서:

cd /data/models/DeepSeek-V4-Flash/inference

export HF_CKPT_PATH=/data/models/DeepSeek-V4-Flash
export SAVE_PATH=/data/models/DeepSeek-V4-Flash-infer
export EXPERTS=256
export MP=4
export CONFIG=config.json

python convert.py \
  --hf-ckpt-path ${HF_CKPT_PATH} \
  --save-path ${SAVE_PATH} \
  --n-experts ${EXPERTS} \
  --model-parallel ${MP}

변수 설명:

변수의미
HF_CKPT_PATH원본 Hugging Face 모델 파일 경로
SAVE_PATH변환된 추론 가중치 출력 경로
EXPERTS=256DeepSeek-V4 추론 변환에 사용되는 전문가 수
MP=4모델 병렬 크기; 보통 실행에 사용하는 GPU 수와 일치시킴
CONFIG생성 스크립트에서 사용하는 모델 구성 파일

더 많은 GPU를 사용할 경우 MP 값을 조정하세요. 예를 들어 8 GPU 노드에서는:

export MP=8

FP8 전문가 옵션

공식 추론 README에 따르면 FP4 전문가 대신 FP8 전문가를 사용하려면 config.json에서 다음 줄을 제거하세요:

"expert_dtype": "fp4"

그런 다음 변환 시 --expert-dtype fp8 옵션을 추가합니다:

python convert.py \
  --hf-ckpt-path ${HF_CKPT_PATH} \
  --save-path ${SAVE_PATH} \
  --n-experts ${EXPERTS} \
  --model-parallel ${MP} \
  --expert-dtype fp8

대부분 사용자는 기본 혼합 FP4/FP8 설정으로 시작하세요. 작동하는 기본선을 확보한 후에만 정밀도를 변경하세요.

4단계: 대화형 채팅 시작

변환이 완료되면 공식 생성 스크립트를 실행하세요:

cd /data/models/DeepSeek-V4-Flash/inference

export MP=4
export SAVE_PATH=/data/models/DeepSeek-V4-Flash-infer
export CONFIG=config.json

torchrun --nproc-per-node ${MP} generate.py \
  --ckpt-path ${SAVE_PATH} \
  --config ${CONFIG} \
  --interactive

배치 입력 파일 사용 시:

torchrun --nproc-per-node ${MP} generate.py \
  --ckpt-path ${SAVE_PATH} \
  --config ${CONFIG} \
  --input-file prompts.txt

다중 노드 실행 시:

torchrun \
  --nnodes ${NODES} \
  --nproc-per-node $((MP / NODES)) \
  --node-rank $RANK \
  --master-addr $ADDR \
  generate.py \
  --ckpt-path ${SAVE_PATH} \
  --config ${CONFIG} \
  --input-file prompts.txt

모든 노드가 변환된 체크포인트 경로에 접근할 수 있도록 하거나, 변환된 파일을 각 머신의 동일 경로에 복사하세요.

5단계: 올바른 샘플링 설정 사용

DeepSeek는 로컬 배포에 다음 샘플링 파라미터를 권장합니다:

temperature = 1.0
top_p = 1.0

생성 스크립트가 CLI 플래그로 노출하면 직접 사용하세요. 그렇지 않으면 스크립트나 구성 파일에서 샘플링 파라미터를 설정하세요.

Think Max 모드에서는 DeepSeek가 최소 다음 컨텍스트 창 크기를 권장합니다:

384K tokens

첫 테스트 시에는 너무 큰 컨텍스트 창으로 시작하지 마세요. 작게 시작해 모델이 정상적으로 로드되고 생성되는지 확인한 후 GPU 메모리를 모니터링하며 점진적으로 컨텍스트 길이를 늘리세요.

6단계: DeepSeek-V4 채팅 인코딩 이해하기

DeepSeek-V4는 표준 Jinja 채팅 템플릿을 포함하지 않습니다. 대신 저장소에 Python 유틸리티가 포함된 encoding/ 폴더가 있습니다.

기본 사용법은 다음과 같습니다:

from encoding_dsv4 import encode_messages, parse_message_from_completion_text

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is 2+2?"},
]

prompt = encode_messages(messages, thinking_mode="thinking")
print(prompt)

비사고(non-thinking) 채팅은 chat 모드를 사용하세요:

prompt = encode_messages(messages, thinking_mode="chat")

사고(thinking) 모드에서는 명시적 추론 구분자가 사용됩니다:

<think> ... </think>

파서는 생성된 텍스트를 구조화된 어시스턴트 메시지로 다시 변환할 수 있습니다:

completion = "Simple arithmetic.</think>2 + 2 = 4.<｜end▁of▁sentence｜>"
parsed = parse_message_from_completion_text(completion, thinking_mode="thinking")
print(parsed)

이는 DeepSeek-V4를 기반으로 자체 로컬 API 래퍼를 구축하려는 경우 특히 중요합니다.

추론 모드 설명

DeepSeek-V4는 세 가지 실용적 추론 스타일을 지원합니다:

모드동작사용 사례
Non-think빠른 직접 답변간단한 Q&A, 요약, 일상 코딩 도움
Think High신중한 분석을 통한 추론 답변디버깅, 계획, 수학, 아키텍처 결정
Think Max최대 추론 노력어려운 코딩 작업, 에이전트 워크플로우, 연구 수준 문제 해결

로컬 서버에서는 다음과 같이 별도 모델 이름으로 노출할 수 있습니다:

deepseek-v4-flash-chat
deepseek-v4-flash-thinking
deepseek-v4-flash-max

내부적으로 각 경로는 다른 프롬프트 인코딩, 컨텍스트 제한, 생성 파라미터를 사용할 수 있습니다.

vLLM 또는 SGLang으로 DeepSeek-V4 실행 가능할까?

출시 시점에서 가장 안전한 경로는 모델 저장소 내 공식 DeepSeek 추론 코드입니다. 일반적인 서빙 프레임워크는 DeepSeek-V4의 아키텍처, 혼합 정밀도, 장기 컨텍스트 동작, 맞춤 인코딩을 완전히 지원하려면 업데이트가 필요할 수 있습니다.

실용적 접근법은:

  1. 먼저 공식 inference/generate.py 경로를 성공적으로 실행
  2. 공식 encoding/ 유틸리티로 출력 품질과 프롬프트 포맷 확인
  3. 선호하는 프레임워크가 명시적 DeepSeek-V4 지원을 추가했는지 확인
  4. 지원이 확인된 후에만 vLLM, SGLang, TensorRT-LLM 또는 다른 서빙 프레임워크로 이전

이렇게 하면 모델은 로드되지만 프롬프트 템플릿이 잘못되어 채팅 품질이 떨어지는 일반적인 실패 모드를 피할 수 있습니다.

간단한 로컬 API 래퍼 구축하기

OpenAI 스타일 로컬 엔드포인트가 필요하면 공식 생성 경로를 FastAPI로 래핑할 수 있습니다. 구체적 구현은 generate.py 통합 방식에 따라 다르지만, 기본 흐름은 다음과 같습니다:

  1. OpenAI 호환 messages 수신
  2. encoding_dsv4.encode_messages()로 변환
  3. 인코딩된 프롬프트를 DeepSeek-V4 추론 엔진에 전송
  4. parse_message_from_completion_text()로 출력 파싱
  5. OpenAI 호환 JSON 응답 반환

의사 코드:

from encoding_dsv4 import encode_messages, parse_message_from_completion_text

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Explain KV cache in simple terms."},
]

prompt = encode_messages(messages, thinking_mode="thinking")

# 로컬 DeepSeek-V4 추론 워커에 프롬프트 전송
raw_completion = run_deepseek_v4(prompt)

assistant_message = parse_message_from_completion_text(
    raw_completion,
    thinking_mode="thinking",
)

print(assistant_message["content"])

프로덕션 환경에서는 다음을 추가하세요:

  • 요청 큐잉
  • 스트리밍 출력
  • 타임아웃 처리
  • GPU 상태 점검
  • 최대 컨텍스트 강제 적용
  • 구조화된 로그
  • 인증

문제 해결

1. CUDA 메모리 부족

메모리 부담을 줄이려면:

  • 컨텍스트 길이 줄이기
  • 배치 크기 줄이기
  • 텐서/모델 병렬 크기 늘리기
  • GPU 수 늘리기
  • Pro 대신 DeepSeek-V4-Flash로 시작

디버깅 시 가장 먼저 줄여야 할 것은 장기 컨텍스트입니다.

2. 다운로드 실패 또는 중단

브라우저 다운로드 대신 huggingface-cli download 사용. 같은 명령어를 다시 실행하면 이어받기 가능.

전용 캐시 디렉터리 설정도 가능합니다:

export HF_HOME=/data/cache/huggingface
export HUGGINGFACE_HUB_CACHE=/data/cache/huggingface/hub

3. 모델이 이상한 채팅 출력 생성

프롬프트 포맷을 확인하세요. DeepSeek-V4는 표준 Jinja 채팅 템플릿을 사용하지 않습니다. 공식 encoding/ 구현을 사용하세요.

4. 다중 GPU 실행 실패

PyTorch가 모든 GPU를 인식하는지 확인:

python - <<'PY'
import torch
print(torch.cuda.device_count())
for i in range(torch.cuda.device_count()):
    print(i, torch.cuda.get_device_name(i))
PY

다중 노드 실행 시 NCCL 네트워킹도 확인:

export NCCL_DEBUG=INFO

5. Think Max가 너무 느림

Think Max는 어려운 추론에 더 많은 계산을 사용하도록 설계되었습니다. 비용이 정당화되는 작업에만 사용하세요. 일반 어시스턴트 용도에는 Non-think 또는 Think High가 보통 더 실용적입니다.

권장 배포 전략

DeepSeek-V4를 처음 로컬 배포할 때는 다음 순서를 따르세요:

  1. DeepSeek-V4-Flash부터 시작
  2. 공식 추론 코드 사용
  3. 작은 테스트 컨텍스트로 시작
  4. 공식 인코딩 작동 확인
  5. 컨텍스트 길이를 점진적으로 늘림
  6. 로컬 생성이 안정된 후 API 래퍼 추가
  7. 클러스터 규모 GPU 자원이 있을 때만 Pro 고려

마무리 생각

DeepSeek-V4는 강력하지만 가벼운 로컬 모델은 아닙니다. Flash 버전이 실용적 진입점이며, Pro는 심각한 다중 GPU 또는 다중 노드 환경에 적합합니다. 성공적인 설치의 핵심은 공식 워크플로우를 존중하는 것입니다: Hugging Face 저장소 다운로드, 제공된 추론 도구로 가중치 변환, torchrun으로 생성 실행, 그리고 일반적인 채팅 템플릿 대신 전용 DeepSeek-V4 인코딩 유틸리티 사용.

프롬프트 실험만 필요하다면 호스팅된 DeepSeek 채팅 서비스나 API 경로가 더 쉬울 수 있습니다. 그러나 데이터 프라이버시, 완전한 제어, 토큰별 과금 없음, 맞춤 인프라가 필요하다면 DeepSeek-V4를 로컬에서 실행하는 것이 프라이빗 장기 컨텍스트 AI 시스템 구축에 강력한 기반을 제공합니다.

저렴한 VPS 호스팅으로 절약하세요