深入解读 @mastra/voice-deepgram:Mastra 语音集成包的完整使用指南与版本演进 深入解读 mastra/voice-deepgramMastra 语音集成包的完整使用指南与版本演进【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇文章以 voice/deepgram/CHANGELOG.md 为骨架结合mastra/voice-deepgram包的 README、核心实现 与测试用例系统讲解如何在 Mastra 框架中接入 Deepgram 的文本转语音TTS与语音转文本STT能力。读完本文你将掌握DeepgramVoice的完整配置方式、说话人分离speaker diarization的实战用法、包内模型与音色清单以及从版本变更记录中梳理出的架构演进、运行环境要求与安全修复要点。一、包概览一个类同时提供 TTS 与 STTmastra/voice-deepgram是 Mastra 官方维护的 Deepgram 语音集成包当前仓库内版本为0.13.1见 package.json。它的定位非常明确通过一个DeepgramVoice类同时提供两种能力文本转语音TTS基于 Deepgram 的aura系列模型合成语音语音转文本STT基于 Deepgram 的nova/whisper等系列模型做流式或预录制音频转录。安装方式与任意 npm 包一致npm install mastra/voice-deepgram安装后包会在node_modules中提供 ESMdist/index.js与 CJSdist/index.cjs双格式产物TypeScript 声明文件为dist/index.d.ts。根据 package.json 的声明该包要求zod^3.25.0 || ^4.0.0作为 peer dependency这一约束源于 changelog 中 0.11.0 版本“Bump zod peerdep to 3.25.0 to support both v3/v4”的调整——即同时兼容 zod v3 与 v4方便与不同版本的 Mastra 项目共存。二、快速上手创建语音实例并完成一次“说话—听话”闭环2.1 实例化与 API Key 处理import { DeepgramVoice } from mastra/voice-deepgram; const voice new DeepgramVoice({ speechModel: { name: aura, // TTS 模型家族 apiKey: your-api-key, // 可选缺省时读取 DEEPGRAM_API_KEY 环境变量 }, listeningModel: { name: nova, // STT 模型家族 apiKey: your-api-key, // 可选缺省时读取 DEEPGRAM_API_KEY 环境变量 }, speaker: asteria-en, // 默认音色 ID见 src/voices.ts });从源码看构造函数 的关键逻辑包括speechModel与listeningModel未显式传apiKey时会自动回退到process.env.DEEPGRAM_API_KEY如果三个来源环境变量、speechModel.apiKey、listeningModel.apiKey都没有 key会直接抛出At least one of DEEPGRAM_API_KEY, speechModel.apiKey, or listeningModel.apiKey must be set错误speech 与 listening 各自维护独立的 Deepgram 客户端createClient允许为 TTS 和 STT 使用不同的 API Key默认音色为asteria-en默认 TTS 模型为aura默认 STT 模型为nova。2.2 完整使用示例// 1. 列出所有可用音色 const voices await voice.getSpeakers(); // [{ voiceId: asteria-en }, { voiceId: luna-en }, ...] // 2. 文本合成语音默认音色 const audioStream await voice.speak(Hello from Mastra!, { speaker: hera-en, // 按需覆盖音色 }); // 3. 语音转文本并开启说话人分离 const result await voice.listen(audioStream, { diarize: true, diarize_speaker_count: 2, }); console.log(result.transcript);这段示例即 README 中的标准用法它展示了本包“双模型 可覆盖音色 可选说话人分离”的完整工作流。三、TTS 能力详解speak 方法3.1 方法签名与返回值speak接受一个字符串或可读流作为输入返回一个 Node.jsReadableStream具体为PassThroughasync speak( input: string | NodeJS.ReadableStream, options?: { speaker?: string; // 覆盖默认音色 [key: string]: any; // 其余参数透传给 Deepgram API }, ): PromiseNodeJS.ReadableStream3.2 底层行为源码级从 index.ts 可以看到三个值得注意的实现细节输入归一化若传入的是流内部会先聚合成 Buffer 再转为 UTF-8 文本空文本或纯空白文本会抛出Input text is empty错误模型名拼接最终请求模型名由baseModel - speakerId拼接而成例如默认aura 音色asteria-en会生成aura-asteria-en若 speakerId 本身已带模型前缀则直接复用Web Stream 转 Node StreamDeepgram SDK 返回的是 Web Stream包内通过getReader()逐块读取并写入PassThrough同时做了完善的错误销毁nodeStream.destroy(error)处理避免流异常泄漏。其余options除speaker外会原样透传给speakClient.request因此你可以直接传入 Deepgram TTS 支持的参数如encoding、container、sample_rate等。3.3 可用模型与音色清单音色列表定义在 src/voices.ts共 12 个英语音色音色 ID说明asteria-en / luna-en / stella-enAura 家族基础音色athena-en / hera-en / orion-en不同音质与语调选择arcas-en / perseus-en / angus-en男声/中性音色选择orpheus-en / helios-en / zeus-en更多合成音色可用模型DeepgramModel为auraTTS、whisper、base、enhanced、nova、nova-2、nova-3STT见 src/voices.ts。测试用例中即使用了auraTTS与whisperSTT的组合见 index.test.ts。四、STT 能力详解listen 方法与说话人分离4.1 方法签名与返回值async listen( audioStream: NodeJS.ReadableStream, options?: { diarize?: boolean; // 是否开启说话人分离 [key: string]: any; // 其余参数透传给 Deepgram 转录 API }, ): Promiseany返回对象的结构随diarize是否开启而变化源码注释见 index.ts字段说明是否依赖 diarizetranscript完整转录文本否words单词数组含时间戳与置信度否rawDeepgram API 完整原始响应否speakerSegments{ word, speaker, start, end }数组区分说话人是4.2 说话人分离Diarization是核心新特性changelog 在0.12.0 版本对应 PR #10206明确记录“Add speaker diarization support for STT”并在0.12.0-beta.1中以feat(voice-deepgram)前缀标记。这是该包近几个版本中最具业务价值的能力更新。从实现看listen会把diarize和diarize_speaker_count从透传参数中单独提取前者作为布尔开关传给transcribeFile后者如果传了用于提示 Deepgram 预设说话人数。开启后包会遍历返回的alt.words为每个词附加speaker编号并组装speakerSegments见 index.ts。典型应用场景会议纪要自动区分发言者、客服通话质检中定位坐席与客户的对话轮次、访谈内容的角色标注等。配合diarize_speaker_count可以进一步提高分离精度const result await voice.listen(audioStream, { diarize: true, diarize_speaker_count: 2, // 明确告诉模型只有两个说话人 }); for (const seg of result.speakerSegments) { console.log([说话人 ${seg.speaker}] ${seg.word} (${seg.start}ms-${seg.end}ms)); }4.3 预录制音频转录listen基于listeningClient.listen.prerecorded.transcribeFile实现属于预录制pre-recorded转录路径先把整个输入流聚合成 Buffer再一次性提交给 Deepgram。测试中通过createReadStream读取__fixtures__/voice-test.m4a并显式传入filetype: m4a完成转录见 index.test.ts说明处理m4a等非默认格式时需在 options 中补充filetype。五、从 Changelog 看包的架构演进5.1 命名继承从 mastra/speech-deepgram 迁移而来0.1.0 版本2024 年即记录deprecate mastra/speech-deepgram for mastra/voice-deepgram原包所有功能迁移到新命名下导入路径统一更新为mastra/voice-deepgram。这次更名是 Mastra 将“语音”能力统一收敛到MastraVoice抽象体系的一部分。5.2 0.12.1语音原语下沉到 internal/voice0.12.1 是一个重要的架构里程碑changelog 记录“Moved shared voice primitives and route metadata into the newinternal/voicepackage so voice providers no longer depend onmastra/coreand server voice routes share the same route definitions”同时说明mastra/core/voice仍会继续 re-export 这些 API 以保持向后兼容。这一点在源码中得到印证DeepgramVoice类继承自internal/voice包导出的MastraVoice基类见 index.ts而不再直接依赖mastra/core。仓库中的packages/_internals/voice/src/voice/voice.ts、packages/_internals/voice/src/routes/index.ts等文件即承载了共享语音原语与路由定义。带来的收益包括解除核心包耦合各语音 provider 不再被迫绑定mastra/core的具体版本路由统一服务端语音相关路由如/api/voice/...在 provider 之间共享同一套定义兼容性保障通过mastra/core/voice的 re-export老代码无需改动即可继续使用。5.3 0.12.0运行环境要求收紧0.12.0 版本同时带来两个重要的环境变更Node.js 最低版本提升至 22.13.0PR #9706。当前 package.json 中engines.node字段即22.13.0使用低于该版本的 Node 运行时会收到引擎不兼容警告移除基于 OpenTelemetry 的旧 tracing 代码PR #9237并同步将 peer dependency 对齐到mastra/core1.0.0的版本号体系。5.4 0.12.0随包发布内嵌文档0.12.0 还引入了“embedded documentation”机制Mastra 各包发布到 npm 时会携带dist/docs/目录包含SKILL.md包的用途与能力说明、SOURCE_MAP.json导出符号到类型/实现文件的机器可读索引以及按功能域组织的 Topic 目录。这套机制让编码 Agent 与 AI 助手可以直接从node_modules读取文档来理解并调用本包。package.json 中的prepack脚本tsx ../../scripts/generate-package-docs.ts正是该文档生成流程的入口。5.5 0.12.2供应链安全修复0.12.2 是一次安全补丁发布changelog 记录其为 2026-06-17 “easy-day-js” 供应链事件的 remediation发布干净版本并将latestdist-tag 前移取代声明了恶意easy-day-js依赖的受影响版本。对于使用者而言这意味着务必升级到 0.12.2 及以上版本并留意安装日志中的依赖来源。5.6 0.13.1包体瘦身与文档更新0.13.1 包含两项 Patch 变更从发布到 npm 的产物中移除CHANGELOG.md减小包体积PR #22737更新 README 以保证信息准确、与当前 API 一致PR #22858。5.7 其他值得留意的变更0.10.2deepgram/sdk从^3.11.2升级到^3.13.0当前 package.json 即锁定该依赖0.10.7修复 TypeScript 声明文件导入以保证 ESM 兼容0.1.3调整 CJS 打包确保产物文件正确拆分0.1.1新增 CommonJS 支持0.1.13包启用 Elastic-2.0 许可注当前仓库该包 package.json 中license字段为 Apache-2.0以实际安装版本为准。六、测试与验证如何确认包行为符合预期包内自带 Vitest 集成测试index.test.ts可运行cd voice/deepgram pnpm test测试覆盖了以下关键行为getSpeakers能返回asteria-en、stella-en、luna-en等内置音色speak能生成非空音频文件deepgram-speech-test.mp3且支持覆盖 speaker 参数空文本 / 纯空白文本 / 非法音色都会正确抛出错误listen能转录voice-test.m4afixture非法音频会被拒绝。这些用例直接印证了本文章前面描述的 API 契约与错误处理逻辑可作为你自行验证时的参考基线注意真实转录需要有效的 Deepgram API Key。七、最佳实践与注意事项API Key 优先走环境变量DEEPGRAM_API_KEY一次配置speech 与 listening 自动共享需要拆分权限时再分别传入speechModel.apiKey与listeningModel.apiKey多说话人场景务必开启 diarize区分对话轮次是语音 Agent 走向真实业务的常用能力diarize_speaker_count在说话人数已知时能显著提升稳定性注意运行环境Node.js 需 ≥ 22.13.0且需要zod ^3.25.0 || ^4.0.0peer dependency及时升级0.12.2 包含供应链安全修复低于该版本的安装应视为存在风险格式处理转录m4a等格式时记得传filetype参数见 index.test.ts流错误处理speak返回的流在底层已做错误销毁兜底消费端仍建议监听error事件以避免未捕获异常。八、结语mastra/voice-deepgram是一个麻雀虽小、五脏俱全的语音集成包一个类完成 TTS/STT 双能力、支持说话人分离、模型与音色可自由组合并在最近的版本中完成了与internal/voice的解耦、Node 版本收紧与供应链安全修复。无论是构建带语音对话的 Agent、会议纪要应用还是客服质检系统本文梳理的配置参数、API 契约与版本演进都能帮助你快速上手并规避踩坑点。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考