OpenAI 프로바이더

OpenAI 프로바이더

OpenAI 프로바이더는 @ai-sdk/openai 모듈로 제공되며, OpenAI의 Responses·Chat·Completion API 언어 모델과 임베딩 API를 한 번에 지원합니다. 기본 프로바이더 인스턴스 openai를 바로 쓰거나 createOpenAI로 커스터마이징한 인스턴스를 만들 수 있습니다. AI SDK 5부터는 별도 지정이 없으면 기본적으로 Responses API를 호출합니다.

출처: 공식문서

본문

설치

pnpm add @ai-sdk/openai

프로바이더 인스턴스

기본 인스턴스 import:

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

커스텀 설정이 필요하면 createOpenAI로 인스턴스를 생성합니다:

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

const openai = createOpenAI({
  // custom settings, e.g.
  headers: {
    'header-name': 'header-value',
  },
});

인스턴스를 커스터마이징할 수 있는 옵션:

  • baseURL — API 호출 URL 프리픽스(프록시 서버용). 기본값 https://api.openai.com/v1. 기본 모델 팩토리 openai('model-id')는 Responses API를 쓰므로, 커스텀 baseURL이 Chat Completions API만 지원한다면 openai.chat('model-id')를 쓰거나 OpenAI 호환 프로바이더를 사용하세요.
  • apiKey — Authorization 헤더로 전송되는 API 키. 기본값은 OPENAI_API_KEY 환경변수.
  • name — 프로바이더 이름(기본 openai). OpenAI 호환 프로바이더 사용 시 model provider 속성을 바꿀 때 설정.
  • organization — OpenAI Organization.
  • project — OpenAI project.
  • headers — 요청에 포함할 커스텀 헤더.
  • fetch — 커스텀 fetch 구현(기본 전역 fetch). 요청 가로채기 미들웨어나 테스트용으로 사용.

언어 모델

프로바이더 인스턴스는 함수처럼 호출해 언어 모델을 만듭니다:

const model = openai('gpt-5');

모델 ID에 따라 올바른 API가 자동 선택됩니다. 특정 API를 명시하려면 .responses·.chat·.completion을 사용합니다. generateText로 텍스트를 생성하는 예:

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

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

Responses 모델 옵션

openai(modelId) / openai.responses(modelId) 팩토리는 Responses API를 사용합니다(AI SDK 5 이후 기본). 대표적인 providerOptions:

  • parallelToolCalls — 병렬 도구 호출 여부(기본 true).
  • store — 생성 결과 저장 여부(기본 true).
  • maxToolCalls — 빌트인 도구 총 호출 상한.
  • previousResponseId — 대화를 이어가기 위한 이전 응답 ID.
  • instructions — previousResponseId로 대화를 이을 때 system/developer 메시지를 바꾸는 지시.
  • logprobs — 토큰 로그 확률 반환(true 또는 1~20 숫자).
  • user — 남용 감지용 사용자 식별자.
  • reasoningEffort — 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'(기본 medium). 지원 범위는 모델별 상이.
  • reasoningSummary — 'auto' | 'detailed'(추론 과정 요약 반환).
  • serviceTier — 'auto' | 'flex' | 'priority' | 'fast' | 'ultrafast' | 'default'. 'flex'는 저렴·지연 증가, 'priority'/'fast'는 우선 처리.
  • textVerbosity — 'low' | 'medium' | 'high' 응답 장황도(기본 medium).
  • strictJsonSchema — 엄격 JSON 스키마 검증(기본 true). OpenAI 구조화 출력은 선택적 속성을 지원하지 않으므로 Zod의 .nullish()·.optional()을 .nullable()로 바꿔야 합니다.
  • systemMessageMode — 'system' | 'developer' | 'remove'.
  • promptCacheKey / promptCacheOptions — 프롬프트 캐싱 제어.
  • forceReasoning — SDK allowlist에 없는 'stealth' 추론 모델을 추론 모델로 강제 처리.

더 알아보기