Pular para o conteúdo

Como Executar DeepSeek-V4 Localmente: Guia de Configuração Pro e Flash

AIDeepSeek-V4LLMLocal AIPor volta de 9 min

Como Executar DeepSeek-V4 Localmente: Guia de Configuração Pro e Flash

DeepSeek-V4 é uma das liberações de modelo open-weight mais ambiciosas da DeepSeek até agora. A família inclui o DeepSeek-V4-Pro, um modelo Mixture-of-Experts com 1,6T de parâmetros e 49B de parâmetros ativados, e o DeepSeek-V4-Flash, um modelo MoE menor com 284B de parâmetros e 13B de parâmetros ativados. Ambos os modelos suportam um comprimento de contexto de até um milhão de tokens.

Essa combinação soa empolgante, mas também gera uma pergunta prática: você realmente pode executar DeepSeek-V4 localmente?

A resposta é sim, mas com uma ressalva importante. DeepSeek-V4 não é um modelo para laptop. Mesmo a versão Flash exige uma implantação séria com múltiplas GPUs. Este guia percorre o caminho de configuração local usando os repositórios oficiais do modelo DeepSeek no Hugging Face, explica o hardware que você deve planejar e mostra como usar corretamente os arquivos oficiais de inferência e codificação.

Páginas de referência dos modelos:

DeepSeek-V4-Pro vs DeepSeek-V4-Flash

Antes de baixar qualquer coisa, escolha a variante correta do modelo.

ModeloTotal de ParâmetrosParâmetros AtivadosComprimento do ContextoPrecisãoMelhor Para
DeepSeek-V4-Flash284B13B1MFP4 + FP8 mistoExperimentos locais mais rápidos, serviço de baixo custo, assistentes de codificação, testes de contexto longo
DeepSeek-V4-Pro1.6T49B1MFP4 + FP8 mistoQualidade máxima, laboratórios de pesquisa, grandes clusters de GPU, tarefas sérias de raciocínio e agentes

O detalhe mais importante é que DeepSeek-V4 usa uma arquitetura Mixture-of-Experts (MoE). Apenas parte do modelo é ativada para cada token, o que reduz o custo computacional. No entanto, você ainda precisa armazenar e carregar os pesos do modelo. Isso significa que os requisitos de memória GPU e armazenamento continuam muito altos.

Para a maioria dos desenvolvedores, DeepSeek-V4-Flash é o ponto de partida realista. DeepSeek-V4-Pro é melhor tratado como uma implantação em escala de cluster.

O Que Torna o DeepSeek-V4 Diferente?

De acordo com o card do modelo DeepSeek, a série V4 introduz várias melhorias importantes:

  1. Arquitetura de Atenção Híbrida: DeepSeek combina Compressed Sparse Attention (CSA) e Heavily Compressed Attention (HCA) para melhorar a eficiência em contextos longos. No cenário de um milhão de tokens, o DeepSeek-V4-Pro supostamente usa muito menos cache KV que o DeepSeek-V3.2.
  2. Conexões Hiper-Constrangidas por Múltiplas Variedades (mHC): Isso melhora a estabilidade em redes muito profundas enquanto preserva a capacidade do modelo.
  3. Otimizador Muon: DeepSeek usa Muon durante o treinamento para melhor convergência e estabilidade.
  4. Contexto Longo: Tanto Pro quanto Flash suportam até 1M tokens, com DeepSeek recomendando pelo menos 384K de contexto para o modo Think Max.
  5. Múltiplos Modos de Raciocínio: DeepSeek-V4 suporta os estilos Non-think, Think High e Think Max.

Para implantação local, as duas mudanças práticas mais importantes são a precisão mista FP4/FP8 e o formato personalizado de codificação de chat.

Requisitos de Hardware

DeepSeek-V4 não foi projetado para GPUs de consumidor como a RTX 4090, a menos que você esteja apenas experimentando quantizações comunitárias fortemente modificadas no futuro. Para os pesos oficiais, planeje GPUs de servidor.

