Este modelo fue aportado a Hugging Face Transformers el 2026-05-02.

DeepSeek-V4

DeepSeek-V4 es el modelo de lenguaje MoE de próxima generación de DeepSeek (paper). La arquitectura reemplaza la atención latente multi-cabeza (MLA) de DeepSeek-V3 por un diseño híbrido de alcance local + largo, sustituye las conexiones residuales por conexiones hiperbólicas con restricciones de variedad (mHC) y arranca las primeras capas MoE con una tabla de hash estática de token-id → expert-id.

Esta implementación cubre DeepSeek-V4-Flash, DeepSeek-V4-Pro y sus variantes preentrenadas -Base. Las cuatro comparten la misma arquitectura; solo difieren en anchura / profundidad / número de expertos y pesos.

Establezca use_kernels=True en from_pretrained() para reemplazar las capas compatibles con kernels optimizados del Hub. Consulte Carga de kernels para obtener más información.

Arquitectura (papel §2)

Atención híbrida (§2.3)

Cada bloque decodificador es uno de tres tipos de atención, asignado por config.layer_types[i]:

• Atención completa con ventana deslizante ("sliding_attention"): solo la ventana local de sliding_window tokens, sin rama de largo alcance. Coincide con el estilo “Full Attention” de V3 para las capas de arranque.
• Compressed Sparse Attention ("compressed_sparse_attention", CSA — paper §2.3.1): un pool de baja compresión (compress_rate_csa, valor predeterminado m=4) con ventanas superpuestas, más un Lightning Indexer (ec. 13–17) que puntúa las consultas contra el pool y recopila los index_topk bloques principales por consulta antes de que lleguen a la atención principal.
• Atención altamente comprimida ("heavily_compressed_attention", HCA — paper §2.3.2): un pool de alta compresión (compress_rate_hca, valor predeterminado m'=128) con ventanas no superpuestas. Sin indexer: cada entrada del pool contribuye a la atención.

Los tres tipos comparten el mismo esqueleto:

• Atención multiconsulta con K=V compartidos: num_key_value_heads = 1; kv_proj produce una única cabeza KV y el mismo tensor se lee como clave y como valor.
• RoPE parcial (interleaved-pair, sección 2.3.3 del artículo “Partial Rotary Positional Embedding”) en los canales finales qk_rope_head_dim = head_dim * partial_rotary_factor de cada cabeza. Se aplica la misma rotación con posición -i a la porción rope de la salida de atención (ec. 26) para que la contribución de cada entrada KV siga siendo una función de la distancia relativa a la consulta.
• Sumidero de atención aprendible por cabeza (ec. 27).
• Proyección de salida de bajo rango agrupada (§2.3.1 “Grouped Output Projection”): o_groups grupos de cabezas → o_lora_rank por grupo → hidden_size, calculada por DeepseekV4GroupedLinear (o_a_proj) seguida de o_b_proj. Reduce el coste por token de la salida de atención ancha sin perder expresividad.
• La rama compartida de ventana deslizante K=V de tamaño sliding_window (“Additional Branch of Sliding Window Attention”, §2.3.1) preserva las dependencias locales de grano fino; la salida del compresor de largo alcance se concatena con los KV de esta rama antes de la atención principal.

Hiperconexiones con restricciones de variedad (§2.2)

Las conexiones residuales se reemplazan por mHC (Xie et al., 2026): hc_mult flujos residuales paralelos mantenidos en la forma [B, S, hc_mult, D] a lo largo de cada bloque. Dos módulos DeepseekV4HyperConnection — attn_hc y ffn_hc — mezclan los flujos de entrada y salida alrededor de las subcapas de atención / MLP mediante una tripleta (pre, post, comb). La matriz comb es una proyección doblemente estocástica producida por iteraciones de Sinkhorn–Knopp hc_sinkhorn_iters sobre el manifold, lo que hace que la propagación de la señal sea no expansiva a través de pilas profundas. Un DeepseekV4HyperHead final colapsa los hc_mult flujos en una única secuencia antes de la normalización del modelo.

Programa de MoE (§2.1)

La enrutación se configura por capa mediante config.mlp_layer_types, con valores de {"hash_moe", "moe"}:

• "hash_moe": los índices de expertos provienen de una búsqueda congelada tid2eid[input_ids] poblada desde el checkpoint de V4. La weight de la puerta aprendida sigue produciendo las puntuaciones por experto que ponderan a los expertos seleccionados; solo qué expertos es estático. Se usa para las primeras capas de arranque (por defecto 3, se puede sobrescribir mediante el parámetro heredado num_hash_layers).
• "moe": MoE estándar con enrutamiento top-k. La afinidad de los expertos utiliza Sqrt(Softplus(·)) en lugar del Sigmoid de V3 (“cambiamos la función de activación que calcula las puntuaciones de afinidad de Sigmoid(·) a Sqrt(Softplus(·))”, papel §2.1), y se elimina la restricción n_group / topk_group de V3. La estrategia sin pérdida auxiliar (noaux_tc de DeepSeek) se conserva mediante el búfer e_score_correction_bias que sesga el argmax top-k sin propagar gradientes.

Los expertos enrutados utilizan un SwiGLU con recorte (gate.clamp(max=swiglu_limit), up.clamp(min=-swiglu_limit, max=swiglu_limit), luego act_fn(gate) * up) sobre el diseño de pesos de expertos estándar de Mixtral [num_experts, 2 * moe_intermediate_size, hidden_size]. Un único experto compartido (un MLP SwiGLU simple con ancho moe_intermediate_size) se ejecuta en paralelo en cada token.

Distribución de la máscara de atención

Cada capa DeepseekV4Attention extiende la máscara causal de ventana deslizante estándar a lo largo del eje de claves con un block_bias devuelto por su compresor y, a continuación, pasa la máscara concatenada a eager_attention_forward. La sección deslizante (izquierda, [S, S]) es la misma para todos los tipos de capa; la sección del compresor (derecha) varía según el tipo de capa y es la pieza realmente “novedosa” introducida por V4.

Los diagramas siguientes se generaron con una configuración mínima (sliding_window=8, CSA m=4, HCA m'=8, index_topk=2) en una entrada de 16 tokens para que la máscara completa por tipo de capa quepa en la pantalla. Verde = la diagonal de consulta/clave en la sección deslizante, oscuro = una posición estándar de KV visible, claro = enmascarado, ámbar = un slot de compresor / indexador al que la consulta puede atender. Las columnas después de la línea discontinua se añaden mediante el compresor a través de cat([sliding_causal_mask, block_bias], dim=-1).

Capa solo deslizante ("sliding_attention"). Sin compresor, sin relleno a la derecha: la máscara es la máscara causal de ventana deslizante simple de forma [S, S] (ventana = 8). Para i ≥ window, el triángulo inferior izquierdo se recorta, recuperando el patrón de atención solo local.

Capa CSA ("compressed_sparse_attention"). El compresor aplana su salida recopilada por consulta a [B, 1, S·k, D] y rellena la máscara a la derecha con S·k columnas. Para la consulta t, solo los k huecos en las columnas [S + t·k, S + (t+1)·k) contienen las selecciones del indexador; todas las demás columnas del compresor son -inf. Las consultas anteriores al cierre de la primera ventana (t < m − 1) no reciben nada: el valor centinela -1 del indexador se propaga directamente a la máscara. A medida que t aumenta, más entradas comprimidas están listas y el indexador puede llenar todos los k huecos.

Capa HCA ("heavily_compressed_attention"). No hay un indexer: cada entrada comprimida en caché es potencialmente visible. Se rellena a la derecha con T_total = entry_count["compressor"] columnas. La consulta t solo puede ver la entrada w una vez que su ventana de origen se ha cerrado, es decir, w < (t + 1) // m. Con m=8 aquí, las entradas 0 (cubre las posiciones 0..7) y 1 (cubre 8..15) solo se vuelven visibles en t ≥ 7 y t ≥ 15 respectivamente.

Estos diagramas son reproducibles de principio a fin mediante:

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

El script ejecuta una pasada hacia adelante en esta configuración diminuta, envuelve cada capa de atención para capturar la máscara exacta posterior a cat([attention_mask, block_bias]), remapea la máscara de ranuras planas [S, S·k] de CSA a una vista de visibilidad de entradas [S, T_entries] (de modo que cada columna C_w sea una entrada comprimida, no una ranura de recolección) y escribe los tres SVG anteriores. También imprime una cuadrícula ANSI en stdout para una inspección rápida en la terminal y volca las selecciones top-k por consulta del indexer para que los centinelas de calentamiento y las elecciones de selección sean auditables.

Capas de caché

Cada bloque de atención no deslizante necesita propagar el estado del compresor / indexador a través de las llamadas de forward. V4 incluye dos tipos de capa de caché que se registran automáticamente con LAYER_TYPE_CACHE_MAPPING:

• DeepseekV4HCACache: ventana deslizante K=V + búfer/pool/contador del compresor HCA (sin solapamiento, sin indexador).
• DeepseekV4CSACache: ventana deslizante K=V + compresor CSA (con estado de solapamiento) + indexador paralelo buffer / pool / count / overlap en index_head_dim.

DynamicCache(config=…) construye la capa de caché adecuada para cada 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."