본문으로 건너뛰기

사용자 지정 모델로 어댑터 확장

extendAdapter 유틸리티를 사용하면 기존 어댑터 팩토리(openaiText, anthropicText 등)를 사용자 지정 모델 이름으로 확장하면서 입력 모달리티와 제공자 옵션에 대한 완전한 타입 안전성을 유지할 수 있습니다.

기본 사용법​

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

// Define your custom models using createModel helper
const myOpenaiModel = createModel('my-fine-tuned-gpt4',['text', 'image']);
const myOpenaiModelButCooler = createModel('my-fine-tuned-gpt5',['text', 'image']);
 

// Create an extended adapter factory - simple API, no type parameters needed
const myOpenai = extendAdapter(openaiText, [
  myOpenaiModel,
  myOpenaiModelButCooler 
])

// Use with original models - full type inference preserved
const gpt5Adapter = myOpenai('gpt-5.5')

// Use with custom models - your custom types are applied
const customAdapter = myOpenai('my-fine-tuned-gpt4')

// Works seamlessly with chat()
import { chat } from '@tanstack/ai'

const stream = chat({
  adapter: myOpenai('my-fine-tuned-gpt4'),
  messages: [{ role: 'user', content: 'Hello!' }]
})

createModel 헬퍼​

createModel 함수는 완전한 타입 추론을 지원하면서 사용자 지정 모델을 정의하는 깔끔한 방법을 제공합니다.

import { createModel } from '@tanstack/ai'

// Arguments define name and input modalities
const model = createModel(
  'my-model',      // model name (literal type inferred)
  ['text', 'image'] // input modalities (tuple type inferred)
)

모델 정의 구조​

사용자 지정 모델 정의(ExtendedModelDef)에는 name, input, modelOptions 필수 속성과 features, tools 선택 속성이 있습니다. 두 createModel 오버로드를 사용하면 다음 두 가지 방식으로 이 속성을 채울 수 있습니다.

입력 모달리티 정의​

위치 인수 형식은 모델 이름과 모델이 지원하는 콘텐츠 유형을 지정하는 input 배열을 받습니다.

import { createModel } from '@tanstack/ai'

const models = [
  createModel('text-only-model', ['text']),
  createModel('multimodal-model', ['text', 'image', 'audio']),
] as const

사용 가능한 모달리티: 'text', 'image', 'audio', 'video', 'document'

기능 객체 형식​

타입이 지정된 modelOptions, 선언된 features 또는 제공자 tools를 사용자 지정 모델에 연결하려면 두 번째 인수로 기능 객체를 받는 두 번째 createModel 오버로드를 사용합니다.

import { createModel } from '@tanstack/ai'
import type { OpenAITextProviderOptions } from '@tanstack/ai-openai'

// Type brand for provider options — the value is unused at runtime.
const modelOptions: OpenAITextProviderOptions = {}

const reasoner = createModel('my-reasoner', {
  input: ['text'],
  features: ['reasoning', 'structured_outputs'],
  tools: ['web_search'],
  modelOptions,
})
  • input — 지원되는 입력 모달리티입니다(위치 인수 형식과 동일합니다).
  • features — 선언된 기능 플래그입니다(예: 'reasoning', 'structured_outputs').
  • tools — 선언된 제공자 도구입니다(예: 'web_search').
  • modelOptions — 이 모델이 허용하는 제공자 옵션의 타입 브랜드입니다. 런타임에는 값을 사용하지 않으므로 제공자 옵션 타입으로 지정한 빈 객체를 선언합니다(예: const modelOptions: OpenAITextProviderOptions = {}).

원래 팩토리 동작 유지​

extendAdapter는 구성 매개변수를 포함하여 원래 팩토리의 시그니처를 완전히 유지합니다.

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

const customModels = [createModel('my-fine-tuned-gpt4', ['text', 'image'])] as const

const myOpenai = extendAdapter(openaiText, customModels)

// Config parameter is preserved
const adapter = myOpenai('my-fine-tuned-gpt4', {
  baseURL: 'https://my-proxy.com/v1',
  timeout: 30000
})

타입 안전성​

확장된 어댑터는 완전한 타입 안전성을 제공합니다.

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

const myOpenai = extendAdapter(openaiText, [createModel('custom-model', ['text'])])

// ✅ Original models work with their original types
const a1 = myOpenai('gpt-5.5')

// ✅ Custom models work with your defined types
const a2 = myOpenai('custom-model')

// ❌ Type error: invalid model name
// Note: Type checking works when you assign the result to a variable
const invalid = myOpenai('nonexistent-model') // TypeScript error!

런타임 동작​

런타임에 extendAdapter는 단순히 원래 팩토리로 전달합니다.

  • 사용자 지정 모델 이름의 검증은 수행하지 않습니다.
  • 원래 팩토리는 전달된 값을 정확히 받습니다.
  • 따라서 원래 제공자의 API가 모델 이름을 처리할 수 있습니다.

이 설계는 의도된 것입니다. 이를 통해 다음을 수행할 수 있습니다.

  • 제공자가 허용하지만 TypeScript가 알지 못하는 미세 조정 모델 이름을 사용할 수 있습니다.
  • 사용자 지정 모델 식별자를 허용하는 다른 백엔드로 요청을 프록시할 수 있습니다.
  • 런타임 오버헤드 없이 타입 안전성을 추가할 수 있습니다.

예시: OpenAI 호환 프록시​

일반적인 사용 사례는 OpenAI 호환 프록시에서 사용할 모델의 타입을 지정하는 것입니다.

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

// Models available through your proxy
const proxyModels = [
  createModel(
    'llama-3.1-70b',
    ['text']
  ),
  createModel(
    'mixtral-8x7b',
    ['text']
  ),
] as const

const proxyAdapter = extendAdapter(openaiText, proxyModels)

// Use with your proxy's base URL
const adapter = proxyAdapter('llama-3.1-70b', {
  baseURL: 'https://my-llm-proxy.com/v1'
})

예시: 미세 조정 모델​

미세 조정 모델에 타입 안전성을 추가합니다.

import { chat, createModel, extendAdapter } from '@tanstack/ai'
import { anthropicText } from '@tanstack/ai-anthropic'

const fineTunedModels = [
  createModel(
    'ft:claude-3-opus:my-org:custom-task:abc123',
    ['text', 'image']
  ),
] as const

const myAnthropic = extendAdapter(anthropicText, fineTunedModels)

chat({
  adapter: myAnthropic('ft:claude-3-opus:my-org:custom-task:abc123'),
  messages: [{ role: 'user', content: 'Analyze this...' }]
})