Planejamento Prático de Hardware

Caso de UsoHardware SugeridoObservações
Implantação de teste DeepSeek-V4-Flash4-8 GPUs NVIDIA com alta memóriaGPUs da classe H100/H200/A100 são o alvo prático
Serviço de produção DeepSeek-V4-Flash8+ GPUs com alta memóriaMais GPUs ajudam no throughput e cargas de trabalho de contexto longo
Implantação de pesquisa DeepSeek-V4-ProGrande cluster multi-nó de GPUsTrate isso como infraestrutura de cluster, não como modelo para estação de trabalho única
Think Max com contexto longoMemória extra de GPU e orçamento para cache KVDeepSeek recomenda pelo menos 384K de contexto para Think Max

Requisitos de Armazenamento

Planeje um armazenamento local grande antes de iniciar o download:

  • Use armazenamento NVMe SSD sempre que possível.
  • Mantenha espaço extra para pesos convertidos.
  • Evite baixar diretamente para um disco do sistema pequeno.
  • Espere que o modelo Pro exija muito mais armazenamento que o Flash.

Um layout seguro é:

/data/models/deepseek-v4-flash-hf      # arquivos originais do Hugging Face
/data/models/deepseek-v4-flash-infer   # pesos convertidos para inferência
/data/cache/huggingface                # cache do HF

Se você estiver alugando um servidor GPU na nuvem, escolha uma instância com NVMe local ou anexe um volume grande de alta taxa de transferência. Para planejamento de implantação estilo VPS, você pode comparar servidores GPU ou com alta memória por provedores como LightNode, mas certifique-se de que a instância realmente tenha a memória GPU necessária para essa classe de modelo.

Requisitos de Software

Você precisa de um ambiente Linux com drivers NVIDIA recentes e CUDA.

Linha de base recomendada:

ComponenteRecomendação
SOUbuntu 22.04 ou superior
Python3.10+
Driver GPUDriver recente NVIDIA para data center
CUDACUDA 12.x preferencial
PyTorchBuild com suporte CUDA
Git LFSNecessário para arquivos do modelo
Hugging Face CLINecessário para downloads confiáveis

Instale as ferramentas básicas:

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

git lfs install
pip install -U huggingface_hub

Se usar ambiente virtual 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

Passo 1: Baixar DeepSeek-V4-Flash

Para a maioria dos usuários, comece com 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

Se quiser o modelo Pro em vez disso:

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

Se o download for interrompido, basta rodar o mesmo comando novamente. O Hugging Face retomará o download.

Passo 2: Inspecionar a Estrutura Oficial do Repositório

Após o download, verifique a pasta do modelo:

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

O card do modelo aponta para duas pastas importantes:

  • inference/ - código oficial de inferência local, incluindo scripts de conversão de pesos e geração
  • encoding/ - utilitários para codificação de prompt e parsing de saída para DeepSeek-V4

Isso é importante porque DeepSeek-V4 não vem com um template de chat no formato Jinja normal. Você não deve assumir que qualquer wrapper genérico compatível com OpenAI formatará os prompts corretamente imediatamente.

Passo 3: Converter os Pesos para Inferência Oficial

O README oficial de inferência usa uma etapa de conversão antes de rodar a geração.

No repositório do modelo:

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}

Notas dos parâmetros:

VariávelSignificado
HF_CKPT_PATHCaminho para os arquivos originais do modelo Hugging Face
SAVE_PATHCaminho de saída para os pesos convertidos para inferência
EXPERTS=256Número de experts usados pela conversão de inferência DeepSeek-V4
MP=4Tamanho do paralelismo de modelo; geralmente combine com o número de GPUs usadas na execução
CONFIGArquivo de configuração do modelo usado pelo script de geração

Se usar mais GPUs, ajuste MP conforme necessário. Por exemplo, em um nó com 8 GPUs:

