OpenAI 호환 프로바이더

OpenAI 호환 프로바이더

OpenAI 호환 프로바이더(@ai-sdk/openai-compatible)를 사용하면 OpenAI API를 구현한 언어 모델 프로바이더(LM Studio, NIM, Heroku, Clarifai, NEAR AI Cloud 등)를 손쉽게 연결할 수 있습니다. createOpenAICompatible로 프로바이더 인스턴스를 만들거나, 이 패키지를 기반으로 자체 프로바이더 패키지를 작성할 수도 있습니다. 모든 호환 프로바이더의 기본 설정과 인스턴스 생성 방식은 동일합니다.

출처: 공식문서

본문

설치

pnpm add @ai-sdk/openai-compatible

프로바이더 인스턴스

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';

const provider = createOpenAICompatible({
  name: 'providerName',
  apiKey: process.env.PROVIDER_API_KEY,
  baseURL: 'https://api.provider.com/v1',
  includeUsage: true, // Include usage information in streaming responses
});

인스턴스 커스터마이징 옵션:

  • baseURL — API 호출 URL 프리픽스.
  • apiKey — 인증용 API 키. 지정하면 Authorization: Bearer <apiKey> 헤더를 추가(헤더 옵션보다 먼저 추가).
  • headers — 커스텀 헤더.
  • queryParams — 요청 URL에 추가할 커스텀 쿼리 파라미터(예: Azure AI Model Inference는 api-version 필요).
  • fetch — 커스텀 fetch 구현.
  • includeUsage — 스트리밍 응답에 usage 정보 포함(기본 undefined/false).
  • supportsStructuredOutputs — 구조화 출력 지원 여부.
  • supportedUrls — 미디어 타입별로 채팅 모델이 직접 접근 가능한 URL 맵.
  • transformRequestBody — API로 전송 전 요청 본문 변환 함수(프록시 프로바이더용).
  • metadataExtractor — API 응답에서 프로바이더별 메타데이터 추출.

언어 모델

const model = provider('model-id');

팩토리 메서드: provider.languageModel('model-id')(chat 모델, provider('model-id')와 동일), provider.chatModel('model-id').

지원 능력: 텍스트 생성, 스트리밍, 도구 호출(스트리밍 지원), 구조화 출력(supportsStructuredOutputs 활성 시), reasoning 콘텐츠(DeepSeek R1 등), 시스템 메시지, 멀티모달 입력.

이미지·임베딩·컴플리션 모델

  • .imageModel('model-id') — 이미지 생성. providerOptions로 size·quality·output_format·output_compression·background 등을 설정. /images/edits 엔드포인트로 이미지 편집·마스크 인페인팅 지원.
  • .embeddingModel('model-id') — 임베딩. providerOptions에 dimensions·user.
  • .completionModel('model-id') — (채팅이 아닌) 텍스트 컴플리션. providerOptions에 echo·logitBias·suffix·user.

채팅 모델 옵션

  • user — 남용 감지용 사용자 식별자.
  • reasoningEffort — reasoning 모델용 노력값(프로바이더별 상이).
  • textVerbosity — 생성 텍스트의 장황도 제어.
  • strictJsonSchema — 엄격 JSON 스키마 검증 여부(strict decoding, 기본 true).

프로바이더 전용 옵션

프로바이더 이름을 name으로 지정했을 때, providerOptions[providerName]으로 요청 본문에 임의 커스텀 필드를 추가할 수 있습니다. 키는 camelCase(providerOptions.providerName)입니다.

커스텀 메타데이터 추출

metadataExtractor로 표준 응답 외 프로바이더별 필드를 캡처할 수 있습니다. extractMetadata(비스트리밍 전체 응답)와 createStreamExtractor(스트리밍 청크 누적) 두 구성요소로 이루어지며, 반환값은 providerMetadata 필드로 노출됩니다.

더 알아보기