본문으로 건너뛰기

커뮤니티 어댑터 가이드

이 가이드에서는 TanStack AI 생태계를 위한 커뮤니티 어댑터를 만들고 기여하는 방법을 설명합니다.

커뮤니티 어댑터는 외부 서비스, API 또는 사용자 지정 모델 로직을 통합하여 TanStack AI를 확장합니다. 커뮤니티가 작성하고 유지 관리하며 여러 프로젝트에서 재사용할 수 있습니다.

커뮤니티 어댑터란 무엇인가요?​

커뮤니티 어댑터는 TanStack AI를 외부 프로바이더 또는 시스템에 연결하는 재사용 가능한 모듈입니다.

일반적인 사용 사례는 다음과 같습니다:

  • 서드 파티 AI 모델 프로바이더 통합
  • 사용자 지정 추론 또는 라우팅 로직 구현
  • 프로바이더별 도구 또는 기능 노출
  • LLM이 아닌 AI 서비스(예: 이미지, 임베딩, 동영상) 연결

커뮤니티 어댑터는 TanStack AI 핵심 팀이 유지 관리하지 않으며, 여러 프로젝트에서 재사용할 수 있습니다.

커뮤니티 어댑터 만들기​

아래 단계에 따라 구조가 잘 갖춰지고 타입 안전한 어댑터를 빌드합니다.

1. 프로젝트 설정​

먼저 TanStack AI GitHub 저장소의 기존 내부 어댑터 구현을 검토합니다. 이 구현은 예상되는 구조, 규칙 및 통합 패턴을 정의합니다.

완전하고 자세한 참고 자료로는 가장 많은 기능을 제공하는 구현인 OpenAI 어댑터를 사용합니다.

2. 모델 메타데이터 정의​

모델 메타데이터는 각 모델의 기능과 제약 조건을 설명하며, TanStack AI가 호환성 검사와 기능 선택에 사용합니다.

메타데이터에는 최소한 다음을 정의해야 합니다:

  • 모델 이름 및 식별자
  • 지원되는 입력 및 출력 모달리티
  • 지원되는 기능(예: 스트리밍, 도구, 구조화된 출력)
  • 가격 또는 비용 정보(제공되는 경우)
  • 프로바이더별 참고 사항 또는 제한 사항

구체적인 예제는 OpenAI 어댑터의 모델 메타데이터를 참고합니다.

3. 모델 기능 배열 정의​

메타데이터를 정의한 후 내보낸 배열을 사용하여 지원되는 기능별로 모델을 그룹화합니다. 이 배열을 통해 TanStack AI가 특정 작업에 호환되는 모델을 자동으로 선택할 수 있습니다.

예제:

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. 모델 프로바이더 옵션 정의​

각 모델은 구성 가능한 옵션 집합이 서로 다릅니다. 사용자가 유효한 구성 옵션만 볼 수 있도록 이러한 옵션을 모델 이름별로 타입 지정해야 합니다.

예제:

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. 지원되는 입력 모달리티 정의​

모델은 일반적으로 서로 다른 입력 모달리티(예: 텍스트, 이미지, 오디오)를 지원합니다. 잘못된 사용을 방지하려면 모델별로 이를 정의해야 합니다.

예제:

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 모델을 기반으로 함):

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 {
  //...
}

그러면 모델은 자신이 지원하는 기능만 선택할 수 있습니다:

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

단 하나의 올바른 조합이 있는 것은 아니며, 이 구조는 통합하는 프로바이더의 기능을 반영해야 합니다.

7. 어댑터 로직 구현​

마지막으로 어댑터의 런타임 로직을 구현합니다.

여기에는 다음이 포함됩니다:

  • 외부 서비스에 요청 전송
  • 스트리밍 및 비스트리밍 응답 처리
  • 프로바이더 응답을 TanStack AI 타입으로 매핑
  • 모델별 옵션 및 제약 조건 적용

어댑터는 기능별로 구현하므로 프로바이더가 지원하는 항목만 구현합니다:

  • 텍스트 어댑터
  • 채팅 어댑터
  • 이미지 어댑터
  • 임베딩 어댑터
  • 동영상 어댑터

완전한 엔드투엔드 구현 예제는 OpenAI 어댑터를 참고합니다.

8. 게시 및 PR 제출​

어댑터가 완성되면 다음을 수행합니다:

  1. npm 패키지로 게시합니다.
  2. TanStack AI 저장소에 PR을 엽니다.
  3. 문서의 커뮤니티 어댑터 목록에 어댑터를 추가합니다.

9. BYOK 프로바이더 내보내기​

사용자가 어댑터에 API 키를 붙여넣을 수 있다면 defineByokProvider 객체를 /byok 하위 경로(@scope/ai-acme/byok)에서 내보냅니다. 패키지의 기본 진입점에서 다시 내보내면 안 됩니다. 이렇게 하면 프로바이더 SDK가 브라우저로 가져와집니다. id는 x-byok-<id> 슬러그이며 필수입니다. env는 어댑터가 이미 읽는 환경 변수 이름으로 설정합니다. 이름만 포함해야 하며, 이 객체는 클라이언트에서 가져옵니다. 릴레이는 @tanstack/ai/byok/server의 getByokKey(request, acmeByok)를 호출합니다.

import { defineByokProvider } from "@tanstack/ai/byok";

export const acmeByok = defineByokProvider({
  id: "acme",
  label: "Acme",
  env: "ACME_API_KEY",
});

앱은 { acmeByok } from "@scope/ai-acme/byok"를 가져오고 릴레이에서 getByokKey(request, acmeByok)에 전달하여 x-byok-acme 헤더를 읽습니다.

10. 문서 구성 동기화​

어댑터를 추가한 후 TanStack AI 모노레포의 루트에서 pnpm run sync-docs-config를 실행합니다. 이렇게 하면 어댑터가 문서 탐색에 올바르게 표시됩니다. 생성된 변경 사항과 함께 PR을 엽니다.

11. 어댑터 유지 관리​

커뮤니티 어댑터 작성자는 지속적인 유지 관리에 책임이 있습니다.

여기에는 다음이 포함됩니다:

  • 업스트림 프로바이더 API 변경 사항 추적
  • TanStack AI 릴리스와의 호환성 유지
  • 사용자의 이슈 및 피드백 처리
  • 기능이 변경될 때 문서 업데이트

새 기능이나 호환성이 깨지는 변경 사항을 추가하면 문서를 동기화 상태로 유지하기 위해 후속 PR을 엽니다.