Baseten 프로바이더

Baseten을 AI SDK에서 쓸 수 있게 해주는 프로바이더예요. Baseten은 최첨단·엔터프라이즈급 오픈소스 AI 모델을 API로 서빙하는 추론 플랫폼이에요.

출처: 문서

본문

Baseten은 최첨단이면서도 엔터프라이즈급 오픈소스 AI 모델을 API로 서빙하는 추론 플랫폼이에요.

설정 (Setup)

Baseten 프로바이더는 @ai-sdk/baseten 모듈로 제공돼요. 다음과 같이 설치할 수 있어요:

프로바이더 인스턴스 (Provider Instance)

@ai-sdk/baseten에서 기본 프로바이더 인스턴스 baseten을 불러올 수 있어요:

import { baseten } from '@ai-sdk/baseten';

커스터마이즈가 필요하다면 @ai-sdk/baseten에서 createBaseten을 불러와 원하는 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createBaseten } from '@ai-sdk/baseten';

const baseten = createBaseten({
  apiKey: process.env.BASETEN_API_KEY ?? '',
});

Baseten 프로바이더 인스턴스를 커스터마이즈할 때 사용할 수 있는 선택적 설정은 다음과 같아요:

baseURL string

API 호출에 다른 URL 접두사를 사용해요. 예를 들어 프록시 서버를 쓸 때 유용해요. 기본 접두사는 https://inference.baseten.co/v1이에요.
apiKey string

Authorization 헤더로 보내는 API 키예요. 기본값은 BASETEN_API_KEY 환경 변수예요. 매번 필드를 포함하지 않도록 export로 환경 변수를 설정하는 것을 권장해요. Baseten API 키는 여기에서 가져올 수 있어요.
modelURL string

특정 모델(챗 또는 임베딩)을 위한 커스텀 모델 URL이에요. 제공하지 않으면 기본 Model API가 사용돼요.
headers Record<string,string>

요청에 포함할 커스텀 헤더예요.
performanceClient PerformanceClient constructor

임베딩을 위한 Baseten 네이티브 퍼포먼스 클라이언트를 선택해서 클라이언트 측 배칭과 요청 헤징(request hedging)을 사용할 수 있어요. 직접 설치하는 @basetenlabs/performance-client에서 PerformanceClient 생성자를 전달하세요. 생략하면 임베딩은 일반 HTTP를 사용해요. 자세한 내용은 네이티브 퍼포먼스 클라이언트를 참고하세요.
fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

커스텀 fetch 구현이에요.

모델 API (Model APIs)

프로바이더 인스턴스로 Baseten 모델을 선택할 수 있어요. 첫 번째 인자는 모델 id예요. 예를 들어 'moonshotai/Kimi-K2-Instruct-0905'죠. Model API에서 지원하는 전체 모델은 여기에서 확인할 수 있어요.

const model = baseten('moonshotai/Kimi-K2-Instruct-0905');

예시 (Example)

generateText 함수로 Baseten 언어 모델을 사용해 텍스트를 생성할 수 있어요:

import { baseten } from '@ai-sdk/baseten';
import { generateText } from 'ai';

const { text } = await generateText({
  model: baseten('moonshotai/Kimi-K2-Instruct-0905'),
  prompt: 'What is the meaning of life? Answer in one sentence.',
});

Baseten 언어 모델은 streamText 함수에서도 사용할 수 있어요 (AI SDK Core 참고).

전용 모델 (Dedicated Models)

Baseten은 챗과 임베딩 모델 모두에 전용 모델 URL을 지원해요. 프로바이더를 만들 때 modelURL을 지정해야 해요:

OpenAI 호환 엔드포인트 (`/sync/v1`)

Baseten의 OpenAI 호환 엔드포인트로 배포된 모델의 경우:

import { createBaseten } from '@ai-sdk/baseten';

const baseten = createBaseten({
  modelURL: 'https://model-{MODEL_ID}.api.baseten.co/sync/v1',
});
// No modelId is needed because we specified modelURL
const model = baseten();
const { text } = await generateText({
  model: model,
  prompt: 'Say hello from a Baseten chat model!',
});

`/predict` 엔드포인트

/predict 엔드포인트는 현재 챗 모델에서 지원되지 않아요. 챗 기능에는 반드시 /sync/v1 엔드포인트를 사용해야 해요.

임베딩 모델 (Embedding Models)

.embeddingModel() 팩토리 메서드로 Baseten 임베딩 API를 호출하는 모델을 만들 수 있어요. Baseten Embeddings Inference 배포는 OpenAI 호환이라서 임베딩은 기본적으로 추가 의존성 없이 일반 HTTP를 사용해요.

