迁移指南

本指南可帮助您从 TanStack AI 的先前版本迁移到最新版本。主要变更集中在改进的 tree-shaking、更清晰的 API 命名和简化的配置上。

变更概述

此版本的主要破坏性变更包括：

适配器函数拆分 - 适配器现在拆分为特定于活动的函数，以实现最佳的 tree-shaking
通用选项扁平化 - 选项现在在配置中扁平化，而不是嵌套
providerOptions 重命名 - 现在命名为 modelOptions，以提高清晰度
toResponseStream 重命名 - 现在命名为 toServerSentEventsStream，以提高清晰度
移除嵌入 (Embeddings) - 移除对嵌入的支持（大多数向量数据库服务都具有内置支持）

1. 适配器函数拆分

适配器已拆分为特定于活动的函数，以实现最佳的 tree-shaking。您现在为每种活动类型导入特定的函数，而不是导入一个整体适配器。

之前

typescript

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

const stream = chat({
  adapter: openai(),
  model: 'gpt-5.2',
  messages: [{ role: 'user', content: 'Hello!' }],
})

之后

typescript

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

const stream = chat({
  adapter: openaiText('gpt-5.2'),
  messages: [{ role: 'user', content: 'Hello!' }],
})

主要变更

模型传递给适配器工厂 - 模型名称现在直接传递给适配器函数（例如，openaiText('gpt-5.2')）
没有单独的 model 参数 - 模型存储在适配器上，因此您无需将其单独传递给 chat()
特定于活动的导入 - 只导入您需要的（例如，openaiText、openaiSummarize、openaiImage）

所有适配器函数

每个提供程序包现在导出特定于活动的函数

OpenAI

typescript

import {
  openaiText,          // Chat/text generation
  openaiSummarize,     // Summarization
  openaiImage,         // Image generation
  openaiSpeech,        // Text-to-speech
  openaiTranscription, // Audio transcription
  openaiVideo,         // Video generation
} from '@tanstack/ai-openai'

Anthropic

typescript

import {
  anthropicText,       // Chat/text generation
  anthropicSummarize,  // Summarization
} from '@tanstack/ai-anthropic'

Gemini

typescript

import {
  geminiText,       // Chat/text generation
  geminiSummarize,  // Summarization
  geminiImage,      // Image generation
  geminiSpeech,     // Text-to-speech (experimental)
} from '@tanstack/ai-gemini'

Ollama

typescript

import {
  ollamaText,       // Chat/text generation
  ollamaSummarize,  // Summarization
} from '@tanstack/ai-ollama'

迁移示例

这是一个完整的适配器用法迁移示例

之前

typescript

import { chat } from '@tanstack/ai'
import { openai } from '@tanstack/ai-openai'
import { anthropic } from '@tanstack/ai-anthropic'

type Provider = 'openai' | 'anthropic'

function getAdapter(provider: Provider) {
  switch (provider) {
    case 'openai':
      return openai()
    case 'anthropic':
      return anthropic()
  }
}

const stream = chat({
  adapter: getAdapter(provider),
  model: provider === 'openai' ? 'gpt-5.2' : 'claude-sonnet-4-5',
  messages,
})

之后

typescript

import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
import { anthropicText } from '@tanstack/ai-anthropic'

type Provider = 'openai' | 'anthropic'

const adapters = {
  openai: () => openaiText('gpt-5.2'),
  anthropic: () => anthropicText('claude-sonnet-4-5'),
}

const stream = chat({
  adapter: adapters[provider](),
  messages,
})

2. 通用选项扁平化

先前嵌套在 options 对象中的通用选项现在直接在配置中扁平化。

之前

typescript

const stream = chat({
  adapter: openai(),
  model: 'gpt-5.2',
  messages,
  options: {
    temperature: 0.7,
    maxTokens: 1000,
    topP: 0.9,
  },
})

之后

typescript

const stream = chat({
  adapter: openaiText('gpt-5.2'),
  messages,
  temperature: 0.7,
  maxTokens: 1000,
  topP: 0.9,
})

可用选项

这些选项现在位于顶层

temperature - 控制随机性（0.0 到 2.0）
topP - 核采样参数
maxTokens - 生成的最大 token 数
metadata - 要附加的额外元数据

3. providerOptions → modelOptions

providerOptions 参数已重命名为 modelOptions，以提高清晰度。此参数包含特定于模型的选项，这些选项因提供程序和模型而异。

之前

typescript

const stream = chat({
  adapter: openai(),
  model: 'gpt-5.2',
  messages,
  providerOptions: {
    // OpenAI-specific options
    responseFormat: { type: 'json_object' },
    logitBias: { '123': 1.0 },
  },
})

之后

typescript

