第 1 章 · AI SDK 概览与架构

本章目标：

• 理解生成式 AI（Generative AI）、大语言模型（LLM）与 Embedding 模型三个核心概念
• 掌握 AI SDK 的三大组成部分：AI SDK Core、AI SDK UI、AI SDK RSC
• 学会根据运行环境（Node.js / Next.js / Vue / Svelte）选择合适的库
• 建立「provider 无关」的心智模型，理解本课程统一的 Provider 写法

1.1 AI SDK 是什么

AI SDK 是一套标准化的工具集，用于在所有受支持的 provider之间统一集成 AI 模型。它让开发者专注于构建出色的 AI 应用，而不必浪费时间处理各家 API 的技术细节。

例如，使用 AI SDK 你可以用同样的代码调用不同厂商的模型生成文本：

// 方式一：Vercel AI Gateway（推荐默认）
import { generateText, createGateway } from 'ai';

const gateway = createGateway({
  apiKey: process.env.AI_GATEWAY_API_KEY ?? '',
});

const { text } = await generateText({
  model: gateway('openai/gpt-5'),
  prompt: 'Hello world',
});

console.log(text);

同样适用于自定义 provider——把 gateway(...) 换成自定义 OpenAI 兼容实例即可，其余代码一字不改：

import { generateText } from 'ai';
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';

const myProvider = createOpenAICompatible({
  name: 'my-provider',
  baseURL: process.env.OPENAI_COMPATIBLE_BASE_URL ?? '',
  apiKey: process.env.OPENAI_COMPATIBLE_API_KEY ?? '',
});

const { text } = await generateText({
  model: myProvider('gpt-4o-mini'), // 模型名按你的服务端实际填写
  prompt: 'Hello world',
});

要高效地使用 AI SDK，首先需要熟悉以下核心概念。

1.2 生成式人工智能（Generative AI）

生成式人工智能指基于训练数据中学到的统计规律，预测并生成各类输出（文本、图像或音频等）的模型。例如：

• 给定一张照片，生成式模型可以生成一段说明文字；
• 给定一个音频文件，生成式模型可以生成转录文本；
• 给定一段文字描述，生成式模型可以生成一张图像。

1.3 大语言模型（LLM）

大语言模型（Large Language Model, LLM）是生成式模型的子集，主要聚焦于文本。LLM 以一串词语作为输入，目标是预测接下来最可能出现的序列：它为候选序列分配概率并选出其一，然后持续生成直到满足指定的停止条件。

LLM 通过在海量书面文本上训练来学习，这意味着它们对某些用例更擅长、对另一些则较弱。例如，在 GitHub 数据上训练的模型会特别擅长理解源代码中的序列概率。

但必须清醒认识 LLM 的局限：当被问到冷门或不存在的信息（比如某位亲戚的生日）时，LLM 可能会「幻觉」出信息。因此务必评估你所需的信息在模型中的覆盖程度——这也是后续章节中 tools（工具） 与 RAG 存在的意义。

1.4 Embedding 模型

Embedding 模型用于把复杂数据（如词语或图像）转换成稠密向量（一串数字）表示，即 embedding。与生成式模型不同，embedding 模型不产生新的文本或数据，而是给出实体间语义和句法关系的表示，可作为其他模型或自然语言处理任务的输入。

💡 本课程第 11 章将深入讲解 embedding 与 reranking，实战一（第 20 章）会用它们构建 RAG 语义搜索。

1.5 AI SDK 的三大组成部分

AI SDK 由三个部分组成：

库	用途	环境兼容性
AI SDK Core	用统一 API 调用任意 LLM（如 generateText、streamText）	任意 JS 环境（Node.js、Deno、浏览器等）
AI SDK UI	构建流式聊天与生成式 UI（如 useChat）	React & Next.js、Vue & Nuxt、Svelte & SvelteKit
AI SDK RSC	基于 React Server Components 流式传输生成式 UI（实验性）	支持 RSC 的框架（如 Next.js App Router）

环境兼容矩阵

环境	AI SDK Core	AI SDK UI	AI SDK RSC
无框架 / Node.js / Deno	✅	❌	❌
Vue / Nuxt	✅	✅	❌
Svelte / SvelteKit	✅	✅	❌
Next.js Pages Router	✅	✅	❌
Next.js App Router	✅	✅	✅

何时使用 AI SDK UI

AI SDK UI 提供一组框架无关的 hooks，用于快速构建生产可用的 AI 原生应用：

• 完整支持流式聊天与客户端 generative UI；
• 内置常见 AI 交互模式（chat、completion、assistant）的工具函数；
• 经过生产环境验证的可靠性与性能；
• 跨主流框架兼容。

各框架的函数支持情况如下：

函数	React	Svelte	Vue.js
useChat	✅	✅	✅
useChat tool calling	✅	✅	❌
useCompletion	✅	✅	✅
useObject	✅	❌	❌
MCP Apps	✅	❌	❌

何时使用 AI SDK RSC

⚠️ AI SDK RSC 目前是实验性的，官方推荐生产环境使用 AI SDK UI。RSC 的已知限制包括：

• 取消（Cancellation）：目前无法通过 Server Actions 中断流；
• 数据传输放大：createStreamableUI 可能导致二次方级别的数据传输，可用 createStreamableValue 替代；
• 流式期间的重挂载问题：createStreamableUI 在 .done() 时组件会重新挂载造成闪烁。

1.6 本课程的 Provider 统一写法

本课程所有示例代码遵循「provider 无关」原则，只使用两种 model 构造方式：

// 方式一：Vercel AI Gateway —— 通过 creator/model-id 字符串访问所有模型
import { createGateway } from 'ai';

export const gateway = createGateway({
  apiKey: process.env.AI_GATEWAY_API_KEY ?? '',
});

// 方式二：任意 OpenAI 兼容服务端（自建网关、Ollama、OneAPI 等）
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';

export const myProvider = createOpenAICompatible({
  name: 'my-provider',
  baseURL: process.env.OPENAI_COMPATIBLE_BASE_URL ?? '',
  apiKey: process.env.OPENAI_COMPATIBLE_API_KEY ?? '',
});

两者产出的 model 对象可以互相替换——这正是第 3 章的主题。

本章小结

• AI SDK 在所有受支持 provider 之上提供统一接口，让「换模型只改一行」成为现实；
• 三大核心概念：Generative AI 生成各类输出，LLM 专注文本预测，Embedding 模型输出语义向量；
• AI SDK 分为 Core（任意 JS 环境）、UI（React/Vue/Svelte）、RSC（实验性）三部分，按环境选择；
• 生产应用优先选 AI SDK UI；RSC 存在取消、传输放大与重挂载等限制；
• 本课程统一使用 createGateway（Vercel AI Gateway）或 createOpenAICompatible（自定义 provider）构造 model。

🛠️ 动手实践

1. 用方式一（createGateway + generateText）跑通第一个「Hello world」，再把同一份代码切换为方式二（createOpenAICompatible）指向任意 OpenAI 兼容服务端，验证输出一致。
2. 对照本章的环境兼容矩阵，确认你当前项目所处的行列；如果同时有 Node.js 脚本与前端界面需求，思考 Core 与 UI 应如何分工。
3. 列举三个你熟悉的 LLM「幻觉」场景，思考哪些适合用 tools 解决、哪些适合用 RAG（提示：实时数据 vs 私有知识库）。