Transformers documentation

Hy3-preview

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Este modelo fue aportado a Hugging Face Transformers el 2026-04-22.

Hy3-preview

Resumen

Hy3-preview es un modelo de lenguaje a gran escala de tipo Mixture-of-Experts (MoE) desarrollado por el equipo Tencent HunYuan. Presenta una arquitectura híbrida dense-MoE con 192 expertos enrutados y 1 experto compartido siempre activo por capa MoE, lo que le permite lograr un rendimiento sólido con una inferencia eficiente mediante la activación de expertos dispersos.

Características arquitectónicas clave:

Híbrido Dense-MoE: la primera capa utiliza un FFN denso; todas las capas posteriores utilizan MoE con enrutamiento top-k (k=8 por defecto).
Expertos compartidos: Cada capa MoE incluye 1 experto compartido que procesa todos los tokens junto con los expertos enrutados.
Enrutamiento sigmoide con corrección de sesgo por experto: Los tokens se enrutan mediante puntuación sigmoide (no softmax) con un sesgo aprendido por experto para el equilibrio de carga.
QK-Norm: RMSNorm por cabeza aplicado a las proyecciones de consulta y clave antes de la atención para mejorar la estabilidad del entrenamiento.

Consejos de uso

Cargar con AutoModelForCausalLM. El modelo requiere varias GPU debido a su tamaño.
Establezca output_router_logits=True en la configuración o en la llamada forward para recopilar los logits del router MoE por capa. Tenga en cuenta que este modelo no calcula una pérdida auxiliar de equilibrio de carga; aux_loss siempre es None.
El modelo admite gradient_checkpointing para reducir la memoria durante el ajuste fino.

from transformers import AutoModelForCausalLM, AutoTokenizer


model_id = "tencent/Hy3-preview"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    device_map="auto",
)

inputs = tokenizer("The future of artificial intelligence is", return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=64)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

HYV3Config

clase transformers.HYV3Config

< source >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 120832hidden_size: int = 4096intermediate_size: int = 13312num_hidden_layers: int = 80num_attention_heads: int = 64num_key_value_heads: int = 8head_dim: int = 128hidden_act: str = 'silu'max_position_embeddings: int = 131072initializer_range: float = 0.006rms_norm_eps: float = 1e-05use_cache: bool = Truepad_token_id: int | None = Nonebos_token_id: int | None = Noneeos_token_id: int | list[int] | None = Nonetie_word_embeddings: bool = Falseattention_bias: bool = Falseattention_dropout: float = 0.0mlp_bias: bool = Falsenum_experts: int | None = 192num_experts_per_tok: int | None = 8num_shared_experts: int | None = 1moe_intermediate_size: int = 1536router_scaling_factor: float = 2.826enable_moe_fp32_combine: bool = Truemlp_layer_types: list[str] | None = Noneoutput_router_logits: bool = Falserope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None )

Parámetros