**중요:** 임베딩 모델에는 커스텀 `modelURL`을 가진 전용 배포가 필요해요. 챗 모델과 달리 임베딩은 Baseten의 기본 Model API를 사용할 수 없고 반드시 전용 모델 엔드포인트를 지정해야 해요.

import { createBaseten } from '@ai-sdk/baseten';
import { embed, embedMany } from 'ai';

const baseten = createBaseten({
  modelURL: 'https://model-{MODEL_ID}.api.baseten.co/sync',
});

const embeddingModel = baseten.embeddingModel();

// Single embedding
const { embedding } = await embed({
  model: embeddingModel,
  value: 'sunny day at the beach',
});

// Batch embeddings
const { embeddings } = await embedMany({
  model: embeddingModel,
  values: [
    'sunny day at the beach',
    'rainy afternoon in the city',
    'snowy mountain peak',
  ],
});

각 요청은 최대 128개의 값을 보내요. embedMany는 더 큰 입력을 그 크기의 청크로 나누고 병렬로 실행하므로, 원하는 만큼 많은 값을 전달할 수 있어요.

임베딩 엔드포인트 지원 (Endpoint Support for Embeddings)

지원됨:

/sync 엔드포인트 (/v1/embeddings가 자동으로 추가돼요)
/sync/v1 엔드포인트

지원 안 됨:

/predict 엔드포인트

네이티브 퍼포먼스 클라이언트 (선택) (Native performance client)

Baseten은 또한 @basetenlabs/performance-client를 배포하는데, 이는 배포가 이미 수행하는 서버 측 동적 배칭 위에 클라이언트 측 배칭과 요청 헤징을 추가하는 네이티브 클라이언트예요. 기본적으로는 설치되지 않아요. 네이티브 애드온이라 에지 런타임에서 로드할 수 없고, 번들러도 플랫폼 바이너리를 해석할 수 없어요.

사용하려면 직접 설치하고 생성자를 전달하세요:

npm i @basetenlabs/performance-client

import { createBaseten } from '@ai-sdk/baseten';
import { PerformanceClient } from '@basetenlabs/performance-client';

const baseten = createBaseten({
  modelURL:
    'https://model-{MODEL_ID}.api.baseten.co/environments/production/sync',
  performanceClient: PerformanceClient,
});

선택하면 클라이언트가 배칭을 직접 처리하므로, 값을 128로 나누지 않고 단일 호출로 보내요.

오류 처리 (Error Handling)

Baseten 프로바이더는 일반적인 API 오류에 대한 내장 오류 처리를 포함해요:

import { baseten } from '@ai-sdk/baseten';
import { generateText } from 'ai';

try {
  const { text } = await generateText({
    model: baseten('moonshotai/Kimi-K2-Instruct-0905'),
    prompt: 'Hello, world!',
  });
} catch (error) {
  console.error('Baseten API error:', error.message);
}

일반적인 오류 시나리오 (Common Error Scenarios)

// Embeddings require a modelURL
try {
  baseten.embeddingModel();
} catch (error) {
  // Error: "No model URL provided for embeddings. Please set modelURL option for embeddings."
}

// /predict endpoints are not supported for chat models
try {
  const baseten = createBaseten({
    modelURL:
      'https://model-{MODEL_ID}.api.baseten.co/environments/production/predict',
  });
  baseten(); // This will throw an error
} catch (error) {
  // Error: "Not supported. You must use a /sync/v1 endpoint for chat models."
}

// /sync/v1 endpoints are now supported for embeddings
const baseten = createBaseten({
  modelURL:
    'https://model-{MODEL_ID}.api.baseten.co/environments/production/sync/v1',
});
const embeddingModel = baseten.embeddingModel(); // This works fine!

// /predict endpoints are not supported for embeddings
try {
  const baseten = createBaseten({
    modelURL:
      'https://model-{MODEL_ID}.api.baseten.co/environments/production/predict',
  });
  baseten.embeddingModel(); // This will throw an error
} catch (error) {
  // Error: "Not supported. You must use a /sync or /sync/v1 endpoint for embeddings."
}

// Image models are not supported
try {
  baseten.imageModel('test-model');
} catch (error) {
  // Error: NoSuchModelError for imageModel
}

Baseten 모델과 배포 옵션에 대한 자세한 내용은 [Baseten 문서](https://docs.baseten.co/)를 참고하세요.

더 알아보기 (Learn more)

전체 사이트맵

Baseten 프로바이더