Este modelo foi contribuído para o Hugging Face Transformers em 2026-05-02.

DeepSeek-V4

DeepSeek-V4 é o modelo de linguagem MoE de próxima geração da DeepSeek (paper). A arquitetura substitui o Multi-head Latent Attention (MLA) do DeepSeek-V3 por um design híbrido local + longo alcance, troca as conexões residuais por Manifold-Constrained Hyper-Connections (mHC) e inicializa as primeiras camadas MoE com uma tabela de hash estática de token-id → expert-id.

Esta implementação abrange DeepSeek-V4-Flash, DeepSeek-V4-Pro e seus equivalentes pré-treinados -Base. Os quatro compartilham a mesma arquitetura; diferem apenas em largura / profundidade / número de especialistas e pesos.

Defina use_kernels=True em from_pretrained() para substituir camadas compatíveis por kernels otimizados do Hub. Consulte Carregando kernels para saber mais.

Arquitetura (artigo §2)

Atenção híbrida (§2.3)

Cada bloco do decodificador é um dos três tipos de atenção, despachado por config.layer_types[i]:

• Atenção completa com janela deslizante ("sliding_attention"): apenas a janela local de sliding_window tokens, sem ramificação de longo alcance. Corresponde ao estilo "Full Attention" do V3 para as camadas de bootstrap.
• Compressed Sparse Attention ("compressed_sparse_attention", CSA — paper §2.3.1): um pool de baixa compressão (compress_rate_csa, padrão m=4) com janelas sobrepostas, além de um Lightning Indexer (eqs. 13–17) que pontua as queries em relação ao pool e coleta os blocos top index_topk por query antes de chegarem à atenção principal.
• Atenção altamente comprimida ("heavily_compressed_attention", HCA — paper §2.3.2): um pool de alta compressão (compress_rate_hca, padrão m'=128) com janelas não sobrepostas. Sem indexer — cada entrada do pool contribui para a atenção.

Todos os três tipos compartilham o mesmo backbone:

• Atenção Multi-Query com K=V compartilhado: num_key_value_heads = 1; kv_proj produz um único cabeçalho KV e o mesmo tensor é lido como chave e valor.
• RoPE parcial (interleaved-pair, seção 2.3.3 do paper, “Partial Rotary Positional Embedding”) nos canais finais qk_rope_head_dim = head_dim * partial_rotary_factor de cada head. A mesma rotação é aplicada com posição -i ao slice de rope da saída de atenção (eq. 26), de modo que a contribuição de cada entrada KV permaneça uma função da distância relativa em relação à query.
• Sumidouro de atenção aprendível por cabeça (eq. 27).
• Projeção de saída de baixo posto agrupada (§2.3.1 “Grouped Output Projection”): o_groups grupos de cabeças → o_lora_rank por grupo → hidden_size, calculada por DeepseekV4GroupedLinear (o_a_proj) seguida de o_b_proj. Reduz o custo por token da saída de atenção larga sem perder expressividade.
• O ramo compartilhado de janela deslizante K=V de tamanho sliding_window (“Additional Branch of Sliding Window Attention”, §2.3.1) preserva as dependências locais de granularidade fina; a saída do compressor de longo alcance é concatenada com os KVs deste ramo antes da atenção principal.

Conexões Hiper Restricas por Variedade (§2.2)

As conexões residuais são substituídas por mHC (Xie et al., 2026): hc_mult fluxos residuais paralelos mantidos na forma [B, S, hc_mult, D] ao longo de cada bloco. Dois módulos DeepseekV4HyperConnection — attn_hc e ffn_hc — misturam os fluxos de entrada e saída em torno das subcamadas de atenção / MLP por meio de uma tríade (pre, post, comb). A matriz comb é uma projeção duplamente estocástica produzida por hc_sinkhorn_iters iterações de Sinkhorn–Knopp no manifold, tornando a propagação do sinal não expansiva em pilhas profundas. Um DeepseekV4HyperHead final reduz os hc_mult fluxos para uma única sequência antes da normalização do modelo.

Agendamento de MoE (§2.1)

O roteamento é configurado por camada por config.mlp_layer_types, com valores de {"hash_moe", "moe"}:

• "hash_moe": os índices de especialistas vêm de uma consulta congelada tid2eid[input_ids] preenchida a partir do checkpoint V4. O weight aprendido do gate ainda produz as pontuações por especialista que ponderam os especialistas selecionados; apenas quais especialistas é estático. Usado para as primeiras camadas de bootstrap (padrão 3, sobrescreva via num_hash_layers legado).
• "moe": MoE roteado padrão top-k. A afinidade dos especialistas usa Sqrt(Softplus(·)) em vez do Sigmoid do V3 (“alteramos a função de ativação que calcula as pontuações de afinidade de Sigmoid(·) para Sqrt(Softplus(·))”, papel §2.1), e a restrição n_group / topk_group do V3 é descartada. A estratégia sem perda auxiliar (noaux_tc do DeepSeek) é mantida por meio do buffer e_score_correction_bias, que aplica um viés ao argmax top-k sem propagar gradientes.

Os especialistas roteados utilizam um SwiGLU limitado (gate.clamp(max=swiglu_limit), up.clamp(min=-swiglu_limit, max=swiglu_limit), em seguida act_fn(gate) * up) sobre o layout padrão de pesos dos especialistas do Mixtral [num_experts, 2 * moe_intermediate_size, hidden_size]. Um único especialista compartilhado (um MLP SwiGLU simples com largura moe_intermediate_size) é executado em paralelo em cada token.

Layout da máscara de atenção

Cada camada DeepseekV4Attention estende a máscara causal de janela deslizante padrão ao longo do eixo das chaves com um block_bias retornado pelo seu compressor e, em seguida, passa a máscara concatenada para eager_attention_forward. A seção deslizante (esquerda, [S, S]) é a mesma para todos os tipos de camada; a seção do compressor (direita) varia conforme o tipo de camada e é a parte realmente “nova” introduzida pela V4.

Os diagramas abaixo foram produzidos com uma configuração mínima (sliding_window=8, CSA m=4, HCA m'=8, index_topk=2) em uma entrada de 16 tokens, para que a máscara completa por tipo de camada caiba na tela. Verde = a diagonal de query/key na seção deslizante, escuro = uma posição KV padrão visível, claro = mascarado, âmbar = um slot de compressor / indexador para o qual a query é permitida a prestar atenção. As colunas após a linha tracejada são adicionadas pelo compressor via cat([sliding_causal_mask, block_bias], dim=-1).

Camada apenas deslizante ("sliding_attention"). Sem compressor, sem preenchimento à direita — a máscara é a máscara causal de janela deslizante simples, de forma [S, S] (janela = 8). Para i ≥ window, o triângulo inferior esquerdo é cortado, recuperando o padrão de atenção apenas local.

Camada CSA ("compressed_sparse_attention"). O compressor achata a saída coletada por consulta em [B, 1, S·k, D] e adiciona padding à direita na máscara com S·k colunas. Para a consulta t, apenas os k slots nas colunas [S + t·k, S + (t+1)·k) contêm as escolhas do indexer; todas as outras colunas do compressor são -inf. Consultas anteriores ao fechamento da primeira janela (t < m − 1) não recebem nada — o sentinela -1 do indexer se propaga diretamente para a máscara. À medida que t aumenta, mais entradas comprimidas ficam prontas e o indexer pode preencher todos os k slots.

Camada HCA ("heavily_compressed_attention"). Sem indexer — cada entrada comprimida em cache é potencialmente visível. Preenchida à direita com T_total = entry_count["compressor"] colunas. A query t só pode ver a entrada w depois que sua janela de origem foi fechada, ou seja, w < (t + 1) // m. Com m=8 aqui, as entradas 0 (cobre as posições 0..7) e 1 (cobre 8..15) só se tornam visíveis em t ≥ 7 e t ≥ 15, respectivamente.

Estes diagramas são reproduzíveis de ponta a ponta por meio de:

python docs/source/en/imgs/deepseek_v4/visualize_attention_masks.py \
    --svg docs/source/en/imgs/deepseek_v4

O script executa uma passagem direta nesta configuração mínima, envolve cada camada de atenção para capturar a máscara exata pós-cat([attention_mask, block_bias]), remapeia a máscara de slots planos [S, S·k] do CSA de volta para uma visão de visibilidade de entradas [S, T_entries] (de modo que cada coluna C_w seja uma entrada comprimida, e não um slot de coleta) e grava os três SVGs acima. Ele também imprime uma grade ANSI no stdout para inspeção rápida no terminal e despeja as escolhas top-k por consulta do indexador, para que os sentinelas de aquecimento e as escolhas de coleta sejam auditáveis.

Camadas de cache

Cada bloco de atenção não deslizante precisa encadear o estado do compressor / indexador entre as chamadas de forward. O V4 oferece dois tipos de camada de cache que se registram automaticamente com LAYER_TYPE_CACHE_MAPPING:

• DeepseekV4HCACache: janela deslizante K=V + buffer/pool/contador do compressor HCA (sem sobreposição, sem indexador).
• DeepseekV4CSACache: janela deslizante K=V + compressor CSA (com estado de sobreposição) + indexador paralelo buffer / pool / count / overlap em index_head_dim.

DynamicCache(config=…) constrói a camada de cache adequada para cada config.layer_types[i].

DeepseekV4Config

DeepseekV4Model

DeepseekV4ForCausalLM

>>> from transformers import AutoTokenizer, DeepseekV4ForCausalLM

>>> model = DeepseekV4ForCausalLM.from_pretrained("mistralai/DeepseekV4-8x7B-v0.1")
>>> tokenizer = AutoTokenizer.from_pretrained("mistralai/DeepseekV4-8x7B-v0.1")

>>> prompt = "Hey, are you conscious? Can you talk to me?"
>>> inputs = tokenizer(prompt, return_tensors="pt")

>>> # Generate
>>> generate_ids = model.generate(inputs.input_ids, max_length=30)
>>> tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
"Hey, are you conscious? Can you talk to me?\nI'm not conscious, but I can talk to you."