Transformers documentation

Qwen3 ASR

Transformers

Comenzar

Transformers Instalación Introducción

Clases base

Modelos

Preprocesadores

Inferencia

API de Pipeline

Generar API

Optimización

Chatear con modelos

Servicio

Entrenamiento

Comenzar

Personalización

Ajuste fino eficiente en parámetros

Rendimiento

Entrenamiento distribuido

Hardware

Cuantización

Integraciones del ecosistema

Recursos

API

Clases principales

Modelos

Modelos de texto

Modelos de visión

Modelos de audio

Modelos de video

Modelos multimodales

Modelos de aprendizaje por refuerzo

Modelos de series temporales

Funciones auxiliares internas

Referencia

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

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 se publicó en HF papers el 29 de enero de 2026 y se contribuyó a Hugging Face Transformers el 26 de junio de 2026.

Qwen3 ASR

Resumen

Qwen3 ASR es un modelo de reconocimiento automático de voz del equipo Qwen de Alibaba que combina un codificador de audio estilo Whisper con un decodificador de modelo de lenguaje Qwen3 para la transcripción de voz a texto. El modelo admite la detección automática de idioma y la transcripción multilingüe.

También se incluye un modelo de alineador forzado. Puede utilizarse para asignar marcas de tiempo a una transcripción y su audio proporcionados. Utiliza el mismo modelo de codificador de audio con una cabeza de clasificación que predice la longitud de una palabra. Este modelo puede usarse con la transcripción de cualquier modelo de ASR (vea el ejemplo a continuación con Parakeet CTC).

Puntos de control disponibles:

Los siguientes idiomas están admitidos:

Qwen3-ASR-1.7B y Qwen3-ASR-0.6B: chino (zh), inglés (en), cantonés (yue), árabe (ar), alemán (de), francés (fr), español (es), portugués (pt), indonesio (id), italiano (it), coreano (ko), ruso (ru), tailandés (th), vietnamita (vi), japonés (ja), turco (tr), hindi (hi), malayo (ms), neerlandés (nl), sueco (sv), danés (da), finés (fi), polaco (pl), checo (cs), filipino (fil), persa (fa), griego (el), húngaro (hu), macedonio (mk), rumano (ro).
Qwen3-ForcedAligner-0.6B: chino (zh), inglés (en), cantonés (yue), francés (fr), alemán (de), italiano (it), japonés (ja), coreano (ko), portugués (pt), ruso (ru), español (es).

Consulte el repositorio original en QwenLM/Qwen3-ASR y el informe para obtener más detalles.

Este modelo fue aportado por Eric Bezzam y Muhammed Tariq.

Uso

Transcripción simple

La forma más sencilla de transcribir audio es con apply_transcription_request, que gestiona el formato de la plantilla de chat por ti; en concreto, es un envoltorio de conveniencia para apply_chat_template (consulta Plantilla de chat a continuación).

from transformers import AutoProcessor, AutoModelForMultimodalLM

model_id = "Qwen/Qwen3-ASR-1.7B-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForMultimodalLM.from_pretrained(model_id, device_map="auto")
print(f"Model loaded on {model.device} with dtype {model.dtype}")

inputs = processor.apply_transcription_request(
    audio="https://huggingface.co/datasets/bezzam/audio_samples/resolve/main/librispeech_mr_quilter.wav",
).to(model.device, model.dtype)

output_ids = model.generate(**inputs, max_new_tokens=256)
generated_ids = output_ids[:, inputs["input_ids"].shape[1]:]

# Raw output includes language tag and <asr_text> marker
raw = processor.decode(generated_ids)[0]
print(f"Raw: {raw}")

# Parsed output: dict with "language" and "transcription"
parsed = processor.decode(generated_ids, return_format="parsed")[0]
print(f"Parsed: {parsed}")

# Extract only the transcription text
transcription = processor.decode(generated_ids, return_format="transcription_only")[0]
print(f"Transcription: {transcription}")

"""
Raw: language English<asr_text>Mr. Quilter is the apostle of the middle classes, and we are glad to welcome his gospel.
Parsed: {'language': 'English', 'transcription': 'Mr. Quilter is the apostle of the middle classes, and we are glad to welcome his gospel.'}
Transcription: Mr. Quilter is the apostle of the middle classes, and we are glad to welcome his gospel.
"""

