音声認識APIだけでは不十分：堅牢な文字起こしシステム構築のための設計指針

デモだけでは測れない信頼性

実際の利用シーンでは、長時間のインタビューや接続切れ、重複したWebhook、単語の重なりや順序入れ替わりなど、さまざまな障害が発生します。これらは単なるAPI呼び出し以上の問題となり、文書管理システムやメディアパイプライン、分散システムとして扱う必要があります。

音声ファイルはメタデータだけで判断しない

ユーザーがアップロードした音声ファイル（例：interview.mp3）の拡張子やMIMEタイプは信頼できません。ffprobe 等で実際のコンテナ形式、音声ストリームの有無、正確な再生時間、使用可能なトラックを確認し、CPU・メモリ・ディスク容量との整合性を検証します。検証結果に基づき、認識エンジン向けの派生ファイルとブラウザ再生用の派生ファイルを生成し、エラーメッセージも具体的に提示します。

ジョブと試行を分離する

「文字起こし」ジョブはユーザーの意図を表し、個々の試行は特定のプロバイダーとモデルへの実行を示します。結果は公開対象として別管理し、プロバイダー失敗時の再試行や遅延コールバック、キャンセル処理を安全に行えるようにします。また、試行ごとのコストとレイテンシを測定でき、ジョブ全体の状態と混同しないようにします。

単純なフェイルオーバーは契約変更になる

プロバイダーは言語、話者分離、タイムスタンプ精度、地域対応など多様な機能を持ちます。「プロバイダーAが失敗したらBへ」という単純な切替は、期待された機能が失われることになり、暗黙の契約変更です。まず互換性のある候補を除外し、残ったものを能力スナップショットに基づいて順位付けします。

非同期処理と状態管理

長時間録音はHTTPリクエスト‑レスポンスで完結せず、バックグラウンドキューで処理します。キューの再配信、ワーカーの中断、Webhook の遅延・重複、ユーザーによるキャンセルなど、すべてが「少なくとも一度」の振る舞いになります。データベース上の状態機械でジョブID、リーストークン、期限を管理し、古いワーカーが新しい結果を書き換えることを防ぎます。Webhook ハンドラは認証とイベント記録のみ行い、速やかに応答します。

プロバイダーからのJSONは未検証入力

受信したJSONはランタイムでスキーマ検証し、負のタイムスタンプや欠損フィールド、異常な信頼度などを排除します。その後、プロバイダー依存の構造を統一フォーマットに正規化し、単語の重なりや逆転は修正または拒否します。正規化済みデータは編集・閲覧ロジックの基礎とし、元のプロバイダー結果は別保存して将来の再評価に備えます。

時間リンク付き文書として扱う

文字起こしは単なる文字列ではなく、各単語に開始・終了時刻が紐付いた文書です。この情報により、クリックで音声再生位置へジャンプ、再生中のハイライト、字幕エクスポート、話者訂正の永続化などが可能になります。編集はパッチ方式で行い、リビジョン番号で競合を回避し、サマリーや翻訳は参照リビジョンを固定して生成します。

AI 後処理は限定的な権限で

句読点追加や章立て、要約生成などのAI活用は、元の文字起こしを改変しない範囲で提案形式に留めます。例えば「単語42の後に句点を挿入」といった操作だけを許可し、インデックスやタイムスタンプの検証に失敗した場合は元データに戻します。翻訳や要約でも、時間参照は元データに合わせてラベル付けし、AI がシステムプロンプトを上書きしないようにします。

観測可能性は内容を残さずに

ログには内部ID、プロバイダー・モデル情報、メディアの長さ・サイズ区分、キュー待ち時間、リトライ回数、エラーコード、請求単位などを記録し、音声本体や文字起こしテキストは出力しません。これにより、障害原因の検索と対策は容易になり、機密情報漏洩リスクを低減できます。

段階的な実装ロードマップ

最小限のプロトタイプは、短い音声ファイルを単一プロバイダーで文字起こしし、スキーマ検証とキュー投入までを行います。その後、ジョブと試行の分離、状態遷移の冪等性、メディア検査・正規化、リビジョン管理、AI 後処理、マルチプロバイダーの互換性フィルタという順に機能を拡張していくことで、堅牢かつ拡張性の高い文字起こしシステムを構築できます。

元記事: https://dev.to/loklok5/why-speech-to-text-is-more-than-calling-an-ai-api-418e