이 모델은 2026-05-02에 Hugging Face Transformers에 기여되었습니다.

DeepSeek-V4

DeepSeek-V4는 DeepSeek의 차세대 MoE 언어 모델(논문)입니다. 이 아키텍처는 DeepSeek-V3의 Multi-head Latent Attention(MLA)을 로컬 + 장거리 하이브리드 설계로 대체하고, residual connections을 Manifold-Constrained Hyper-Connections(mHC)로 교체하며, 처음 몇 개의 MoE 레이어를 정적 token-id → expert-id 해시 테이블로 부트스트랩합니다.

이 구현은 DeepSeek-V4-Flash, DeepSeek-V4-Pro 및 해당 -Base 사전 학습 모델을 대상으로 합니다. 네 모델 모두 동일한 아키텍처를 공유하며, 폭 / 깊이 / 전문가 수와 가중치에서만 차이가 있습니다.

use_kernels=True를 from_pretrained()에 설정하여 Hub의 최적화 커널로 지원되는 레이어를 대체합니다. 자세한 내용은 커널 로딩을 참고하세요.

아키텍처(논문 §2)

하이브리드 어텐션(§2.3)

각 decoder block은 config.layer_types[i]에 의해 분기되는 세 가지 attention 유형 중 하나입니다:

• 슬라이딩 윈도우 전체 어텐션 ("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", HCA — 논문 §2.3.2): 겹치지 않는 윈도우를 사용하는 고압축 풀링(compress_rate_hca, 기본값 m'=128). 인덱서가 없으며, 모든 풀링된 항목이 어텐션에 기여합니다.

세 가지 유형 모두 동일한 백본을 공유합니다:

• 공유 K=V 멀티-쿼리 어텐션: num_key_value_heads = 1; kv_proj가 단일 KV 헤드를 생성하고 동일한 텐서가 키와 값으로 모두 읽힙니다.
• 각 헤드의 뒤쪽 qk_rope_head_dim = head_dim * partial_rotary_factor 채널에 Partial RoPE(interleaved-pair, 논문 §2.3.3 “Partial Rotary Positional Embedding”)를 적용합니다. 동일한 회전은 attention 출력의 rope 슬라이스에 위치 -i로 적용되어(eq. 26), 각 KV 항목의 기여도가 query에 대한 상대 거리의 함수로 유지됩니다.
• 헤드별 학습 가능한 어텐션 싱크 (식 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은 mHC(Xie et al., 2026)로 대체됩니다: 각 블록 전체에서 hc_mult개의 병렬 residual stream이 [B, S, hc_mult, D] 형태로 유지됩니다. DeepseekV4HyperConnection 모듈 두 개, 즉 attn_hc와 ffn_hc가 (pre, post, comb) 3원조를 통해 attention / MLP 서브레이어 주위로 stream을 혼합합니다. comb 행렬은 매니폴드에서 hc_sinkhorn_iters Sinkhorn–Knopp 반복을 통해 생성되는 doubly-stochastic projection으로, 깊은 스택에 걸쳐 신호 전파가 비확장(non-expansive)이 되도록 합니다. 마지막 DeepseekV4HyperHead가 모델 norm 전에 hc_mult개의 stream을 단일 시퀀스로 축소합니다.

MoE 스케줄(§2.1)

라우팅은 config.mlp_layer_types를 통해 레이어별로 설정되며, 값은 {"hash_moe", "moe"} 중 하나입니다:

• "hash_moe": expert indices는 V4 checkpoint에서 채워진 동결된 tid2eid[input_ids] 조회에서 가져옵니다. 학습된 게이트 weight는 여전히 선택된 expert를 가중하는 per-expert scores를 생성하며, 어떤 expert를 선택하는지만 정적입니다. 처음 몇 개의 bootstrap layer(기본값 3, legacy 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] expert weight layout 위에 clamped SwiGLU (gate.clamp(max=swiglu_limit), up.clamp(min=-swiglu_limit, max=swiglu_limit), 그 다음 act_fn(gate) * up)를 사용합니다. 단일 shared expert(moe_intermediate_size 폭의 일반 SwiGLU MLP)는 모든 token에 대해 병렬로 실행됩니다.

Attention mask 레이아웃

각 DeepseekV4Attention 레이어는 압축기(compressor)가 반환하는 block_bias를 사용하여 키 축을 따라 표준 슬라이딩 윈도우 카우zal 마스크를 확장한 뒤, 연결된 마스크를 eager_attention_forward에 전달합니다. 슬라이딩 섹션(왼쪽, [S, S])은 모든 레이어 유형에서 동일하며, 압축기 섹션(오른쪽)은 레이어 유형에 따라 달라지며 V4에서 도입된 실제 “신규” 부분입니다.

아래 다이어그램은 16-token 입력에 대해 매우 작은 설정(sliding_window=8, CSA m=4, HCA m'=8, index_topk=2)으로 생성되어 레이어 유형별 전체 마스크가 화면에 들어오도록 했습니다. 녹색 = 슬라이딩 섹션의 query/key 대각선, 어두운 색 = 가시적인 표준 KV 위치, 밝은 색 = 마스크 처리됨, 앰버 = query가 attend할 수 있는 compressor / indexer 슬롯. 점선 너머의 열은 compressor가 cat([sliding_causal_mask, block_bias], dim=-1)을 통해 추가합니다.

슬라이딩 전용 레이어("sliding_attention"). 압축기나 오른쪽 패딩이 없으며, 마스크는 [S, S] 크기의 일반 슬라이딩 윈도우 카우zal 마스크입니다(윈도우 = 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 < (t + 1) // m일 때에만 항목 w를 볼 수 있습니다. 여기서 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

스크립트는 이 작은 config에 대해 forward pass를 실행하고, 각 attention layer를 래핑하여 cat([attention_mask, block_bias]) 이후의 정확한 mask를 캡처합니다. 또한 CSA의 [S, S·k] flat-slot mask를 [S, T_entries] entry-visibility view로 다시 매핑합니다(각 C_w 열은 gather slot이 아닌 압축된 entry가 됩니다). 그리고 위에서 언급한 세 개의 SVG를 작성합니다. 또한 빠른 터미널 검사를 위해 stdout에 ANSI grid를 출력하고, warm-up sentinel과 pick 선택이 감사(audit) 가능하도록 indexer의 per-query top-k 선택 결과를 덤프합니다.

캐시 레이어

각 non-sliding attention 블록은 forward 호출 간에 compressor / indexer 상태를 전달해야 합니다. V4에는 LAYER_TYPE_CACHE_MAPPING에 자동 등록되는 두 가지 cache layer 유형이 포함되어 있습니다:

• 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."