AI SDK 的 Hume 语音提供方全景：@ai-sdk/hume 从 1.0 到 3.0 的版本演进与 v4 实现解析

AI SDK 的 Hume 语音提供方全景：@ai-sdk/hume 从 1.0 到 3.0 的版本演进与 v4 实现解析

发布时间：2026/9/12 19:40:23
AI SDK 的 Hume 语音提供方全景：@ai-sdk/hume 从 1.0 到 3.0 的版本演进与 v4 实现解析 AI SDK 的 Hume 语音提供方全景ai-sdk/hume 从 1.0 到 3.0 的版本演进与 v4 实现解析【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/aiai-sdk/hume是 AI SDKTypeScript AI Toolkit中对接 Hume API 的官方语音合成提供方本文以其 CHANGELOG.md 为脉络主线梳理该包从 1.0.0 引入 speech 能力、到 2.x 时代 speech model v3 规范、再到 3.x 全量 ESM 化与 v4 规范落地的完整演进史。读完本文你将掌握 ai-sdk/hume 的安装与基本用法、请求体与输出格式的底层构造逻辑、版本升级时需要注意的全部破坏性变更以及工作流序列化、user-agent 版本标识等底层机制在源码中的具体实现位置。包定位与快速上手Hume 提供方的能力在 README.md 中有明确定位它仅提供语音合成speech模型不提供语言模型、嵌入模型或图像模型。这一点在 hume-provider.ts 中有直接体现——languageModel、embeddingModel、imageModel三个方法一律抛出NoSuchModelError错误信息分别为 Hume does not provide language models / Hume does not provide embedding models / Hume does not provide image models。安装与使用极为简单npm i ai-sdk/humeimport { hume } from ai-sdk/hume; import { generateSpeech } from ai; const result await generateSpeech({ model: hume.speech(aurora), text: Hello, world!, });从 package.json 可以看到该包的运行时依赖仅有ai-sdk/provider与ai-sdk/provider-utils两个工作区包zod作为 peer 依赖^3.25.76 || ^4.1.8引擎要求 Node.js22。所有源码位于 packages/hume/src测试使用 Vitest 分为 node 与 edge 两套配置运行。版本演进主线从引入 speech 到 v4 规范CHANGELOG 完整记录了该包从 1.0.0-canary 时代到 3.0.39 的 1770 行演进历史。剔除大量 Updated dependencies 例行条目后真正影响使用方式与技术架构的变更集中在以下几个版本节点1.0.0speech 能力正式落地在 1.0.0 之前的 canary/beta 阶段包的核心功能已经存在但直到 1.0.0 才正式发布018f3c7: feat(providers/hume): add speech—— 引入语音合成能力这是整个包的功能基石d1a034f: feature: using Zod 4 for internal stuff—— 内部 schema 校验切换到 Zod 4205077b: fix: improve Zod compatibility—— 改善与不同 Zod 版本的兼容性这也解释了 package.json 中 peer 依赖同时兼容 zod 3 与 4 的设计。2.0.0AI SDK 6 与 speech model v3 规范2.0.0 是伴随 AI SDK 6 betadee8b05发布的大版本其中多个补丁变更塑造了提供方包的标准形态046aa3b: feat(provider): speech model v3 spec—— 语音模型规范升级到 v3为后续 v4 打基础ed329cb: feat: Provider-V3—— 提供方接口规范进入 v31cad0ab: feat: add provider version to user-agent header——user-agent 头中注入提供方版本号这是可观测性的一次关键增强下文会结合源码展开457318b: chore(provider,ai): switch to SharedV3Warning and unified warnings—— 统一警告机制242696c: feat: normalize and export provider specific model options type names2.0.19—— 规范化并导出提供方专属的模型 options 类型名即今天源码中HumeSpeechModelOptions的由来。3.0.0ESM-only 与 v7 预发布3.0.0 是破坏性最集中的一个版本标志着 AI SDK v7 的开启8359612: Start v7 pre-releaseef992f8Major移除全部 CommonJS 导出所有包变为 ESM-onlytype: module使用require()的消费者必须切换到 ESMimport语法04e9009Major统一各提供方的代码模式重命名部分导出符号旧名称通过 deprecated aliases 继续可用7fc6bd6Node.js 最低版本提升到 22官方支持版本为 22、24、26b3976a2为所有提供方模型加入工作流序列化支持详见下文专节38fc777在提供方 README 中加入 AI Gateway 提示9f0e36c/0c4c275/b8396f0provenance 设置、canary/beta 发布等工程化动作。3.0.5实验性流式转录支持5c5c0f5引入了一项值得关注的能力为转录模型添加实验性流式转录支持包括 OpenAIgpt-realtime-whisper与 xAI WebSocket STT。需要说明的是该条目出现在 ai-sdk/hume 的补丁变更中实质是 AI SDK 核心语音/转录能力的一次横向扩展在 packages/ai 核心包与相关提供方中落地它说明语音提供方生态正从单次 TTS向实时流式转录方向演进。源码级实现v4 规范的 Hume 语音模型当前仓库中 Hume 提供方已全面落地v4 规范。入口在 hume-provider.tsHumeProvider extends ProviderV4provider.specificationVersion v4语音模型类 HumeSpeechModel 实现SpeechModelV4readonly specificationVersion v4。这正是 CHANGELOG 中 speech model v3 → v4 演进路径的最终形态。createHume 与默认实例export function createHume(options: HumeProviderSettings {}): HumeProvider export const hume createHume();HumeProviderSettings支持三个配置项hume-provider.ts配置项类型说明apiKeystringAPI 密钥不传时从环境变量HUME_API_KEY读取loadApiKey负责解析headersRecordstring, string附加到每个请求的自定义头fetchFetchFunction自定义 fetch 实现可作中间件拦截请求或用于测试密钥最终以X-Hume-Api-Key请求头发送并经由withUserAgentSuffix在 UA 末尾追加ai-sdk/hume/${VERSION}后缀——这正是 2.0.0 中1cad0ab变更的落地位置。版本号本身由 version.ts 在构建时注入__PACKAGE_VERSION__。doGenerate 调用链与请求体构造HumeSpeechModel.doGenerate的核心流程hume-speech-model.ts为解析 provider optionsparseProviderOptionshumeSpeechModelOptionsSchema构造请求体POST到https://api.hume.ai/v0/tts/file使用createBinaryResponseHandler()处理二进制音频响应返回{ audio, warnings, request, response }。请求体结构hume-api-types.ts{ utterances: [{ text, speed?, description?, voice?, trailing_silence? }], format: { type: mp3 | pcm | wav }, context?: { generation_id: string } | { utterances: [...] } }几个值得注意的默认与边界行为默认声音voice缺省时为 Hume 内置声音 IDd8ab67c6-953d-4bd8-9370-8fa53a0f1453provider固定为HUME_AI输出格式仅接受mp3、pcm、wav其他值会降级回 mp3 并产生unsupported类型的警告语言参数language不被支持传入时会生成警告并忽略Hume speech models do not support language selection描述即指令instructions参数映射到 utterance 的description字段用于描述文本应如何被朗读。provider optionscontext 与逐条 utterance 控制vitest 测试 与 hume-speech-model-options.ts 共同勾勒出HumeSpeechModelOptions的完整形态可通过providerOptions: { hume: {...} }透传context.generationId引用某次先前生成的 ID 进行检索context.utterances直接传入一组 utterance每条支持text、description、speed语速倍率、trailingSilence句尾静音秒数、voice可按id或name指定provider可选HUME_AI或CUSTOM_VOICE。schema 基于 Zod 4 编写并导出类型HumeSpeechModelOptions这正是 1.0.0 的 Zod 4 迁移与 2.0.19 类型名规范化两个变更的直接产物。错误处理与警告hume-error.ts 定义了统一的失败响应处理humeErrorDataSchema期望{ error: { message, code } }结构通过createJsonErrorResponseHandler将错误转换为可读消息。结合 2.0.0 中457318b的统一警告机制模型返回的warnings均为SharedV4Warning类型用于承载输出格式不支持、语言参数忽略等非致命提示。工作流序列化模型跨越 step 边界的机制3.0.0 的b3976a2为所有提供方模型引入了工作流序列化支持Hume 是首批落地该机制的提供方之一。其包含三个层面的变化ai-sdk/provider-utils新增serializeModel()助手只提取模型实例中可序列化的属性过滤掉函数及包含函数的对象headers在提供方配置类型中变为可选非破坏性变更模型从工作流 step 边界反序列化时认证信息可另行注入无需在配置中携带 headers每个模型类新增WORKFLOW_SERIALIZE与WORKFLOW_DESERIALIZE静态方法使模型能跨工作流 step 边界传递而不产生序列化错误。在 hume-speech-model.ts 中可以看到具体实现static WORKFLOW_SERIALIZE { return serializeModelOptions({ modelId: model.modelId, config: model.config, }); } static WORKFLOW_DESERIALIZE { return new HumeSpeechModel(options.modelId as , options.config); }序列化时仅保留modelId与config认证头等函数型字段被过滤反序列化时用纯数据重建模型实例。第三方提供方作者也可以借助serializeModel()为自己的模型增加同样的工作流支持。测试佐证与工程化细节hume-speech-model.test.ts 使用ai-sdk/test-server的 Vitest 集成对https://api.hume.ai/v0/tts/file进行端到端断言覆盖了请求体正确性text、默认voice.id、format.type与传入的speed请求头合并x-hume-api-key、content-type: application/json、provider 自定义头与请求级自定义头UA 后缀断言ai-sdk/hume/0.0.0-test测试中 mock 了VERSION二进制音频响应与其content-type的透传。这些测试同时验证了createHume({ apiKey, headers })与hume.speech().doGenerate(...)两条使用路径。工程层面package.json 的prepack脚本会在发布前将 content/providers/01-ai-sdk-providers/150-hume.mdx 文档复制进包内并开启provenance: true发布签名对应 CHANGELOG 中的 provenance 相关条目。升级到 3.x 的破坏性变更清单综合 CHANGELOG 的 Major/Patch 变更从 2.x 升级到 3.0.x 时需关注ESM-only移除 CommonJS 导出require(ai-sdk/hume)不再可用必须改用importNode 版本最低要求提升至 Node 22支持 22、24、26导出符号重命名04e9009统一了提供方代码模式并重命名部分导出符号但旧名称通过 deprecated aliases 继续可用属于非破坏性过渡headers可选化provider 配置类型中headers变为可选手动构造模型配置的实现可以省略它认证可工作流级注入peer 依赖zod需满足^3.25.76 || ^4.1.8底层ai-sdk/provider/ai-sdk/provider-utils随版本矩阵同步升级3.0.39 对应ai-sdk/provider4.0.13与ai-sdk/provider-utils5.0.39。整体来看ai-sdk/hume 的版本史清晰地反映了 AI SDK 提供方生态的标准化进程从 1.x 的功能引入到 2.x 的规范统一Provider-V3、speech model v3、UA 版本标识再到 3.x 的 ESM 化、Node 22 基线、工作流序列化与 v4 规范。对于需要接入 Hume 语音合成或研究 AI SDK 提供方架构的开发者而言结合本文梳理的变更脉络与 packages/hume/src 下的实现细节可以快速定位到任何功能行为的源码出处。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考