Chapter 1 · AI SDK Overview and Architecture

Chapter goals:

• Understand three core concepts of generative AI: Generative AI, Large Language Models (LLM), and Embedding models
• Master the three components of AI SDK: AI SDK Core, AI SDK UI, AI SDK RSC
• Learn to choose the right library based on runtime environment (Node.js / Next.js / Vue / Svelte)
• Build a "provider-agnostic" mental model and understand the unified provider pattern used throughout this course

1.1 What Is AI SDK

AI SDK is a standardized toolkit for uniformly integrating AI models across all supported providers. It lets developers focus on building great AI applications instead of wasting time on the technical details of each vendor API.

For example, with AI SDK you can use the same code to call models from different vendors to generate text:

// Method 1: Vercel AI Gateway (recommended default)
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);

The same applies to custom providers — just swap gateway(...) for a custom OpenAI-compatible instance, with no other changes:

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'), // model name as your server actually provides
  prompt: 'Hello world',
});

To use AI SDK efficiently, you first need to familiarize yourself with the following core concepts.

1.2 Generative AI

Generative AI refers to models that predict and generate various outputs (text, images, audio, etc.) based on statistical patterns learned from training data. For example:

• Given a photo, a generative model can produce a description;
• Given an audio file, a generative model can produce a transcription;
• Given a text description, a generative model can produce an image.

1.3 Large Language Models (LLM)

Large Language Models (LLM) are a subset of generative models, focusing primarily on text. LLMs take a sequence of tokens as input and aim to predict the most likely next sequence: they assign probabilities to candidate sequences and select one, then continue generating until a specified stopping condition is met.

LLMs are trained on massive amounts of written text, meaning they excel at some use cases and are weaker at others. For example, models trained on GitHub data are particularly good at understanding sequence probabilities in source code.

But it is crucial to recognize LLM limitations: when asked about obscure or non-existent information (such as a relative's birthday), LLMs may "hallucinate" information. Therefore you must assess how well the information you need is covered by the model — which is exactly the purpose of tools and RAG covered in later chapters.

1.4 Embedding Models

Embedding models convert complex data (such as words or images) into dense vector representations (a sequence of numbers), i.e., embeddings. Unlike generative models, embedding models do not produce new text or data — they provide representations of semantic and syntactic relationships between entities, which can be used as input for other models or NLP tasks.

💡 Chapter 11 covers embeddings and reranking in depth; Capstone 1 (Chapter 20) uses them to build a RAG semantic search.

1.5 The Three Components of AI SDK

AI SDK consists of three parts:

Library	Purpose	Environment Compatibility
AI SDK Core	Call any LLM with a unified API (e.g. generateText, streamText)	Any JS environment (Node.js, Deno, browser, etc.)
AI SDK UI	Build streaming chat and generative UI (e.g. useChat)	React & Next.js, Vue & Nuxt, Svelte & SvelteKit
AI SDK RSC	Stream generative UI based on React Server Components (experimental)	Frameworks supporting RSC (e.g. Next.js App Router)

Environment Compatibility Matrix

Environment	AI SDK Core	AI SDK UI	AI SDK RSC
No framework / Node.js / Deno	✅	❌	❌
Vue / Nuxt	✅	✅	❌
Svelte / SvelteKit	✅	✅	❌
Next.js Pages Router	✅	✅	❌
Next.js App Router	✅	✅	✅

When to Use AI SDK UI

AI SDK UI provides a set of framework-agnostic hooks for rapidly building production-ready AI-native applications:

• Full support for streaming chat and client-side generative UI;
• Built-in utility functions for common AI interaction patterns (chat, completion, assistant);
• Production-validated reliability and performance;
• Cross-framework compatibility.

Per-framework function support:

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

When to Use AI SDK RSC

⚠️ AI SDK RSC is currently experimental; the official recommendation for production is AI SDK UI. Known RSC limitations include:

• Cancellation: currently cannot interrupt streams via Server Actions;
• Data transmission amplification: createStreamableUI can cause quadratic-level data transfer; use createStreamableValue as a替代;
• Re-mount issues during streaming: createStreamableUI re-mounts components at .done() causing flicker.

1.6 Unified Provider Pattern for This Course

All example code in this course follows the "provider-agnostic" principle, using only two model construction methods:

// Method 1: Vercel AI Gateway — access all models via creator/model-id string
import { createGateway } from 'ai';

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

// Method 2: Any OpenAI-compatible server (self-hosted gateway, Ollama, OneAPI, etc.)
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 ?? '',
});

Both approaches produce interchangeable model objects — this is the theme of Chapter 3.

1.7 Chapter Summary

• AI SDK provides a unified interface above all supported providers, making "switch models with one line" a reality;
• Three core concepts: Generative AI generates various outputs, LLMs focus on text prediction, Embedding models output semantic vectors;
• AI SDK is divided into Core (any JS environment), UI (React/Vue/Svelte), and RSC (experimental); choose based on environment;
• Prefer AI SDK UI for production apps; RSC has cancellation, amplification, and re-mount limitations;
• This course uniformly uses createGateway (Vercel AI Gateway) or createOpenAICompatible (custom provider) to construct models.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Which of the following is NOT one of the three components of AI SDK?

2. In a framework-less pure Node.js environment, which parts of AI SDK can you use?

3. Regarding Embedding models, which statement is correct?

4. Why does the official documentation recommend AI SDK UI over AI SDK RSC for production?

🛠️ Hands-On Exercises

1. Run the first "Hello world" with Method 1 (createGateway + generateText), then switch the same code to Method 2 (createOpenAICompatible) pointing to any OpenAI-compatible server, and verify consistent output. 2.对照 the environment compatibility matrix in this chapter, confirm your current project's row and column; if you need both a Node.js script and a frontend interface, think about how Core and UI should be divided.
2. List three LLM "hallucination" scenarios you are familiar with, and思考 which are suitable for tools vs. RAG (hint: real-time data vs. private knowledge base).

Next: Chapter 2 · Quick Start: Environment Setup and First Generation