ai-sdk/assemblyai 版本演进全解从转录模型选型到音频智能结果透出【免费下载链接】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 SDKThe AI Toolkit for TypeScript官方仓库中 ai-sdk/assemblyai 的 CHANGELOG 为主线系统梳理 AssemblyAI 转录提供者的能力演进、模型选型、provider options 体系、破坏性变更与底层调用链。读完本文你将掌握如何正确选用universal-3-5-pro等转录模型、理解speech_model/speech_models参数路由机制、使用新增的音频智能audio-intelligence与说话人分离speaker diarization结果并能够评估从 v2 升级到 v3 时需要注意的 ESM、Node.js 版本与 API 兼容性约束。一、包定位AI SDK 生态中的 AssemblyAI 转录提供者ai-sdk/assemblyai是 AI SDK 官方提供者包之一职责是封装 AssemblyAI 转录 API当前版本为3.0.39对应 package.json。从 CHANGELOG 的版本轨迹可以清晰看到这条演进主线1.0.0首次加入transcribe能力将 transcription 与 speech model 支持接入 provider registrycommitcb68df0、3ea56562.0.0随 AI SDK 6 beta 引入Provider-V3commited329cb与 transcription model v3 speccommit21e20c0并加入转录异步轮询commitb400d673.0.0随 v7 预发布进入 ESM-only 时代移除 CommonJS 导出3.0.4/3.0.5功能最密集的两个补丁版本——新增universal-3-5-pro支持、透出音频智能结果、实验性流式转录。下文将以这些关键变更点为骨架展开。二、模型支持演进从nano/best到universal-3-5-pro2.1 模型清单与当前状态assemblyai-transcription-settings.ts 中定义了完整的转录模型 ID 类型export type AssemblyAIDeprecatedTranscriptionModelId best; export type AssemblyAITranscriptionModelId | universal-2 | universal-3-pro | universal-3-5-pro | AssemblyAIDeprecatedTranscriptionModelId | (string {});结合 CHANGELOG 3.0.4 条目commitec598e2与官方 provider 文档 content/providers/01-ai-sdk-providers/100-assemblyai.mdx各模型的地位如下模型 ID状态说明universal-3-5-pro✅ 推荐AssemblyAI 最新旗舰模型新代码的默认选择universal-3-pro✅ 可用信息性警告仍可工作但使用时会收到建议迁移到universal-3-5-pro的提示universal-2✅ 可用信息性警告同上best⚠️ 已废弃deprecated遗留模型仍可用但会输出废弃警告nano❌ 已移除AssemblyAI 已不再接受该模型这里有一个值得注意的细节废弃deprecated与信息性警告informational warning是两回事。best模型走的是deprecated警告通道而universal-3-pro/universal-2尽管也是建议替换到universal-3-5-pro但两者仍完全受支持警告仅用于前瞻性提示forward-looking nudge并非废弃通知。这一语义区分可以在 assemblyai-transcription-model.ts 的getArgs()中看到具体实现。2.2 参数路由speech_model与speech_models的自动选择3.0.4 版本的一个关键行为变化是新模型必须通过 AssemblyAI 的speech_models复数数组参数传递而废弃的speech_model单数只用于遗留的best模型。源码在 assemblyai-transcription-model.ts 中实现了自动路由if (this.modelId best) { body.speech_model this.modelId as best; // 推送 deprecated 警告建议改用 universal-3-5-pro } else { body.speech_models [this.modelId]; // 其余模型全部走数组参数 // universal-3-pro / universal-2 额外推送信息性警告 }也就是说你只需在.transcription(universal-3-5-pro)中指定模型 ID请求参数的选择由提供者自动完成——这正是 content/providers/01-ai-sdk-providers/100-assemblyai.mdx 中provider selects automatically based on the model id一说的源码依据。同时代码注释明确引用了 AssemblyAI 官方文档select-the-speech-model作为路由规则的依据见 assemblyai-transcription-model.ts。三、3.0.4 新增 Provider Options 全解CHANGELOG 3.0.4commitec598e2一次性引入了大量新的 provider optionsprompt、keytermsPrompt、temperature、removeAudioTags、domain、speakerOptions、languageDetectionOptions、redactPiiAudioOptions、redactPiiReturnUnredacted、redactStaticEntities。这些参数的类型定义集中在 assemblyai-transcription-model-options.ts通过assemblyaiTranscriptionModelOptionsSchema基于 zod v4做运行时校验并在getArgs()中映射为 AssemblyAI API 的 snake_case 请求体字段。3.1 如何传入 Provider Options使用方式是通过transcribe()的providerOptions.assemblyai传入并且类型可以安全地satisfies AssemblyAITranscriptionModelOptions校验import { transcribe } from ai; import { assemblyai } from ai-sdk/assemblyai; import { type AssemblyAITranscriptionModelOptions } from ai-sdk/assemblyai; import { readFile } from fs/promises; const result await transcribe({ model: assemblyai.transcription(universal-3-5-pro), audio: await readFile(audio.mp3), providerOptions: { assemblyai: { contentSafety: true, } satisfies AssemblyAITranscriptionModelOptions, }, });3.2 核心参数速查表以下参数在 CHANGELOG 3.0.4 与 provider 文档 中均有描述此处整理其作用与约束校验逻辑详见 assemblyai-transcription-model-options.ts参数类型说明与约束promptstring自然语言上下文最多 1500 词引导模型输出。仅universal-3-pro/universal-3-5-pro/slam-1支持keytermsPromptstring[]领域关键词增强每短语最多 6 词替代wordBoost新模型专用temperaturenumber(0–1)采样温度控制随机性Universal-3 Pro 系列模型removeAudioTagsall \| speaker移除富文本转录中的内联标注all全部、speaker仅说话人提示domainstring领域专用模型当前支持medical-v1医疗模式speakerOptions{ minSpeakersExpected?, maxSpeakersExpected? }说话人分离的说话人数范围languageDetectionOptions{ expectedLanguages?, fallbackLanguage?, codeSwitching?, codeSwitchingConfidenceThreshold? }自动语言检测选项码切换置信度阈值为 0–1redactPiiAudioOptions{ returnRedactedNoSpeechAudio?, overrideAudioRedactionMethod? }PII 音频脱敏选项overrideAudioRedactionMethod仅支持silence依赖redactPiiAudioredactPiiReturnUnredactedboolean同时返回未脱敏原文依赖redactPiiredactStaticEntitiesRecordstring, string[]自定义静态实体脱敏映射如{ INTERNAL_TOOL: [Bearclaw] }依赖redactPii3.3 参数间的依赖与冲突检查源码getArgs()assemblyai-transcription-model.ts内置了三组依赖/冲突保护逻辑会在不满足前置条件时输出警告而不是静默失败redactPiiReturnUnredacted/redactStaticEntities设置了但未开启redactPii→ 警告AssemblyAI 会直接拒绝请求redactPiiAudioOptions设置了但未开启redactPiiAudio→ 警告该选项会被忽略languageDetection与显式languageCode同时设置 → 警告AssemblyAI 拒绝同时设置两者的请求。这些行为属于只警告、不替用户改写输入Warn rather than mutate user input的设计取舍可以在代码注释中找到明确说明。3.4 废弃项wordBoost/boostParam的归宿CHANGELOG 3.0.4 明确废弃了wordBoost/boostParam原因是 AssemblyAI 在新模型上直接拒绝word_boost参数。源码中对应处理有两层在 assemblyai-transcription-model-options.ts 中wordBoost与boostParam均标记为deprecated并注明universal-3-pro/universal-3-5-pro/slam-1会拒绝仅universal-2/best可用在getArgs()中assemblyai-transcription-model.ts只要检测到二者之一被传入就推送deprecated警告并提示改用keytermsPrompt。与此同时best模型也被标记废弃见 assemblyai-transcription-settings.ts而nano则被直接移除——这正是 CHANGELOG 中 Deprecate the legacybestmodel (still works, warns) and removenano 的完整含义。四、说话人分离与音频智能结果的透出机制4.1 为什么需要额外的透出通道AI SDK 的transcribe()结果形状固定为text、segments、language、durationInSeconds无法承载 AssemblyAI 更丰富的结构化输出。3.0.4 的解决方案是双通道透出assemblyai-transcription-model.tsproviderMetadata.assemblyai结构化透出已启用的音频智能结果包括utterances开启speakerLabels时的说话人分离片段、entities、sentimentAnalysisResults、contentSafetyLabels、iabCategoriesResult、autoHighlightsResultresponse.body完整保留原始 AssemblyAI 转录响应因此即使某个字段未在上述清单中例如chapters、词级speaker标签也依然可以拿到。实现上doGenerate()将response.body直接赋值为轮询最终 GET 返回的rawTranscript见 assemblyai-transcription-model.ts而providerMetadata的各字段虽然以解析后的 transcript 判断存在性取值却来自原始响应避免被 schema 过滤掉任何字段。4.2 读取示例import { transcribe } from ai; import { assemblyai } from ai-sdk/assemblyai; import { readFile } from fs/promises; const result await transcribe({ model: assemblyai.transcription(universal-3-5-pro), audio: await readFile(audio.mp3), providerOptions: { assemblyai: { speakerLabels: true, entityDetection: true, }, }, }); const { utterances, entities } result.providerMetadata?.assemblyai ?? {}; // utterances: [{ speaker: A, text: …, start, end, … }, …]4.3 时间戳单位修复毫秒与秒的边界CHANGELOG 3.0.4 中有一个容易被忽略但影响数据正确性的修复Fix transcription segment timings, which were reported in milliseconds instead of seconds.。AssemblyAI API 返回的词级时间戳以毫秒为单位而 AI SDK 的segments约定以秒为单位。修复后的实现assemblyai-transcription-model.ts在映射segments时统一除以 1000segments: transcript.words?.map(word ({ text: word.text, startSecond: word.start / 1000, endSecond: word.end / 1000, })) ?? [],同时providerMetadata与response.body内部的时间戳如utterances[].start仍保持毫秒单位、与 AssemblyAI API 一致。官方文档content/providers/01-ai-sdk-providers/100-assemblyai.mdx特别提醒了这组单位差异使用时务必区分。4.4 已废弃的 AssemblyAI 功能按官方文档说明Summarization、Auto Chapters、Custom Topics 已被 AssemblyAI API 层面废弃不再透出到providerMetadata若开启其输出仍保留在原始response.body中。此外部分功能存在语言门槛例如 sentiment analysis 以英语为中心具体可用性需参考 AssemblyAI 官方文档。五、3.0.5实验性流式转录支持CHANGELOG 3.0.5commit5c5c0f5为转录模型加入了实验性流式转录支持experimental streaming transcription support覆盖 OpenAI 的gpt-realtime-whisper与 xAI WebSocket STT。该条目同时更新了ai-sdk/provider4.0.2与ai-sdk/provider-utils5.0.5说明流式能力建立在 provider 层新增的流式接口之上。需要明确的是该功能在 CHANGELOG 中标注为experimental意味着其 API 形态在后续版本中可能调整生产环境接入前应关注后续版本变更记录可从 packages/assemblyai/CHANGELOG.md 持续跟踪。六、3.0.0面向 v7 的破坏性变更清单3.0.0 是自 2.0.0 之后最大的一次语义化主版本跳跃涉及四条 major 变更见 CHANGELOG 的3.0.0段移除 CommonJS 导出全面 ESM-onlycommitef992f8所有包改为type: module使用require()的消费方必须迁移到 ESMimport语法。这一点在 package.json 的type: module与exports字段仅暴露import/default条件中得到印证。启动 v7 预发布commit8359612版本线从3.0.0-beta.*一路演进到正式版。Provider 实现代码模式统一commit04e9009重命名部分对外导出的符号旧名称通过 deprecated 别名继续可用属于软性兼容变更。Node.js 版本下限提升至 22commit7fc6bd6官方支持的版本为 22、24、26。这与 package.json 中engines: { node: 22 }完全一致升级前请确认运行环境。6.1 Workflow 序列化支持3.0.0以及 3.0.0-beta.22引入的 workflow 序列化能力值得单独说明ai-sdk/provider-utils新增serializeModel()帮助函数只提取模型实例中可序列化的属性过滤函数及包含函数的对象所有 provider 模型类新增静态方法WORKFLOW_SERIALIZE与WORKFLOW_DESERIALIZE使模型实例可以跨 workflow step 边界传输而不触发序列化错误。AssemblyAI 侧的实现见 assemblyai-transcription-model.ts。配套的兼容性调整是provider 配置类型中headers变为可选。这意味着从 workflow step 反序列化模型时可以在 auth 由外部单独提供的情况下省略headers——已有代码传入headers不受影响。6.2 从 v2 升级到 v3 的检查清单综合 CHANGELOG 与源码升级时至少需要确认构建产物改为 ESM检查require(ai-sdk/assemblyai)的使用点运行环境 Node.js ≥ 22若自定义了 provider 配置对象headers现在可选可精简依赖zod的 peer 版本范围为^3.25.76 || ^4.1.8见 package.json同时包内部已切换为import * from zod/v4commit95f65c2若使用了被重命名的导出符号注意 deprecated 别名的存在可平滑过渡。七、底层调用链上传 → 提交 → 轮询AssemblyAITranscriptionModel.doGenerate()assemblyai-transcription-model.ts展示了完整的同步转录流程这也是理解 CHANGELOG 中b400d67adding polling to assemblyai transcribe async价值的关键上传音频POST /v2/uploadContent-Type: application/octet-stream请求体即原始音频字节返回upload_url提交转录POST /v2/transcript在getArgs()组装好的请求体基础上追加audio_url: uploadResponse.upload_url返回转录任务id与初始status轮询结果waitForCompletion()以默认3000msPOLLING_INTERVAL_MS间隔 GET/v2/transcript/{id}直至status变为completed或error。轮询间隔可通过 provider 配置的pollingInterval覆盖见 assemblyai-transcription-model.ts。轮询循环实现了对AbortSignal的响应一旦外部取消立即抛出Transcription request was aborted同时轮询 GET 使用与上传/提交一致的config.fetch允许注入自定义 fetch 以支持代理、鉴权注入或测试见 assemblyai-transcription-model.ts。7.1 错误处理非 2xx 响应统一交给assemblyaiFailedResponseHandlerassemblyai-error.ts它基于createJsonErrorResponseHandler解析 AssemblyAI 的错误结构export const assemblyaiErrorDataSchema z.object({ error: z.object({ message: z.string(), code: z.number(), }), });即错误信息提取自error.message字段轮询阶段若转录任务自身进入error状态则会抛出Transcription failed: error。7.2 返回结构doGenerate()的返回包含text转录文本segments按秒归一化的词级片段startSecond/endSecondlanguage检测到的语言代码durationInSeconds优先取audio_duration缺失时由最后一个词的end毫秒值换算warnings3.0.4 起集中返回的各类废弃/信息性/依赖缺失警告providerMetadata.assemblyai与response含完整原始 body。八、Provider 实例与配置项8.1 默认实例与工厂函数assemblyai-provider.ts 导出两个入口见 index.tsassemblyai默认 provider 实例直接可用createAssemblyAI(options)工厂函数用于定制配置。import { assemblyai } from ai-sdk/assemblyai; // 或 import { createAssemblyAI } from ai-sdk/assemblyai; const custom createAssemblyAI({ apiKey: process.env.MY_KEY, // 默认读取 ASSEMBLYAI_API_KEY headers: { X-Custom: value }, fetch: customFetch, // 可拦截请求或注入测试实现 });8.2 配置项说明AssemblyAIProviderSettingsassemblyai-provider.ts支持三个可选字段配置项类型默认行为apiKeystring通过Authorization请求头发送缺省时读取ASSEMBLYAI_API_KEY环境变量loadApiKey逻辑headersRecordstring, string附加自定义请求头fetchFetchFunction自定义 fetch 实现默认为全局fetch此外所有请求头会通过withUserAgentSuffix追加ai-sdk/assemblyai/${VERSION}后缀commit1cad0ab引入 provider version 到 user-agent便于服务端识别 SDK 版本。8.3 能力边界仅转录无其他模型类型值得注意的一个设计事实AssemblyAI provider只提供转录模型。createAssemblyAI返回的 provider 对languageModel、embeddingModel、imageModel的调用均抛出NoSuchModelErrorassemblyai-provider.ts其中languageModel的错误信息明确写道 AssemblyAI does not provide language models。如果你在 AI SDK 中既要用 AssemblyAI 转录、又要用文本生成需要同时引入其他 provider如ai-sdk/openai按provider.transcription()与languageModel()各自路由。九、版本治理与依赖节奏从 CHANGELOG 的结构可以观察到该包成熟稳定的发布纪律语义化版本节奏清晰绝大多数补丁版本如3.0.6~3.0.39仅包含ai-sdk/provider/ai-sdk/provider-utils的依赖升级包自身无功能变更有功能变更的版本3.0.4、3.0.5、3.0.0则详细记录变更内容并附 commit hash便于追溯。预发布通道完整3.0.0经历了canary.50→beta.52→ 正式版的完整流程反映了仓库的发布工作流仓库根目录 CONTRIBUTING.md 与 contributing/releases.md 有更完整的发布规范说明。质量相关变更4de5a1dnpm 包中排除测试文件、2b8369ddist 中加入文档、8dc54db包中纳入 src 目录、10c1322ai-sdk/test-server移入 devDependencies等条目体现了对发布产物整洁度的持续治理。十、总结ai-sdk/assemblyai的 CHANGELOG 远不止是一份变更流水账它完整记录了一个生产级 provider 的能力演进路径从 1.0.0 的能用到 3.0.4 的好用模型路由、音频智能透出、参数依赖校验再到 3.0.5 的实时化实验性流式转录以及 3.0.0 面向 v7 的工程化收敛ESM-only、Node 22、workflow 序列化。对于使用 AI SDK 构建转录应用的开发者建议以universal-3-5-pro作为默认模型、通过providerOptions.assemblyai按需开启说话人分离与音频智能功能并在升级时重点核对 ESM、Node.js 版本与wordBoost等废弃参数的替换方案。后续如遇任何行为变化直接查阅 packages/assemblyai/CHANGELOG.md 与 官方 provider 文档 即可获得最准确的依据。【免费下载链接】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），仅供参考 @ai-sdk/assemblyai 版本演进全解：从转录模型选型到音频智能结果透出
ai-sdk/assemblyai 版本演进全解从转录模型选型到音频智能结果透出【免费下载链接】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 SDKThe AI Toolkit for TypeScript官方仓库中 ai-sdk/assemblyai 的 CHANGELOG 为主线系统梳理 AssemblyAI 转录提供者的能力演进、模型选型、provider options 体系、破坏性变更与底层调用链。读完本文你将掌握如何正确选用universal-3-5-pro等转录模型、理解speech_model/speech_models参数路由机制、使用新增的音频智能audio-intelligence与说话人分离speaker diarization结果并能够评估从 v2 升级到 v3 时需要注意的 ESM、Node.js 版本与 API 兼容性约束。一、包定位AI SDK 生态中的 AssemblyAI 转录提供者ai-sdk/assemblyai是 AI SDK 官方提供者包之一职责是封装 AssemblyAI 转录 API当前版本为3.0.39对应 package.json。从 CHANGELOG 的版本轨迹可以清晰看到这条演进主线1.0.0首次加入transcribe能力将 transcription 与 speech model 支持接入 provider registrycommitcb68df0、3ea56562.0.0随 AI SDK 6 beta 引入Provider-V3commited329cb与 transcription model v3 speccommit21e20c0并加入转录异步轮询commitb400d673.0.0随 v7 预发布进入 ESM-only 时代移除 CommonJS 导出3.0.4/3.0.5功能最密集的两个补丁版本——新增universal-3-5-pro支持、透出音频智能结果、实验性流式转录。下文将以这些关键变更点为骨架展开。二、模型支持演进从nano/best到universal-3-5-pro2.1 模型清单与当前状态assemblyai-transcription-settings.ts 中定义了完整的转录模型 ID 类型export type AssemblyAIDeprecatedTranscriptionModelId best; export type AssemblyAITranscriptionModelId | universal-2 | universal-3-pro | universal-3-5-pro | AssemblyAIDeprecatedTranscriptionModelId | (string {});结合 CHANGELOG 3.0.4 条目commitec598e2与官方 provider 文档 content/providers/01-ai-sdk-providers/100-assemblyai.mdx各模型的地位如下模型 ID状态说明universal-3-5-pro✅ 推荐AssemblyAI 最新旗舰模型新代码的默认选择universal-3-pro✅ 可用信息性警告仍可工作但使用时会收到建议迁移到universal-3-5-pro的提示universal-2✅ 可用信息性警告同上best⚠️ 已废弃deprecated遗留模型仍可用但会输出废弃警告nano❌ 已移除AssemblyAI 已不再接受该模型这里有一个值得注意的细节废弃deprecated与信息性警告informational warning是两回事。best模型走的是deprecated警告通道而universal-3-pro/universal-2尽管也是建议替换到universal-3-5-pro但两者仍完全受支持警告仅用于前瞻性提示forward-looking nudge并非废弃通知。这一语义区分可以在 assemblyai-transcription-model.ts 的getArgs()中看到具体实现。2.2 参数路由speech_model与speech_models的自动选择3.0.4 版本的一个关键行为变化是新模型必须通过 AssemblyAI 的speech_models复数数组参数传递而废弃的speech_model单数只用于遗留的best模型。源码在 assemblyai-transcription-model.ts 中实现了自动路由if (this.modelId best) { body.speech_model this.modelId as best; // 推送 deprecated 警告建议改用 universal-3-5-pro } else { body.speech_models [this.modelId]; // 其余模型全部走数组参数 // universal-3-pro / universal-2 额外推送信息性警告 }也就是说你只需在.transcription(universal-3-5-pro)中指定模型 ID请求参数的选择由提供者自动完成——这正是 content/providers/01-ai-sdk-providers/100-assemblyai.mdx 中provider selects automatically based on the model id一说的源码依据。同时代码注释明确引用了 AssemblyAI 官方文档select-the-speech-model作为路由规则的依据见 assemblyai-transcription-model.ts。三、3.0.4 新增 Provider Options 全解CHANGELOG 3.0.4commitec598e2一次性引入了大量新的 provider optionsprompt、keytermsPrompt、temperature、removeAudioTags、domain、speakerOptions、languageDetectionOptions、redactPiiAudioOptions、redactPiiReturnUnredacted、redactStaticEntities。这些参数的类型定义集中在 assemblyai-transcription-model-options.ts通过assemblyaiTranscriptionModelOptionsSchema基于 zod v4做运行时校验并在getArgs()中映射为 AssemblyAI API 的 snake_case 请求体字段。3.1 如何传入 Provider Options使用方式是通过transcribe()的providerOptions.assemblyai传入并且类型可以安全地satisfies AssemblyAITranscriptionModelOptions校验import { transcribe } from ai; import { assemblyai } from ai-sdk/assemblyai; import { type AssemblyAITranscriptionModelOptions } from ai-sdk/assemblyai; import { readFile } from fs/promises; const result await transcribe({ model: assemblyai.transcription(universal-3-5-pro), audio: await readFile(audio.mp3), providerOptions: { assemblyai: { contentSafety: true, } satisfies AssemblyAITranscriptionModelOptions, }, });3.2 核心参数速查表以下参数在 CHANGELOG 3.0.4 与 provider 文档 中均有描述此处整理其作用与约束校验逻辑详见 assemblyai-transcription-model-options.ts参数类型说明与约束promptstring自然语言上下文最多 1500 词引导模型输出。仅universal-3-pro/universal-3-5-pro/slam-1支持keytermsPromptstring[]领域关键词增强每短语最多 6 词替代wordBoost新模型专用temperaturenumber(0–1)采样温度控制随机性Universal-3 Pro 系列模型removeAudioTagsall \| speaker移除富文本转录中的内联标注all全部、speaker仅说话人提示domainstring领域专用模型当前支持medical-v1医疗模式speakerOptions{ minSpeakersExpected?, maxSpeakersExpected? }说话人分离的说话人数范围languageDetectionOptions{ expectedLanguages?, fallbackLanguage?, codeSwitching?, codeSwitchingConfidenceThreshold? }自动语言检测选项码切换置信度阈值为 0–1redactPiiAudioOptions{ returnRedactedNoSpeechAudio?, overrideAudioRedactionMethod? }PII 音频脱敏选项overrideAudioRedactionMethod仅支持silence依赖redactPiiAudioredactPiiReturnUnredactedboolean同时返回未脱敏原文依赖redactPiiredactStaticEntitiesRecordstring, string[]自定义静态实体脱敏映射如{ INTERNAL_TOOL: [Bearclaw] }依赖redactPii3.3 参数间的依赖与冲突检查源码getArgs()assemblyai-transcription-model.ts内置了三组依赖/冲突保护逻辑会在不满足前置条件时输出警告而不是静默失败redactPiiReturnUnredacted/redactStaticEntities设置了但未开启redactPii→ 警告AssemblyAI 会直接拒绝请求redactPiiAudioOptions设置了但未开启redactPiiAudio→ 警告该选项会被忽略languageDetection与显式languageCode同时设置 → 警告AssemblyAI 拒绝同时设置两者的请求。这些行为属于只警告、不替用户改写输入Warn rather than mutate user input的设计取舍可以在代码注释中找到明确说明。3.4 废弃项wordBoost/boostParam的归宿CHANGELOG 3.0.4 明确废弃了wordBoost/boostParam原因是 AssemblyAI 在新模型上直接拒绝word_boost参数。源码中对应处理有两层在 assemblyai-transcription-model-options.ts 中wordBoost与boostParam均标记为deprecated并注明universal-3-pro/universal-3-5-pro/slam-1会拒绝仅universal-2/best可用在getArgs()中assemblyai-transcription-model.ts只要检测到二者之一被传入就推送deprecated警告并提示改用keytermsPrompt。与此同时best模型也被标记废弃见 assemblyai-transcription-settings.ts而nano则被直接移除——这正是 CHANGELOG 中 Deprecate the legacybestmodel (still works, warns) and removenano 的完整含义。四、说话人分离与音频智能结果的透出机制4.1 为什么需要额外的透出通道AI SDK 的transcribe()结果形状固定为text、segments、language、durationInSeconds无法承载 AssemblyAI 更丰富的结构化输出。3.0.4 的解决方案是双通道透出assemblyai-transcription-model.tsproviderMetadata.assemblyai结构化透出已启用的音频智能结果包括utterances开启speakerLabels时的说话人分离片段、entities、sentimentAnalysisResults、contentSafetyLabels、iabCategoriesResult、autoHighlightsResultresponse.body完整保留原始 AssemblyAI 转录响应因此即使某个字段未在上述清单中例如chapters、词级speaker标签也依然可以拿到。实现上doGenerate()将response.body直接赋值为轮询最终 GET 返回的rawTranscript见 assemblyai-transcription-model.ts而providerMetadata的各字段虽然以解析后的 transcript 判断存在性取值却来自原始响应避免被 schema 过滤掉任何字段。4.2 读取示例import { transcribe } from ai; import { assemblyai } from ai-sdk/assemblyai; import { readFile } from fs/promises; const result await transcribe({ model: assemblyai.transcription(universal-3-5-pro), audio: await readFile(audio.mp3), providerOptions: { assemblyai: { speakerLabels: true, entityDetection: true, }, }, }); const { utterances, entities } result.providerMetadata?.assemblyai ?? {}; // utterances: [{ speaker: A, text: …, start, end, … }, …]4.3 时间戳单位修复毫秒与秒的边界CHANGELOG 3.0.4 中有一个容易被忽略但影响数据正确性的修复Fix transcription segment timings, which were reported in milliseconds instead of seconds.。AssemblyAI API 返回的词级时间戳以毫秒为单位而 AI SDK 的segments约定以秒为单位。修复后的实现assemblyai-transcription-model.ts在映射segments时统一除以 1000segments: transcript.words?.map(word ({ text: word.text, startSecond: word.start / 1000, endSecond: word.end / 1000, })) ?? [],同时providerMetadata与response.body内部的时间戳如utterances[].start仍保持毫秒单位、与 AssemblyAI API 一致。官方文档content/providers/01-ai-sdk-providers/100-assemblyai.mdx特别提醒了这组单位差异使用时务必区分。4.4 已废弃的 AssemblyAI 功能按官方文档说明Summarization、Auto Chapters、Custom Topics 已被 AssemblyAI API 层面废弃不再透出到providerMetadata若开启其输出仍保留在原始response.body中。此外部分功能存在语言门槛例如 sentiment analysis 以英语为中心具体可用性需参考 AssemblyAI 官方文档。五、3.0.5实验性流式转录支持CHANGELOG 3.0.5commit5c5c0f5为转录模型加入了实验性流式转录支持experimental streaming transcription support覆盖 OpenAI 的gpt-realtime-whisper与 xAI WebSocket STT。该条目同时更新了ai-sdk/provider4.0.2与ai-sdk/provider-utils5.0.5说明流式能力建立在 provider 层新增的流式接口之上。需要明确的是该功能在 CHANGELOG 中标注为experimental意味着其 API 形态在后续版本中可能调整生产环境接入前应关注后续版本变更记录可从 packages/assemblyai/CHANGELOG.md 持续跟踪。六、3.0.0面向 v7 的破坏性变更清单3.0.0 是自 2.0.0 之后最大的一次语义化主版本跳跃涉及四条 major 变更见 CHANGELOG 的3.0.0段移除 CommonJS 导出全面 ESM-onlycommitef992f8所有包改为type: module使用require()的消费方必须迁移到 ESMimport语法。这一点在 package.json 的type: module与exports字段仅暴露import/default条件中得到印证。启动 v7 预发布commit8359612版本线从3.0.0-beta.*一路演进到正式版。Provider 实现代码模式统一commit04e9009重命名部分对外导出的符号旧名称通过 deprecated 别名继续可用属于软性兼容变更。Node.js 版本下限提升至 22commit7fc6bd6官方支持的版本为 22、24、26。这与 package.json 中engines: { node: 22 }完全一致升级前请确认运行环境。6.1 Workflow 序列化支持3.0.0以及 3.0.0-beta.22引入的 workflow 序列化能力值得单独说明ai-sdk/provider-utils新增serializeModel()帮助函数只提取模型实例中可序列化的属性过滤函数及包含函数的对象所有 provider 模型类新增静态方法WORKFLOW_SERIALIZE与WORKFLOW_DESERIALIZE使模型实例可以跨 workflow step 边界传输而不触发序列化错误。AssemblyAI 侧的实现见 assemblyai-transcription-model.ts。配套的兼容性调整是provider 配置类型中headers变为可选。这意味着从 workflow step 反序列化模型时可以在 auth 由外部单独提供的情况下省略headers——已有代码传入headers不受影响。6.2 从 v2 升级到 v3 的检查清单综合 CHANGELOG 与源码升级时至少需要确认构建产物改为 ESM检查require(ai-sdk/assemblyai)的使用点运行环境 Node.js ≥ 22若自定义了 provider 配置对象headers现在可选可精简依赖zod的 peer 版本范围为^3.25.76 || ^4.1.8见 package.json同时包内部已切换为import * from zod/v4commit95f65c2若使用了被重命名的导出符号注意 deprecated 别名的存在可平滑过渡。七、底层调用链上传 → 提交 → 轮询AssemblyAITranscriptionModel.doGenerate()assemblyai-transcription-model.ts展示了完整的同步转录流程这也是理解 CHANGELOG 中b400d67adding polling to assemblyai transcribe async价值的关键上传音频POST /v2/uploadContent-Type: application/octet-stream请求体即原始音频字节返回upload_url提交转录POST /v2/transcript在getArgs()组装好的请求体基础上追加audio_url: uploadResponse.upload_url返回转录任务id与初始status轮询结果waitForCompletion()以默认3000msPOLLING_INTERVAL_MS间隔 GET/v2/transcript/{id}直至status变为completed或error。轮询间隔可通过 provider 配置的pollingInterval覆盖见 assemblyai-transcription-model.ts。轮询循环实现了对AbortSignal的响应一旦外部取消立即抛出Transcription request was aborted同时轮询 GET 使用与上传/提交一致的config.fetch允许注入自定义 fetch 以支持代理、鉴权注入或测试见 assemblyai-transcription-model.ts。7.1 错误处理非 2xx 响应统一交给assemblyaiFailedResponseHandlerassemblyai-error.ts它基于createJsonErrorResponseHandler解析 AssemblyAI 的错误结构export const assemblyaiErrorDataSchema z.object({ error: z.object({ message: z.string(), code: z.number(), }), });即错误信息提取自error.message字段轮询阶段若转录任务自身进入error状态则会抛出Transcription failed: error。7.2 返回结构doGenerate()的返回包含text转录文本segments按秒归一化的词级片段startSecond/endSecondlanguage检测到的语言代码durationInSeconds优先取audio_duration缺失时由最后一个词的end毫秒值换算warnings3.0.4 起集中返回的各类废弃/信息性/依赖缺失警告providerMetadata.assemblyai与response含完整原始 body。八、Provider 实例与配置项8.1 默认实例与工厂函数assemblyai-provider.ts 导出两个入口见 index.tsassemblyai默认 provider 实例直接可用createAssemblyAI(options)工厂函数用于定制配置。import { assemblyai } from ai-sdk/assemblyai; // 或 import { createAssemblyAI } from ai-sdk/assemblyai; const custom createAssemblyAI({ apiKey: process.env.MY_KEY, // 默认读取 ASSEMBLYAI_API_KEY headers: { X-Custom: value }, fetch: customFetch, // 可拦截请求或注入测试实现 });8.2 配置项说明AssemblyAIProviderSettingsassemblyai-provider.ts支持三个可选字段配置项类型默认行为apiKeystring通过Authorization请求头发送缺省时读取ASSEMBLYAI_API_KEY环境变量loadApiKey逻辑headersRecordstring, string附加自定义请求头fetchFetchFunction自定义 fetch 实现默认为全局fetch此外所有请求头会通过withUserAgentSuffix追加ai-sdk/assemblyai/${VERSION}后缀commit1cad0ab引入 provider version 到 user-agent便于服务端识别 SDK 版本。8.3 能力边界仅转录无其他模型类型值得注意的一个设计事实AssemblyAI provider只提供转录模型。createAssemblyAI返回的 provider 对languageModel、embeddingModel、imageModel的调用均抛出NoSuchModelErrorassemblyai-provider.ts其中languageModel的错误信息明确写道 AssemblyAI does not provide language models。如果你在 AI SDK 中既要用 AssemblyAI 转录、又要用文本生成需要同时引入其他 provider如ai-sdk/openai按provider.transcription()与languageModel()各自路由。九、版本治理与依赖节奏从 CHANGELOG 的结构可以观察到该包成熟稳定的发布纪律语义化版本节奏清晰绝大多数补丁版本如3.0.6~3.0.39仅包含ai-sdk/provider/ai-sdk/provider-utils的依赖升级包自身无功能变更有功能变更的版本3.0.4、3.0.5、3.0.0则详细记录变更内容并附 commit hash便于追溯。预发布通道完整3.0.0经历了canary.50→beta.52→ 正式版的完整流程反映了仓库的发布工作流仓库根目录 CONTRIBUTING.md 与 contributing/releases.md 有更完整的发布规范说明。质量相关变更4de5a1dnpm 包中排除测试文件、2b8369ddist 中加入文档、8dc54db包中纳入 src 目录、10c1322ai-sdk/test-server移入 devDependencies等条目体现了对发布产物整洁度的持续治理。十、总结ai-sdk/assemblyai的 CHANGELOG 远不止是一份变更流水账它完整记录了一个生产级 provider 的能力演进路径从 1.0.0 的能用到 3.0.4 的好用模型路由、音频智能透出、参数依赖校验再到 3.0.5 的实时化实验性流式转录以及 3.0.0 面向 v7 的工程化收敛ESM-only、Node 22、workflow 序列化。对于使用 AI SDK 构建转录应用的开发者建议以universal-3-5-pro作为默认模型、通过providerOptions.assemblyai按需开启说话人分离与音频智能功能并在升级时重点核对 ESM、Node.js 版本与wordBoost等废弃参数的替换方案。后续如遇任何行为变化直接查阅 packages/assemblyai/CHANGELOG.md 与 官方 provider 文档 即可获得最准确的依据。【免费下载链接】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），仅供参考