Vercel AI SDK 是什麼、怎麼用：安裝、generateText、切換模型與智能體入門

本文根據 Vercel AI SDK 官方倉庫的 README 整理，資料核對於 2026-10-11。文中代碼取自官方 README，沒有在本機運行驗證。

適用於誰

• 搜「vercel ai sdk 是什麼」「vercel ai sdk 教學」「vercel ai sdk 中文文檔」的人；
• 用 TypeScript、Next.js 或 Node.js 做應用，想接入大模型又不想被某一家的 SDK 綁住的人；
• 想做聊天介面，在找現成的前端 hook 的人。

結論先說

1. AI SDK 是一個與模型廠商無關的 TypeScript 工具包，用來構建 AI 應用和智能體，可以配合 Next.js、React、Svelte、Vue、Angular 等介面框架，也可以在 Node.js 等運行時裏單獨用。
2. 安裝：npm install ai，需要 Node.js 22 及以上。
3. 換模型只改一處。同一個 generateText，模型可以寫成 '廠商/模型' 這樣的字符串（走 Vercel AI Gateway），也可以裝各家的 provider 包直連。
4. 兩個主要部分：ai 包是核心（生成文本、結構化輸出、工具、智能體）；@ai-sdk/react 等是介面層（useChat 這類 hook）。
5. 智能體用 ToolLoopAgent：給模型一組工具，由它循環調用直到完成任務。

一、安裝

shell
npm install ai

用 pnpm、yarn、bun 的寫對應的安裝命令即可。

二、兩種接模型的方式

方式一：模型字符串，走 Vercel AI Gateway（預設）

README 說明：不做額外設定時，SDK 通過 Vercel AI Gateway 轉發請求，由它提供對主流廠商模型的訪問。寫法是直接給一個 '廠商/模型' 字符串：

ts
import { generateText } from 'ai';

const { text } = await generateText({
  model: 'openai/gpt-6-astra', // use Vercel AI Gateway
  prompt: 'What is an agent?',
});

方式二：安裝 provider 包，直連廠商

shell
npm install @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google

ts
import { anthropic } from '@ai-sdk/anthropic';

const result = await generateText({
  model: anthropic('claude-opus-5-5'), // or openai('gpt-6-astra'), google('gemini-3.8-flash'), etc.
  prompt: 'Hello!',
});

怎麼選：

各家 Key 的獲取見《OpenAI API Key 怎麼獲取》、《Claude API Key》、《Gemini API Key》。密鑰放在環境變量裏，不要寫進前端代碼。

三、生成文本

上面的 generateText 就是最基本的用法：給模型和提示詞，拿回 text。它是一次性返回完整結果的函數，適合後端任務、腳本和不需要逐字顯示的場景。

四、結構化輸出

README 說明 generateText 可以通過 Output.object 返回帶類型的數據，它接收一個 Zod schema，官方的例子是生成一份包含名稱、配料表和步驟的菜譜。

這樣拿到的是可以直接在代碼裏使用的對象，而不是需要自己解析的一段文字。為什麼這比在提示詞裏寫「請輸出 JSON」可靠，見《如何讓大模型穩定輸出 JSON》。

五、智能體：ToolLoopAgent

README 的智能體示例定義了一個帶終端工具的智能體：

ts
import { ToolLoopAgent } from 'ai';

const sandboxAgent = new ToolLoopAgent({
  model: 'openai/gpt-6-astra',
  system: 'You are an agent with access to a shell environment.',
  tools: {
    shell: openai.tools.localShell({
      execute: async ({ action }) => {
        const [cmd, ...args] = action.command;
        const sandbox = await getSandbox(); // Vercel Sandbox
        const command = await sandbox.runCommand({ cmd, args });
        return { output: await command.stdout() };
      },
    }),
  },
});

說明：README 的這段代碼省略了 openai 的導入和 getSandbox 的定義，不能原樣運行，這裏引用它是為了看結構。

三個要素：

• model：用哪個模型；
• system：系統提示詞，說明智能體的角色和邊界；
• tools：一組工具，每個工具有一個 execute 函數。模型決定調用哪個，SDK 負責執行並把結果交回模型，如此循環。

注意示例裏命令是在沙箱中執行的，而不是直接在伺服器上。讓模型執行命令或代碼時，這一層隔離不要省，沙箱是什麼見《E2B 是什麼》。

六、做聊天介面：AI SDK UI

shell
npm install @ai-sdk/react

@ai-sdk/react 裏的 useChat hook 負責管理聊天消息，並把用戶輸入發到你的聊天接口。前端調用這個 hook，後端的路由裏用 ai 包調用模型並流式返回，兩邊由 SDK 約定好的格式對接。核心包裏還導出了 createAgentUIStreamResponse 等與介面對接相關的函數，用法見官方文檔。

README 稱 SDK 可以配合 Svelte、Vue、Angular 等框架使用，各框架對應的包名以官方文檔為準。

七、模組一覽

README 還提到官方提供了按用途、廠商和框架分類的模板，可以直接起步。

常見問題

Q：只做後端、不用 Next.js 能用嗎？

能。ai 包可以在 Node.js 等運行時裏單獨使用，介面包是可選的。

Q：和各家官方 SDK 相比有什麼好處？

統一的接口。同一段業務代碼換個模型字符串或 provider 函數就能切換廠商，流式、工具調用、結構化輸出的寫法也統一。代價是各家最新的專有功能，可能要等 SDK 跟進。

Q：和 OpenAI Agents SDK、Mastra 怎麼選？

語言和側重點不同：AI SDK 是 TypeScript 的基礎工具包；OpenAI Agents SDK 的 Python 版見《OpenAI Agents SDK 教學》；Mastra 是 TypeScript 的智能體框架，見《Mastra 是什麼》。

Q：網上教學的寫法和這裏不一樣？

AI SDK 更新很快，不同大版本之間的接口有變化。以官方倉庫 README 和文檔的當前版本為準，升級時看官方的遷移說明。

參考資料

• vercel/ai（官方倉庫）：https://github.com/vercel/ai
• AI SDK README：https://github.com/vercel/ai/blob/main/packages/ai/README.md