TanStack AI – 用于构建生成式 AI 应用的类型安全、与提供商无关的 SDK

它是什么 – 一组 TypeScript 包，可让您编写流式聊天、工具调用代理、结构化输出流程、多模态生成（图像、音频、视频、文档）、实时语音和代码执行代理。核心 SDK 与提供商无关；您可以为 OpenAI、Anthropic、Gemini、Ollama 等添加适配器，并为 React、Vue、Solid、Svelte、Preact 或无头客户端添加框架绑定。

---

核心概念

概念	它为您提供什么
可组合活动	聊天、生成、实时、工具等是独立的“活动”，您仅在需要时导入，从而保持包体积小巧。
与提供商无关的适配器	通过单个 adapter 对象在 OpenAI、Anthropic、Grok、Ollama、Cloudflare Workers AI 等之间切换。
类型安全契约	工具、结构化输出，甚至每个模型的负载都使用 Zod/Valibot/ArkType 或原始 JSON Schema 定义，因此 TypeScript 知道输入和结果的确切形状。
框架原生钩子	useChat、useRealtimeChat、生成钩子以及适用于 React、Vue、Solid、Svelte、Preact 的 UI 组件。
代理技能集成	包可以公开 SKILL.md，编码助手（Claude、Cursor、Copilot…）可以自动安装，将 SDK 转变为 AI 辅助开发的一流技能。

---

快速入门

# 核心 SDK + OpenAI 适配器
pnpm add @tanstack/ai @tanstack/ai-openai

# 对于 React UI（钩子 + UI 组件）
pnpm add @tanstack/ai-react @tanstack/ai-client

服务端流式聊天示例

import { chat, toServerSentEventsResponse } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const stream = chat({
    adapter: openaiText('gpt-5.2'),
    messages,
  })
  return toServerSentEventsResponse(stream)   // 用于浏览器的 SSE
}

相同的 chat 调用可在浏览器、worker 或测试脚本中工作。

---

主要功能

1. 流式聊天和工具调用

• 类型化消息对象（role、content）。
• 内置对工具定义（toolDefinition）的支持，可在服务器或客户端上以相同的类型契约执行。
• 自动工具审批流程和延迟发现，用于动态工具加载。

2. 结构化输出

const Person = z.object({ name: z.string(), age: z.number() })
const result = await chat({
  adapter: openaiText('gpt-5.2'),
  messages: [{ role: 'user', content: '给我一个 Ada Lovelace 的简短传记' }],
  outputSchema: Person,
})
// result 的类型为 { name: string; age: number }

适用于任何模式库或原始 JSON Schema。

3. 多模态生成

• 像 openaiImage、falVideo、geminiSpeech 这样的单行适配器可让您使用相同的 generationClient 模式请求图像、视频、音频、转录、摘要等。

4. 实时语音聊天

适配器公开一个实时会话，该会话铸造令牌并流式传输音频块，从而实现低延迟语音助手。

5. 代码模式

模型可以编写在沙盒 VM 中运行的 TypeScript，允许循环、分支和并行工具调用——对于复杂的编排或数据处理代理很有用。

6. 可观察性和开发工具

• 用于消息、工具调用、使用情况和错误的事件流。
• 用于供应商中立跟踪的 OpenTelemetry 导出器。
• 可选的 UI 开发工具包，用于检查实时流。

---

生态系统和可扩展性

部分	用途
@tanstack/ai-client	无头客户端 – 没有框架绑定的核心逻辑。
@tanstack/ai‑react、‑solid、‑vue、‑svelte、‑preact	相应 UI 库的钩子/组合式函数。
@tanstack/ai‑react/ui（及类似）	用于聊天窗口的现成无头 UI 组件（已弃用，推荐使用自定义 UI）。
提供商适配器（‑openai、‑anthropic、‑gemini、‑ollama、‑groq、…）	将通用 SDK 调用转换为每个供应商的 HTTP API。
@tanstack/ai‑openrouter	单个 API 密钥，可路由到 300 多个模型，并具有每次请求的成本跟踪功能。
@tanstack/ai‑cloudflare	在 Cloudflare Workers 上运行，公开 AI Gateway、嵌入等。

由于每个活动和适配器都是可摇树优化的，您只发送实际使用的代码。

---

谁可能使用这个？

• 全栈开发人员构建聊天机器人、AI 增强 UI 或需要类型安全的内部工具。
• 产品团队希望在提供商之间切换（OpenAI ↔ Anthropic ↔ 本地 Ollama）而无需重写代码。
• LLM 运维工程师寻找统一的可观察性层和 OpenTelemetry 支持。
• 工具构建平台向下游代理公开类型化工具契约。
• 教育或业余项目想要一个现成的、文档完善的 SDK，而不是自己编写 HTTP 包装器。

---

文档和社区

• 完整文档 – https://tanstack.com/ai（概述、快速入门、与 Vercel AI SDK 的比较、高级主题）。
• GitHub 讨论、Discord 和面向贡献者的赞助计划。
• 代理技能 – 一个独特的功能，可让编码助手自动将 SDK 安装为技能，使 TanStack AI 成为开发人员的一流助手。

---

总结

TanStack AI 是一个类型安全、模块化的 TypeScript SDK，用于构建任何类型的生成式 AI 应用程序——聊天、工具调用代理、多模态生成、实时语音或沙盒代码执行。它通过适配器抽象了许多提供商，提供特定于框架的钩子，并强调开发人员体验（模式、可观察性、摇树优化）。非常适合希望获得强 TypeScript 保证同时保持提供商无关的团队。