垦荒学园
  • 中文

      • AI SDK 简介

      AI SDK 是什么？

      Vercel AI SDK 是面向 TypeScript 的工具包，用来在 React、Next.js、Vue、Svelte、Node.js 等环境里接入大模型。官方定位不是「又一个 Python Agent 框架」，而是：统一模型调用 + 流式协议 + 前端 hooks，让你把时间花在产品上，而不是各家 HTTP 细节。

      文档入口：sdk.vercel.ai/docs（与 ai-sdk.dev 为同一套文档）。本教程跟踪 AI SDK 7.x。

      为什么需要它？

      直接调 OpenAI / Anthropic / xAI 时，请求体、流式 chunk、工具调用形状都不一样。AI SDK 用 Language Model 规范 把差异收掉：同一套 generateText / streamText，换模型时尽量只改 model 参数。

      7.x 的默认全局 Provider 是 Vercel AI Gateway：你可以写 "openai/gpt-4.1-mini" 或 "xai/grok-4.6" 这种 provider/model 字符串，不必先 import 厂商包。官方 Quickstart 当前示例常用 xai/grok-4.6；模型 ID 会变，本教程用看起来更稳的 Gateway 字符串 openai/gpt-4.1-mini，你按账号里实际可用的 ID 替换即可。

      三大 Surface

      ┌─────────────────────────────────────────────────────────────┐
│                      AI SDK 7.x                              │
└─────────────────────────────────────────────────────────────┘
   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
   │  Core        │   │  UI          │   │  Harnesses   │
   │  generateText│   │  useChat     │   │  HarnessAgent│
   │  streamText  │   │  useObject   │   │  Claude/Codex│
   └──────────────┘   └──────────────┘   └──────────────┘
         ▲                    ▲                    │
         └──── 同一套 stream / UIMessage 原语 ──────┘
      Surface职责典型 API
      AI SDK Core模型调用、工具、结构化输出、Agent 循环generateText、streamText、tool()、Output.object()
      AI SDK UI框架无关的聊天 / 生成式 UI hooksuseChat、useCompletion、useObject
      AI SDK Harnesses跑现成的编码 Agent harnessHarnessAgent + @ai-sdk/harness-claude-code 等

      HarnessAgent（简介）： 它实现 AI SDK 的 Agent 接口，背后接 Claude Code、Codex、Pi 等 harness。会话状态在 harness 里，不要像普通聊天那样把完整 messages 重放进去；HTTP 路由应持久化 / 恢复 HarnessAgentSession。本教程后文以 Core + UI 为主；需要编码 Agent 时再读官方 HarnessAgent。

      另外还有 AI SDK RSC（@ai-sdk/rsc）：用 streamUI 从服务端流 React 组件。官方明确标注 experimental，生产推荐迁到 AI SDK UI。见 RSC 与 streamUI。

      Core 里最常用的两个函数

      函数何时用
      generateText无 UI、批处理、摘要、脚本、服务端一次性生成
      streamText聊天、需要尽快把 token 推到浏览器

      二者都支持 messages、instructions（系统提示）、tools、output（结构化）。流式结果通过 result.stream 交给 toUIMessageStream + createUIMessageStreamResponse，供 useChat 消费。

      与 LangChain 怎么选

      维度AI SDKLangChain
      语言TypeScript 优先Python（也有 JS）优先
      强项Next.js 流式 UI、统一 Provider、前端 hooksAgent / 图编排 / RAG 生态
      默认聊天useChat + UIMessage partscreate_agent + messages
      本地模型OpenAI 兼容 baseURL 或社区 Ollama Providerlangchain-ollama 等

      选型： 你在做 Next.js / React 产品、要流式聊天和工具 → 用本教程。你在做 Python 后端 Agent、复杂图与评测 → 看 LangChain。二者可以并存：Python 负责检索，Next.js 用 AI SDK 负责对话层。

      适合与不适合

      适合：

      • App Router 聊天机器人、带工具的助手
      • 同一套代码切换 Gateway / OpenAI / Anthropic
      • 把流式 token 接到现有 React 布局

      需谨慎：

      • 只要一次 HTTP 调用、无流、无 UI → 直接调厂商 SDK 也够
      • 把密钥放进浏览器 → 禁止；Key 只放 Route Handler / Server Action
      • 把 RSC streamUI 当生产默认 → 仍是实验 API

      7.x 阅读约定

      • Node 22+，ESM（"type": "module" 或 .mjs），不要 require('ai')
      • 聊天消息用 UIMessage + parts，不要依赖旧的 content 字符串
      • 系统提示字段是 instructions（不要照抄旧教程的 system）
      • 默认不要用已删除的 toDataStreamResponse；用 createUIMessageStreamResponse + toUIMessageStream

      下一步

      评论