AI SDK Angular 组件库演进指南:从 1.0 到 3.0 的版本变迁与核心 API 实战
AI SDK Angular 组件库演进指南:从 1.0 到 3.0 的版本变迁与核心 API 实战
@ai-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 SDK(Vercel 出品的 TypeScript AI 工具包)的 Angular 官方实现。根据 packages/angular/package.json 中的声明,它通过 ai 与 @ai-sdk/provider-utils 两个运行时依赖复用 AI SDK 核心能力,面向 Angular 场景提供三组信号驱动的 API:
- Chat:多轮对话,支持流式响应、工具调用(tool calls)、文件附件与多步推理(multi-step);
- Completion:单轮文本补全,带流式输出与加载态;
- StructuredObject:配合 Zod 等 schema 生成类型安全的结构化对象,支持流式增量返回。
安装方式(见 README.md):
npm install @ai-sdk/angular ai
其 Peer 依赖要求为:
@angular/core>= 16.0.0(package.json中peerDependencies声明);- Zod v3+(可选,仅在需要结构化对象时使用)。
package.json 还声明了包级别的运行前提:engines.node >= 22,包类型为 ESM("type": "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.0:Angular 支持正式落地
在 CHANGELOG.md 中,1.0.0 版本的核心变更为:
654ff2b:Add 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 v6",2.0.46/2.0.48 分别涉及将 src 目录纳入包产物、并从 npm 包中排除测试文件(4de5a1d),这些工程化调整直接影响了开发者调试与打包体积。
3.0.0:v7 预发布、ESM-only 与 Node 版本门槛
3.0.0 是破坏性变更最集中的一个版本(CHANGELOG.md):
ef992f8:移除所有包的 CommonJS 导出,全面切换为 ESM-only。仍使用require()的消费方必须迁移到 ESMimport语法;8359612:启动 AI SDK v7 预发布;7fc6bd6:Node.js 最低版本提升到 22,支持版本为 22、24、26;0c4c275/b8396f0:触发初始 canary 与 beta 发布;258c093:统一导入处理,避免重复导入或循环依赖。
这些约束与当前 packages/angular/package.json 中的 "type": "module"、"engines": { "node": ">=22" } 完全一致。
3.x 稳定版中具有实质内容的 Patch
3.0.97 之前的稳定版大多只是依赖升级,但以下三条 Patch 承载了真实的行为改进:
- 3.0.92(
d1904d3):fix(ai): surface fallback errors for empty HTTP response bodies——当服务端返回空响应体时,不再静默失败,而是将 fallback 错误暴露出来,便于定位服务端问题; - 3.0.79(
4396fe0):提交聊天消息前不再深拷贝(deep-clone),避免不可克隆的元数据(non-cloneable metadata)阻断请求——对于消息中携带自定义非序列化对象(如 DOM 引用、类实例)的场景,这是一项直接的可用性修复; - 3.0.62(
e0bcf52):feat(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 class="messages">
@for (message of chat.messages; track message.id) {
<div class="message" [ngClass]="message.role">
@for (part of message.parts; track $index) {
@switch (part.type) {
@case ('text') {
<div style="white-space: pre-wrap">
{{ part.text }}
@if (part.state === 'streaming') { <span class="cursor">▮</span> }
</div>
}
@case ('reasoning') {
<details>
<summary>Reasoning</summary>
<div style="white-space: pre-wrap; opacity: 80%">{{ part.text }}</div>
</details>
}
@default { <code>{{ part | json }}</code> }
}
}
</div>
}
@if (chat.status === 'submitted') { <div><em>Waiting...</em></div> }
</div>
<form [formGroup]="chatForm" (ngSubmit)="sendMessage()">
<input formControlName="userInput" placeholder="Type your message..." />
@if (chat.status === 'ready') {
<button type="submit" [disabled]="!chatForm.valid">Send</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 type="file" 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)、streamProtocol('data' | '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" placeholder="Enter your prompt..." rows="4"></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 class="error">{{ 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() 随时中断请求。
StructuredObject:Schema 驱动的结构化输出
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" placeholder="Enter content to analyze..." rows="4"></textarea>
<button (click)="analyze()" [disabled]="structuredObject.loading">
{{ structuredObject.loading ? 'Analyzing...' : 'Analyze' }}
</button>
@if (structuredObject.object) {
<div class="result">
<div><strong>Title:</strong> {{ structuredObject.object.title }}</div>
<div><strong>Summary:</strong> {{ structuredObject.object.summary }}</div>
<div><strong>Tags:</strong> {{ structuredObject.object.tags?.join(', ') }}</div>
<div><strong>Sentiment:</strong> {{ structuredObject.object.sentiment }}</div>
</div>
}
@if (structuredObject.error) { <div class="error">{{ 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。响应式属性为 object(DeepPartial<RESULT> | 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 泛型(InferSchema<SCHEMA>)协同的结果。
四、源码剖析:signals 如何支撑响应式状态
三大类都以 Angular signal 作为状态存储,从而获得细粒度的变更检测(change detection),避免整棵组件树不必要的重渲染。
以 chat.ng.ts 中的 AngularChatState 为例:
class AngularChatState<UI_MESSAGE extends UIMessage = UIMessage>
implements ChatState<UI_MESSAGE> {
readonly #messages = signal<UI_MESSAGE[]>([]);
readonly #status = signal<ChatStatus>('ready');
readonly #error = signal<Error | 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: ai@x.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 与 selectedModel):
import {
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: 'text'):
app.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 示例的本地联调方式:在示例目录写入 .env(AI_GATEWAY_API_KEY=your_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.46(add src folders to package bundle)和 2.0.48(excluded tests from src folder in npm package)两条工程化 Patch 一脉相承; - 测试:使用 vitest + jsdom(
vitest.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 源码理解信号驱动的状态实现,即可快速完成从原型到生产的落地。