Transformers documentation

Qwen3 ASR

Transformers

Comece agora

Transformers Instalação Início rápido

Classes base

Modelos

Pré-processadores

Inferência

Pipeline API

API de geração

Otimização

Conversar com modelos

Serving

Treinamento

Comece agora

Personalização

Ajuste fino de parâmetros eficientes

Desempenho

Treinamento distribuído

Hardware

Quantização

Integrações com o ecossistema

Recursos

API

Principais classes

Modelos

Modelos de texto

Modelos de visão

Modelos de áudio

Modelos de vídeo

Modelos multimodais

Modelos de aprendizado por reforço

Modelos de séries temporais

Helpers internos

Referência

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 foi publicado no HF papers em 29/01/2026 e contribuído para o Hugging Face Transformers em 26/06/2026.

Qwen3 ASR

Visão geral

O Qwen3 ASR é um modelo de reconhecimento automático de fala da equipe Qwen da Alibaba que combina um codificador de áudio no estilo Whisper com um decodificador de modelo de linguagem Qwen3 para transcrição de fala em texto. O modelo suporta detecção automática de idioma e transcrição multilíngue.

Um modelo de alinhador forçado também está incluído. Ele pode ser usado para atribuir timestamps a uma transcrição e ao áudio fornecidos. Ele utiliza o mesmo modelo de codificador de áudio com uma cabeça de classificação que prevê o comprimento de uma palavra. Este modelo pode ser usado com a transcrição de qualquer modelo de ASR (veja o exemplo abaixo com Parakeet CTC).

Checkpoints disponíveis:

Os seguintes idiomas são suportados:

Qwen3-ASR-1.7B e Qwen3-ASR-0.6B: chinês (zh), inglês (en), cantonês (yue), árabe (ar), alemão (de), francês (fr), espanhol (es), português (pt), indonésio (id), italiano (it), coreano (ko), russo (ru), tailandês (th), vietnamita (vi), japonês (ja), turco (tr), hindi (hi), malaio (ms), holandês (nl), sueco (sv), dinamarquês (da), finlandês (fi), polonês (pl), tcheco (cs), filipino (fil), persa (fa), grego (el), húngaro (hu), macedônio (mk), romeno (ro).
Qwen3-ForcedAligner-0.6B: chinês (zh), inglês (en), cantonês (yue), francês (fr), alemão (de), italiano (it), japonês (ja), coreano (ko), português (pt), russo (ru), espanhol (es).

Veja o repositório original em QwenLM/Qwen3-ASR e o relatório para mais detalhes.

Este modelo foi contribuído por Eric Bezzam e Muhammed Tariq.

Uso

Transcrição simples

A maneira mais simples de transcrever áudio é com apply_transcription_request, que trata do formatação do chat template para você, ou seja, é um wrapper de conveniência para apply_chat_template (veja Chat template abaixo).

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

Forçando o idioma

Você pode forçar o idioma da transcrição, conforme mostrado abaixo.

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 / palavras-chave

Você pode passar um contexto livre (por exemplo, vocabulário específico do domínio, nomes ou informações de contexto) via prompt para direcionar a transcrição.

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])

Inferência em lote

A inferência em lote é possível ao passar uma lista de áudios e, se fornecidas, uma lista de idiomas e/ou 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}")

Modelo de chat

O Qwen3 ASR também aceita entradas de modelo de chat. O uso de apply_transcription_request acima é um wrapper de conveniência para apply_chat_template.

A linguagem pode ser forçada por meio do modelo de chat, pré-preenchendo a vez do assistente com language <NAME><asr_text> e passando continue_final_message=True, o que é o que apply_transcription_request faz por baixo dos panos. Observe que, ao forçar a linguagem, um pré-preenchimento deve ser definido para todos os áudios em um lote (conforme mostrado abaixo).

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)

Treinamento

Passe os transcritos-alvo para apply_transcription_request com transcription para obter os labels usados para calcular a perda.

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()

Alinhamento forçado (carimbo de tempo em nível de palavra)

Use Qwen3ASRForTokenClassification para obter timestamps no nível de palavra a partir de uma transcrição. Primeiro, transcreva com o modelo de ASR e, em seguida, alinhe com o alinhador forçado.

Os seguintes idiomas são suportados: chinês (zh), inglês (en), cantonês (yue), francês (fr), alemão (de), italiano (it), japonês (ja), coreano (ko), português (pt), russo (ru), espanhol (es).

O japonês requer a biblioteca nagisa, enquanto o coreano requer a biblioteca soynlp:

pip install nagisa soynlp

Com o 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
...
"""

Com outro modelo de ASR

O alinhador forçado é agnóstico em relação ao modelo, o que significa que é possível fornecer transcrições de qualquer sistema de ASR. Abaixo, há um exemplo de inferência em lote usando NVIDIA Parakeet CTC para transcrição.

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 os modelos de ASR quanto os de alinhamento forçado suportam torch.compile para inferência mais rápida. O alinhador forçado é especialmente adequado para compilação, pois executa um único passo de propagação direta (sem decodificação autoregressiva). Isso o torna ideal para carimbo de tempo em lote de áudio: transcreva com qualquer modelo de ASR e, em seguida, alinhe em lote com o alinhador forçado compilado para obter o máximo de rendimento.

Alinhador forçado

Em uma A100, observamos uma aceleração de ~1,2 para um tamanho 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 transcrição autoregressiva, torch.compile acelera as passadas de frente por token dentro de generate, fornecendo um objeto CompileConfig.

Em uma A100, observamos uma aceleração de ~3,8 para um tamanho 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 do 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

Visão geral

Uso

Transcrição simples

Forçando o idioma

Contexto / palavras-chave

Inferência em lote

Modelo de chat

Treinamento

Alinhamento forçado (carimbo de tempo em nível de palavra)

Com o Qwen3 ASR

Com outro modelo de ASR

Torch compile

Alinhador forçado

Modelo de ASR (generate)

Uso do Pipeline

Qwen3ASRConfig

classe transformers.Qwen3ASRConfig

Qwen3ASREncoderConfig

classe transformers.Qwen3ASREncoderConfig

Qwen3ASRFeatureExtractor

classe transformers.Qwen3ASRFeatureExtractor

__call__

Qwen3ASRProcessor

classe transformers.Qwen3ASRProcessor

__call__

apply_transcription_request

prepare_forced_aligner_inputs

decode_forced_alignment

decode

Qwen3ASREncoder

classe transformers.Qwen3ASREncoder

forward

Qwen3ASRModel

classe transformers.Qwen3ASRModel

forward

get_audio_features

get_placeholder_mask

Qwen3ASRForConditionalGeneration

classe transformers.Qwen3ASRForConditionalGeneration

forward

get_audio_features

Qwen3ASRForTokenClassification

classe transformers.Qwen3ASRForTokenClassification

forward

call

call