Mô hình này đã được đóng góp cho Hugging Face Transformers vào ngày 2026-05-02.

DeepSeek-V4

DeepSeek-V4 là mô hình ngôn ngữ MoE thế hệ tiếp theo từ DeepSeek (bài báo). Kiến trúc thay thế Multi-head Latent Attention (MLA) của DeepSeek-V3 bằng thiết kế hybrid local + long-range, thay thế các kết nối residual bằng Manifold-Constrained Hyper-Connections (mHC), và khởi tạo vài lớp MoE đầu tiên bằng bảng băm tĩnh token-id → expert-id.

Cài đặt này bao gồm DeepSeek-V4-Flash, DeepSeek-V4-Pro và các phiên bản -Base được huấn luyện trước của chúng. Cả bốn đều chia sẻ cùng một kiến trúc; chúng chỉ khác nhau về độ rộng / độ sâu / số lượng chuyên gia và trọng số.

Đặt use_kernels=True trong from_pretrained() để thay thế các lớp được hỗ trợ bằng các kernel tối ưu từ Hub. Xem Tải kernel để biết thêm.

Kiến trúc (bài báo §2)

Chú ý lai (§2.3)

Mỗi khối decoder là một trong ba loại attention, được điều phối bởi config.layer_types[i]:

• Chú ý đầy đủ theo cửa sổ trượt ("sliding_attention"): chỉ bao gồm cửa sổ cục bộ gồm sliding_window token, không có nhánh tầm xa. Phù hợp với phong cách “Full Attention” của V3 cho các lớp khởi tạo.
• Compressed Sparse Attention ("compressed_sparse_attention", CSA — bài báo §2.3.1): một pool nén thấp (compress_rate_csa, mặc định m=4) với các cửa sổ chồng lấn, cùng với Lightning Indexer (các phương trình 13–17) đánh điểm các query so với pool và thu thập index_topk khối hàng đầu cho mỗi query trước khi chúng đến core attention.
• Heavily Compressed Attention ("heavily_compressed_attention", HCA — bài báo §2.3.2): một pool nén cao (compress_rate_hca, mặc định m'=128) với các cửa sổ không chồng lấn. Không có indexer — mọi mục được pool đều đóng góp vào attention.

Cả ba loại đều chia sẻ cùng một phần lõi:

• Chú ý Multi-Query với K=V dùng chung: num_key_value_heads = 1; kv_proj tạo ra một đầu KV duy nhất và cùng một tensor được đọc như cả key lẫn value.
• Partial RoPE (interleaved-pair, mục 2.3.3 trong bài báo “Partial Rotary Positional Embedding”) được áp dụng trên qk_rope_head_dim = head_dim * partial_rotary_factor kênh cuối của mỗi head. Cùng một phép quay được áp dụng với vị trí -i lên phần rope của đầu ra attention (phương trình 26) để đảm bảo đóng góp của mỗi mục KV vẫn là một hàm của khoảng cách tương đối so với query.
• Chìm chú ý có thể học được theo từng đầu (phương trình 27).
• Chiếu đầu ra hạng thấp nhóm (§2.3.1 “Grouped Output Projection”): o_groups nhóm đầu → o_lora_rank mỗi nhóm → hidden_size, được tính bởi DeepseekV4GroupedLinear (o_a_proj) tiếp theo là o_b_proj. Giảm chi phí cho mỗi token của đầu ra chú ý rộng mà không mất đi khả năng biểu diễn.
• Nhánh K=V trượt cửa sổ dùng chung có kích thước sliding_window (“Additional Branch of Sliding Window Attention”, §2.3.1) bảo toàn các phụ thuộc cục bộ chi tiết; đầu ra của bộ nén tầm xa được nối với KV của nhánh này trước khi thực hiện chú ý lõi.

Kết nối siêu bị ràng buộc đa tạp (§2.2)

Các kết nối dư (residual connections) được thay thế bằng mHC (Xie et al., 2026): hc_mult luồng dư song song được giữ ở hình dạng [B, S, hc_mult, D] xuyên suốt mỗi khối. Hai module DeepseekV4HyperConnection — attn_hc và ffn_hc — trộn các luồng vào và ra xung quanh các lớp con attention / MLP thông qua bộ ba (pre, post, comb). Ma trận comb là một phép chiếu doubly-stochastic được tạo ra bởi hc_sinkhorn_iters bước lặp Sinkhorn–Knopp trên đa tạp, khiến sự lan truyền tín hiệu không mở rộng (non-expansive) qua các chồng mạng sâu. Một DeepseekV4HyperHead cuối cùng thu gọn hc_mult luồng xuống còn một chuỗi duy nhất trước khi thực hiện chuẩn hóa mô hình.

Lịch trình MoE (§2.1)

Routing được cấu hình theo từng lớp bằng config.mlp_layer_types, với các giá trị từ {"hash_moe", "moe"}:

• "hash_moe": các chỉ số chuyên gia được lấy từ bảng tra tid2eid[input_ids] đã đóng băng, được nạp từ checkpoint V4. Trọng số cổng học được weight vẫn tạo ra các điểm số cho từng chuyên gia để trọng số hóa các chuyên gia được chọn; chỉ có chuyên gia nào là tĩnh. Được dùng cho một vài lớp khởi tạo đầu tiên (mặc định là 3, ghi đè bằng num_hash_layers cũ).
• "moe": MoE top-k định tuyến chuẩn. Độ ưu tiên chuyên gia sử dụng Sqrt(Softplus(·)) thay vì Sigmoid của V3 (“chúng tôi thay đổi hàm kích hoạt tính điểm độ ưu tiên từ Sigmoid(·) sang Sqrt(Softplus(·))”, giấy §2.1), và ràng buộc n_group / topk_group của V3 bị bỏ. Chiến lược không có tổn thất phụ (noaux_tc của DeepSeek) được giữ lại thông qua bộ đệm e_score_correction_bias làm lệch argmax top-k mà không truyền gradient.

Các chuyên gia được định tuyến sử dụng SwiGLU bị kẹp (gate.clamp(max=swiglu_limit), up.clamp(min=-swiglu_limit, max=swiglu_limit), sau đó là act_fn(gate) * up) trên bố cục trọng số chuyên gia Mixtral chuẩn [num_experts, 2 * moe_intermediate_size, hidden_size]. Một chuyên gia dùng chung duy nhất (một MLP SwiGLU thông thường có độ rộng moe_intermediate_size) chạy song song trên mọi token.

Bố cục mặt nạ chú ý

Mỗi lớp DeepseekV4Attention mở rộng mặt nạ trượt cửa sổ nhân quả chuẩn dọc theo trục key bằng block_bias do bộ nén của nó trả về, sau đó truyền mặt nạ đã nối vào eager_attention_forward. Phần trượt (bên trái, [S, S]) giống nhau cho mọi loại lớp; phần bộ nén (bên phải) khác nhau tùy theo loại lớp và là phần “mới” thực sự được giới thiệu bởi V4.

Các sơ đồ bên dưới được tạo với một cấu hình nhỏ (sliding_window=8, CSA m=4, HCA m'=8, index_topk=2) trên một đầu vào 16 token để toàn bộ mask theo từng loại lớp vừa vặn trên màn hình. Màu xanh lá = đường chéo query/key trong phần trượt, màu đậm = một vị trí KV chuẩn có thể nhìn thấy, màu nhạt = bị mask, màu hổ phách = một slot của bộ nén / bộ chỉ mục mà query được phép chú ý đến. Các cột nằm sau đường đứt nét được thêm vào bởi bộ nén thông qua cat([sliding_causal_mask, block_bias], dim=-1).

Chỉ lớp trượt ("sliding_attention"). Không có bộ nén, không có đệm bên phải — mặt nạ là mặt nạ nhân quả cửa sổ trượt đơn giản có hình dạng [S, S] (cửa sổ = 8). Với i ≥ window, tam giác dưới bên trái bị cắt bỏ, khôi phục lại mẫu chú ý chỉ cục bộ.

CSA layer ("compressed_sparse_attention"). Bộ nén làm phẳng đầu ra thu thập theo từng truy vấn của nó thành [B, 1, S·k, D] và đệm bên phải mặt nạ thêm S·k cột. Đối với truy vấn t, chỉ có k ô ở các cột [S + t·k, S + (t+1)·k) chứa các lựa chọn của bộ chỉ mục; tất cả các cột bộ nén khác đều là -inf. Các truy vấn trước khi cửa sổ đầu tiên đóng lại (t < m − 1) không nhận được gì — giá trị sentinel -1 của bộ chỉ mục được truyền thẳng đến mặt nạ. Khi t tăng lên, nhiều mục đã nén hơn sẵn sàng và bộ chỉ mục có thể điền đầy tất cả k ô.

Tầng HCA ("heavily_compressed_attention"). Không có indexer — mọi mục nén được lưu trong cache đều có khả năng hiển thị. Phần đệm bên phải gồm T_total = entry_count["compressor"] cột. Query t chỉ có thể nhìn thấy mục w khi cửa sổ nguồn của nó đã đóng, tức là w < (t + 1) // m. Với m=8 ở đây, mục 0 (bao phủ các vị trí 0..7) và 1 (bao phủ 8..15) chỉ trở nên hiển thị lần lượt tại t ≥ 7 và t ≥ 15.

Các sơ đồ này có thể tái tạo được từ đầu đến cuối thông qua:

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

Script thực hiện một bước truyền tiến trên cấu hình nhỏ này, bọc mỗi lớp attention để bắt chính xác mask sau cat([attention_mask, block_bias]), ánh xạ lại mask slot phẳng [S, S·k] của CSA về dạng hiển thị khả kiến entry [S, T_entries] (để mỗi cột C_w là một entry đã nén, không phải một slot gather), và ghi ba tệp SVG ở trên. Nó cũng in một lưới ANSI ra stdout để kiểm tra nhanh trên terminal và xuất các lựa chọn top-k theo từng query của indexer để có thể kiểm toán các sentinel khởi động nóng và các lựa chọn pick.

Các lớp bộ nhớ đệm

Mỗi khối chú ý trượt (non-sliding attention) cần truyền trạng thái bộ nén / bộ chỉ mục (compressor / indexer) qua các lần gọi forward. V4 cung cấp hai loại lớp cache tự đăng ký với LAYER_TYPE_CACHE_MAPPING:

• DeepseekV4HCACache: bộ đệm K=V cửa sổ trượt + bộ đệm/bộ đếm/bộ đệm nén HCA (không chồng lấn, không có bộ chỉ mục).
• DeepseekV4CSACache: cửa sổ trượt K=V + bộ nén CSA (có trạng thái chồng lấn) + bộ chỉ mục song song buffer / pool / count / overlap tại index_head_dim.

DynamicCache(config=…) xây dựng lớp cache phù hợp cho từng 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."