export MP=8

Opção de Expert FP8

O README oficial de inferência observa que, se quiser usar experts FP8 em vez de FP4, remova esta linha do config.json:

"expert_dtype": "fp4"

Então passe --expert-dtype fp8 durante a conversão:

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

Para a maioria dos usuários, comece com a configuração padrão mista FP4/FP8 primeiro. Mude a precisão somente depois de ter uma base funcional.

Passo 4: Iniciar um Chat Interativo

Quando a conversão terminar, execute o script oficial de geração:

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

Para um arquivo de entrada em lote:

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

Para execução multi-nó:

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

Certifique-se de que cada nó possa acessar o caminho do checkpoint convertido, ou copie os arquivos convertidos para o mesmo caminho em cada máquina.

Passo 5: Usar as Configurações Corretas de Amostragem

DeepSeek recomenda os seguintes parâmetros de amostragem para implantação local:

temperature = 1.0
top_p = 1.0

Se seu script de geração expõe esses parâmetros como flags CLI, use-os diretamente. Caso contrário, defina-os no script ou na configuração onde os parâmetros de amostragem são definidos.

Para o modo Think Max, DeepSeek recomenda usar uma janela de contexto de pelo menos:

384K tokens

Não comece com uma janela de contexto enorme no seu primeiro teste. Comece pequeno, confirme que o modelo carrega e gera corretamente, depois aumente o comprimento do contexto gradualmente enquanto monitora a memória da GPU.

Passo 6: Entenda a Codificação de Chat do DeepSeek-V4

DeepSeek-V4 não inclui um template padrão de chat Jinja. Em vez disso, o repositório fornece uma pasta encoding/ com utilitários Python.

O uso básico é assim:

from encoding_dsv4 import encode_messages, parse_message_from_completion_text

messages = [
    {"role": "system", "content": "Você é um assistente prestativo."},
    {"role": "user", "content": "Quanto é 2+2?"},
]

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

Para chat sem raciocínio, use o modo chat:

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

Para o modo thinking, o modelo usa delimitadores explícitos de raciocínio:

<think> ... </think>

O parser pode converter o texto gerado de volta em mensagens estruturadas do assistente:

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

Isso é especialmente importante se você quiser construir seu próprio wrapper local de API em torno do DeepSeek-V4.

Modos de Raciocínio Explicados

DeepSeek-V4 suporta três estilos práticos de raciocínio:

ModoComportamentoCaso de Uso
Non-thinkRespostas rápidas e diretasPerguntas simples, sumarização, ajuda rotineira de codificação
Think HighRespostas com raciocínio e análise deliberadaDebugging, planejamento, matemática, decisões arquiteturais
Think MaxMáximo esforço de raciocínioTarefas difíceis de codificação, fluxos de trabalho agentes, resolução de problemas em nível de pesquisa

Para um servidor local, você pode querer expor esses modos como nomes de modelo separados, por exemplo:

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

Internamente, cada rota pode usar codificação de prompt diferente, limites de contexto e parâmetros de geração distintos.

É Possível Rodar DeepSeek-V4 com vLLM ou SGLang?

No lançamento, o caminho mais seguro é o código oficial de inferência DeepSeek no repositório do modelo. Frameworks genéricos de serving podem precisar de atualizações antes de suportar totalmente a arquitetura DeepSeek-V4, precisão mista, comportamento de contexto longo e codificação personalizada.

Uma abordagem prática é:

  1. Primeiro, execute com sucesso o caminho oficial inference/generate.py.
  2. Confirme a qualidade da saída e a formatação do prompt com as utilidades oficiais encoding/.
  3. Depois, verifique se seu framework preferido adicionou suporte explícito ao DeepSeek-V4.
  4. Só migre para vLLM, SGLang, TensorRT-LLM ou outro framework de serving após a confirmação do suporte.

Isso evita um modo comum de falha: o modelo carrega, mas a qualidade do chat é ruim porque o template do prompt está errado.

