본문으로 건너뛰기

인터페이스: ResponseFormat<TData>

정의 위치: packages/ai/src/types.ts:845

구조화된 출력 형식 사양입니다.

모델의 출력이 특정 JSON 구조와 일치하도록 제한합니다. 구조화된 데이터를 추출하거나, 양식을 작성하거나, 일관된 응답 형식을 보장할 때 유용합니다.

참고​

타입 매개변수​

TData​

TData = any

예상 데이터 구조의 TypeScript 타입(타입 안전성을 위해 사용)

속성​

__data?​

optional __data?: TData;

정의 위치: packages/ai/src/types.ts:923

Internal

추론된 데이터 타입을 전달하는 타입 전용 속성입니다.

런타임에는 절대 설정되지 않으며 TypeScript 타입 추론을 위해서만 존재합니다. 응답을 파싱할 때 SDK가 예상할 타입을 알 수 있도록 합니다.

json_schema?​

optional json_schema?: object;

정의 위치: packages/ai/src/types.ts:862

JSON 스키마 사양입니다(type이 "json_schema"일 때 필요).

모델의 출력이 따라야 하는 정확한 구조를 정의합니다. OpenAI의 구조화된 출력은 출력이 이 스키마와 일치하도록 보장합니다.

description?​

optional description?: string;

스키마가 나타내는 내용을 설명하는 선택적 설명입니다.

이 구조화된 출력의 목적을 문서화하는 데 도움이 됩니다.

예시​
"User profile information including name, email, and preferences"

name​

name: string;

스키마의 고유한 이름입니다.

로그와 디버깅에서 스키마를 식별하는 데 사용됩니다. 설명적인 이름이어야 합니다(예: "user_profile", "search_results").

schema​

schema: Record<string, any>;

예상 출력 구조의 JSON Schema 정의입니다.

유효한 JSON Schema여야 합니다(draft 2020-12 또는 호환 형식). 모델의 출력은 이 스키마를 기준으로 검증됩니다.

참고​

https://json-schema.org/

예시​
{
     *   type: "object",
     *   properties: {
     *     name: { type: "string" },
     *     age: { type: "number" },
     *     email: { type: "string", format: "email" }
     *   },
     *   required: ["name", "email"],
     *   additionalProperties: false
     * }

strict?​

optional strict?: boolean;

엄격한 스키마 검증을 적용할지 여부입니다.

true인 경우(권장) 모델이 출력이 스키마와 정확히 일치하도록 보장합니다. false인 경우 모델은 "최선을 다해" 스키마와 일치시킵니다.

기본값: true(지원하는 프로바이더의 경우)

참고​

https://platform.openai.com/docs/guides/structured-outputs#strict-mode

type​

type: "json_object" | "json_schema";

정의 위치: packages/ai/src/types.ts:854

구조화된 출력의 타입입니다.

  • "json_object": 모델이 유효한 JSON을 출력하도록 강제합니다(구조 제한 없음).
  • "json_schema": 제공된 JSON Schema를 기준으로 출력을 검증합니다(엄격한 구조).

참고​

https://platform.openai.com/docs/api-reference/chat/create#chat-create-response_format