추론 제어

추론 제어 (Reasoning)

많은 LLM은 응답을 내기 전에 내부 '추론(reasoning, 일명 thinking)' 단계를 거칩니다. AI SDK는 generateText/streamText의 최상위 reasoning 파라미터 하나로, provider마다 다른 추론 API를 하나의 이식 가능한 설정으로 통일합니다. 추론 모델을 쓰는 애플리케이션에서 빼놓을 수 없는 제어 지점입니다.

출처: 공식문서

본문

기본 사용법

reasoning 파라미터로 추론 수준을 선택합니다.

import { generateText } from 'ai';
const { text, reasoning, reasoningText } = await generateText({
  model: 'anthropic/claude-sonnet-4.6',
  reasoning: 'medium',
  prompt: 'How many people will live in the world in 2040?',
});

허용 값은 다음과 같습니다.

값 동작
'provider-default' provider 기본 동작 (생략 시 기본)
'none' 추론 비활성
'minimal' 최소한의 추론
'low' 빠르고 간결한 추론
'medium' 균형 잡힌 추론
'high' 충실한(깊은) 추론
'xhigh' 최대 추론

스트리밍

streamText에서도 동일하게 동작합니다. 결과 stream에서 reasoning 파트로 추론 토큰(사고 과정)을, text-delta 파트로 실제 답변 텍스트를 각각 수신합니다.

import { streamText } from 'ai';
const result = streamText({ model: 'google/gemini-3-flash-preview', reasoning: 'high',
  prompt: 'Explain the Riemann hypothesis in simple terms.' });
for await (const part of result.stream) {
  if (part.type === 'reasoning') process.stdout.write(part.textDelta);
  else if (part.type === 'text-delta') process.stdout.write(part.textDelta);
}

우선순위 규칙 — providerOptions가 우선

최상위 reasoning과 provider 전용 providerOptions는 절대 병합되지 않습니다. providerOptions에 추론 관련 옵션(예: openai.reasoningEffort, anthropic.thinking, google.thinkingConfig.thinkingBudget)을 설정하면 그 값이 완전한 우선권을 가지며 최상위 reasoning은 무시됩니다.

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
const { text } = await generateText({
  model: openai.responses('gpt-5.4'),
  reasoning: 'low', // 무시됨 — providerOptions.openai.reasoningEffort가 설정됨
  providerOptions: { openai: { reasoningEffort: 'high' } }, // 이 값이 이김
  prompt: 'Explain quantum entanglement.',
});

이 설계 덕분에 기본은 이식 가능한 최상위 reasoning을 쓰고, 정확한 토큰 예산 같은 provider 전용 기능이 필요할 때만 providerOptions로 내려오면 됩니다.

Provider 지원

reasoning 파라미터는 OpenAI, Anthropic, Google, xAI, Groq, DeepSeek, Fireworks, Amazon Bedrock에서 지원됩니다. 값은 각 provider의 네이티브 추론 API로 번역되며, 일부 provider는 6단계를 모두 지원하지 못해 강제 변환될 때 경고가 발생합니다. 숫자 토큰 예산으로 추론을 제어하는 provider는 최상위 reasoning 값을 모델 최대 출력 토큰의 백분율로 매핑합니다. 추론을 지원하지 않는 provider(Mistral, Perplexity, Cohere 등)는 unsupported 경고를 내고 파라미터를 무시합니다.

providerOptions에서 이전

기존에 providerOptions로 추론을 제어했다면, 이식성을 위해 최상위 reasoning으로 옮길 수 있습니다. 예를 들어 Anthropic은 providerOptions.anthropic.thinking 대신 reasoning: 'high'로, OpenAI는 providerOptions.openai.reasoningEffort 대신 reasoning: 'high'로 바꿉니다. 추론 수준과 무관한 provider 전용 기능(예: OpenAI의 reasoningSummary)은 providerOptions에 그대로 둘 수 있습니다.

더 알아보기