vocab_size (int, opcional, valor predeterminado 120832) — Tamaño del vocabulario del modelo. Define el número de tokens diferentes que pueden representarse mediante input_ids.
hidden_size (int, opcional, valor predeterminado 4096) — Dimensión de las representaciones ocultas.
intermediate_size (int, opcional, valor predeterminado 13312) — Dimensión de las representaciones del MLP.
num_hidden_layers (int, opcional, valor predeterminado 80) — Número de capas ocultas en el decodificador Transformer.
num_attention_heads (int, opcional, valor predeterminado 64) — Número de cabezas de atención para cada capa de atención en el decodificador Transformer.
num_key_value_heads (int, opcional, valor predeterminado 8) — Este es el número de cabezas key_value que se deben utilizar para implementar Grouped Query Attention. Si num_key_value_heads=num_attention_heads, el modelo utilizará Multi Head Attention (MHA); si num_key_value_heads=1, el modelo utilizará Multi Query Attention (MQA); en caso contrario, se utilizará GQA. Al convertir un checkpoint multi-head en un checkpoint GQA, cada cabeza de clave y valor del grupo debe construirse mediante el promediado (meanpooling) de todas las cabezas originales dentro de ese grupo. Para más detalles, consulta este artículo. Si no se especifica, el valor predeterminado será num_attention_heads.
head_dim (int, opcional, valor predeterminado 128) — La dimensión de la cabeza de atención. Si es None, se establecerá en hidden_size // num_attention_heads
hidden_act (str, opcional, valor predeterminado silu) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo, "gelu", "relu", "silu", etc.
max_position_embeddings (int, opcional, valor predeterminado 131072) — La longitud máxima de secuencia con la que podría utilizarse este modelo.
initializer_range (float, opcional, valor predeterminado 0.006) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos.
rms_norm_eps (float, opcional, valor predeterminado 1e-05) — La epsilon utilizada por las capas de normalización rms.
use_cache (bool, opcional, valor predeterminado True) — Indica si el modelo debe devolver las últimas claves/valores de atención (no utilizado por todos los modelos). Solo es relevante si config.is_decoder=True o cuando el modelo es un modelo generativo solo de decodificador.
pad_token_id (int, opcional) — Id del token utilizado para el relleno en el vocabulario.
bos_token_id (int, opcional) — Id del token utilizado para el inicio de la secuencia en el vocabulario.
eos_token_id (Union[int, list[int]], opcional) — Id del token utilizado para el fin de secuencia en el vocabulario.
tie_word_embeddings (bool, opcional, valor predeterminado False) — Si se deben vincular las matrices de pesos de embeddings según el mapeo tied_weights_keys del modelo.
attention_bias (bool, opcional, valor predeterminado False) — Si se debe usar un sesgo en las capas de proyección de consulta, clave, valor y salida durante la autoatención.
attention_dropout (float, opcional, valor predeterminado 0.0) — La proporción de dropout para las probabilidades de atención.
mlp_bias (bool, opcional, valor predeterminado False) — Si se debe usar un sesgo en las capas up_proj, down_proj y gate_proj de las capas MLP.
num_experts (int, opcional, valor predeterminado 192) — Número de expertos enrutados en las capas MoE.
num_experts_per_tok (int, opcional, valor predeterminado 8) — Número de expertos a los que enrutar cada token. Este es el valor top-k para el enrutamiento de selección de tokens.
num_shared_experts (int, opcional, valor predeterminado 1) — Número de expertos compartidos que se activan siempre para todos los tokens.
moe_intermediate_size (int, opcional, valor predeterminado 1536) — Tamaño intermedio de los MLP de los expertos enrutados.
router_scaling_factor (float, opcional, valor predeterminado 2.826) — Factor de escala de los pesos top-k de la selección de expertos MoE.
enable_moe_fp32_combine (bool, opcional, valor predeterminado True) — Si se deben añadir los expertos compartidos al resultado final de MoE en fp32 o en el dtype base existente del modelo.
mlp_layer_types (list, opcional) — Patrón de MLP (Moe frente a Dense) para cada capa.
output_router_logits (bool, opcional, valor predeterminado False) — Indica si el modelo debe devolver los logits del router. Habilitar esta opción también permite que el modelo devuelva la pérdida auxiliar, que incluye la pérdida de equilibrio de carga y la pérdida z del router.
rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], opcional) — Diccionario que contiene los parámetros de configuración para las incrustaciones RoPE. El diccionario debe contener un valor para rope_theta y, opcionalmente, parámetros utilizados para el escalado en caso de que desee usar RoPE con max_position_embeddings más largos.

Esta es la clase de configuración para almacenar la configuración de un HYV3Model. Se utiliza para instanciar un modelo Hy V3 según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de tencent/Hy3-preview

Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.

Ejemplo:

>>> from transformers import HYV3Config, HYV3Model

>>> config = HYV3Config()
>>> model = HYV3Model(config)

HYV3Model

clase transformers.HYV3Model

< source >

( config: HYV3Config )

Parámetros

config (HYV3Config) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.

El modelo Hy V3 básico que genera estados ocultos sin ninguna cabeza específica en la parte superior.

Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

forward

< source >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → MoeModelOutputWithPast or tuple(torch.FloatTensor)

Parámetros

input_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices de los tokens de la secuencia de entrada en el vocabulario. El relleno se ignorará de forma predeterminada.
Los índices se pueden obtener usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() y PreTrainedTokenizer.call() para más detalles.

¿Qué son los IDs de entrada?
attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de máscara seleccionados en [0, 1]:
- 1 para los tokens que no están enmascarados,
- 0 para los tokens que están enmascarados.
¿Qué son las máscaras de atención?
position_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices de las posiciones de los tokens de cada secuencia de entrada en los embeddings de posición. Seleccionados en el rango [0, config.n_positions - 1].
¿Qué son los IDs de posición?
past_key_values (~cache_utils.Cache, opcional) — Estados ocultos precalculados (claves y valores en los bloques de autoatención y en los bloques de atención cruzada) que se pueden usar para acelerar la decodificación secuencial. Esto generalmente consiste en la past_key_values devuelta por el modelo en una etapa anterior de la decodificación, cuando use_cache=True o config.use_cache=True.
Solo se permite una instancia de Cache como entrada, consulte nuestra guía de caché kv. Si no se pasan past_key_values, DynamicCache se inicializará de forma predeterminada.

