Ce modèle a été contribué à Hugging Face Transformers le 2026-05-02.

DeepSeek-V4

DeepSeek-V4 est le modèle de langage MoE de nouvelle génération de DeepSeek (paper). L’architecture remplace le Multi-head Latent Attention (MLA) de DeepSeek-V3 par une conception hybride locale + longue portée, substitue les connexions résiduelles par des Manifold-Constrained Hyper-Connections (mHC) et initialise les premières couches MoE avec une table de hachage statique token-id → expert-id.

Cette implémentation couvre DeepSeek-V4-Flash, DeepSeek-V4-Pro et leurs variantes pré-entraînées -Base. Les quatre modèles partagent la même architecture ; ils ne diffèrent que par leur largeur / profondeur / nombre d'experts et leurs poids.

Définissez use_kernels=True dans from_pretrained() pour remplacer les couches prises en charge par des noyaux optimisés du Hub. Consultez Chargement des noyaux pour en savoir plus.

Architecture (article §2)

Attention hybride (§2.3)

Chaque bloc décodeur est de l'un des trois types d'attention, dispatché par config.layer_types[i] :

• Attention complète à fenêtre glissante ("sliding_attention") : uniquement la fenêtre locale de sliding_window jetons, sans branche longue portée. Correspond au style « Full Attention » de V3 pour les couches de démarrage.
• Compressed Sparse Attention ("compressed_sparse_attention", CSA — article §2.3.1) : un pool à faible compression (compress_rate_csa, valeur par défaut m=4) avec des fenêtres chevauchantes, ainsi qu'un Lightning Indexer (équations 13–17) qui évalue les requêtes par rapport au pool et rassemble les index_topk meilleurs blocs par requête avant qu'elles n'atteignent l'attention principale.
• Attention fortement compressée ("heavily_compressed_attention", HCA — article §2.3.2) : un pool à forte compression (compress_rate_hca, valeur par défaut m'=128) avec des fenêtres non chevauchantes. Aucun indexeur — chaque entrée poolée contribue à l'attention.

Les trois types partagent le même tronc commun :

• Attention multi-requête avec K=V partagés : num_key_value_heads = 1 ; kv_proj produit une seule tête KV et le même tenseur est lu à la fois comme clé et comme valeur.
• RoPE partiel (paires entrelacées, section 2.3.3 du papier « Partial Rotary Positional Embedding ») sur les qk_rope_head_dim = head_dim * partial_rotary_factor derniers canaux de chaque tête. La même rotation est appliquée avec la position -i à la tranche rope de la sortie d’attention (équation 26) afin que la contribution de chaque entrée KV reste une fonction de la distance relative à la requête.
• Évier d'attention apprenable par tête (eq. 27).
• Projection de sortie de faible rang groupée (§2.3.1 « Grouped Output Projection ») : o_groups groupes de têtes → o_lora_rank par groupe → hidden_size, calculée par DeepseekV4GroupedLinear (o_a_proj) suivie de o_b_proj. Réduit le coût par jeton de la sortie d'attention large sans perdre d'expressivité.
• La branche partagée de fenêtre glissante K=V de taille sliding_window (« Additional Branch of Sliding Window Attention », §2.3.1) préserve les dépendances locales fines ; la sortie du compresseur longue portée est concaténée avec les KV de cette branche avant l’attention de base.

Hyper-Contraintes sur Variété (§2.2)

Les connexions résiduelles sont remplacées par mHC (Xie et al., 2026) : hc_mult flux résiduels parallèles maintenus sous la forme [B, S, hc_mult, D] tout au long de chaque bloc. Deux modules DeepseekV4HyperConnection — attn_hc et ffn_hc — mélangent les flux en entrée et en sortie autour des sous-couches d'attention / MLP via un triplet (pre, post, comb). La matrice comb est une projection doublement stochastique produite par des itérations de Sinkhorn–Knopp hc_sinkhorn_iters sur la variété, rendant la propagation du signal non expansive à travers les piles profondes. Un DeepseekV4HyperHead final réduit les hc_mult flux en une seule séquence avant la normalisation du modèle.

Planification MoE (§2.1)

Le routage est configuré par couche via config.mlp_layer_types, avec des valeurs issues de {"hash_moe", "moe"} :

• "hash_moe" : les indices d’experts proviennent d’une table de correspondance figée tid2eid[input_ids] alimentée à partir du point de contrôle V4. Le poids appris de la porte weight produit toujours les scores par expert qui pondèrent les experts sélectionnés ; seul le choix des experts est statique. Utilisé pour les premières couches de démarrage (3 par défaut, modifiable via le paramètre hérité num_hash_layers).
• "moe" : MoE routé top-k standard. L’affinité des experts utilise Sqrt(Softplus(·)) au lieu du Sigmoid de V3 (« nous changeons la fonction d’activation qui calcule les scores d’affinité de Sigmoid(·) en Sqrt(Softplus(·)) », papier §2.1), et la contrainte n_group / topk_group de V3 est supprimée. La stratégie sans perte auxiliaire (noaux_tc de DeepSeek) est conservée via le tampon e_score_correction_bias qui biaise l’argmax top-k sans propager de gradients.

Les experts routés utilisent un SwiGLU borné (gate.clamp(max=swiglu_limit), up.clamp(min=-swiglu_limit, max=swiglu_limit), puis act_fn(gate) * up) au-dessus de la disposition standard des poids d’experts Mixtral [num_experts, 2 * moe_intermediate_size, hidden_size]. Un expert partagé unique (un MLP SwiGLU simple de largeur moe_intermediate_size) s’exécute en parallèle sur chaque jeton.

Disposition du masque d'attention

Chaque couche DeepseekV4Attention étend le masque causal à fenêtre glissante standard le long de l'axe des clés avec un block_bias renvoyé par son compresseur, puis transmet le masque concaténé à eager_attention_forward. La section glissante (gauche, [S, S]) est identique pour tous les types de couches ; la section compresseur (droite) varie selon le type de couche et constitue la pièce réellement « nouvelle » introduite par V4.

Les diagrammes ci-dessous ont été générés avec une configuration réduite (sliding_window=8, CSA m=4, HCA m'=8, index_topk=2) sur une entrée de 16 jetons afin que le masque complet par type de couche tienne à l'écran. Vert = la diagonale requête/clé dans la section glissante, foncé = une position KV standard visible, clair = masqué, ambre = un emplacement compresseur / indexeur auquel la requête est autorisée à prêter attention. Les colonnes situées après la ligne pointillée sont ajoutées par le compresseur via cat([sliding_causal_mask, block_bias], dim=-1).

Couche à glissement uniquement ("sliding_attention"). Aucun compresseur, aucun bourrage à droite — le masque est le masque causal à fenêtre glissante simple de forme [S, S] (fenêtre = 8). Pour i ≥ window, le triangle inférieur gauche est coupé, ce qui restaure le motif d’attention uniquement local.

Couche CSA ("compressed_sparse_attention"). Le compresseur aplati sa sortie collectée par requête en [B, 1, S·k, D] et remplit le masque à droite de S·k colonnes. Pour la requête t, seuls les k emplacements situés aux colonnes [S + t·k, S + (t+1)·k) contiennent les choix de l’indexeur ; toutes les autres colonnes du compresseur sont -inf. Les requêtes avant que la première fenêtre ne soit fermée (t < m − 1) ne reçoivent rien — le sentinel -1 de l’indexeur se propage directement dans le masque. À mesure que t augmente, davantage d’entrées compressées sont prêtes et l’indexeur peut remplir tous les k emplacements.

Couche HCA ("heavily_compressed_attention"). Aucun indexeur — chaque entrée compressée mise en cache est potentiellement visible. Remplissage à droite par T_total = entry_count["compressor"] colonnes. La requête t ne peut voir l'entrée w qu'une fois que sa fenêtre source est fermée, c'est-à-dire w < (t + 1) // m. Avec m=8 ici, les entrées 0 (couvre les positions 0..7) et 1 (couvre 8..15) ne deviennent visibles qu'à t ≥ 7 et t ≥ 15 respectivement.

Ces diagrammes sont reproductibles de bout en bout via :

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

Le script exécute un passage avant sur cette petite configuration, enveloppe chaque couche d’attention afin de capturer le masque exact post-cat([attention_mask, block_bias]), remappe le masque à slots plats [S, S·k] de CSA vers une vue de visibilité par entrée [S, T_entries] (chaque colonne C_w étant alors une entrée compressée, et non un slot de collecte), et génère les trois SVG ci-dessus. Il affiche également une grille ANSI sur la sortie standard pour une inspection rapide dans le terminal et déverse les choix top-k par requête de l’indexeur, afin que les sentinelles de préchauffage et les choix de sélection soient auditable.

Couches de cache

Chaque bloc d’attention non glissante doit transmettre l’état du compresseur / indexateur entre les appels de propagation avant. V4 fournit deux types de couche de cache qui s’enregistrent automatiquement dans LAYER_TYPE_CACHE_MAPPING :

• DeepseekV4HCACache : fenêtre glissante K=V + tampon / pool / compteur du compresseur HCA (sans chevauchement, sans indexeur).
• DeepseekV4CSACache : fenêtre glissante K=V + compresseur CSA (avec état de chevauchement) + indexeur parallèle tampon / pool / compteur / chevauchement à index_head_dim.

DynamicCache(config=…) construit la couche de cache appropriée pour chaque 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."