用途
Azure AI Speech 语音转文本用于将音频转写为文本，基于 Azure 快速转录（Fast Transcription）REST API 实现同步转录，支持词级时间戳、说话人分离（diarization）和多语言识别。在 OpenMontage 中通过 azure_stt 工具暴露（capability=analysis，provider=azure）。它是一个可选的云端 STT 提供方：当配置了 AZURE_SPEECH_KEY 时，优先使用它进行云端转录；本地转录工具（faster-whisper）仍是默认的离线路径，也是 Azure 不可用时的回退方案。
为什么选择快速转录而非批量转录
Azure 提供三种 STT 接口，OpenMontage 选择快速转录，因为其流水线处理的是本地音频文件：
- 快速转录（本工具使用）：输入为本地文件，multipart POST；同步、亚实时延迟；需要 key + region。
- 批量转录（Batch Transcription）：输入为 URL 上的音频（Blob + SAS）；异步任务 + 轮询；需要 Blob 存储相关配置。
- 语音 SDK（spx）：输入为麦克风 / 流 / 文件；流式；需要原生 azure-cognitiveservices-speech 包。
快速转录不需要 Blob 存储、不需要 SAS URL、也不需要原生 SDK——只需 requests 和两个环境变量。
设置
- 在 Azure 门户创建 Speech 资源；从其 Keys and Endpoint 页面复制 key 和 region。
- 设置环境变量：
export AZURE_SPEECH_KEY=your_speech_resource_key export AZURE_SPEECH_REGION=eastus # your resource's region
export AZURE_SPEECH_ENDPOINT=https://... # optional: overrides region
当 AZURE_SPEECH_KEY 加上 AZURE_SPEECH_REGION 或 AZURE_SPEECH_ENDPOINT 任一设置后，azure_stt 会报告 AVAILABLE。
在流水线中使用
除非运行必须离线，否则优先使用 azure_stt 而非 transcriber。其输出与 transcriber 模式完全一致，因此可直接替换用于 subtitle_gen 以及任何消费转录结果的阶段。
from tools.tool_registry import registry registry.discover() stt = registry._tools["azure_stt"]
result = stt.execute({ "input_path": "projects/my-video/assets/audio/narration.mp3", # "language": "en", # ISO 639-1 or BCP-47 ("en-US"); omit for auto-ID # "diarize": True, # speaker labels, no HuggingFace token needed # "max_speakers": 4, "output_dir": "projects/my-video/artifacts", }) if result.success: segs = result.data["segments"] # [{id,start,end,text,words:[...]}] words = result.data["word_timestamps"] # flat [{word,start,end,probability}]
如果 azure_stt 不可用（无 key）或出错，回退到 transcriber（本地 whisper）——其 execute 签名和输出完全相同。
重要参数
- language：传入 ISO 代码（"en"）或完整区域设置（"en-US"）。已知语言时固定它，比自动识别更快更准确。
- candidate_locales：当省略 language 时，Azure 在此候选列表上运行语言识别。将其缩小到你实际预期的语言；过大的列表会拖慢检测并容易误分类。
- diarize / max_speakers：多说话人音频（访谈、播客）时启用。将 max_speakers 设为真实上限。
- profanity_filter：None | Masked（默认）| Removed | Tags。
响应结构（映射到 transcriber 模式）
原始 Azure 响应（phrases[] 含 offsetMilliseconds / words[]）会转换为秒并映射到 OpenMontage 转录模式：
{ "segments": [ {"id": 0, "start": 0.0, "end": 2.4, "text": "Hello world", "speaker": 1, "words": [{"word": "Hello", "start": 0.0, "end": 0.5, "probability": 0.98}]} ], "word_timestamps": [{"word": "Hello", "start": 0.0, "end": 0.5, "probability": 0.98}], "language": "en-US", "duration_seconds": 2.4, "provider": "azure" }
注意：快速转录没有逐词置信度，因此每个词携带的是短语置信度作为 probability。
限制与提示
- 单次请求单文件最大约 2 小时 / 几百 MB。更长或批量任务请改用 Azure 批量转录。
- 发送干净音频（16 kHz+ 单声道足够）。如果只需要语音，先将视频转码为音频——上传更小，结果相同。
- 验证时间轴：词时间戳驱动 subtitle_gen 中的字幕提示。对照源音频抽查首尾提示。
适用场景
音频/视频转文本、生成字幕、处理多说话人录音（访谈、播客）、需要词级时间戳或多语言识别的转录任务。