El modelo generará el mismo formato de caché que se proporciona como entrada.

Si se utilizan past_key_values, se espera que el usuario introduzca únicamente los input_ids no procesados (aquellos que no tienen sus estados de clave y valor pasados proporcionados a este modelo) con forma (batch_size, unprocessed_length) en lugar de todos los input_ids con forma (batch_size, sequence_length).
inputs_embeds (torch.FloatTensor de forma (batch_size, sequence_length, hidden_size), opcional) — Opcionalmente, en lugar de pasar input_ids, puedes elegir pasar directamente una representación incrustada. Esto es útil si deseas tener más control sobre cómo convertir los índices de input_ids en los vectores asociados que en la matriz de búsqueda de incrustaciones interna del modelo.
use_cache (bool, opcional) — Si se establece en True, se devuelven los estados de clave-valor de past_key_values y pueden usarse para acelerar la decodificación (ver past_key_values).

Devuelve

MoeModelOutputWithPast o tuple(torch.FloatTensor)

Un MoeModelOutputWithPast o una tupla de torch.FloatTensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios elementos según la configuración (HYV3Config) y las entradas.

El método forward de HYV3Model sobrescribe el método especial __call__.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de Module después en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.

last_hidden_state (torch.FloatTensor de forma (batch_size, sequence_length, hidden_size)) — Secuencia de estados ocultos en la salida de la última capa del modelo.
past_key_values (Cache, opcional, se devuelve cuando se pasa use_cache=True o cuando config.use_cache=True) — Es una instancia de Cache. Para más detalles, consulta nuestra guía de caché kv.

