Azure AI Transcription Python SDK,支持实时与批量语音转文字,含说话人分离与时间戳
Azure Ai Translaction Py.是一项面向实际任务的技能,主要用于Azure AI Translaction(逐字逐句) CHLPYON QQ, TRANSCRIPTION ENDPOINT TRURE AI URL, https://<resource>.cognitives.azure.com, 与资源, 与资源。它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。
若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;
涉及批量任务时,还应保存进度,避免中断后重复操作。该技能适合用于一次性任务,也可以接入自动化工作流,与其他技能或上层代理配合完成更完整的业务链路;在组合使用时,应明确每一步的输入输出关系,并避免不同步骤之间出现参数冲突。
Azure AI Transcription(speech-to-text)的 Python 客户端库,支持实时与批量转写。
pip install azure-ai-transcription
TRANSCRIPTION_ENDPOINT=https://.cognitiveservices.azure.com TRANSCRIPTION_KEY=API_KEY
TRANSCRIPTION_ENDPOINT 为 Azure AI 资源的终结点 URL,形如 https://,与资源所在区域一致。TRANSCRIPTION_KEY 为该资源的订阅密钥(primary 或 secondary 均可),用于鉴权。两个变量都不要硬编码进源码,建议放入 .env 或系统环境变量;密钥泄漏后须在门户轮换并更新变量。
使用订阅密钥认证(此客户端不支持 DefaultAzureCredential):
import os
from azure.ai.transcription import TranscriptionClient
client = TranscriptionClient(
endpoint=os.environ["TRANSCRIPTION_ENDPOINT"],
credential=os.environ["TRANSCRIPTION_KEY"]
)
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|---|---|---|---|
| LLM API | API | 必需 | 由Agent内置LLM提供 |
需要配置对应API Key,详见上文环境配置章节
API Key配置方式:
export API_KEY="your_api_key_here"
配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。
diarization_enabled 区分多说话人,标注每段发言归属locale 指定识别语言(如 en-US、zh-CN),提升识别准确率解析用户指令,执行核心操作并返回处理结果。
输入: 用户提供操作指令和必要参数。
输出: 返回操作执行的结果。
指令解析与执行操作,处理输入数据并返回结果指令解析与执行相关配置参数进行设置处理输入数据,执行转换操作并输出结果。
输入: 用户提供操作指令和必要参数。
输出: 返回操作执行的结果。
数据处理与转换操作,处理输入数据并返回结果数据处理与转换相关配置参数进行设置验证处理结果的正确性,格式化输出并返回给用户。
输入: 用户提供操作指令和必要参数。
输出: 返回操作执行的结果。
结果验证与输出操作,处理输入数据并返回结果结果验证与输出相关配置参数进行设置本skill还覆盖以下能力场景: Azure、Transcription、Python、SDK、支持实时与批量语、音转文字、含说话人分离与时、客户端库、覆盖实时流式与批、量两种语音转文字、批量模式适合存储、实时模式通过流式、使用订阅密钥认证、ENDPOINT、KEY、环境变量配置资源、提供时间戳、流式背压处理与会、话关闭等实践要点。这些能力在上述核心功能中均有对应处理逻辑。
本skill覆盖源skill的以下能力点:
| 源能力点 | 支持状态 | 实现方式 |
|---|---|---|
| Specify language | 支持 | 通过核心功能实现对应能力 |
| Capture timestamps | 支持 | 通过核心功能实现对应能力 |
处理: 按照skill规范执行源能力映射操作,遵循单一意图原则。 输出: 返回源能力映射的执行结果,包含操作状态和输出数据。
本skill涉及以下领域术语: 创意判断的任务, real, variables, environment, best, 需要提升效率, 不适用于需要人工, authentication, 批量处理, handle, practices, 自动化流程, 工作流优化时使用, installation, batch
输入: 用户提供领域术语所需的指令和必要参数。 输出: 返回领域术语的执行结果,包含操作状态和输出数据。
azure-ai-transcription-py的相关能力-US: 命令参数,用于指定操作选项-US: 命令参数,用于指定操作选项-US: 命令参数,用于指定操作选项-US: 命令参数,用于指定操作选项-US: 命令参数,用于指定操作选项-US: 命令参数,用于指定操作选项-US: 命令参数,用于指定操作选项-US: 命令参数,用于指定操作选项-US: 命令参数,用于指定操作选项job = client.begin_transcription(
name="meeting-transcription",
locale="en-US",
content_urls=["https:///audio.wav"],
diarization_enabled=True
)
result = job.result()
print(result.status)
begin_transcription 提交一个批量转写作业并立即返回作业句柄;job.result() 阻塞等待作业完成并返回结果。content_urls 指向可公开访问或带 SAS 的音频 URL。开启 diarization_enabled 后结果中会标注每段发言的说话人标识。
长音频建议优先用批量模式:服务端异步处理,不受客户端连接时长限制;结果可包含分通道、分说话人的完整文稿。
stream = client.begin_stream_transcription(locale="en-US")
stream.send_audio_file("audio.wav")
for event in stream:
print(event.text)
begin_stream_transcription 建立一个流式会话;send_audio_file 把本地音频文件按块送入会话;迭代 stream 逐事件获取识别结果(含中间结果与最终结果)。适合会议同传、字幕生成、语音助手等需要低延迟反馈的场景。
实时转写对音频输入速率敏感:发送速率远超识别速率会产生背压,建议按块限速使其接近真实音频时长。中间结果会在最终结果到达后被覆盖,渲染字幕时须区分中间结果与最终结果,避免重复显示。
job.result() 返回结果对象,包含作业状态与转写内容。常见状态值:
Running:作业仍在处理,继续轮询等待Succeeded:作业成功完成,可取回完整文稿Failed:作业失败,需检查 content_urls 可达性、locale 合法性与配额结果内容按识别片段组织,每个片段含文本、起止时间戳与(开启时)说话人标识。批量结果可按通道、按说话人分组导出;实时结果按事件顺序累积,中间结果会被最终结果覆盖。导出 SRT/VTT 字幕时,把每个片段起止时间戳格式化为时间码(形如 00:00:01,000 至 00:00:03,000)与文本拼接成字幕条目;导出纯文稿时按片段顺序拼接文本并丢弃时间戳。
diarization,结果中标注每段发言归属locale 提升识别准确率,避免语言误判send_audio_file 发送速率,避免缓冲堆积azure-ai-transcription 包(通过 pip install azure-ai-transcription 安装)TRANSCRIPTION_ENDPOINT 与 TRANSCRIPTION_KEY将会议录音(WAV/MP3)上传至 Blob 存储并生成 SAS URL,提交批量转写作业并开启说话人分离,异步等待作业完成后取回分说话人的完整会议文稿。适合长会议、离线归档、会议纪要生成。
建立流式会话,边采集音频边送入 send_audio_file,迭代事件流获取识别文本并实时渲染字幕。适合线上会议同传、直播字幕、语音助手等低延迟场景。
对含多位发言人的音频(如圆桌讨论、访谈)开启 diarization_enabled,结果中标注每段发言的说话人标识,便于区分发言人、生成发言人维度统计。批量与实时模式均可使用。
为识别结果启用时间戳捕获,把时间戳与文本对齐导出为 SRT/VTT 字幕格式;也可按时间戳定位关键片段做摘要或剪辑。适合视频字幕、播客归档、媒体资产管理。
用户有一段 90 分钟的会议录音 meeting.wav 已上传至 Blob 并得到 SAS URL。先配置环境变量 TRANSCRIPTION_ENDPOINT 与 TRANSCRIPTION_KEY,实例化 TranscriptionClient。调用 begin_transcription(name="meeting-20260406", locale="zh-CN", content_urls=["https://。job.result() 阻塞等待,完成后从 result 取回分说话人的完整文稿,每段发言附带说话人标识与时间戳。导出为会议纪要后关闭会话。
用户需要把一段本地 audio.wav 实时转写为字幕。建立流式会话 stream = client.begin_stream_transcription(locale="en-US"),调用 stream.send_audio_file("audio.wav") 按块送入音频,迭代 for event in stream 获取识别事件,把 event.text 实时渲染到字幕层。处理流式背压避免发送速率过快,转写结束后关闭会话释放资源。
用户有一段英文播客 podcast.wav,需要生成 SRT 字幕。批量提交 begin_transcription(locale="en-US", content_urls=[...], diarization_enabled=False),在结果处理中提取每个识别片段的起始与结束时间戳,按 SRT 格式拼接序号、时间码与文本后写入 podcast.srt。指定 en-US 后专有名词识别准确率明显提升。
实例化 TranscriptionClient 时 os.environ["TRANSCRIPTION_ENDPOINT"] 抛 KeyError。检查环境变量是否已导出(常见为 https://),在 shell 或 .env 中配置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令。不要把 endpoint 硬编码进源码。
调用转写接口返回 401 或 403。核对 TRANSCRIPTION_KEY 是否为该资源的有效订阅密钥(primary 或 secondary 均可),确认 endpoint 与 key 属于同一资源同一区域。密钥泄漏或轮换后旧 key 会失效,需更新环境变量。
尝试用 DefaultAzureCredential 认证时报错。此客户端仅支持订阅密钥认证,改用 credential=os.environ["TRANSCRIPTION_KEY"] 传入订阅密钥。不要尝试用托管标识或工作负载标识。
批量转写作业提交后长时间不返回或返回失败。确认 content_urls 指向的 URL 可被服务端公开访问或附带了未过期的 SAS 令牌;Blob 容器若为私有须生成只读 SAS;URL 协议须为 HTTPS。
指定 locale 后识别准确率低或报错语言不支持。核对 locale 是否在 Azure AI Speech 支持的语言列表内(如 en-US、zh-CN、ja-JP),多语言音频可考虑自动语言识别或分段指定。
实时转写时 send_audio_file 发送速率过快,事件流消费不及时导致内存或缓冲堆积。控制发送速率使其接近真实音频时长(可按块限速),或在消费者侧异步处理事件;避免一次性灌入超长音频。
实时转写结束后未关闭会话,服务端连接与配额未释放。转写完成后显式关闭会话(如 stream.close() 或使用 with 上下文管理),避免连接配额耗尽影响后续转写。
短时间内提交过多批量作业或并发流式会话触发服务限流。收到 429 时按 Retry-After 头退避后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令;对批量作业做队列化与并发上限控制;实时会话控制同时在线数。
长音频(数十分钟以上)、已存储在 Blob、可离线处理、需要分说话人完整文稿的场景用批量转写;需要低延迟反馈、边录边出文字、会议同传与直播字幕场景用实时转写。两者都支持说话人分离与时间戳。
此客户端仅支持订阅密钥认证,通过 TRANSCRIPTION_ENDPOINT 与 TRANSCRIPTION_KEY 环境变量配置资源,实例化时传入 credential=os.environ["TRANSCRIPTION_KEY"]。不支持 DefaultAzureCredential。
批量模式在 begin_transcription 中设置 diarization_enabled=True;实时模式按会话配置开启。开启后结果中标注每段发言的说话人标识。多说话人场景建议开启,单人录音可关闭以降低成本。
填 BCP-47 语言标签,如 en-US、zh-CN、ja-JP、en-GB。指定与音频一致的语言可显著提升识别准确率,避免语言误判。多语言音频可考虑自动语言识别或分段指定。
长文件优先用批量转写并存储在 Blob 中,服务端异步处理不受客户端连接时长限制;job.result() 阻塞等待完成。不要用实时流式会话处理超长音频,容易触发背压与超时。
实时转写完成后显式关闭会话释放服务端资源与连接配额,建议使用 with 上下文管理或 try/finally 确保异常路径也会关闭。批量作业通过轮询 job.result() 等待完成,无须显式关闭会话。
| 错误场景 | 原因 | 处理方式 |
|---|---|---|
| LLM响应超时或无响应 | 网络延迟或模型负载过高 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接,执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令请求;确认Agent平台LLM服务正常 |
| 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求,参考示例章节 |
| 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述,补充必要的上下文信息 |
| 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求;检查命令权限设置 |
相关专题
热门下载
相关下载
精品课程
共6课时 | 54.7万人学习
共89课时 | 134.3万人学习
共49课时 | 82.7万人学习