Forzar el idioma

Puede forzar el idioma de transcripción como se muestra a continuación.

from transformers import AutoProcessor, AutoModelForMultimodalLM

model_id = "Qwen/Qwen3-ASR-1.7B-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForMultimodalLM.from_pretrained(model_id, device_map="auto")

# Without language hint (auto-detect)
inputs = processor.apply_transcription_request(
    audio="https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/mandarin_voxcpm_zh.wav",
).to(model.device, model.dtype)
output_ids = model.generate(**inputs, max_new_tokens=256)
generated_ids = output_ids[:, inputs["input_ids"].shape[1]:]
print(f"Auto-detect: {processor.decode(generated_ids, return_format='transcription_only')[0]}")

# With forced language
inputs = processor.apply_transcription_request(
    audio="https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/mandarin_voxcpm_zh.wav",
    language="Chinese",  # or language code "zh"
).to(model.device, model.dtype)
output_ids = model.generate(**inputs, max_new_tokens=256)
generated_ids = output_ids[:, inputs["input_ids"].shape[1]:]
print(f"Forced:      {processor.decode(generated_ids, return_format='transcription_only')[0]}")

Contexto / palabras clave

Puede pasar un contexto libre (por ejemplo, vocabulario específico del dominio, nombres o información de fondo) a través de prompt para sesgar la transcripción.

from transformers import AutoProcessor, AutoModelForMultimodalLM

model_id = "Qwen/Qwen3-ASR-1.7B-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForMultimodalLM.from_pretrained(model_id, device_map="auto")

inputs = processor.apply_transcription_request(
    audio="https://huggingface.co/datasets/bezzam/audio_samples/resolve/main/librispeech_mr_quilter.wav",
    prompt="Vocabulary: Quilter, apostle, gospel.",
    language="English",
).to(model.device, model.dtype)

output_ids = model.generate(**inputs, max_new_tokens=256)
generated_ids = output_ids[:, inputs["input_ids"].shape[1]:]
print(processor.decode(generated_ids, return_format="transcription_only")[0])

Inferencia por lotes

La inferencia por lotes es posible pasando una lista de audios y, si se proporcionan, una lista de idiomas y/o prompts.

from transformers import AutoProcessor, AutoModelForMultimodalLM

model_id = "Qwen/Qwen3-ASR-1.7B-hf"
audio = [
    "https://huggingface.co/datasets/bezzam/audio_samples/resolve/main/librispeech_mr_quilter.wav",
    "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/mandarin_voxcpm_zh.wav",
]

processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForMultimodalLM.from_pretrained(model_id, device_map="auto")

inputs = processor.apply_transcription_request(
    audio,
    prompt=["Vocabulary: Quilter, apostle, gospel.", None],
    language=[None, "zh"],  # language codes ("zh") and full names ("Chinese") are both accepted
).to(model.device, model.dtype)

output_ids = model.generate(**inputs, max_new_tokens=256)
generated_ids = output_ids[:, inputs["input_ids"].shape[1]:]
transcriptions = processor.decode(generated_ids, return_format="transcription_only")

for i, text in enumerate(transcriptions):
    print(f"Audio {i + 1}: {text}")

Plantilla de chat

Qwen3 ASR también acepta entradas de plantilla de chat. El uso de apply_transcription_request anterior es un envoltorio de conveniencia para apply_chat_template.

El idioma puede forzarse a través de la plantilla de chat mediante prefill del turno del asistente con language <NAME><asr_text> y pasando continue_final_message=True, que es lo que hace apply_transcription_request internamente. Tenga en cuenta que, si se fuerza el idioma, se debe establecer un prefill para todo el audio de un lote (como se muestra a continuación).

from transformers import AutoProcessor, Qwen3ASRForConditionalGeneration

model_id = "Qwen/Qwen3-ASR-1.7B-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = Qwen3ASRForConditionalGeneration.from_pretrained(model_id, device_map="auto")

