Model ini disumbangkan ke Hugging Face Transformers pada 2026-05-02.

DeepSeek-V4

DeepSeek-V4 adalah model bahasa MoE generasi berikutnya dari DeepSeek (paper). Arsitekturnya mengganti Multi-head Latent Attention (MLA) dari DeepSeek-V3 dengan desain hybrid lokal + jarak jauh, mengganti koneksi residual dengan Manifold-Constrained Hyper-Connections (mHC), dan mem-bootstrapping beberapa lapisan MoE pertama dengan tabel hash statis token-id → expert-id.

Implementasi ini mencakup DeepSeek-V4-Flash, DeepSeek-V4-Pro, dan saudara pretrained mereka -Base. Keempatnya berbagi arsitektur yang sama; mereka hanya berbeda dalam lebar / kedalaman / jumlah pakar dan bobot.

Setel use_kernels=True di from_pretrained() untuk mengganti lapisan yang didukung dengan kernel yang dioptimalkan dari Hub. Lihat Memuat kernel untuk mempelajari lebih lanjut.

Arsitektur (makalah §2)

Perhatian hibrida (§2.3)

Setiap blok decoder adalah salah satu dari tiga jenis perhatian, yang dikirimkan oleh config.layer_types[i]:

• Perhatian penuh jendela geser ("sliding_attention"): hanya jendela lokal dari sliding_window token, tanpa cabang jarak jauh. Cocok dengan gaya “Full Attention” V3 untuk lapisan bootstrap.
• Compressed Sparse Attention ("compressed_sparse_attention", CSA — paper §2.3.1): pool dengan kompresi rendah (compress_rate_csa, default m=4) dengan jendela yang tumpang tindih, ditambah Lightning Indexer (pers. 13–17) yang menilai query terhadap pool dan mengumpulkan index_topk blok teratas per query sebelum mencapai core attention.
• Perhatian Terkompresi Tinggi ("heavily_compressed_attention", HCA — paper §2.3.2): pool kompresi tinggi (compress_rate_hca, default m'=128) dengan jendela yang tidak tumpang tindih. Tidak ada indexer — setiap entri yang di-pool berkontribusi pada perhatian.

Ketiga tipe ini berbagi backbone yang sama:

• Shared K=V Multi-Query Attention: num_key_value_heads = 1; kv_proj menghasilkan satu kepala KV dan tensor yang sama dibaca sebagai kunci dan nilai.
• Partial RoPE (interleaved-pair, paper §2.3.3 “Partial Rotary Positional Embedding”) pada qk_rope_head_dim = head_dim * partial_rotary_factor channel terakhir dari setiap head. Rotasi yang sama diterapkan dengan posisi -i pada slice rope dari output attention (eq. 26) sehingga kontribusi dari setiap entri KV tetap menjadi fungsi dari jarak relatif ke query.
• Per-head learnable attention sink (pers. 27).
• Proyeksi output ber-rank rendah berkelompok (§2.3.1 “Grouped Output Projection”): o_groups grup kepala → o_lora_rank per grup → hidden_size, dihitung oleh DeepseekV4GroupedLinear (o_a_proj) yang diikuti oleh o_b_proj. Mengurangi biaya per token dari output perhatian yang lebar tanpa kehilangan ekspresivitas.
• Cabang K=V sliding-window bersama berukuran sliding_window (“Additional Branch of Sliding Window Attention”, §2.3.1) mempertahankan dependensi lokal yang halus; keluaran kompresor jarak jauh digabungkan dengan KV cabang ini sebelum perhatian inti.

Hyper-Connections dengan Kendala Manifold (§2.2)

Koneksi residual diganti oleh mHC (Xie et al., 2026): hc_mult aliran residual paralel yang dipertahankan dalam bentuk [B, S, hc_mult, D] di sepanjang setiap blok. Dua modul DeepseekV4HyperConnection — attn_hc dan ffn_hc — mencampur aliran masuk dan keluar di sekitar sublayer attention / MLP melalui triplet (pre, post, comb). Matriks comb adalah proyeksi doubly-stochastic yang dihasilkan oleh iterasi Sinkhorn–Knopp hc_sinkhorn_iters pada manifold, sehingga membuat propagasi sinyal menjadi non-expansive di seluruh tumpukan yang dalam. DeepseekV4HyperHead terakhir meruntuhkan hc_mult aliran menjadi satu urutan tunggal sebelum model norm.

Jadwal MoE (§2.1)

Routing dikonfigurasi per lapisan oleh config.mlp_layer_types, dengan nilai dari {"hash_moe", "moe"}:

• "hash_moe": indeks expert berasal dari pencarian tid2eid[input_ids] yang dibekukan dan diisi dari checkpoint V4. Bobot gerbang yang dipelajari weight tetap menghasilkan skor per-expert yang menimbang expert yang dipilih; hanya expert mana yang statis. Digunakan untuk beberapa lapisan bootstrap pertama (default 3, dapat ditimpa melalui num_hash_layers legacy).
• "moe": MoE top-k routed standar. Afinitas pakar menggunakan Sqrt(Softplus(·)) alih-alih Sigmoid dari V3 (“we change the activation function that computes the affinity scores from Sigmoid(·) into Sqrt(Softplus(·))”, paper §2.1), dan kendala n_group / topk_group dari V3 dihapus. Strategi tanpa auxiliary-loss (DeepSeek’s noaux_tc) dipertahankan melalui buffer e_score_correction_bias yang memberikan bias pada top-k argmax tanpa mengalirkan gradien.

Routed experts menggunakan clamped SwiGLU (gate.clamp(max=swiglu_limit), up.clamp(min=-swiglu_limit, max=swiglu_limit), lalu act_fn(gate) * up) di atas tata letak bobot expert Mixtral standar [num_experts, 2 * moe_intermediate_size, hidden_size]. Satu expert bersama (MLP SwiGLU biasa dengan lebar moe_intermediate_size) berjalan secara paralel pada setiap token.

Tata letak attention mask

Setiap lapisan DeepseekV4Attention memperluas mask sliding-window-causal standar di sepanjang sumbu key dengan block_bias yang dikembalikan oleh kompresornya, kemudian memberikan mask yang digabungkan tersebut ke eager_attention_forward. Bagian sliding-section (kiri, [S, S]) sama untuk setiap jenis lapisan; bagian compressor-section (kanan) berbeda berdasarkan jenis lapisan dan merupakan bagian “baru” yang sebenarnya diperkenalkan oleh V4.

Diagram di bawah dibuat dengan konfigurasi kecil (sliding_window=8, CSA m=4, HCA m'=8, index_topk=2) pada input 16 token agar mask lengkap per jenis layer muat di layar. Hijau = diagonal query/key pada bagian sliding, gelap = posisi KV standar yang terlihat, terang = ter-mask, amber = slot kompresor / indexer yang boleh diperhatikan oleh query. Kolom setelah garis putus-putus ditambahkan oleh kompresor melalui cat([sliding_causal_mask, block_bias], dim=-1).

Lapisan sliding-only ("sliding_attention"). Tidak ada kompresor, tidak ada right-padding — mask-nya adalah mask sliding-window-causal polos dengan bentuk [S, S] (window = 8). Untuk i ≥ window, segitiga kiri-bawah dipotong, sehingga memulihkan pola perhatian lokal-only.

Lapisan CSA ("compressed_sparse_attention"). Kompresor meratakan output terkumpul per query-nya menjadi [B, 1, S·k, D] dan mengisi mask di sisi kanan dengan S·k kolom. Untuk query t, hanya k slot di kolom [S + t·k, S + (t+1)·k) yang membawa pilihan indexer; semua kolom kompresor lainnya bernilai -inf. Query sebelum jendela pertama tertutup (t < m − 1) tidak mendapat apa-apa — sentinel -1 dari indexer langsung menyebar ke mask. Seiring t membesar, lebih banyak entri terkompresi yang siap dan indexer dapat mengisi semua k slot.

Lapisan HCA ("heavily_compressed_attention"). Tidak ada indexer — setiap entri terkompresi yang di-cache berpotensi terlihat. Di-pad ke kanan dengan T_total = entry_count["compressor"] kolom. Query t hanya dapat melihat entri w setelah jendela sumbernya tertutup, yaitu w < (t + 1) // m. Dengan m=8 di sini, entri 0 (menutupi posisi 0..7) dan 1 (menutupi 8..15) baru menjadi terlihat pada t ≥ 7 dan t ≥ 15 masing-masing.

Diagram-diagram ini dapat direproduksi secara end-to-end melalui:

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

Skrip menjalankan forward pass pada konfigurasi kecil ini, membungkus setiap lapisan perhatian untuk menangkap mask pasca-cat([attention_mask, block_bias]) yang tepat, memetakan ulang mask flat-slot [S, S·k] CSA kembali ke tampilan visibilitas entri [S, T_entries] (sehingga setiap kolom C_w adalah entri yang dikompresi, bukan slot gather), dan menulis tiga SVG di atas. Skrip ini juga mencetak grid ANSI ke stdout untuk inspeksi terminal yang cepat dan menyimpan pilihan top-k per-query dari indexer sehingga sentinel warm-up dan pilihan pick dapat diaudit.

Lapisan cache

Setiap blok perhatian non-sliding perlu mengalirkan state kompresor / indexer di antara panggilan forward. V4 menyediakan dua tipe lapisan cache yang otomatis terdaftar dengan LAYER_TYPE_CACHE_MAPPING:

• DeepseekV4HCACache: buffer / pool / count kompresor HCA untuk K=V jendela geser (tanpa tumpang tindih, tanpa indexer).
• DeepseekV4CSACache: sliding-window K=V + kompresor CSA (dengan state overlap) + indexer paralel buffer / pool / count / overlap pada index_head_dim.

DynamicCache(config=…) membangun lapisan cache yang tepat untuk setiap 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."