설정(Settings): 생성 옵션과 요청 옵션

설정(Settings): 생성 옵션과 요청 옵션

많은 LLM이 출력을 다듬기 위한 설정을 제공해요. AI SDK 함수는 여기에 더해 모델 생성 동작을 조절하는 옵션과 전송·재시도·타임아웃을 조절하는 옵션을 구분해서 지원해요. 이 둘을 구분하면 "모델이 뭘 생성할지"와 "SDK가 프로바이더와 어떻게 통신할지"를 각각 제어할 수 있어요.

출처: 공식문서

본문

모든 AI SDK 함수는 모델·프롬프트·프로바이더별 설정 외에 다음 공통 설정을 지원해요.

const result = await generateText({
  model: "xai/grok-4.6",
  maxOutputTokens: 512,
  temperature: 0.3,
  maxRetries: 5,
  timeout: 10000,
  prompt: 'Invent a new holiday and describe its traditions.',
});

일부 프로바이더는 공통 설정 전체를 지원하지 않아요. 지원하지 않는 설정을 쓰면 경고가 생성되고, 결과 객체의 warnings 프로퍼티로 확인할 수 있어요.

언어 모델 호출 옵션 (LanguageModelCallOptions)

이런 옵션은 모델이 응답을 어떻게 생성할지(토큰 제한, 샘플링, 페널티, 정지 시퀀스, 시드, 리저닝)를 정하며, 내부 모델로 그대로 전달돼요.

  • maxOutputTokens — 생성할 최대 토큰 수
  • temperature — 온도 설정. 0에 가까울수록 거의 결정적이고, 값이 클수록 무작위성이 커져요. 대부분의 프로바이더에서 그런 범위예요. temperature와 topP는 둘 다 정하지 말고 하나만 정하는 걸 권장해요. AI SDK 5.0부터는 temperature가 기본 0이 아니에요.
  • topP — 핵 샘플링. 0과 1 사이 값으로, 예컨대 0.1이면 상위 10% 확률 질량의 토큰만 고려해요. 역시 temperature와 하나만 쓰는 걸 권장해요.
  • topK — 다음 토큰마다 상위 K개 옵션에서만 샘플링해요. "긴 꼬리" 저확률 응답을 제거하는 데 쓰되, 보통은 temperature만으로 충분하니 고급 사용 사례에 한해 쓰는 게 좋아요.
  • presencePenalty — 프롬프트에 이미 있는 정보를 모델이 반복할 가능성에 영향을 줘요. 프로바이더에 그대로 전달되고, 대부분 0이면 페널티 없음이에요.
  • frequencyPenalty — 모델이 같은 단어·구를 반복해서 쓸 가능성에 영향을 줘요. 마찬가지로 프로바이더에 전달되고 0이면 페널티 없음이에요.
  • stopSequences — 텍스트 생성을 멈추는 정지 시퀀스. 정지 시퀀스 중 하나가 생성되면 모델이 생성을 멈춰요. 프로바이더마다 개수 제한이 있을 수 있어요.
  • seed — 무작위 샘플링에 쓸 시드(정수). 설정되고 모델이 지원하면 결정적 결과가 나와요.
  • reasoning — 응답 전에 모델이 얼마나 리저닝할지 제어해요. 'provider-default'(기본), 'none', 'minimal', 'low', 'medium', 'high', 'xhigh' 값을 써요. providerOptions에 리저닝 관련 옵션을 함께 주면(예: openai.reasoningEffort, anthropic.thinking) 프로바이더별 옵션이 우선하고 최상위 reasoning은 무시돼요.

요청 옵션 (RequestOptions)

이런 옵션은 전송·재시도·취소·타임아웃에 영향을 주는 것으로, 모델 생성 동작을 바꾸지 않아요. SDK가 프로바이더 API와 어떻게 통신할지 제어하죠.

  • maxRetries — 최대 재시도 횟수. 0으로 설정하면 재시도를 끄고, 기본값은 2예요.
  • abortSignal — 호출을 취소하는 데 쓰는 abort 신호. UI에서 전달해 호출을 취소하거나 AbortSignal.timeout(5000)으로 타임아웃을 정할 수 있어요.
  • timeout — 밀리초 단위 타임아웃. 지정한 시간보다 오래 걸리면 호출이 중단돼요. 내부적으로 abort 신호를 만드는 편의 파라미터이며 abortSignal과 함께 쓸 수 있어요. 숫자(밀리초) 또는 객체로 지정할 수 있어요.

타임아웃 객체의 프로퍼티는 다음과 같아요.

  • totalMs — 모든 스텝을 포함한 전체 호출의 총 타임아웃
  • stepMs — 개별 스텝(LLM 호출)의 타임아웃. 멀티 스텝 생성에서 각 스텝 시간을 따로 제한하고 싶을 때 유용해요.
  • firstChunkMs — 각 스텝의 첫 콘텐츠 출력까지의 타임아웃(스트리밍 전용). 텍스트 델타·리저닝 델타·도구 입력 델타·생성 파일·도구 호출이 이 조건을 충족해요. 응답 메타데이터나 스트림 시작, 빈 델타, 원시 청크, 전송 활동은 충족시키지도, 초기화하지도 않아요.
  • chunkMs — 출력이 시작된 뒤 콘텐츠 청크 사이의 타임아웃(스트리밍 전용). 콘텐츠가 아닌 청크는 초기화하지 않아요. 생성이 시작된 뒤 스트림이 멈추는 것을 감지하는 데 유용해요.
  • toolMs — 모든 도구 실행의 기본 타임아웃. 도구가 오래 걸리면 중단되고 tool-error를 반환해 모델이 응답하거나 재시도할 수 있게 해요.
  • tools — {toolName}Ms 키(예: weatherMs, slowApiMs)로 도구별 타임아웃 오버라이드. toolMs보다 우선하고, 도구 이름은 자동완성을 위해 타입 검사돼요.
// 5초 전체 타임아웃 (객체 형식)
const result = await generateText({
  model: "xai/grok-4.6",
  prompt: 'Invent a new holiday and describe its traditions.',
  timeout: { totalMs: 5000 },
});

// 스텝별 10초 타임아웃
const result = await generateText({
  model: "xai/grok-4.6",
  prompt: 'Invent a new holiday and describe its traditions.',
  timeout: { stepMs: 10000 },
});

// 스트리밍 전용: 콘텐츠가 5초 멈추면 중단
const result = streamText({
  model: "xai/grok-4.6",
  prompt: 'Invent a new holiday and describe its traditions.',
  timeout: { chunkMs: 5000 },
});

// 도구 실행 타임아웃: 기본 5초, weather는 3초, slowApi는 10초
const result = await generateText({
  model: "xai/grok-4.6",
  tools: { weather: weatherTool, slowApi: slowApiTool },
  timeout: {
    toolMs: 5000,
    tools: {
      weatherMs: 3000,
      slowApiMs: 10000,
    },
  },
  prompt: 'What is the weather in San Francisco?',
});
  • headers — 요청과 함께 보낼 추가 HTTP 헤더. HTTP 기반 프로바이더에만 적용돼요. 예컨대 일부 관찰성 프로바이더는 Prompt-Id 같은 헤더를 지원해요. headers는 요청별 헤더이고, 프로바이더 설정에도 헤더를 둘 수 있는데 그건 해당 프로바이더가 만드는 모든 요청에 보내져요.

더 알아보기