Azure AI 转录 Python 技能
为 Python 应用提供 Azure AI 实时与批量语音转文字指导。
文档要求通过环境变量提供凭据、生产环境优先使用 DefaultAzureCredential，并说明客户端生命周期管理，降低了硬编码凭据和资源泄漏风险。扣分原因是未说明音频/转录数据的数据流、隐私、保留期限或跨境处理，也未对外部存储 URL、网络调用和删除操作提供用户确认、权限最小化或恢复方案。
批处理、实时处理、重试、超时和清理均有示例，且异常场景有所涉及。扣分原因是仅静态示例，未提供该技能路径对应的测试；分页示例实际只是遍历惰性迭代器，异步示例和若干 API 行为未在文件中得到验证，失败反馈和边界条件覆盖有限。
触发词、Python SDK、批处理与实时转录场景较明确，并提到时间戳、说话人分离和语言设置。扣分原因是未清楚界定不适用场景、输入输出格式、服务区域/网络要求、中文识别注意事项及大陆网络可达性；核心功能依赖 Azure 服务和外部音频 URL。
具备 front matter、MIT 许可、版本号、安装说明、环境变量、分层参考文件和若干示例，信息组织基本清晰。扣分原因是未说明 SDK 版本约束、变更日志、维护责任和更新路径，限制、FAQ、故障排查以及当前 API 兼容性说明不足；仓库 README 表明项目仍在持续开发。
技能覆盖从客户端创建到批处理、实时转录、重试、超时、列表和删除的核心路径，能为编码代理提供直接代码模式。扣分原因是示例缺少可直接交付的结果持久化、错误处理、字幕/时间戳输出和生产级数据治理；部分方法和参数是否适用于当前包版本无法由静态材料确认。
技能文件包含具体代码、包名、环境变量和参考索引，仓库还提供通用 CI、评估工作流及测试工具。扣分原因是没有看到该技能的专属测试、评估结果或第三方执行证据；README、通用 harness 和工作流不能证明此技能示例本身可运行，关键事实缺少版本固定或可核验引用。
- 转录涉及可能包含个人或敏感语音信息的数据；使用前应确认 Azure 区域、数据保留、访问控制和合规要求。
- 不要直接采用删除已完成转录的示例而跳过用户确认、审计和恢复策略。
- 应先核对当前 azure-ai-transcription 包的实际 API、同步/异步凭据要求以及实时流接口；文档未固定依赖版本或提供专属测试。
- 大陆网络环境下 Azure 端点、外部存储 URL 和身份认证链路的可达性未在材料中验证。
它能做什么 & 适用场景
该技能面向使用 Azure AI Transcription Python SDK 的开发者。它覆盖实时和批量语音转文字，并介绍时间戳、说话人分离、语言指定及流式处理等实践。示例使用环境变量保存终结点和密钥，并要求客户端使用上下文管理器。适合已经拥有 Azure 转录资源、需要在编码代理中获得 SDK 使用指导的团队。
指导开发者安装 azure-ai-transcription，配置 TRANSCRIPTION_ENDPOINT 和 TRANSCRIPTION_KEY，并创建 TranscriptionClient。它展示使用 AzureKeyCredential 或 DefaultAzureCredential/TokenCredential 进行身份验证；批量流程提交音频 URL、等待作业结果并读取状态；实时流程启动流式转录、发送本地音频文件并读取事件文本。
- 需要将存储在 Blob Storage 中的长音频批量转换为文字的 Python 开发者。
- 需要处理实时音频流并逐事件读取转录文本的应用开发者。
- 需要在多人会议中启用说话人分离的团队。
- 需要生成字幕或其他时间对齐文本、因此要捕获时间戳的开发者。
- 希望使用 DefaultAzureCredential 避免在生产代码中硬编码密钥的 Azure 团队。
优缺点一览
- 同时覆盖批量和实时转录。
- 给出可复制的 Python 安装命令和客户端示例。
- 明确说明密钥认证与 Entra ID 认证两种模式。
- 强调上下文管理器、说话人分离、语言指定和流式背压等实践。
- 示例主要使用同步 API，未提供完整异步实现。
- SKILL.md 未提供定价、配额或服务区域信息。
- 引用的 capabilities.md 和 non-hero-scenarios.md 内容未包含在提供材料中。
- 批量和实时示例未展示具体错误处理代码。
如何安装
安装该集合：运行 npx skills add microsoft/skills，在向导中选择所需技能；集合技能会安装到所选代理的目录，例如 .github/skills/。安装 SDK：运行 pip install azure-ai-transcription。SKILL.md 未说明特定代理的进一步配置步骤。
如何使用
在支持 Agent Skills 的编码代理中输入包含“transcription”“speech to text”“Azure AI Transcription”或“TranscriptionClient”的请求以触发该技能。代码中设置 TRANSCRIPTION_ENDPOINT，并在使用密钥认证时设置 TRANSCRIPTION_KEY；用 with TranscriptionClient(...) as client: 管理客户端。批量转录调用 begin_transcription 并提供 content_urls；实时转录调用 begin_stream_transcription，发送音频文件并遍历事件。