AI SDK Angular 组件库演进指南从 1.0 到 3.0 的版本变迁与核心 API 实战【免费下载链接】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/angular是 AI SDK 官方为 Angular 提供的 UI 组件库以 Angular signals 为响应式状态底座为开发者提供Chat多轮流式对话、Completion单轮文本生成与StructuredObject基于 Zod schema 的类型安全结构化输出三大开箱即用的能力。本文以 packages/angular/CHANGELOG.md 记录的版本演进为主线结合 packages/angular/README.md 与 packages/angular/src 源码实现梳理该包从 1.0.0 引入 Angular 支持到当前 3.0.97 的里程碑变迁并给出三大组件的完整实战用法、响应式原理与服务端配套方案帮助你在 Angular 项目中直接落地流式 AI 交互。一、ai-sdk/angular 在 AI SDK 中的定位ai-sdk/angular是 AI SDKVercel 出品的 TypeScript AI 工具包的 Angular 官方实现。根据 packages/angular/package.json 中的声明它通过ai与ai-sdk/provider-utils两个运行时依赖复用 AI SDK 核心能力面向 Angular 场景提供三组信号驱动的 APIChat多轮对话支持流式响应、工具调用tool calls、文件附件与多步推理multi-stepCompletion单轮文本补全带流式输出与加载态StructuredObject配合 Zod 等 schema 生成类型安全的结构化对象支持流式增量返回。安装方式见 README.mdnpm install ai-sdk/angular ai其 Peer 依赖要求为angular/core 16.0.0package.json中peerDependencies声明Zod v3可选仅在需要结构化对象时使用。package.json还声明了包级别的运行前提engines.node 22包类型为 ESMtype: module产物通过dist/index.js导出入口再统一从 packages/angular/src/index.ts 导出Chat、Completion与StructuredObject三个类及对应 Options 类型。二、版本演进主线CHANGELOG 里的关键里程碑CHANGELOG 完整记录了该包自 1.0.0-beta.0 至今 3.0.97 的全部变更。其中大量条目是跟随ai与ai-sdk/provider-utils的依赖同步更新但有几处具有独立技术价值的里程碑值得单独拆解。1.0.0Angular 支持正式落地在 CHANGELOG.md 中1.0.0 版本的核心变更为654ff2bAdd Angular support——Angular 支持正式合入ac34802为 React 与 Angular 包增加 clear object 函数205077b修复并改进 Zod 兼容性。这意味着从 AI SDK v5 时代起Angular 就与 React 等框架并列成为一等公民其定位与职责在引入之初即已定型把 AI SDK 的流式传输与工具能力封装成 Angular 友好的类 API。2.0.0对齐 AI SDK 6 与 zod 策略调整CHANGELOG.md 记录 2.0.0 随 AI SDK 6 beta 发布其中值得关注的点e8109d3新增tool execution approval工具执行审批能力f6f0c5a从 UI 包中移除 zod 依赖——zod 不再是包的运行时依赖改为由使用方提供这也解释了 README 中 zod 被列为可选 peer 依赖的缘由95f65c2切换到import * from zod/v4的导入方式10c1322将ai-sdk/test-server移到 devDependencies保证发布包的依赖面干净。此外 2.0.79 的82c721e明确标记为 Align with v62.0.46/2.0.48 分别涉及将 src 目录纳入包产物、并从 npm 包中排除测试文件4de5a1d这些工程化调整直接影响了开发者调试与打包体积。3.0.0v7 预发布、ESM-only 与 Node 版本门槛3.0.0 是破坏性变更最集中的一个版本CHANGELOG.mdef992f8移除所有包的 CommonJS 导出全面切换为 ESM-only。仍使用require()的消费方必须迁移到 ESMimport语法8359612启动 AI SDK v7 预发布7fc6bd6Node.js 最低版本提升到 22支持版本为 22、24、260c4c275/b8396f0触发初始 canary 与 beta 发布258c093统一导入处理避免重复导入或循环依赖。这些约束与当前 packages/angular/package.json 中的type: module、engines: { node: 22 }完全一致。3.x 稳定版中具有实质内容的 Patch3.0.97 之前的稳定版大多只是依赖升级但以下三条 Patch 承载了真实的行为改进3.0.92d1904d3fix(ai): surface fallback errors for empty HTTP response bodies——当服务端返回空响应体时不再静默失败而是将 fallback 错误暴露出来便于定位服务端问题3.0.794396fe0提交聊天消息前不再深拷贝deep-clone避免不可克隆的元数据non-cloneable metadata阻断请求——对于消息中携带自定义非序列化对象如 DOM 引用、类实例的场景这是一项直接的可用性修复3.0.62e0bcf52feat(ui): add typed custom bodies to Completion APIs——为 Completion API 增加类型化的自定义请求体支持Completion类的泛型参数BODY因此可以让 body 字段获得完整的类型提示。三、三大核心 API 实战详解以下用法均来自 packages/angular/README.md可直接复制到 Angular 组件中运行。Chat多轮流式对话Chat类在构造时接收初始化选项常用字段包括id对话唯一标识、messages初始消息、maxSteps最大推理步数、onToolCall客户端工具调用回调、onFinish、onError等。基础组件写法import { Component, inject } from angular/core; import { FormBuilder, ReactiveFormsModule, Validators } from angular/forms; import { Chat } from ai-sdk/angular; import { CommonModule } from angular/common; Component({ selector: app-chat, imports: [CommonModule, ReactiveFormsModule], template: div classmessages for (message of chat.messages; track message.id) { div classmessage [ngClass]message.role for (part of message.parts; track $index) { switch (part.type) { case (text) { div stylewhite-space: pre-wrap {{ part.text }} if (part.state streaming) { span classcursor#9646;/span } /div } case (reasoning) { details summaryReasoning/summary div stylewhite-space: pre-wrap; opacity: 80%{{ part.text }}/div /details } default { code{{ part | json }}/code } } } /div } if (chat.status submitted) { divemWaiting.../em/div } /div form [formGroup]chatForm (ngSubmit)sendMessage() input formControlNameuserInput placeholderType your message... / if (chat.status ready) { button typesubmit [disabled]!chatForm.validSend/button } else { button [disabled]chat.status error (click)chat.stop()Stop/button } /form , }) export class ChatComponent { private fb inject(FormBuilder); public chat new Chat({}); chatForm this.fb.group({ userInput: [, Validators.required] }); sendMessage() { if (this.chatForm.invalid) return; const userInput this.chatForm.value.userInput; this.chatForm.reset(); this.chat.sendMessage( { text: userInput }, { body: { selectedModel: openai/gpt-5.4 } }, ); } }要点说明消息渲染按message.parts展开part.type区分text、reasoning与默认如工具调用类型part.state streaming用于展示流式游标chat.status可取ready/submitted/error等状态据此切换发送与停止按钮selectedModel传的是 AI Gateway 的模型 ID如openai/gpt-5.4当传入字符串模型 ID 时 AI SDK 默认走 AI Gateway 作为 Provider无需再 import 具体 Provider 包见 README.md。Chat还支持以下方法与能力await chat.sendMessage(message, { body?, headers? }); // 发送消息 await chat.regenerate({ body?, headers? }); // 重新生成最后一条助手消息 await chat.resumeStream({ body?, headers? }); // 恢复被中断的流 chat.addToolResult({ toolCallId, output }); // 注入工具执行结果 chat.stop(); // 立即停止当前生成文件附件sendMessage的输入可直接携带files来自input typefile multiple (change)onFileSelect($event) /实现分析这些文件式的多模态消息。客户端工具调用通过构造参数注册onToolCall在浏览器侧执行工具并返回结果const chat new Chat({ async onToolCall({ toolCall }) { switch (toolCall.toolName) { case get_weather: return await getWeather(toolCall.input.location); case search: return await search(toolCall.input.query); default: throw new Error(Unknown tool: ${toolCall.toolName}); } }, });Completion单轮文本补全Completion面向一次输入、一次输出的场景核心可配项包括api默认/api/completion、streamProtocoldata | text默认data、initialCompletion、initialInput、onFinish、onError、fetch、headers、body、credentials。组件示例import { Component } from angular/core; import { Completion } from ai-sdk/angular; Component({ selector: app-completion, template: textarea [(ngModel)]completion.input placeholderEnter your prompt... rows4/textarea button (click)completion.complete(completion.input) [disabled]completion.loading {{ completion.loading ? Generating... : Generate }} /button if (completion.loading) { button (click)completion.stop()Stop/button } pre{{ completion.completion }}/pre if (completion.error) { div classerror{{ completion.error.message }}/div } , }) export class CompletionComponent { completion new Completion({ api: /api/completion, streamProtocol: text, onFinish: (prompt, completion) console.log(Completed:, { prompt, completion }), }); }其信号驱动的响应式属性包括completion生成文本可写、input当前输入可写、loading、error、id、api、streamProtocol。方法上除complete(prompt, options?)与stop()外还提供handleSubmit(event?)用于表单提交场景——内部会自动preventDefault()并基于当前input发起请求见 completion.ng.ts。从 completion.ng.ts 的源码可以看到complete最终调用 AI SDK 的callCompletionApi并利用normalizeHeaders将构造选项与单次请求的 headers 合并后一并发送同时内部持有AbortController以便stop()随时中断请求。StructuredObjectSchema 驱动的结构化输出StructuredObject让你用 Zod schema 定义输出形状服务端流式返回 JSON 分片前端增量解析并类型化。README 中的完整示例import { Component } from angular/core; import { StructuredObject } from ai-sdk/angular; import { z } from zod; const schema z.object({ title: z.string(), summary: z.string(), tags: z.array(z.string()), sentiment: z.enum([positive, negative, neutral]), }); Component({ selector: app-structured-object, template: textarea [(ngModel)]input placeholderEnter content to analyze... rows4/textarea button (click)analyze() [disabled]structuredObject.loading {{ structuredObject.loading ? Analyzing... : Analyze }} /button if (structuredObject.object) { div classresult divstrongTitle:/strong {{ structuredObject.object.title }}/div divstrongSummary:/strong {{ structuredObject.object.summary }}/div divstrongTags:/strong {{ structuredObject.object.tags?.join(, ) }}/div divstrongSentiment:/strong {{ structuredObject.object.sentiment }}/div /div } if (structuredObject.error) { div classerror{{ structuredObject.error.message }}/div } , }) export class StructuredObjectComponent { input ; structuredObject new StructuredObject({ api: /api/analyze, schema, onFinish: ({ object, error }) { if (error) console.error(Schema validation failed:, error); else console.log(Generated object:, object); }, }); async analyze() { if (!this.input.trim()) return; await this.structuredObject.submit(this.input); } }构造选项见 structured-object.ng.ts包括必填的api与schema以及可选的id相同id可在多个组件间共享状态、initialValue初始对象、onFinish、onError、fetch、headers、credentials。响应式属性为objectDeepPartialRESULT | undefined随流式 JSON 分片增量更新、loading、error方法为submit(input)与stop()。关于类型推断README 给出了一个关键点object的类型由 schema 自动推导例如z.object({ name: z.string(), age: z.number() })对应{ name?: string; age?: number } | undefined。这正是 Zod 与 TypeScript 泛型InferSchemaSCHEMA协同的结果。四、源码剖析signals 如何支撑响应式状态三大类都以 Angularsignal作为状态存储从而获得细粒度的变更检测change detection避免整棵组件树不必要的重渲染。以 chat.ng.ts 中的AngularChatState为例class AngularChatStateUI_MESSAGE extends UIMessage UIMessage implements ChatStateUI_MESSAGE { readonly #messages signalUI_MESSAGE[]([]); readonly #status signalChatStatus(ready); readonly #error signalError | undefined(undefined); get messages(): UI_MESSAGE[] { return this.#messages(); } set messages(messages: UI_MESSAGE[]) { this.#messages.set([...messages]); } // ... status / error 同理 setMessages (messages: UI_MESSAGE[]) { this.#messages.set([...messages]); }; pushMessage (message: UI_MESSAGE) { this.#messages.update(msgs [...msgs, message]); }; popMessage () { this.#messages.update(msgs msgs.slice(0, -1)); }; replaceMessage (index: number, message: UI_MESSAGE) { this.#messages.update(msgs { const copy [...msgs]; copy[index] message; return copy; }); }; }Chat类本身继承自 AI SDK 的AbstractChat仅通过构造函数注入这套基于 signal 的状态实现chat.ng.ts。也就是说对话状态机与传输逻辑完全复用ai核心包Angular 包只负责把状态读写翻译成 signal 语义——这也解释了 CHANGELOG 中大量Updated dependencies: aix.y.z条目每当核心包升级Angular 包都会同步发版以保持行为一致。Completion与StructuredObject同样使用私有 signal 字段#input、#completion、#error、#loading、#object并通过 getter 对外暴露只读视角stop()均通过AbortController中断 fetch 请求同时保留已生成内容见 completion.ng.ts 与 structured-object.ng.ts。而StructuredObject的增量解析依赖ai导出的parsePartialJson、asSchema、isDeepEqualData等工具见 structured-object.ng.ts这也解释了其 schema 校验与onFinish中error如TypeValidationError的来源。五、服务端配套AI Gateway 与流式端点当客户端传字符串模型 ID如openai/gpt-5.4时AI SDK 默认使用 AI Gateway 作为 Provider。README 给出了三个 Express 服务端端点模板可直接对接到前端的三大组件Chat 端点客户端sendMessage携带messages与selectedModelimport { convertToModelMessages, pipeTextStreamToResponse, pipeUIMessageStreamToResponse, streamText, toTextStream, toUIMessageStream, } from ai; import express from express; const app express(); app.use(express.json({ strict: false })); app.post(/api/chat, async (req, res) { const { messages, selectedModel } req.body; const result streamText({ model: selectedModel || openai/gpt-5.4, messages: convertToModelMessages(messages), }); pipeUIMessageStreamToResponse({ response: res, stream: toUIMessageStream({ stream: result.stream }), }); });Completion 端点配合streamProtocol: textapp.post(/api/completion, async (req, res) { const { prompt } req.body; const result streamText({ model: openai/gpt-5.4, prompt }); pipeTextStreamToResponse({ response: res, stream: toTextStream({ stream: result.stream }), }); });Structured Object 端点streamObject输出 schema 化 JSON 流import { streamObject } from ai; import { z } from zod; app.post(/api/analyze, async (req, res) { const input req.body; const result streamObject({ model: openai/gpt-5.4, schema: z.object({ title: z.string(), summary: z.string(), tags: z.array(z.string()), sentiment: z.enum([positive, negative, neutral]), }), prompt: Analyze this content: ${JSON.stringify(input)}, }); result.pipeTextStreamToResponse(res); });README 还演示了基于examples/angular示例的本地联调方式在示例目录写入.envAI_GATEWAY_API_KEYyour_key_here或使用 OIDC 认证时写入VERCEL_OIDC_TOKEN随后pnpm start会同时启动 Angular 开发服务器http://localhost:4200与 Express API 服务器http://localhost:3000并将/api/*代理到 Express。六、工程化实践构建、测试与发布配置在 packages/angular/package.json 中可以看到该包的完整工程化约定pnpm install # 安装依赖 pnpm build # 构建clean tsup pnpm build:watch # 监听构建 pnpm test # 运行 vitest 测试 pnpm test:update # 更新快照 pnpm test:watch # 测试监听模式 pnpm type-check # TypeScript 类型检查关键配置说明构建通过tsup --tsconfig tsconfig.build.json产出dist/index.js与类型声明dist/index.d.ts产物范围files字段包含dist/**/*、src但排除*.test.ts、*.test-d.ts、__snapshots__与__fixtures__以及 CHANGELOG 和 README——这与 CHANGELOG 中 2.0.46add src folders to package bundle和 2.0.48excluded tests from src folder in npm package两条工程化 Patch 一脉相承测试使用 vitest jsdomvitest.config.ts并依赖ai-sdk/test-server作为测试用服务端devDependencies见 2.0.0 中10c1322的调整同目录下的 chat.ng.test.ts、completion.ng.test.ts、structured-object.ng.test.ts 即对应三大组件的测试用例类型层面completion.ng.test-d.ts 用于静态类型断言确保泛型推导如 3.0.62 引入的 typed custom bodies在编译期即被验证发布publishConfig.access public且启用provenance供应链来源证明许可证为 Apache-2.0。七、小结与升级建议回顾 CHANGELOG 的演进脉络ai-sdk/angular的每次主版本跳跃都对应 AI SDK 核心的大版本1.0 随 v5 引入 Angular 支持2.0 随 v6 完成 zod 策略与工具执行审批的调整3.0 随 v7 全面转向 ESM-only 并将 Node 门槛提升到 22。日常升级时建议关注三条线索破坏性变更窗口跨主版本升级时重点核对 ESM 导出、Node 版本22/24/26与 zod 的提供方式行为修复类 Patch如 3.0.79 的不再深拷贝聊天消息、3.0.92 的空响应体错误透出往往能解释线上偶发问题依赖同步节奏ai-sdk/angular与ai、ai-sdk/provider-utils严格同版发布升级时三者应保持一致避免版本错配。如果你正在 Angular 应用中构建流式对话、单轮补全或 schema 化数据抽取能力直接从 packages/angular/README.md 的示例起步再对照 packages/angular/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），仅供参考