Construindo um Wrapper Simples de API Local

Se quiser um endpoint local estilo OpenAI, você pode envolver o caminho oficial de geração com FastAPI. A implementação exata depende de como você integra o generate.py, mas o fluxo geral é:

  1. Receber messages compatíveis com OpenAI.
  2. Convertê-los usando encoding_dsv4.encode_messages().
  3. Enviar o prompt codificado para o motor de inferência DeepSeek-V4.
  4. Analisar a saída usando parse_message_from_completion_text().
  5. Retornar uma resposta JSON compatível com OpenAI.

Pseudo-código:

from encoding_dsv4 import encode_messages, parse_message_from_completion_text

messages = [
    {"role": "system", "content": "Você é um assistente prestativo."},
    {"role": "user", "content": "Explique cache KV em termos simples."},
]

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

# Envie o prompt para seu worker local de inferência DeepSeek-V4
raw_completion = run_deepseek_v4(prompt)

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

print(assistant_message["content"])

Para produção, adicione:

  • enfileiramento de requisições
  • saída em streaming
  • tratamento de timeout
  • checagens de saúde da GPU
  • aplicação de limite máximo de contexto
  • logs estruturados
  • autenticação

Solução de Problemas

1. CUDA Out of Memory

Reduza a pressão de memória por:

  • diminuir o comprimento do contexto
  • reduzir o tamanho do batch
  • aumentar o paralelismo tensor/modelo
  • usar mais GPUs
  • começar com DeepSeek-V4-Flash em vez do Pro

Contexto longo geralmente é a primeira coisa a reduzir durante o debug.

2. Download Falha ou Congela

Use huggingface-cli download em vez de downloads pelo navegador. Rode o mesmo comando para retomar.

Você também pode definir um diretório de cache dedicado:

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

3. O Modelo Gera Saída Estranha no Chat

Verifique a formatação do prompt. DeepSeek-V4 não usa template padrão Jinja para chat. Use a implementação oficial encoding/.

4. Execução Multi-GPU Falha

Verifique se o PyTorch vê todas as GPUs:

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

Também verifique a rede NCCL para execuções multi-nó:

export NCCL_DEBUG=INFO

5. Think Max Está Muito Lento

Think Max é projetado para gastar mais computação em raciocínios difíceis. Use-o apenas para tarefas que justifiquem o custo. Para uso normal de assistente, Non-think ou Think High são geralmente mais práticos.

Estratégia Recomendada de Implantação

Se você está implantando DeepSeek-V4 localmente pela primeira vez, siga esta sequência:

  1. Comece com DeepSeek-V4-Flash.
  2. Use o código oficial de inferência.
  3. Use um contexto de teste pequeno inicialmente.
  4. Confirme que a codificação oficial funciona.
  5. Aumente o comprimento do contexto gradualmente.
  6. Adicione um wrapper de API somente após a geração local estar estável.
  7. Considere o Pro apenas quando tiver recursos de GPU em escala de cluster.

Considerações Finais

DeepSeek-V4 é poderoso, mas não é um modelo casual para uso local. A versão Flash é o ponto de entrada prático, enquanto o Pro pertence a ambientes sérios multi-GPU ou multi-nó. A chave para uma configuração bem-sucedida é respeitar o fluxo oficial: baixe o repositório Hugging Face, converta os pesos com as ferramentas de inferência fornecidas, execute a geração com torchrun e use as utilidades dedicadas de codificação DeepSeek-V4 em vez de assumir um template genérico de chat.

Se você só precisa experimentar prompts, o serviço de chat hospedado DeepSeek ou rotas de API podem ser mais fáceis. Mas se precisar de privacidade de dados, controle total, sem cobrança por token ou infraestrutura customizada, rodar DeepSeek-V4 localmente oferece uma base sólida para construir sistemas de IA privados com contexto longo.

Economize Muito em VPS Barato