Azure AI Transcription Python SDK,支持实时与批量语音转文字,含说话人分离与时间戳
Azure Ai Translaction Py.
功能概述
Azure Ai Translaction Py.是一项面向实际任务的技能,主要用于Azure AI Translaction(逐字逐句) CHLPYON QQ, TRANSCRIPTION ENDPOINT TRURE AI URL, https://<resource>.cognitives.azure.com, 与资源, 与资源。它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。
核心要点
- 使用时应结合输入条件选择合适的执行方式,核对必要参数、依赖环境与输出内容,并按原始要求处理异常情况。
- 从功能定位来看,该技能强调把分散的操作要求整理成清晰、可复用的处理流程,使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。
- 实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;
使用与执行
若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;
结果检查与注意事项
涉及批量任务时,还应保存进度,避免中断后重复操作。该技能适合用于一次性任务,也可以接入自动化工作流,与其他技能或上层代理配合完成更完整的业务链路;在组合使用时,应明确每一步的输入输出关系,并避免不同步骤之间出现参数冲突。
Azure Ai Transcription Py
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"]
)
依赖说明
运行环境
- Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
- 操作系统: Windows / macOS / Linux
依赖项
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|---|---|---|---|
| LLM API | API | 必需 | 由Agent内置LLM提供 |
API Key 配置
需要配置对应API Key,详见上文环境配置章节
可用性分类
- 分类: MD+EXEC()
API Key配置方式:
export API_KEY="your_api_key_here"
配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。
核心能力
- 批量转写:对存储在 Blob 中的长音频文件提交转写作业,支持说话人分离与多通道
- 实时转写:通过流式会话边录边转,逐事件输出识别文本,适合会议同传与字幕生成
- 说话人分离:开启
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
输入: 用户提供领域术语所需的指令和必要参数。 输出: 返回领域术语的执行结果,包含操作状态和输出数据。
使用流程
- 环境确认: 确认Agent平台已加载本skill,检查依赖说明中的环境要求
- 指令输入: 向Agent描述需要执行的任务,引用
azure-ai-transcription-py的相关能力 - 执行处理: Agent按照核心能力章节的指令执行任务
- 结果验证: 检查输出结果是否符合预期,参考错误处理章节处理异常
命令参数说明
-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,结果中标注每段发言归属 - 存储在 Blob 中的长文件用批量转写,避免客户端连接时长限制
- 捕获时间戳用于字幕对齐与片段定位
- 指定
locale提升识别准确率,避免语言误判 - 实时转写时处理流式背压,控制
send_audio_file发送速率,避免缓冲堆积 - 转写完成后关闭会话,释放服务端资源与连接配额
依赖
- Python 3.8 及以上
azure-ai-transcription包(通过pip install azure-ai-transcription安装)- 已部署的 Azure AI 资源,获得
TRANSCRIPTION_ENDPOINT与TRANSCRIPTION_KEY - 批量转写的音频须可通过 HTTPS 公开访问或附 SAS 令牌;实时转写的本地音频须为支持的格式(WAV / MP3 等)
适用场景
会议录音批量转写
将会议录音(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 后专有名词识别准确率明显提升。
异常处理
TRANSCRIPTION_ENDPOINT 未设置
实例化 TranscriptionClient 时 os.environ["TRANSCRIPTION_ENDPOINT"] 抛 KeyError。检查环境变量是否已导出(常见为 https://),在 shell 或 .env 中配置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令。不要把 endpoint 硬编码进源码。
TRANSCRIPTION_KEY 无效(401/403)
调用转写接口返回 401 或 403。核对 TRANSCRIPTION_KEY 是否为该资源的有效订阅密钥(primary 或 secondary 均可),确认 endpoint 与 key 属于同一资源同一区域。密钥泄漏或轮换后旧 key 会失效,需更新环境变量。
DefaultAzureCredential 不被支持
尝试用 DefaultAzureCredential 认证时报错。此客户端仅支持订阅密钥认证,改用 credential=os.environ["TRANSCRIPTION_KEY"] 传入订阅密钥。不要尝试用托管标识或工作负载标识。
content_urls 不可访问
批量转写作业提交后长时间不返回或返回失败。确认 content_urls 指向的 URL 可被服务端公开访问或附带了未过期的 SAS 令牌;Blob 容器若为私有须生成只读 SAS;URL 协议须为 HTTPS。
locale 不被支持
指定 locale 后识别准确率低或报错语言不支持。核对 locale 是否在 Azure AI Speech 支持的语言列表内(如 en-US、zh-CN、ja-JP),多语言音频可考虑自动语言识别或分段指定。
流式背压导致缓冲堆积
实时转写时 send_audio_file 发送速率过快,事件流消费不及时导致内存或缓冲堆积。控制发送速率使其接近真实音频时长(可按块限速),或在消费者侧异步处理事件;避免一次性灌入超长音频。
会话未关闭导致资源泄漏
实时转写结束后未关闭会话,服务端连接与配额未释放。转写完成后显式关闭会话(如 stream.close() 或使用 with 上下文管理),避免连接配额耗尽影响后续转写。
限流(429)
短时间内提交过多批量作业或并发流式会话触发服务限流。收到 429 时按 Retry-After 头退避后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令;对批量作业做队列化与并发上限控制;实时会话控制同时在线数。
常见问题
Q1:批量转写与实时转写如何选择?
长音频(数十分钟以上)、已存储在 Blob、可离线处理、需要分说话人完整文稿的场景用批量转写;需要低延迟反馈、边录边出文字、会议同传与直播字幕场景用实时转写。两者都支持说话人分离与时间戳。
Q2:如何认证?
此客户端仅支持订阅密钥认证,通过 TRANSCRIPTION_ENDPOINT 与 TRANSCRIPTION_KEY 环境变量配置资源,实例化时传入 credential=os.environ["TRANSCRIPTION_KEY"]。不支持 DefaultAzureCredential。
Q3:如何开启说话人分离?
批量模式在 begin_transcription 中设置 diarization_enabled=True;实时模式按会话配置开启。开启后结果中标注每段发言的说话人标识。多说话人场景建议开启,单人录音可关闭以降低成本。
Q4:locale 怎么填?
填 BCP-47 语言标签,如 en-US、zh-CN、ja-JP、en-GB。指定与音频一致的语言可显著提升识别准确率,避免语言误判。多语言音频可考虑自动语言识别或分段指定。
Q5:如何处理长文件?
长文件优先用批量转写并存储在 Blob 中,服务端异步处理不受客户端连接时长限制;job.result() 阻塞等待完成。不要用实时流式会话处理超长音频,容易触发背压与超时。
Q6:会话怎么管理?
实时转写完成后显式关闭会话释放服务端资源与连接配额,建议使用 with 上下文管理或 try/finally 确保异常路径也会关闭。批量作业通过轮询 job.result() 等待完成,无须显式关闭会话。
错误处理
| 错误场景 | 原因 | 处理方式 |
|---|---|---|
| LLM响应超时或无响应 | 网络延迟或模型负载过高 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接,执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令请求;确认Agent平台LLM服务正常 |
| 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求,参考示例章节 |
| 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述,补充必要的上下文信息 |
| 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求;检查命令权限设置 |
已知限制
- 依赖云服务,需要网络连接,断网时无法转写
- 仅支持订阅密钥认证,不支持 DefaultAzureCredential、托管标识等
- 批量转写要求音频可通过公开 URL 或 SAS 访问,纯本地文件须先上传
- 实时转写对超长音频容易触发背压,长文件建议用批量模式
- 识别准确率受音频质量、背景噪声、口音与 locale 匹配度影响
- 说话人分离为基于声纹的启发式标注,不保证完全准确,跨频道同说话人可能合并
- 服务端有并发与限流配额,高频提交需做队列化与退避
热门AI工具
相关专题
本专题聚焦Go-Zero的API开发,拆解.api描述文件的语法结构、路由与分组定义、参数绑定与校验规则,说明统一响应体、JWT鉴权、跨域与接口文档生成的落地方式,并给出网关聚合与接口测试的实践建议。
0
2026.11.12
本专题围绕Go-Zero的安装与工具链配置展开,讲清Go版本要求、goctl安装方式、代理镜像、protoc依赖与环境变量设置,说明多版本共存、升级回退与CI流水线安装的做法,并整理安装阶段的常见报错与验证步骤。
0
2026.11.12
本专题整理Go-Zero的入门知识,从框架定位、环境准备到跑通第一个API服务,讲清目录分层、配置加载、日志与中间件的基本用法,并对比Gin、Kratos的差异,帮助Go开发者建立整体认知,判断它是否适合当前项目。
0
2026.11.12
本专题从实际API接口调试场景出发,讲解Postman身份认证的完整配置流程,包括常见认证协议介绍、授权参数设置、访问令牌填写、OAuth 2.0授权及认证失败排查,帮助用户正确完成接口授权与访问验证。
0
2026.11.06
围绕Postman HTTP请求头配置展开,讲解Headers选项的具体使用方式,包括Key和Value参数填写、请求头信息添加、常见Header字段设置及请求头修改方法,帮助用户解决接口调试过程中遇到的请求头配置问题。
0
2026.11.06
详细介绍Postman接口请求的创建与发送方法,涵盖GET和POST请求、URL配置、请求参数、Headers请求头、Body请求体设置以及响应结果查看,帮助用户掌握Postman接口请求的完整操作流程。
0
2026.11.06
DBeaver数据导入专题,整理Excel、CSV、SQL、TXT等常见文件的数据导入方法,涵盖目标数据库选择、数据表创建、字段映射、数据类型设置及导入参数配置等操作,帮助用户将本地文件中的数据写入数据库,并了解批量导入、重复数据处理和导入失败等常见问题的解决方法。
0
2026.11.05
DBeaver安全防护专题,围绕数据库连接安全、账号密码保护和访问权限管理展开,整理SSL/TLS加密连接、SSH隧道、数据库凭据保存及证书验证等配置方法,同时介绍敏感信息保护、远程连接风险和高权限账号使用等注意事项,帮助用户提高数据库日常管理的安全性。
0
2026.11.05
本专题聚焦DBeaver数据库连接配置与管理,覆盖从新建连接、选择数据库类型到填写连接参数和验证连接的完整流程。针对MySQL、PostgreSQL、SQL Server等常见数据库,整理相应的连接设置方法,并提供驱动缺失、认证失败和连接异常等问题的排查方向。
0
2026.11.04
热门下载
相关下载
精品课程
共6课时 | 12.1万人学习
共79课时 | 161.9万人学习
共6课时 | 54.7万人学习