Azure Ai Transcription Py Free

Azure AI Transcription 的 Python 客户端库基础功能。支持对存储在 Blob 中的音频 提交批量转写作业,通过 locale 指定识别语言。使用订阅密钥认证,通过 TRANSCRIPTION_ENDPOINT 与 TRANSCRIPTION_KEY 环境变量配置资源。本基础版不含 实时流式转写、说话人分离、时间戳字幕生成等高级能力。

Azure AI Transcription(speech-to-text)Python 客户端库基础功能,支持批量转写。

安装

bash

pip install azure-ai-transcription

环境变量

bash

TRANSCRIPTION_ENDPOINT=https://<resource>.cognitiveservices.azure.com
TRANSCRIPTION_KEY=API_KEY

TRANSCRIPTION_ENDPOINT 为 Azure AI 资源终结点,TRANSCRIPTION_KEY 为该资源的订阅密钥(primary 或 secondary 均可)。两个变量建议放入 .env 或系统环境变量,不要硬编码进源码;密钥泄漏后须在门户轮换并更新变量。

认证

使用订阅密钥认证(此客户端不支持 DefaultAzureCredential):

python

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配置方式:

bash

export API_KEY="your_api_key_here"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。

核心能力

• 批量转写:对存储在 Blob 中的音频文件提交转写作业,异步等待完成
• 语言指定:通过 locale 指定识别语言(如 en-US、zh-CN),提升识别准确率
• 订阅密钥认证:通过环境变量配置资源,实例化时传入密钥
• 作业结果查询:job.result() 阻塞等待作业完成并返回结果

指令解析与执行

解析用户指令,执行核心操作并返回处理结果。

输入: 用户提供操作指令和必要参数。

输出: 返回操作执行的结果。

• 执行指令解析与执行操作，处理输入数据并返回结果
• 验证执行结果，确认输出符合预期格式
• 参考指令解析与执行相关配置参数进行设置

数据处理与转换

处理输入数据,执行转换操作并输出结果。

输入: 用户提供操作指令和必要参数。

输出: 返回操作执行的结果。

• 执行数据处理与转换操作，处理输入数据并返回结果
• 验证执行结果，确认输出符合预期格式
• 参考数据处理与转换相关配置参数进行设置

结果验证与输出

验证处理结果的正确性,格式化输出并返回给用户。

输入: 用户提供操作指令和必要参数。

输出: 返回操作执行的结果。

• 执行结果验证与输出操作，处理输入数据并返回结果
• 验证执行结果，确认输出符合预期格式
• 参考结果验证与输出相关配置参数进行设置

能力覆盖范围

本skill还覆盖以下能力场景: Azure、Transcription、基础功能、支持批量语音转文、字与语言指定、Python、客户端库基础功能、支持对存储在、提交批量转写作业、使用订阅密钥认证、ENDPOINT、KEY、本基础版不含、实时流式转写、说话人分离、时间戳字幕生成等、高级能力。这些能力在上述核心功能中均有对应处理逻辑。

使用流程

1. 环境确认: 确认Agent平台已加载本skill，检查依赖说明中的环境要求
2. 指令输入: 向Agent描述需要执行的任务，引用azure-ai-transcription-py-free的相关能力
3. 执行处理: Agent按照核心能力章节的指令执行任务
4. 结果验证: 检查输出结果是否符合预期，参考错误处理章节处理异常

命令参数说明

• -US: 命令参数,用于指定操作选项

命令参数说明

• -US: 命令参数,用于指定操作选项

命令参数说明

• -US: 命令参数,用于指定操作选项

命令参数说明

• -US: 命令参数,用于指定操作选项

命令参数说明

• -US: 命令参数,用于指定操作选项

命令参数说明

• -US: 命令参数,用于指定操作选项

命令参数说明

• -US: 命令参数,用于指定操作选项

命令参数说明

• -US: 命令参数,用于指定操作选项

命令参数说明

• -US: 命令参数,用于指定操作选项

批量转写

python

job = client.begin_transcription(
    name="meeting-transcription",
    locale="en-US",
    content_urls=["https://<storage>/audio.wav"]
)
result = job.result()
print(result.status)

begin_transcription 提交一个批量转写作业并立即返回作业句柄;job.result() 阻塞等待作业完成并返回结果。content_urls 指向可公开访问或带 SAS 的音频 URL。

结果处理

result.status 反映作业状态:Succeeded 表示成功可取回文稿,Failed 表示失败需检查 content_urls 可达性与 locale 合法性。结果按识别片段组织,每个片段含文本与时间戳。导出纯文稿时按片段顺序拼接文本即可;导出字幕时把每个片段起止时间戳格式化为时间码(形如 00:00:01,000 至 00:00:03,000)与文本拼接成字幕条目。批量作业通过轮询 job.result() 等待完成,无须显式关闭会话。

