このモデルは2026年5月2日にHugging Face Transformersに貢献されました。

DeepSeek-V4

DeepSeek-V4は、DeepSeekによる次世代MoE言語モデルです（論文）。このアーキテクチャでは、DeepSeek-V3のMulti-head Latent Attention (MLA)をローカルと長距離のハイブリッド設計に置き換え、残差接続をManifold-Constrained Hyper-Connections (mHC)に変更し、最初の数層のMoE層には静的なtoken-id → expert-idハッシュテーブルでブートストラップを行います。

この実装は、DeepSeek-V4-Flash、DeepSeek-V4-Pro、およびそれらの-Base事前学習モデルをカバーしています。4モデルはいずれも同じアーキテクチャを共有しており、幅 / 深さ / エキスパート数と重みのみ異なります。

use_kernels=True を from_pretrained() に設定すると、対応するレイヤーが Hub からの最適化されたカーネルに置き換えられます。詳細は カーネルの読み込み を参照してください。

アーキテクチャ（論文 §2）

ハイブリッドアテンション(§2.3)

各デコーダーブロックは3つのアテンションタイプのいずれかであり、config.layer_types[i]によってディスパッチされます。

• スライディングウィンドウによるフルアテンション（"sliding_attention"）: sliding_windowトークンのローカルウィンドウのみを対象とし、長距離ブランチは使用しません。ブートストラップレイヤーにおいて、V3の「Full Attention」スタイルと一致します。
• Compressed Sparse Attention（"compressed_sparse_attention"、CSA — 論文 §2.3.1）: 重複するウィンドウを持つ低圧縮プール（compress_rate_csa、デフォルトは m=4）と、クエリをプールに対してスコアリングし、コアアテンションに到達する前にクエリごとに上位 index_topk ブロックを集める Lightning Indexer（式 13–17）から構成されます。
• Heavily Compressed Attention（"heavily_compressed_attention"、HCA — 論文 §2.3.2）: 重複しないウィンドウを用いた高圧縮プール（compress_rate_hca、デフォルトは m'=128）。インデクサーは不要であり、プールされたすべてのエントリがアテンションに寄与します。

3つのタイプはすべて同じバックボーンを共有しています:

• 共有 K=V マルチクエリアテンション: num_key_value_heads = 1; kv_proj は単一の KV ヘッドを生成し、同じテンソルがキーとバリューの両方として読み取られます。
• Partial RoPE（interleaved-pair、論文 §2.3.3 “Partial Rotary Positional Embedding”）は、各ヘッドの末尾の qk_rope_head_dim = head_dim * partial_rotary_factor チャネルに適用されます。同じ回転が、位置 -i を用いてアテンション出力の rope スライス（式 26）にも適用されるため、各 KV エントリの寄与はクエリからの相対距離の関数として保持されます。
• ヘッドごとの学習可能なアテンションシンク(式 27)。
• グループ化された低ランク出力投影（§2.3.1 “Grouped Output Projection”）: o_groups 個のヘッドグループ → グループごとに o_lora_rank → hidden_size。まず DeepseekV4GroupedLinear（o_a_proj）で計算し、続いて o_b_proj を適用します。表現力を損なうことなく、広いアテンション出力のトークンごとのコストを削減します。
• サイズ sliding_window の共有スライディングウィンドウ K=V ブランチ（「Additional Branch of Sliding Window Attention」、§2.3.1）は、局所的な細粒度の依存関係を保持します。長距離コンプレッサーの出力は、コアアテンションの前にこのブランチの KV と連結されます。

Manifold-Constrained Hyper-Connections（§2.2）

Residual connections are replaced by mHC (Xie et al., 2026): hc_mult parallel residual streams kept in shape [B, S, hc_mult, D] throughout each block. Two DeepseekV4HyperConnection modules — attn_hc and ffn_hc — mix streams in and out around the attention / MLP sublayers via a (pre, post, comb) triplet. The comb matrix is a doubly-stochastic projection produced by hc_sinkhorn_iters Sinkhorn–Knopp iterations on the manifold, making signal propagation non-expansive across deep stacks. A final DeepseekV4HyperHead collapses the hc_mult streams down to a single sequence before the model norm.

MoEスケジュール(§2.1)

ルーティングはconfig.mlp_layer_typesによってレイヤーごとに設定され、{"hash_moe", "moe"}のいずれかの値が指定されます。

• "hash_moe": エキスパートのインデックスは、V4 チェックポイントから設定された凍結済みのtid2eid[input_ids]ルックアップから取得されます。学習されたゲートのweightは、選択されたエキスパートを重み付けするためのエキスパートごとのスコアを依然として生成します。静的なのはどのエキスパートを選択するかのみです。最初の数層のブートストラップ層に使用されます（デフォルトは 3 層、レガシーのnum_hash_layersで上書き可能）。
• "moe": 標準的な top-k ルーティング MoE。エキスパートのアフィニティには、V3 の Sigmoid の代わりに Sqrt(Softplus(·)) が使用されます（「アフィニティスコアを計算する活性化関数を Sigmoid(·) から Sqrt(Softplus(·)) に変更する」、論文 §2.1）。また、V3 の n_group / topk_group 制約は廃止されています。DeepSeek の noaux_tc による補助損失なし戦略は、e_score_correction_bias バッファを介して維持されており、このバッファは勾配を伝播させることなく top-k argmax にバイアスを付与します。

