Transformers documentation

Qwen3 ASR

Transformers

はじめに

Transformers インストールクイックスタート

ベースクラス

モデル

プリプロセッサ

推論

Pipeline API

Generate API

最適化

モデルとチャットする

サービング

トレーニング

はじめに

カスタマイズ

パラメータ効率の良いファインチューニング

パフォーマンス

分散学習

ハードウェア

量子化

エコシステム統合

リソース

API

主要クラス

モデル

テキストモデル

ビジョンモデル

音声モデル

動画モデル

マルチモーダルモデル

強化学習モデル

時系列モデル

内部ヘルパー

リファレンス

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

このモデルは2026年1月29日にHF papersで公開され、2026年6月26日にHugging Face Transformersに貢献されました。

Qwen3 ASR

概要

Qwen3 ASRは、AlibabaのQwenチームが開発した自動音声認識モデルです。Whisperスタイルの音声エンコーダーとQwen3言語モデルデコーダーを組み合わせ、音声からテキストへの書き起こしを実現します。このモデルは、自動言語検出と多言語対応の書き起こしをサポートしています。

強制アライナーモデルも含まれています。これは、提供された文字起こしとその音声にタイムスタンプを付与するために使用できます。このモデルは、単語の長さを予測する分類ヘッドを備えた、同じ音声エンコーダーモデルを使用しています。このモデルは、任意のASRモデルの文字起こしと組み合わせて使用できます（以下はParakeet CTCを用いた例です）。

利用可能なチェックポイント:

サポートされている言語は以下の通りです:

Qwen3-ASR-1.7B および Qwen3-ASR-0.6B: 中国語 (zh)、英語 (en)、広東語 (yue)、アラビア語 (ar)、ドイツ語 (de)、フランス語 (fr)、スペイン語 (es)、ポルトガル語 (pt)、インドネシア語 (id)、イタリア語 (it)、韓国語 (ko)、ロシア語 (ru)、タイ語 (th)、ベトナム語 (vi)、日本語 (ja)、トルコ語 (tr)、ヒンディー語 (hi)、マレー語 (ms)、オランダ語 (nl)、スウェーデン語 (sv)、デンマーク語 (da)、フィンランド語 (fi)、ポーランド語 (pl)、チェコ語 (cs)、フィリピン語 (fil)、ペルシア語 (fa)、ギリシャ語 (el)、ハンガリー語 (hu)、マケドニア語 (mk)、ルーマニア語 (ro)。
Qwen3-ForcedAligner-0.6B: 中国語 (zh)、英語 (en)、広東語 (yue)、フランス語 (fr)、ドイツ語 (de)、イタリア語 (it)、日本語 (ja)、韓国語 (ko)、ポルトガル語 (pt)、ロシア語 (ru)、スペイン語 (es)。

詳細については、QwenLM/Qwen3-ASRの元のリポジトリおよびレポートを参照してください。

このモデルは、Eric Bezzam氏とMuhammed Tariq氏によって提供されました。

使用方法

単純な文字起こし

音声の文字起こしを行う最もシンプルな方法は、apply_transcription_request を使用することです。この関数はチャットテンプレートの整形を自動で行うため、apply_chat_template のための便利なラッパーとして機能します（Chat template を参照）。

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

言語の強制

以下に示すように、転写言語を強制指定できます。

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

コンテキスト / ホットワード

prompt を介して、自由形式のコンテキスト（例：ドメイン固有の語彙、名前、背景情報など）を渡すことで、文字起こしを偏らせることができます。

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

バッチ推論

listのオーディオを渡すことでバッチ推論が可能であり、指定された場合はlistの言語および/またはプロンプトも渡すことができます。

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}")

チャットテンプレート

Qwen3 ASR はチャットテンプレート形式の入力も受け入れます。上記の上記に示された apply_transcription_request の使い方は、apply_chat_template のための簡便なラッパーです。

プリフィルによってアシスタントのターンをlanguage <NAME><asr_text>で事前入力し、continue_final_message=Trueを渡すことで、チャットテンプレートを通じて言語を強制指定できます。apply_transcription_requestは内部でこの処理を行っています。なお、言語を強制指定する場合は、バッチ内のすべての音声に対してプリフィルを設定する必要があります（以下に示すように）。

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)

