프로바이더 옵션

프로바이더 옵션 (Provider Options)

모든 프로바이더가 공유하는 표준 설정만으로는 부족할 때가 있어요. 프로바이더 옵션은 그런 표준 설정을 넘어서는 프로바이더 고유 설정을 전달하는 방법이에요. generateText나 streamText 같은 함수의 providerOptions 속성으로 설정하죠.

프로바이더 옵션은 프로바이더 이름(예: openai, anthropic)별로 네임스페이스가 나뉘어 있어요. 같은 호출 안에서 여러 프로바이더의 옵션을 함께 넣어도 되고, 실제 활성 프로바이더와 일치하는 옵션만 사용돼요.

출처: 공식문서

본문

const result = await generateText({
  model: openai('gpt-5.2'),
  prompt: 'Explain quantum entanglement.',
  providerOptions: {
    openai: {
      reasoningEffort: 'low',
    },
  },
});

💡 추론 노력을 제어할 때는 프로바이더 특화 옵션 대신 최상위 reasoning 파라미터를 쓰는 걸 고려해보세요. 추론을 지원하는 모든 프로바이더에서 동작하는 이식 가능한 설정이에요. 정확한 토큰 예산 같은 기능이 필요할 때만 프로바이더 특화 옵션을 쓰는 게 좋아요.

OpenAI 옵션

추론 노력(Reasoning Effort) — 추론 모델(예: o3, o4-mini, gpt-5.2)에서 reasoningEffort는 응답 전에 모델이 수행하는 내부 추론량을 제어해요. 값이 낮을수록 빠르고 저렴하고, 높을수록 더 철저한 답변을 내요.

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

const result = await generateText({
  model: openai('gpt-5.2'),
  prompt: 'Invent a new holiday and describe its traditions.',
  providerOptions: {
    openai: {
      reasoningEffort: 'low', // 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});

console.log('Text:', result.text);
console.log('Usage:', result.usage);
console.log(
  'Reasoning tokens:',
  result.finalStep.providerMetadata?.openai?.reasoningTokens,
);

⚠️ 'none'과 'xhigh'는 특정 모델에서만 지원돼요. 지원하지 않는 모델과 함께 쓰면 오류가 발생해요.

추론 요약(Reasoning Summary) — 모델이 어떻게 답에 도달했는지 보려면 reasoningSummary 옵션을 써요. reasoningEffort가 'none'이 아닌 값이면 OpenAI Responses 프로바이더는 reasoningSummary를 기본값 'detailed'로 두고, 요약을 생략하려면 reasoningSummary: null로 설정해요.

스트리밍:

import {
  openai,
  type OpenAILanguageModelResponsesOptions,
} from '@ai-sdk/openai';
import { streamText } from 'ai';

const result = streamText({
  model: openai('gpt-5.2'),
  prompt: 'Tell me about the Mission burrito debate in San Francisco.',
  providerOptions: {
    openai: {
      reasoningSummary: 'detailed', // 'auto' | 'detailed'
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});

for await (const part of result.stream) {
  if (part.type === 'reasoning') {
    console.log(`Reasoning: ${part.textDelta}`);
  } else if (part.type === 'text-delta') {
    process.stdout.write(part.textDelta);
  }
}

텍스트 장황도(Text Verbosity) — 추론과 독립적으로 모델 텍스트 응답의 길이와 상세도를 제어해요.

const result = await generateText({
  model: openai('gpt-5-mini'),
  prompt: 'Write a poem about a boy and his first pet dog.',
  providerOptions: {
    openai: {
      textVerbosity: 'low', // 'low' | 'medium' | 'high'
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});

'low'는 간결하고 최소한의 응답, 'medium'은 균형(기본값), 'high'는 장황하고 포괄적인 응답이에요.

Anthropic 옵션

생각하기(Thinking, 확장 추론) — Anthropic의 thinking 기능은 응답 전에 Claude 모델에게 전용 "생각" 단계를 부여해요. 토큰 예산이 담긴 thinking 객체를 제공하면 활성화돼요.

import { anthropic, AnthropicLanguageModelOptions } from '@ai-sdk/anthropic';
import { generateText } from 'ai';

const { text, reasoning, reasoningText } = await generateText({
  model: anthropic('claude-opus-4-20250514'),
  prompt: 'How many people will live in the world in 2040?',
  providerOptions: {
    anthropic: {
      thinking: { type: 'enabled', budgetTokens: 12000 },
    } satisfies AnthropicLanguageModelOptions,
  },
});

console.log('Reasoning:', reasoningText);
console.log('Answer:', text);

budgetTokens은 모델이 내부 추론에 쓸 수 있는 토큰의 상한이에요. 예산이 높을수록 더 깊이 추론하지만 지연과 비용도 늘어나요. Thinking은 claude-opus-4-20250514, claude-sonnet-4-20250514, claude-sonnet-4-5-20250929 모델에서 지원돼요.

노력(Effort) — 토큰 예산을 지정하지 않고 추론 깊이를 제어하는 더 간단한 방법이에요. 생각하기, 텍스트 응답, 함수 호출에 모두 영향을 줘요.

const { text, usage } = await generateText({
  model: anthropic('claude-opus-4-20250514'),
  prompt: 'How many people will live in the world in 2040?',
  providerOptions: {
    anthropic: {
      effort: 'low', // 'low' | 'medium' | 'high'
    } satisfies AnthropicLanguageModelOptions,
  },
});

'low'는 최소 추론·가장 빠른 응답, 'medium'은 균형, 'high'는 철저한 추론(기본값)이에요.

빠른 모드(Fast Mode) — claude-opus-4-6에서는 speed 옵션으로 출력 토큰 속도를 약 2.5배 빠르게 할 수 있어요.

const { text } = await generateText({
  model: anthropic('claude-opus-4-6'),
  prompt: 'Write a short poem about the sea.',
  providerOptions: {
    anthropic: {
      speed: 'fast', // 'fast' | 'standard'
    } satisfies AnthropicLanguageModelOptions,
  },
});

옵션 조합 (Combining Options)

한 번의 호출에서 여러 프로바이더 옵션을 조합할 수 있어요. OpenAI에서 추론 노력과 추론 요약을 함께 쓰거나, Anthropic에서 thinking을 켜고 effort를 낮게 설정하는 식으로요.

AI Gateway와 함께 쓰기

Vercel AI Gateway를 쓸 때도 프로바이더 옵션은 똑같이 동작해요. 키는 gateway가 아니라 실제 프로바이더 이름(예: openai, anthropic)을 써요. AI Gateway가 이 옵션을 대상 프로바이더에 자동으로 전달해줘요. 라우팅·폴백 같은 게이트웨이 특화 옵션과 프로바이더 특화 옵션을 한 호출에서 함께 쓸 수도 있어요.

타입 안전성 (Type Safety)

각 프로바이더는 자기 옵션용 타입을 export해요. satisfies와 함께 쓰면 자동완성과 빌드 타임 오타 검출을 얻을 수 있어요.

import { type OpenAILanguageModelResponsesOptions } from '@ai-sdk/openai';
import { type AnthropicLanguageModelOptions } from '@ai-sdk/anthropic';

더 알아보기

• Overview
• Providers and Models
• Prompts
• Tools
• Streaming
• Settings