chat_template = [
    [
        # Context/hotwords as system message
        {"role": "system", "content": [{"type": "text", "text": "Vocabulary: Quilter, apostle, gospel."}]},
        {
            "role": "user",
            "content": [
                {
                    "type": "audio",
                    "path": "https://huggingface.co/datasets/bezzam/audio_samples/resolve/main/librispeech_mr_quilter.wav",
                },
            ],
        },
        # empty prefill since forcing language in the other sample
        {"role": "assistant", "content": [{"type": "text", "text": ""}]},
    ],
    [
        {
            "role": "user",
            "content": [
                {
                    "type": "audio",
                    "path": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/mandarin_voxcpm_zh.wav",
                },
            ],
        },
        {"role": "assistant", "content": [{"type": "text", "text": "language Chinese<asr_text>"}]},
    ],
]

inputs = processor.apply_chat_template(
    chat_template, tokenize=True, return_dict=True, continue_final_message=True,
).to(model.device, model.dtype)

output_ids = model.generate(**inputs, max_new_tokens=256)
generated_ids = output_ids[:, inputs["input_ids"].shape[1]:]
transcriptions = processor.decode(generated_ids, return_format="transcription_only")
for text in transcriptions:
    print(text)

Entrenamiento

Pase los transcripciones objetivo a apply_transcription_request con transcription para obtener las labels utilizadas para calcular la pérdida.

from datasets import Audio, load_dataset
from transformers import AutoProcessor, Qwen3ASRForConditionalGeneration

model_id = "Qwen/Qwen3-ASR-1.7B-hf"
NUM_SAMPLES = 2

processor = AutoProcessor.from_pretrained(model_id)
model = Qwen3ASRForConditionalGeneration.from_pretrained(model_id, device_map="auto")
model.train()

ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
ds = ds.cast_column("audio", Audio(sampling_rate=processor.feature_extractor.sampling_rate))
speech_samples = [el["array"] for el in ds["audio"][:NUM_SAMPLES]]
text_samples = ds["text"][:NUM_SAMPLES]

inputs = processor.apply_transcription_request(speech_samples, language="en", transcription=text_samples)
inputs.to(model.device, dtype=model.dtype)

loss = model(**inputs).loss
print("Loss:", loss.item())
loss.backward()

Alineación forzada (marcas de tiempo a nivel de palabra)

Use Qwen3ASRForTokenClassification para obtener marcas de tiempo a nivel de palabra a partir de una transcripción. Primero, transcribe con el modelo ASR y luego alinea con el alineador forzado.

Los siguientes idiomas son compatibles: chino (zh), inglés (en), cantonés (yue), francés (fr), alemán (de), italiano (it), japonés (ja), coreano (ko), portugués (pt), ruso (ru), español (es).

El japonés requiere la biblioteca nagisa, mientras que el coreano requiere la biblioteca soynlp:

pip install nagisa soynlp

Con Qwen3 ASR

import torch
from transformers import AutoProcessor, AutoModelForMultimodalLM, AutoModelForTokenClassification

asr_model_id = "Qwen/Qwen3-ASR-0.6B-hf"
aligner_model_id = "Qwen/Qwen3-ForcedAligner-0.6B-hf"

asr_processor = AutoProcessor.from_pretrained(asr_model_id)
asr_model = AutoModelForMultimodalLM.from_pretrained(asr_model_id, device_map="auto")

aligner_processor = AutoProcessor.from_pretrained(aligner_model_id)
aligner_model = AutoModelForTokenClassification.from_pretrained(
    aligner_model_id, dtype=torch.bfloat16, device_map="auto"
)

audio_url = "https://huggingface.co/datasets/bezzam/audio_samples/resolve/main/librispeech_mr_quilter.wav"

# Step 1: Transcribe
inputs = asr_processor.apply_transcription_request(audio=audio_url)
inputs = inputs.to(asr_model.device, asr_model.dtype)
output_ids = asr_model.generate(**inputs, max_new_tokens=256)
generated_ids = output_ids[:, inputs["input_ids"].shape[1]:]
parsed = asr_processor.decode(generated_ids, return_format="parsed")[0]
transcript = parsed["transcription"]
language = parsed["language"] or "English"

# Step 2: Prepare alignment inputs
aligner_inputs, word_lists = aligner_processor.prepare_forced_aligner_inputs(
    audio=audio_url, transcript=transcript, language=language,
)
aligner_inputs = aligner_inputs.to(aligner_model.device, aligner_model.dtype)

# Step 3: Run forced aligner
with torch.inference_mode():
    outputs = aligner_model(**aligner_inputs)