トレーニング

Qwen3 ASR は、モデルが出力する損失で学習できます。事前学習済みの動作を維持するために、ターゲットの文字起こしをアシスタントターンに、モデルの出力形式 language <NAME><asr_text>... で配置し、output_labels=True を渡します。音声とパディングの位置は自動的にマスクされます。

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")
model.train()

transcript = "Mr. Quilter is the apostle of the middle classes, and we are glad to welcome his gospel."
conversation = [
    [
        {
            "role": "user",
            "content": [
                {
                    "type": "audio",
                    "path": "https://huggingface.co/datasets/bezzam/audio_samples/resolve/main/librispeech_mr_quilter.wav",
                },
            ],
        },
        {"role": "assistant", "content": [{"type": "text", "text": f"language English<asr_text>{transcript}"}]},
    ],
]

inputs = processor.apply_chat_template(
    conversation, tokenize=True, return_dict=True, processor_kwargs={"output_labels": True},
).to(model.device, model.dtype)

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

強制アライメント（単語レベルのタイムスタンプ）

Qwen3ASRForTokenClassification を使用して、文字起こし結果から単語単位のタイムスタンプを取得します。まず ASR モデルで文字起こしを行い、その後、フォースドアライナーでアラインメントを実行します。

サポートされている言語は以下の通りです：中国語（zh）、英語（en）、広東語（yue）、フランス語（fr）、ドイツ語（de）、イタリア語（it）、日本語（ja）、韓国語（ko）、ポルトガル語（pt）、ロシア語（ru）、スペイン語（es）。

日本語にはnagisaライブラリ、韓国語にはsoynlpライブラリが必要です:

pip install nagisa soynlp

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

別のASRモデルを使用する場合

強制アライナーはモデル非依存であり、任意のASRシステムからの文字起こし結果を提供できます。以下は、文字起こしにNVIDIA Parakeet CTCを使用するバッチ推論の例です。

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

ASRモデルとforced alignerモデルの両方で、より高速な推論のためにtorch.compileをサポートしています。forced alignerは自己回帰デコーディングを伴わない単一のフォワードパスで動作するため、コンパイルとの相性が特に良好です。これにより、大量の音声タイムスタンプ付与に最適です。任意のASRモデルで文字起こしを行い、その後、コンパイル済みのforced alignerでバッチアラインメントを実行することで、最大のスループットを実現できます。

強制アライナー

A100では、バッチサイズが4の場合に約1.2倍の高速化を確認しました（スクリプト）。

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)

ASRモデル(generate)

自己回帰型文字起こしでは、CompileConfig オブジェクトを指定して generate を設定すると、generate 内のトークンごとのフォワードパスが torch.compile によって高速化されます。

A100では、バッチサイズが4の場合、約3.8倍の高速化を確認しました（スクリプト）。

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}")

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

概要

使用方法

単純な文字起こし

言語の強制

コンテキスト / ホットワード

バッチ推論

チャットテンプレート

トレーニング

強制アライメント（単語レベルのタイムスタンプ）

Qwen3 ASR を使用して

別のASRモデルを使用する場合

Torch compile

強制アライナー

ASRモデル(generate)

Pipelineの使用方法

Qwen3ASRConfig

クラス transformers.Qwen3ASRConfig

Qwen3ASREncoderConfig

class transformers.Qwen3ASREncoderConfig

Qwen3ASRFeatureExtractor

クラス transformers.Qwen3ASRFeatureExtractor

__call__

Qwen3ASRProcessor

クラス transformers.Qwen3ASRProcessor

__call__

apply_transcription_request

prepare_forced_aligner_inputs

decode_forced_alignment

decode

Qwen3ASREncoder

class transformers.Qwen3ASREncoder

forward

Qwen3ASRModel

クラス transformers.Qwen3ASRModel

forward

get_audio_features

get_placeholder_mask

Qwen3ASRForConditionalGeneration

クラス transformers.Qwen3ASRForConditionalGeneration

forward

get_audio_features

Qwen3ASRForTokenClassification

クラス transformers.Qwen3ASRForTokenClassification

forward

call

call