AI SDK Angular 组件库演进指南:从 1.0 到 3.0 的版本变迁与核心 API 实战

原创2026-09-12 18:31:231,441 阅读
文章标签:人工智能大模型AI 应用AI AgentAgent 框架工具调用LLM 网关前端MCP Clients后端

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() 的消费方必须迁移到 ESM import 语法;
  • 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">&#9646;</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。日常升级时,建议关注三条线索:

  1. 破坏性变更窗口:跨主版本升级时重点核对 ESM 导出、Node 版本(22/24/26)与 zod 的提供方式;
  2. 行为修复类 Patch:如 3.0.79 的"不再深拷贝聊天消息"、3.0.92 的"空响应体错误透出",往往能解释线上偶发问题;
  3. 依赖同步节奏:@ai-sdk/angular 与 ai、@ai-sdk/provider-utils 严格同版发布,升级时三者应保持一致,避免版本错配。

如果你正在 Angular 应用中构建流式对话、单轮补全或 schema 化数据抽取能力,直接从 packages/angular/README.md 的示例起步,再对照 packages/angular/src 源码理解信号驱动的状态实现,即可快速完成从原型到生产的落地。

登录后查看全文
ai