# Step 4: Decode timestamps
timestamps = aligner_processor.decode_forced_alignment(
    logits=outputs.logits,
    input_ids=aligner_inputs["input_ids"],
    word_lists=word_lists,
    timestamp_token_id=aligner_model.config.timestamp_token_id,
)[0]

for item in timestamps:
    print(f"{item['text']:<20} {item['start_time']:>8.3f}s → {item['end_time']:>8.3f}s")

"""
Word                  Start (s)    End (s)
------------------------------------------
Mr                        0.560      0.800
Quilter                   0.800      1.280
is                        1.280      1.440
the                       1.440      1.520
apostle                   1.520      2.080
...
"""

Con otro modelo de ASR

El alineador forzado es agnóstico al modelo, lo que significa que se pueden proporcionar transcripciones de cualquier sistema ASR. A continuación se muestra un ejemplo de inferencia por lotes que utiliza NVIDIA Parakeet CTC para la transcripción.

import torch
from datasets import Audio, load_dataset
from transformers import AutoModelForCTC, AutoProcessor, AutoModelForTokenClassification

parakeet_processor = AutoProcessor.from_pretrained("nvidia/parakeet-ctc-1.1b")
parakeet_model = AutoModelForCTC.from_pretrained(
    "nvidia/parakeet-ctc-1.1b", dtype="auto", device_map="auto",
)

aligner_model_id = "Qwen/Qwen3-ForcedAligner-0.6B-hf"
aligner_processor = AutoProcessor.from_pretrained(aligner_model_id)
aligner_model = AutoModelForTokenClassification.from_pretrained(
    aligner_model_id, dtype=torch.bfloat16, device_map="auto",
)

ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
ds = ds.cast_column("audio", Audio(sampling_rate=parakeet_processor.feature_extractor.sampling_rate))
audio_arrays = [ds[i]["audio"]["array"] for i in range(3)]
sr = ds[0]["audio"]["sampling_rate"]

# Batch transcribe with Parakeet
inputs = parakeet_processor(audio_arrays, sampling_rate=sr, return_tensors="pt", padding=True).to(
    parakeet_model.device, dtype=parakeet_model.dtype
)
with torch.inference_mode():
    outputs = parakeet_model.generate(**inputs)
transcripts = parakeet_processor.decode(outputs)

# Batch align with Qwen3 Forced Aligner
aligner_inputs, word_lists = aligner_processor.prepare_forced_aligner_inputs(
    audio=audio_arrays, transcript=transcripts, language="English",
)
aligner_inputs = aligner_inputs.to(aligner_model.device, aligner_model.dtype)

with torch.inference_mode():
    aligner_outputs = aligner_model(**aligner_inputs)

batch_timestamps = aligner_processor.decode_forced_alignment(
    logits=aligner_outputs.logits,
    input_ids=aligner_inputs["input_ids"],
    word_lists=word_lists,
    timestamp_token_id=aligner_model.config.timestamp_token_id,
)

for i, (transcript, timestamps) in enumerate(zip(transcripts, batch_timestamps)):
    print(f"\n[Sample {i}] {transcript}")
    for item in timestamps[:5]:
        print(f"  {item['text']:<20} {item['start_time']:>8.3f}s → {item['end_time']:>8.3f}s")
    if len(timestamps) > 5:
        print(f"  ... ({len(timestamps) - 5} more words)")

Torch compile

Tanto los modelos de ASR como los de alineación forzada admiten torch.compile para una inferencia más rápida. El alineador forzado es especialmente adecuado para la compilación porque ejecuta una única pasada hacia adelante (sin decodificación autoregresiva). Esto lo hace ideal para la marcaje de tiempo por lotes de audio: transcribe con cualquier modelo de ASR y luego alinea por lotes con el alineador forzado compilado para obtener el máximo rendimiento.

Alineador forzado

En una A100, observamos una aceleración de ~1.2 para un tamaño de lote de 4 (script).

import torch
from transformers import AutoProcessor, AutoModelForTokenClassification

model_id = "Qwen/Qwen3-ForcedAligner-0.6B-hf"
num_warmup = 5
batch_size = 4

processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForTokenClassification.from_pretrained(model_id, dtype=torch.bfloat16).to("cuda")