Contiene estados ocultos precalculados (claves y valores en los bloques de autoatención y, opcionalmente, si config.is_encoder_decoder=True, en los bloques de atención cruzada) que pueden utilizarse (véase la entrada past_key_values) para acelerar la decodificación secuencial.
hidden_states (tuple(torch.FloatTensor), opcional, se devuelve cuando se pasa output_hidden_states=True o cuando config.output_hidden_states=True) — Tupla de torch.FloatTensor (una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma (batch_size, sequence_length, hidden_size).

Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
attentions (tuple(torch.FloatTensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.FloatTensor (una por cada capa) de forma (batch_size, num_heads, sequence_length, sequence_length).

Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
router_logits (tuple(torch.FloatTensor), opcional, se devuelve cuando se pasa output_router_probs=True y config.add_router_probs=True o cuando config.output_router_probs=True) — Tupla de torch.FloatTensor (una por cada capa) de forma (batch_size, sequence_length, num_experts).

Logits crudos del enrutador (post-softmax) que se calculan mediante los enrutadores de MoE; estos términos se utilizan para calcular la pérdida auxiliar en los modelos Mixture of Experts.

HYV3ForCausalLM

clase transformers.HYV3ForCausalLM

< source >

( config: HYV3Config )

Parámetros

config (HYV3Config) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.

El modelo Hy V3 para el modelado de lenguaje causal.

forward

< source >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → MoeCausalLMOutputWithPast or tuple(torch.FloatTensor)

Parámetros

input_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices de los tokens de la secuencia de entrada en el vocabulario. El relleno se ignorará de forma predeterminada.
Los índices se pueden obtener usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() y PreTrainedTokenizer.call() para más detalles.

¿Qué son los IDs de entrada?
attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de máscara seleccionados en [0, 1]:
- 1 para los tokens que no están enmascarados,
- 0 para los tokens que están enmascarados.
¿Qué son las máscaras de atención?
position_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices de las posiciones de los tokens de cada secuencia de entrada en los embeddings de posición. Seleccionados en el rango [0, config.n_positions - 1].
¿Qué son los IDs de posición?
past_key_values (~cache_utils.Cache, opcional) — Estados ocultos precalculados (claves y valores en los bloques de autoatención y en los bloques de atención cruzada) que se pueden usar para acelerar la decodificación secuencial. Esto generalmente consiste en la past_key_values devuelta por el modelo en una etapa anterior de la decodificación, cuando use_cache=True o config.use_cache=True.
Solo se permite una instancia de Cache como entrada, consulte nuestra guía de caché kv. Si no se pasan past_key_values, DynamicCache se inicializará de forma predeterminada.

El modelo generará el mismo formato de caché que se proporciona como entrada.

Si se utilizan past_key_values, se espera que el usuario introduzca únicamente los input_ids no procesados (aquellos que no tienen sus estados de clave y valor pasados proporcionados a este modelo) con forma (batch_size, unprocessed_length) en lugar de todos los input_ids con forma (batch_size, sequence_length).
inputs_embeds (torch.FloatTensor de forma (batch_size, sequence_length, hidden_size), opcional) — Opcionalmente, en lugar de pasar input_ids, puedes elegir pasar directamente una representación incrustada. Esto es útil si deseas tener más control sobre cómo convertir los índices de input_ids en los vectores asociados que en la matriz de búsqueda de incrustaciones interna del modelo.
labels (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Etiquetas para calcular la pérdida de modelado de lenguaje enmascarado. Los índices deben estar en [0, ..., config.vocab_size] o ser -100 (ver la docstring de input_ids). Los tokens con índices establecidos en -100 se ignoran (enmascarados); la pérdida solo se calcula para los tokens con etiquetas en [0, ..., config.vocab_size].
use_cache (bool, opcional) — Si se establece en True, se devuelven los estados de clave-valor de past_key_values y pueden usarse para acelerar la decodificación (ver past_key_values).
logits_to_keep (Union[int, torch.Tensor], opcional, valor predeterminado 0) — Si es un int, calcula los logits para los últimos logits_to_keep tokens. Si es 0, calcula los logits para todos los input_ids (caso especial). Solo se necesitan los logits del último token para la generación, y calcularlos solo para ese token puede ahorrar memoria, lo cual se vuelve bastante significativo para secuencias largas o un tamaño de vocabulario grande. Si es un torch.Tensor, debe ser de 1D y corresponder a los índices a conservar en la dimensión de longitud de secuencia. Esto es útil al usar el formato de tensor empaquetado (una sola dimensión para el lote y la longitud de secuencia).

Devuelve

MoeCausalLMOutputWithPast o tuple(torch.FloatTensor)

Un MoeCausalLMOutputWithPast o una tupla de torch.FloatTensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios elementos según la configuración (HYV3Config) y las entradas.

El método forward de HYV3ForCausalLM sobrescribe el método especial __call__.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de Module después en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.

loss (torch.FloatTensor de forma (1,), opcional, devuelta cuando se proporciona labels) — Pérdida de modelado de lenguaje (para la predicción del siguiente token).
logits (torch.FloatTensor de forma (batch_size, sequence_length, config.vocab_size)) — Puntuaciones de predicción de la cabeza de modelado de lenguaje (puntuaciones para cada token del vocabulario antes de SoftMax).
aux_loss (torch.FloatTensor, opcional, se devuelve cuando se pasa output_router_logits=True o cuando config.output_router_logits=True, y el modelo entrena su router con una pérdida de equilibrio de carga) — Pérdida auxiliar de equilibrio de carga para los módulos dispersos. Los modelos que equilibran sus expertos con un sesgo del router en su lugar (DeepSeek-V3 y las arquitecturas derivadas de él) devuelven None aquí, aunque siguen devolviendo router_logits.
router_logits (tuple(torch.FloatTensor), opcional, se devuelve cuando se pasa output_router_logits=True o cuando config.output_router_logits=True) — Tupla de torch.FloatTensor (una por cada capa dispersa) de forma (batch_size * sequence_length, num_experts).

Logits crudos del router calculados por los routers de MoE. Se pueden utilizar para calcular una pérdida de equilibrado de carga o para inspeccionar cómo se distribuyen los tokens entre los expertos.
past_key_values (Cache, opcional, se devuelve cuando se pasa use_cache=True o cuando config.use_cache=True) — Es una instancia de Cache. Para más detalles, consulta nuestra guía de caché kv.

Contiene estados ocultos precalculados (claves y valores en los bloques de autoatención) que pueden utilizarse (véase la entrada past_key_values) para acelerar la decodificación secuencial.
hidden_states (tuple(torch.FloatTensor), opcional, se devuelve cuando se pasa output_hidden_states=True o cuando config.output_hidden_states=True) — Tupla de torch.FloatTensor (una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma (batch_size, sequence_length, hidden_size).

Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
attentions (tuple(torch.FloatTensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.FloatTensor (una por cada capa) de forma (batch_size, num_heads, sequence_length, sequence_length).

Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.

Ejemplo:

Update on GitHub

←HyperCLOVAX HYV4→