社区适配器指南

本指南解释了如何创建和贡献 TanStack AI 生态系统的社区适配器。

社区适配器通过集成外部服务、API 或自定义模型逻辑来扩展 TanStack AI。它们由社区编写和维护，并且可以在不同的项目中重用。

什么是社区适配器？

社区适配器是一个可重用的模块，用于将 TanStack AI 连接到外部提供商或系统。

常见的用例包括

集成第三方 AI 模型提供商
实现自定义推理或路由逻辑
暴露提供商特定的工具或功能
连接到非 LLM AI 服务（例如图像、嵌入、视频）

社区适配器不由核心 TanStack AI 团队维护，并且可以在不同的项目中重用。

创建社区适配器

请按照以下步骤构建结构良好、类型安全的适配器。

1. 设置你的项目

首先，请查看 TanStack AI GitHub 仓库中现有的内部适配器实现。这些定义了预期的结构、约定和集成模式。

为了获得完整、详细的参考，请使用 OpenAI 适配器，它是功能最全面的实现。

2. 定义模型元数据

模型元数据描述了每个模型的功能和限制，并由 TanStack AI 用于兼容性检查和功能选择。

你的元数据至少应定义

模型名称和标识符
支持的输入和输出模态
支持的功能（例如流式传输、工具、结构化输出）
定价或成本信息（如果可用）
任何提供商特定的说明或限制

请参阅 OpenAI 适配器的模型元数据，以获取具体的示例。

3. 定义模型能力数组

定义元数据后，使用导出的数组按支持的功能对模型进行分组。这些数组允许 TanStack AI 自动为给定任务选择兼容的模型。

示例

typescript

export const OPENAI_CHAT_MODELS = [
  // Frontier models
  GPT5_2.name,
  GPT5_2_PRO.name,
  GPT5_2_CHAT.name,
  GPT5_1.name,
  GPT5_1_CODEX.name,
  GPT5.name,
  GPT5_MINI.name,
  GPT5_NANO.name,
  GPT5_PRO.name,
  GPT5_CODEX.name,
  // ...other models
] as const
export const OPENAI_IMAGE_MODELS = [
  GPT_IMAGE_1.name,
  GPT_IMAGE_1_MINI.name,
  DALL_E_3.name,
  DALL_E_2.name,
] as const

export const OPENAI_VIDEO_MODELS = [SORA2.name, SORA2_PRO.name] as const

每个数组应仅包含完全支持相关功能的模型。

4. 定义模型提供商选项

每个模型暴露一组不同的可配置选项。这些选项必须按模型名称进行类型化，以便用户仅看到有效的配置选项。

示例

typescript

export type OpenAIChatModelProviderOptionsByName = {
  [GPT5_2.name]: OpenAIBaseOptions &
    OpenAIReasoningOptions &
    OpenAIStructuredOutputOptions &
    OpenAIToolsOptions &
    OpenAIStreamingOptions &
    OpenAIMetadataOptions
  [GPT5_2_CHAT.name]: OpenAIBaseOptions &
    OpenAIReasoningOptions &
    OpenAIStructuredOutputOptions &
    OpenAIToolsOptions &
    OpenAIStreamingOptions &
    OpenAIMetadataOptions
  // ... repeat for each model
}

这确保了编译时严格的类型安全性和功能正确性。

5. 定义支持的输入模态

模型通常支持不同的输入模态（例如文本、图像、音频）。这些必须按模型定义，以防止无效的使用。

示例

typescript

export type OpenAIModelInputModalitiesByName = {
  [GPT5_2.name]: typeof GPT5_2.supports.input
  [GPT5_2_PRO.name]: typeof GPT5_2_PRO.supports.input
  [GPT5_2_CHAT.name]: typeof GPT5_2_CHAT.supports.input
  //  ... repeat for each model
}

6. 定义模型选项片段

模型选项应由可重用的片段组成，而不是在每个模型中重复。

一种常见的模式是

所有模型共享的基本选项
按模型拼接的功能片段

示例（基于 OpenAI 模型）

typescript

export interface OpenAIBaseOptions {
  // base options that every chat model supports
}

// Feature fragments that can be stitched per-model 

/**
 * Reasoning options for models  
 */
export interface OpenAIReasoningOptions {
   //...
}
 
/**
 * Structured output options for models.
 */
export interface OpenAIStructuredOutputOptions {
  //...
}

模型可以只选择它们支持的功能

typescript

export type OpenAIChatModelProviderOptionsByName = {
  [GPT5_2.name]: OpenAIBaseOptions &
    OpenAIReasoningOptions &
    OpenAIStructuredOutputOptions &
    OpenAIToolsOptions &
    OpenAIStreamingOptions &
    OpenAIMetadataOptions
}

没有唯一的正确组合；此结构应反映你集成的提供商的功能。

7. 实现适配器逻辑

最后，实现适配器的运行时逻辑。

这包括

将请求发送到外部服务
处理流式传输和非流式传输响应
将提供商响应映射到 TanStack AI 类型
强制执行模型特定的选项和约束

适配器是按功能实现的，因此仅实现你的提供商支持的内容

文本适配器
聊天适配器
图像适配器
嵌入适配器
视频适配器

请参阅 OpenAI 适配器，以获取完整的端到端实现示例。

8. 发布并提交 PR

完成适配器后

将其发布为 npm 包
向 TanStack AI 仓库打开 PR
将你的适配器添加到文档中的社区适配器列表

9. 同步文档配置

添加适配器后，在 TanStack AI monorepo 的根目录中运行 pnpm run sync-docs-config。这将确保你的适配器在文档导航中正确显示。提交包含生成的更改的 PR。

10. 维护你的适配器

作为社区适配器作者，你负责持续维护。

这包括

跟踪上游提供商 API 的更改
保持与 TanStack AI 版本的兼容性
解决用户的问题和反馈
当功能发生变化时更新文档

如果你添加了新功能或破坏性更改，请打开后续 PR 以保持文档同步。