ホットワード(即時・事前コンパイル)とコンテキストバイアシングを使用して、人名、製品名、業界用語などの音声認識を改善します。
最適化方法の選択
人名、製品名、業界用語は一般的な単語と発音が似ている場合があり、同音異字や誤った単語として認識されることがあります。ホットワードとコンテキストバイアシングは、正しい表記や関連情報をモデルに提供し、認識の改善を支援します。
アプリケーションが持つ情報に応じて選択します。用語の一覧がある場合はホットワードを、会話履歴や業務の説明文がある場合はコンテキストバイアシングを使用できます。ホットワードは、同じリストを複数のリクエストで再利用するかどうかに応じて、即時または事前コンパイルを選択します。使用前にサポートされるモデルとリージョンを確認してください。
| 方法 | 適した状況 | 使用方法 |
|---|---|---|
| インスタントホットワード | 人名や製品名がリクエストごとに変わる場合、または一時的な用語が少数で、リストの保存や管理が不要な場合。 | 認識リクエストごとに「用語:重み」のオブジェクトを渡します。アプリケーション側で正しい表記を用意し、重みによりモデルが各用語を優先する程度を調整できます。 |
| 事前コンパイルホットワード | 既存の業務用語集がある場合、または同じ用語を何度も認識するため、リストを一元管理したい場合。 | 用語、重み、任意の言語を含むリストを作成し、認識時にその ID を指定します。用語集の変更時にリストを更新すれば、各リクエストで全エントリを送信する必要はありません。 |
| コンテキストバイアシング | 直近の会話、業務の説明文、専門分野のテキストが保存されており、それらを認識に活用したい場合。 | 関連テキストをコンテキストメッセージとして音声と一緒に送信します。用語の抽出や個別の重み付けは不要です。対象用語の正しい表記を含めてください。明確な用語一覧がある場合は、ホットワードでも同様の誤りに対処できます。 |
ホットワードの使用
例を実行する前に、サンプル音声をダウンロードし、Model Studio コンソールで API キーを用意してください。音声の内容:「Please send the quarterly project report to Kelyra before Friday.」
インスタントホットワード
即時ホットワードはリクエストごとに変わる用語に適しています。認識リクエストの parameters.vocabulary に、ホットワード文字列(string)をキー、重み(integer)を値とする JSON オブジェクトを渡します。リストの事前作成は不要です。
-
ホットワードを設定せずに認識する
ホットワードを設定しない場合、この例の名前は正確に認識されません。次のリクエストで未設定時の認識結果を取得します。
cURL
-
即時ホットワードをリクエストに追加する
同じリクエストに「Kelyra」を追加し、重みを 4 に設定します。他の入力は変更しません。重みの範囲と調整方法はホットワードの重みの調整を参照してください。
cURL
| 設定 | 認識テキストの例 |
|---|---|
| 設定なし | Please send the quarterly project report to Kellira before Friday. |
| 設定あり | Please send the quarterly project report to Kelyra before Friday. |
事前コンパイルホットワード
事前コンパイル済みホットワードは、複数のリクエストで再利用する業務用語集に適しています。リストを事前に作成し、認識時に vocabulary_id を渡すことで、エントリの再送信が不要になります。
作成時にエントリを JSON 配列で送信します。各要素のフィールドは次のとおりです。
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
text | string | はい | 選択したモデルがサポートする言語の実在する単語です。長さの要件はホットワードテキストのルールをご参照ください。 |
weight | integer | はい | 通常のホットワードは 1~5 を使用し、4 から調整します。一部のモデルはスーパーホットワードの重み 50 もサポートします。ホットワードの重みの調整をご参照ください。 |
lang | string | いいえ | 単語が適用される言語を指定するコードです。不明な場合は省略できます。認識パラメーター language_hints との関係は語彙の整理と管理をご参照ください。 |
ホットワード管理と音声認識では同じアカウントを使用する必要があります。異なる場合、認識 API は語彙にアクセスできません。
- HTTP / cURL
- SDK
-
ホットワードリストを作成する
以下の例では
qwen-audio-3.1-asr-flashを使用し、target_modelで対象モデルを指定します。レスポンスのoutput.vocabulary_idを保存してください。cURL -
リストが使用可能であることを確認する
<vocabulary_id>を作成 API が返した ID に置き換え、状態を照会します。output.statusがOKであることを確認してから認識を実行します。cURL -
認識リクエストでリストを参照する
認識リクエストの
parameters.vocabulary_idでリストを参照します。エントリを再送信する必要はありません。cURL -
リストを再利用または削除する
後続のリクエストでも同じ ID を利用できます。リストが不要になった場合にのみ、次の削除 API を呼び出してリストのクォータを解放してください。
cURL
コンテキスト強化の使用
コンテキストバイアシングでは、既存の会話履歴や専門分野のテキストを直接利用できます。用語と重みを指定するホットワードとは異なり、テキストメッセージを渡すため、業務資料を個々のエントリに分解する必要はありません。どちらも固有名詞の認識を改善できるため、アプリケーションが持つ情報に応じて選択します。
コンテキストの準備
サンプル音声の受信者名「Kelyra」の正しい表記が既存のメッセージに含まれていれば、コンテキストとして利用できます。主なコンテキストの情報源は次の 2 種類です。
- 業務背景・専門分野のテキスト
- 会話履歴
既存のプロジェクト説明や専門資料から関連するテキストを選び、
role=user、type=input_text のメッセージに入れます。会話や返答を新たに作る必要はありません。次の配列をコンテキストとして渡します。assistant メッセージは省略できます。会話履歴はターン順に並べ、各 user を対応する assistant より前に配置します。テキスト長と保持ターン数の上限は使用制限を参照してください。設定と呼び出し
準備したコンテキストで同じ音声を認識します。モデルファミリーに応じて呼び出し例を選択してください。
- Qwen-Audio-ASR
- Qwen-Audio-ASR-Message / Qwen-Audio-ASR-Streaming
- Qwen-Audio-ASR-Filetrans
以下の例では
qwen-audio-3.1-asr-flash を使用します。input.messages にコンテキストメッセージを順に配置し、input_audio を含む現在の音声メッセージを最後に配置します。cURL
| 設定 | 認識テキストの例 |
|---|---|
| 設定なし | Please send the quarterly project report to Kellira before Friday. |
| 設定あり | Please send the quarterly project report to Kelyra before Friday. |
認識の調整とトラブルシューティング
同じ音声で設定前後の結果を比較し、単語、重み、コンテキストを調整します。ホットワードの調整は両方のホットワード方式に適用されます。
ホットワードの重みの調整
通常のホットワードの重みは 1~5 です。weight=4 から調整してください。重みが高いほど優先されますが、高すぎると発音が似た別の単語を誤って置き換える場合があります。
| 重み | 優先度 | 適した状況 |
|---|---|---|
| 1~2 | 弱い | 一般的な単語と発音が似ており、過剰な修正を避ける場合 |
| 3~4 | 中程度 | 推奨:大半のシナリオでの初期設定 |
| 5 | 強い | 音声内で頻繁に使用され、他の単語と混同されにくい用語 |
weight=50 もサポートし、対象用語の再現率を向上できます。語彙またはリクエストごとに最大 50 語です。
語彙の整理と管理
- シナリオ別に分類:事前コンパイル済みホットワードでは、業務シナリオごとにリストを作成できます。医療用語と製品名などを別々に管理し、無関係なエントリを減らします。
-
単語の言語と音声の言語を区別:事前コンパイル語彙では複数の言語を混在させ、
langで区別できます。認識パラメーターlanguage_hintsは音声の言語を指定します。設定すると、一致する言語のホットワードのみが有効になり、その他は無視されます。 - 定期的に管理:業務の変化に応じてエントリを更新し、不要なリストを削除してクォータを解放します。
ホットワードリストの更新は 5 分以上の間隔を空けることを推奨します。それより短いと、更新後のホットワードが反映されない場合があります。
認識品質のトラブルシューティング
まず、設定が反映されていないのか、ホットワードへの偏りが強すぎるのか、音声自体の認識が難しいのかを区別し、該当する項目を確認します。
| 現象 | 確認と対処 |
|---|---|
| ホットワードが期待どおり認識されない | まずサポートされるモデルとリージョンを確認します。即時ホットワードは parameters.vocabulary に指定します。事前コンパイル済みホットワードでは、アカウント、vocabulary_id、status=OK、作成時の target_model と認識モデルの一致を確認します。対応範囲内でホットワードの重みを上げ、同じ音声の結果を比較して、重みが低すぎることが原因か確認します。 |
| 別の単語がホットワードに誤変換される | 対応範囲内でホットワードの重みを下げ、業務シナリオと関係のないエントリを減らします。lang と認識 API の language_hints が一致し、対象言語のエントリを使用しているか確認します。 |
| コンテキストで対象語が改善しない | 用語の正しい表記、メッセージのロール、型、順序、API の入力フィールドを確認します。長さやターン数の上限を超えたテキストは切り詰め、または破棄される場合があります。使用制限を参照してください。 |
| 一般的な単語も多く誤認識される | 音声形式とサンプルレートがモデル要件を満たしているか確認し、背景雑音を減らします。単一言語の音声では、認識 API の language_hints で言語を指定できます。モデル選択と音声要件は音声認識の概要を参照してください。 |
サポートされるモデルとリージョン
- 事前コンパイルホットワード
- インスタントホットワード
- コンテキストバイアシング
- シンガポール
- 中国 (北京)
ホットワードはプライマリワークスペースのみでサポートされ、サブワークスペースでは使用できません。
- Qwen-Audio-ASR:qwen-audio-3.1-asr-flash、qwen-audio-3.0-asr-flash
- Qwen-Audio-ASR-Streaming:qwen-audio-3.1-asr-flash-streaming、qwen-audio-3.0-asr-flash-streaming
- Qwen-Audio-ASR-Filetrans:qwen-audio-3.1-asr-flash-filetrans、qwen-audio-3.0-asr-flash-filetrans
- Qwen-Audio-ASR-Message:qwen-audio-3.1-asr-flash-message
- Fun-ASR-Realtime:fun-asr-realtime
- Fun-ASR-Flash:fun-asr-flash-2026-06-15
- Fun-ASR:fun-asr
使用制限
- ホットワードの制限
- ホットワードテキストのルール
- コンテキストの制限
| 制限項目 | 説明 |
|---|---|
| ホットワードリスト数 | アカウントごとに最大 50 個の事前コンパイル語彙を作成でき、全モデルで共有します。各語彙には vocabulary_id があります。 |
| ホットワード数 | Qwen-Audio-ASR-Message、Qwen-Audio-ASR-Streaming、Qwen-Audio-ASR-Filetrans、Qwen-Audio-ASR シリーズ:最大 2000 語。Fun-ASR-Realtime、Fun-ASR-Flash、Fun-ASR シリーズのメインバージョン:最大 2000 語。これらの他のモデルおよび Paraformer シリーズ:最大 500 語。事前コンパイルホットワードは語彙ごと、インスタントホットワードはリクエストごとに数えます。 |
| スーパーホットワード数 | 重みが 50 のエントリは最大 50 個です。 |
Qwen-Audio-ASR-Message、Qwen-Audio-ASR-Streaming、Qwen-Audio-ASR-Filetrans、Qwen-Audio-ASR シリーズで事前コンパイルホットワードとインスタントホットワードを両方設定すると、サービスは両方をマージします。マージ後に 2000 語を超える場合は、ランダムに 2000 語を選択して使用します。
機能の料金
即時および事前コンパイル済みホットワードの機能自体は無料です。ホットワードやコンテキストバイアシングを使用するモデルの呼び出し料金は、課金ルールを参照してください。
関連 API
- ホットワードリストの作成、照会、更新、削除などの操作はホットワード管理 APIを参照してください。
- ホットワード管理 SDK:Java SDK、Python SDK。
- モデル呼び出し API:Qwen-Audio-ASR-Message クライアントイベント、Qwen-Audio-ASR-Streaming クライアントイベント、Qwen-Audio-ASR-Filetrans HTTP API、Qwen-Audio-ASR HTTP API。