实践要点

1. 长文件用批量转写,服务端异步处理不受客户端连接时长限制
2. 指定 locale 提升识别准确率,避免语言误判
3. content_urls 须为可公开访问或带 SAS 的 HTTPS URL
4. 转写完成后取回结果,异常路径注意释放连接
5. 作业名 name 建议含日期或业务标识,便于在门户中检索与归档
6. 多段音频分多次提交作业,单作业 content_urls 控制在合理数量便于结果聚合

依赖

• Python 3.8 及以上,azure-ai-transcription 包(通过 pip 安装)
• 已部署的 Azure AI 资源,获得 endpoint 与 key
• 批量转写的音频须可通过 HTTPS 公开访问或附 SAS 令牌,纯本地文件须先上传

适用场景

会议录音批量转写

将会议录音上传至 Blob 存储并生成 SAS URL,提交批量转写作业并指定 locale,异步等待完成后取回完整会议文稿。适合长会议、离线归档、会议纪要生成。

指定语言提升准确率

对中英文等不同语言音频指定对应 locale(如 zh-CN、en-US),避免语言误判,提升专有名词与口音的识别准确率。

案例

批量转写会议录音

用户有一段会议录音 meeting.wav 已上传至 Blob 并得到 SAS URL。先配置环境变量 TRANSCRIPTION_ENDPOINT 与 TRANSCRIPTION_KEY,实例化 TranscriptionClient。调用 begin_transcription(name="meeting-20260406", locale="zh-CN", content_urls=["https://<storage>/meeting.wav?<sas>"])。job.result() 阻塞等待,完成后从 result 取回完整文稿并导出为会议纪要。

指定语言转写英文音频

用户有一段英文播客 podcast.wav,不指定语言时识别准确率低。批量提交 begin_transcription(locale="en-US", content_urls=[...]),指定 en-US 后专有名词识别准确率明显提升,取回结果后导出文本。

异常处理

TRANSCRIPTION_ENDPOINT 未设置

实例化 TranscriptionClient 时 os.environ["TRANSCRIPTION_ENDPOINT"] 抛 KeyError。检查环境变量是否已导出(常见为 https://<resource>.cognitiveservices.azure.com),在 shell 或 .env 中配置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令。不要把 endpoint 硬编码进源码。

TRANSCRIPTION_KEY 无效(401/403)

调用转写接口返回 401 或 403。核对 TRANSCRIPTION_KEY 是否为该资源的有效订阅密钥,确认 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)。

常见问题

Q1:如何认证?

此客户端仅支持订阅密钥认证,通过 TRANSCRIPTION_ENDPOINT 与 TRANSCRIPTION_KEY 环境变量配置资源,实例化时传入 credential=os.environ["TRANSCRIPTION_KEY"]。不支持 DefaultAzureCredential。

Q2:locale 怎么填?

填 BCP-47 语言标签,如 en-US、zh-CN、ja-JP。指定与音频一致的语言可显著提升识别准确率,避免语言误判。

Q3:长文件怎么处理?

长文件优先用批量转写并存储在 Blob 中,服务端异步处理不受客户端连接时长限制;job.result() 阻塞等待完成。

Q4:content_urls 有什么要求?

须为可被服务端公开访问或带 SAS 令牌的 HTTPS URL;Blob 容器若为私有须生成只读 SAS;URL 协议须为 HTTPS。

错误处理

错误场景	原因	处理方式
LLM响应超时或无响应	网络延迟或模型负载过高	执行ping命令测试网络连通性,检查防火墙和代理设置连接，执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令请求；确认Agent平台LLM服务正常
输入内容格式不正确	用户输入不符合skill预期格式	检查输入是否符合skill使用说明中的格式要求，参考示例章节
执行结果与预期不符	指令描述不够明确或上下文不足	提供更详细的指令描述，补充必要的上下文信息
命令执行失败	运行环境不满足要求或权限不足	确认运行环境符合依赖说明中的要求；检查命令权限设置

已知限制

• 依赖云服务,需要网络连接,断网时无法转写
• 仅支持订阅密钥认证,不支持 DefaultAzureCredential、托管标识等
• 批量转写要求音频可通过公开 URL 或 SAS 访问,纯本地文件须先上传
• 本基础版不含实时流式转写、说话人分离、时间戳字幕生成等高级能力
• 识别准确率受音频质量、背景噪声、口音与 locale 匹配度影响

升级提示

本基础版仅覆盖批量转写与语言指定。如需实时流式转写(begin_stream_transcription 与 send_audio_file)、说话人分离(diarization_enabled)、时间戳捕获与字幕生成、流式背压处理与会话管理实践要点,请升级至付费版 azure-ai-transcription-py。