# Prepare a batch of 4 samples
audio_url = "https://huggingface.co/datasets/bezzam/audio_samples/resolve/main/librispeech_mr_quilter.wav"
transcript = "Mr. Quilter is the apostle of the middle classes."

aligner_inputs, word_lists = processor.prepare_forced_aligner_inputs(
    audio=[audio_url] * batch_size,
    transcript=[transcript] * batch_size,
    language=["English"] * batch_size,
)
aligner_inputs = aligner_inputs.to(model.device, torch.bfloat16)

# Warm-up and apply model
model = torch.compile(model)
with torch.no_grad():
    for _ in range(num_warmup):
        _ = model(**aligner_inputs)
with torch.no_grad():
    _ = model(**aligner_inputs)

Modelo de ASR (generate)

Para la transcripción autoregresiva, torch.compile acelera las pasadas hacia adelante por token dentro de generate al proporcionar un objeto CompileConfig.

En una A100, observamos una aceleración de ~3.8 para un tamaño de lote de 4 (script).

import torch
from transformers import AutoProcessor, AutoModelForMultimodalLM, CompileConfig

model_id = "Qwen/Qwen3-ASR-1.7B-hf"
num_warmup = 3
max_new_tokens = 256

processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForMultimodalLM.from_pretrained(model_id, dtype=torch.bfloat16).to("cuda").eval()

audio_url = "https://huggingface.co/datasets/bezzam/audio_samples/resolve/main/librispeech_mr_quilter.wav"
inputs = processor.apply_transcription_request(
    audio=[audio_url] * 4,  # batch of 4
).to(model.device, torch.bfloat16)

compile_config = CompileConfig()

# Warmup
with torch.inference_mode():
    for _ in range(num_warmup):
        _ = model.generate(
            **inputs, max_new_tokens=max_new_tokens, do_sample=False,
            cache_implementation="static", compile_config=compile_config,
        )
torch.cuda.synchronize()

# Apply model
with torch.inference_mode():
    output_ids = model.generate(
        **inputs, max_new_tokens=max_new_tokens, do_sample=False,
        cache_implementation="static", compile_config=compile_config,
    )
generated_ids = output_ids[:, inputs["input_ids"].shape[1] :]
text_compiled = processor.decode(generated_ids, return_format="transcription_only")[0]
print(f"Output:  {text_compiled}")

Uso de Pipeline

from transformers import pipeline

model_id = "Qwen/Qwen3-ASR-1.7B-hf"
pipe = pipeline("any-to-any", model=model_id, device_map="auto")

chat_template = [
    {
        "role": "user",
        "content": [
            {
                "type": "audio",
                "path": "https://huggingface.co/datasets/bezzam/audio_samples/resolve/main/librispeech_mr_quilter.wav",
            },
        ],
    }
]
outputs = pipe(text=chat_template, return_full_text=False)
raw_text = outputs[0]["generated_text"]
print(f"Raw: {raw_text}")

# Use processor helper to extract transcription
transcription = pipe.processor.extract_transcription(raw_text)
print(f"Transcription: {transcription}")

Transformers

Qwen3 ASR

Resumen

Uso

Transcripción simple

Forzar el idioma

Contexto / palabras clave

Inferencia por lotes

Plantilla de chat

Entrenamiento

Alineación forzada (marcas de tiempo a nivel de palabra)

Con Qwen3 ASR

Con otro modelo de ASR

Torch compile

Alineador forzado

Modelo de ASR (generate)

Uso de Pipeline

Qwen3ASRConfig

clase transformers.Qwen3ASRConfig

Qwen3ASREncoderConfig

clase transformers.Qwen3ASREncoderConfig

Qwen3ASRFeatureExtractor

clase transformers.Qwen3ASRFeatureExtractor

__call__

Qwen3ASRProcessor

clase transformers.Qwen3ASRProcessor

__call__

apply_transcription_request

prepare_forced_aligner_inputs

decode_forced_alignment

decode

Qwen3ASREncoder

clase transformers.Qwen3ASREncoder

forward

Qwen3ASRModel

clase transformers.Qwen3ASRModel

forward

get_audio_features

get_placeholder_mask

Qwen3ASRForConditionalGeneration

clase transformers.Qwen3ASRForConditionalGeneration

forward

get_audio_features

Qwen3ASRForTokenClassification

clase transformers.Qwen3ASRForTokenClassification

forward

call

call