Routed experts は、標準的な Mixtral の [num_experts, 2 * moe_intermediate_size, hidden_size] 形式のエキスパート重みレイアウトの上に、clamped SwiGLU（gate.clamp(max=swiglu_limit)、up.clamp(min=-swiglu_limit, max=swiglu_limit)、その後 act_fn(gate) * up）を使用します。単一の共有エキスパート（幅が moe_intermediate_size の通常の SwiGLU MLP）は、すべてのトークンに対して並列に実行されます。

アテンションマスクのレイアウト

各 DeepseekV4Attention レイヤーは、キー軸に沿って標準的なスライディングウィンドウ因果マスクを、そのコンプレッサーが返す block_bias で拡張し、その後、連結されたマスクを eager_attention_forward に渡します。スライディングセクション（左、[S, S]）はすべてのレイヤータイプで同一ですが、コンプレッサーセクション（右）はレイヤータイプによって異なり、V4 で導入された実際の「新規」部分です。

以下の図は、16トークンの入力に対して、各レイヤータイプのマスク全体を画面に収めるために、非常に小さな設定（sliding_window=8、CSA m=4、HCA m'=8、index_topk=2）で生成されました。緑 = スライディングセクションにおけるクエリ/キーの対角線、濃い色 = 可視の標準KV位置、薄い色 = マスク済み、アンバー = クエリがアテンションを許可されるコンプレッサー/インデクサーのスロットです。破線より右の列は、コンプレッサーによってcat([sliding_causal_mask, block_bias], dim=-1)で追加されます。

スライディング専用レイヤー（"sliding_attention"）。コンプレッサーも右パディングもありません。マスクは、[S, S] の形状を持つ通常のスライディングウィンドウ因果マスク（ウィンドウ = 8）です。i ≥ window の場合、左下の三角形が切り取られ、ローカル専用のアテンションパターンが復元されます。

CSA レイヤー（"compressed_sparse_attention"）。コンプレッサーは、クエリごとに集約した出力を [B, 1, S·k, D] にフラット化し、マスクを S·k 列だけ右パディングします。クエリ t に対しては、[S + t·k, S + (t+1)·k) の列にある k スロットにのみインデクサーの選択結果が格納され、それ以外のコンプレッサーの列はすべて -inf になります。最初のウィンドウが閉じる前のクエリ（t < m − 1）には何も与えられず、インデクサーの -1 センチネル値がそのままマスクに伝播します。t が大きくなるにつれて、利用可能な圧縮エントリが増え、インデクサーは k 個のスロットすべてを埋めることができます。

HCA レイヤー（"heavily_compressed_attention"）。インデクサーはありません。キャッシュされた圧縮エントリはすべて、潜在的に可視化されます。T_total = entry_count["compressor"] 列分だけ右パディングされます。クエリ t がエントリ w を参照できるのは、そのソースウィンドウがクローズした後のみです。つまり、w < (t + 1) // m の場合です。ここでは m=8 であるため、エントリ 0（位置 0..7 をカバー）とエントリ 1（8..15 をカバー）は、それぞれ t ≥ 7 および t ≥ 15 で初めて可視化されます。

これらの図は、以下を通じてエンドツーエンドで再現できます:

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

このスクリプトは、この小さな設定に対してフォワードパスを実行し、各アテンション層をラップして、cat([attention_mask, block_bias]) 適用後の正確なマスクをキャプチャします。次に、CSA の [S, S·k] フラットスロットマスクを [S, T_entries] エントリ可視性ビューに再マッピングします（これにより、各 C_w 列は集約スロットではなく、圧縮されたエントリになります）。最後に、上記の 3 つの SVG を書き出します。また、ターミナルでの素早い確認のために ANSI グリッドを標準出力に出力し、インデクサーのクエリごとのトップ k 選択をダンプして、ウォームアップのセンチネルと選択内容が監査可能になります。

キャッシュレイヤー

各非スライディングアテンションブロックは、フォワード呼び出し間でコンプレッサー / インデクサーの状態をスレッドする必要があります。V4には、LAYER_TYPE_CACHE_MAPPINGに自動登録される2つのキャッシュレイヤータイプが同梱されています:

• DeepseekV4HCACache: スライディングウィンドウ K=V + HCA コンプレッサバッファ / プール / カウント（重複なし、インデクサなし）。
• DeepseekV4CSACache: スライディングウィンドウ K=V + CSA コンプレッサー（オーバーラップ状態付き）+ 並列インデクサー index_head_dim でのバッファ / プール / カウント / オーバーラップ

DynamicCache(config=…) は、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."