const stream = chat({
  adapter: openaiText('gpt-5.2'),
  messages,
  modelOptions: {
    // OpenAI-specific options
    responseFormat: { type: 'json_object' },
    logitBias: { '123': 1.0 },
  },
})

类型安全

modelOptions 根据您使用的适配器和模型完全类型化

typescript

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

const adapter = openaiText('gpt-5.2')

// TypeScript knows the exact modelOptions type for gpt-5.2
const stream = chat({
  adapter,
  messages,
  modelOptions: {
    // Autocomplete and type checking for gpt-5.2 options
    responseFormat: { type: 'json_object' },
  },
})

4. toResponseStream → toServerSentEventsStream

toResponseStream 函数已重命名为 toServerSentEventsStream，以更好地反映其目的。此外，API 已略有更改。

之前

typescript

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

export async function POST(request: Request) {
  const { messages } = await request.json()
  const abortController = new AbortController()

  const stream = chat({
    adapter: openai(),
    model: 'gpt-5.2',
    messages,
    abortController,
  })

  return toResponseStream(stream, { abortController })
}

之后

typescript

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

export async function POST(request: Request) {
  const { messages } = await request.json()
  const abortController = new AbortController()

  const stream = chat({
    adapter: openaiText('gpt-5.2'),
    messages,
    abortController,
  })

  const readableStream = toServerSentEventsStream(stream, abortController)
  return new Response(readableStream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      Connection: 'keep-alive',
    },
  })
}

主要变更

函数重命名 - toResponseStream → toServerSentEventsStream
返回 ReadableStream - 现在返回 ReadableStream 而不是 Response
手动创建 Response - 您需要使用适当的标头手动创建 Response 对象
AbortController 参数 - 作为单独的参数传递，而不是在选项中

替代方案：HTTP 流格式

如果您需要 HTTP 流格式（以换行符分隔的 JSON）而不是 SSE，请使用 toHttpStream

typescript

import { toHttpStream } from '@tanstack/ai'

const readableStream = toHttpStream(stream, abortController)
return new Response(readableStream, {
  headers: {
    'Content-Type': 'application/x-ndjson',
  },
})

5. 移除嵌入

TanStack AI 移除了对嵌入的支持。大多数向量数据库服务（如 Pinecone、Weaviate、Qdrant 等）都具有内置的嵌入支持，并且大多数应用程序会选择一个嵌入模型并坚持使用它。

之前

typescript

import { embedding } from '@tanstack/ai'
import { openaiEmbed } from '@tanstack/ai-openai'

const result = await embedding({
  adapter: openaiEmbed(),
  model: 'text-embedding-3-small',
  input: 'Hello, world!',
})

之后

使用您的向量数据库服务的内置嵌入支持，或直接调用提供程序的 API

typescript

// Example with OpenAI SDK directly
import OpenAI from 'openai'

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

const result = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'Hello, world!',
})

变更原因？

向量数据库服务处理它 - 大多数向量数据库都具有原生嵌入支持
更简单的 API - 减少 API 表面积和复杂性
直接提供程序访问 - 您可以直接使用提供程序 SDK 进行嵌入
专注范围 - TanStack AI 专注于聊天、工具和代理工作流程

完整的迁移示例

这是一个显示所有变更的完整示例

之前

typescript

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

export async function POST(request: Request) {
  const { messages } = await request.json()
  const abortController = new AbortController()

  const stream = chat({
    adapter: openai(),
    model: 'gpt-5.2',
    messages,
    options: {
      temperature: 0.7,
      maxTokens: 1000,
    },
    providerOptions: {
      responseFormat: { type: 'json_object' },
    },
    abortController,
  })

  return toResponseStream(stream, { abortController })
}

之后

typescript

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

export async function POST(request: Request) {
  const { messages } = await request.json()
  const abortController = new AbortController()

  const stream = chat({
    adapter: openaiText('gpt-5.2'),
    messages,
    temperature: 0.7,
    maxTokens: 1000,
    modelOptions: {
      responseFormat: { type: 'json_object' },
    },
    abortController,
  })

  const readableStream = toServerSentEventsStream(stream, abortController)
  return new Response(readableStream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      Connection: 'keep-alive',
    },
  })
}

这些变更的好处

更好的 Tree-Shaking - 只导入您需要的，从而减小捆绑包大小
更清晰的 API - 函数名称清楚地表明其用途
类型安全 - 特定于模型的选项完全类型化
更简单的配置 - 扁平化的选项更易于使用
专注范围 - 移除了在其他地方更好地处理的功能

需要帮助？

如果在迁移过程中遇到问题

请查看 Tree-Shaking 指南，了解有关新的适配器结构的详细信息
查看 API 参考，了解完整的函数签名
查看示例，了解可用的代码示例