For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
기본 탐색 메뉴
Theme

추천

모델 선택하기

텍스트 및 코드

프롬프트 작성

추론

이미지

실시간 처리 및 오디오

특화 모델

API 대시보드
ChatGPT 사용해 보기

구조화된 모델 출력값

모델의 텍스트 응답이 직접 정의한 JSON 스키마를 따르도록 하세요.

JSON은 애플리케이션 간에 데이터를 교환할 때 전 세계적으로 가장 널리 쓰이는 형식 중 하나입니다.

구조화된 출력값은 모델이 항상 지정한 JSON 스키마에 맞춰 응답을 생성하도록 하는 기능입니다. 모델이 필수 키를 누락하거나 열거형에 정의되지 않은 값을 지어낼 걱정을 할 필요가 없습니다.

구조화된 출력값을 사용하면 다음과 같은 이점이 있습니다.

  1. 타입 안전성 보장: 응답 형식을 별도로 검증하거나 잘못된 형식 때문에 요청을 다시 보낼 필요가 없습니다.
  2. 명시적인 거부 응답: 모델이 안전상의 이유로 요청을 거부했는지 코드에서 확인할 수 있습니다.
  3. 간단한 프롬프트: 일관된 응답 형식을 얻기 위해 프롬프트에서 형식을 거듭 강조할 필요가 없습니다.

OpenAI의 REST API는 JSON 스키마를 지원합니다. Python과 JavaScript용 OpenAI 라이브러리에서는 각각 pydantic.BaseModel과 z.object로 객체 스키마를 정의할 수도 있습니다. 아래 예제에서는 비정형 텍스트에서 정보를 추출해 코드로 정의한 스키마에 맞춰 반환하는 방법을 보여 줍니다.

Ruby SDK는 Sorbet의 T::Struct로 정의한 스키마를 지원하며, 파싱한 결과를 해당 타입으로 반환합니다.

구조화된 응답 받기
from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()


class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]


response = client.responses.parse(
    model="gpt-6-astra",
    input=[
        {"role": "system", "content": "Extract the event information."},
        {
            "role": "user",
            "content": "Alice and Bob are going to a science fair on Friday.",
        },
    ],
    text_format=CalendarEvent,
)

event = response.output_parsed

지원 모델

GPT-4o부터 OpenAI의 최신 대규모 언어 모델에서 구조화된 출력값을 사용할 수 있습니다. 새 프로젝트에서는 gpt-6-astra로 시작하세요. gpt-4-turbo와 그 이전 모델에서는 대신 JSON 모드를 사용할 수 있습니다.

구조화된 출력값의 용도별 선택 기준: 함수 호출과 text.format

OpenAI API에서 구조화된 출력값을 사용하는 방법은 두 가지입니다.

  1. 모델의 함수 호출 사용
  2. 응답 형식으로 json_schema 사용

함수 호출은 모델을 애플리케이션의 기능과 연결할 때 유용합니다.

예를 들어 모델이 데이터베이스를 조회하는 함수를 호출하도록 하면 사용자의 주문 관련 문의를 처리하는 AI 어시스턴트를 만들 수 있습니다. 모델에 UI와 상호작용하는 함수를 제공할 수도 있습니다.

반면 모델이 도구를 호출할 때가 아니라 사용자에게 응답할 때 따를 스키마를 지정하려면 response_format을 사용하는 구조화된 출력값이 더 적합합니다.

예를 들어 수학 학습 애플리케이션에서는 어시스턴트가 특정 JSON 스키마에 맞춰 응답하도록 할 수 있습니다. 그러면 모델 출력의 각 부분을 서로 다른 방식으로 표시하는 UI를 만들 수 있습니다.

용도에 따라 다음과 같이 선택하세요.

  • 모델을 시스템의 도구, 함수, 데이터 등에 연결하려면 함수 호출을 사용하세요. 모델이 사용자에게 보내는 응답을 구조화하려면 구조화된 text.format을 사용하세요.

이 가이드의 나머지 부분에서는 Responses API에서 함수 호출 없이 구조화된 출력값을 사용하는 사례를 다룹니다. 함수 호출과 함께 구조화된 출력값을 사용하는 방법은

함수 호출

가이드를 참고하세요.

구조화된 출력값과 JSON 모드 비교

구조화된 출력값은 JSON 모드를 발전시킨 기능입니다. 두 기능 모두 유효한 JSON을 생성하지만, 지정한 스키마까지 따르도록 보장하는 기능은 구조화된 출력값뿐입니다. Responses API, Chat Completions API, Assistants API, Fine-tuning API, Batch API에서 두 기능을 모두 지원합니다.

가능하면 항상 JSON 모드 대신 구조화된 출력값을 사용하는 것이 좋습니다.

다만 response_format: {type: "json_schema", ...}를 사용하는 구조화된 출력값은 gpt-4o-mini, gpt-4o-mini-2024-07-18, gpt-4o-2024-08-06 모델 스냅샷과 그 이후 버전에서만 지원됩니다.

구조화된 출력값 JSON 모드
유효한 JSON 출력 예 예
스키마 준수 예(지원되는 스키마 참고) 아니요
호환 모델 gpt-4o-mini, gpt-4o-2024-08-06 및 이후 모델 gpt-3.5-turbo, gpt-4-*, gpt-4o-* 및 호환되는 GPT-5 모델
활성화 방법 text: { format: { type: "json_schema", "strict": true, "schema": ... } } text: { format: { type: "json_object" } }

예제

추론 과정

사용자가 풀이 과정을 따라갈 수 있도록 모델에 답변을 단계별로 구조화해 출력하도록 요청할 수 있습니다.

구조화된 출력값으로 수학 문제의 추론 과정 설명하기
from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()


class Step(BaseModel):
    explanation: str
    output: str


class MathReasoning(BaseModel):
    steps: list[Step]
    final_answer: str


response = client.responses.parse(
    model="gpt-6-astra",
    input=[
        {
            "role": "system",
            "content": "You are a helpful math tutor. Guide the user through the solution step by step.",
        },
        {"role": "user", "content": "how can I solve 8x + 7 = -23"},
    ],
    text_format=MathReasoning,
)

math_reasoning = response.output_parsed

응답 예시

{
  "steps": [
    {
      "explanation": "Start with the equation 8x + 7 = -23.",
      "output": "8x + 7 = -23"
    },
    {
      "explanation": "Subtract 7 from both sides to isolate the term with the variable.",
      "output": "8x = -23 - 7"
    },
    {
      "explanation": "Simplify the right side of the equation.",
      "output": "8x = -30"
    },
    {
      "explanation": "Divide both sides by 8 to solve for x.",
      "output": "x = -30 / 8"
    },
    {
      "explanation": "Simplify the fraction.",
      "output": "x = -15 / 4"
    }
  ],
  "final_answer": "x = -15 / 4"
}

구조화된 출력값 사용 방법: text.format

대화 도중 응답 형식 변경하기

다음 응답부터 새 스키마를 적용하려면 configuration_update 항목을 input에 추가한 뒤 다음 사용자 메시지를 추가하세요. 요청마다 최상위 text.format에 원래 값을 유지하면 이전 프롬프트의 접두부가 계속 프롬프트 캐싱 대상이 됩니다.

GPT-6 및 이후 모델 중 이 기능을 지원하는 모델에서는 표준 단일 에이전트 모드로 응답 형식을 변경할 수 있습니다.

이전 턴에서 빨간색 상자 17개와 파란색 상자 26개로 구성된 화물을 일반 텍스트로 설명했다고 가정해 보겠습니다. previous_response_id로 대화를 이어가고 다음 배열을 input으로 전달하세요.

일반 텍스트에서 상자 수를 구조화해 반환하는 형식으로 전환하기
from openai import OpenAI
from pydantic import BaseModel, ConfigDict


class CrateCount(BaseModel):
    model_config = ConfigDict(extra="forbid")
    total_crates: int


client = OpenAI()
model = "gpt-6-astra"

first = client.responses.create(
    model=model,
    input="Summarize this shipment in one sentence: 17 red crates and 26 blue crates.",
    store=True,
)

second = client.responses.parse(
    model=model,
    previous_response_id=first.id,
    input=[
        {
            "type": "configuration_update",
            "text": {
                "format": {
                    "type": "json_schema",
                    "name": "crate_count",
                    "schema": CrateCount.model_json_schema(),
                    "strict": True,
                }
            },
        },
        {"role": "user", "content": "How many crates are in the shipment?"},
    ],
    parse_as=CrateCount,
)

if second.status == "completed" and second.output_parsed is not None:
    print(second.output_parsed.total_crates)

예상 답변은 {"total_crates":43}입니다. 응답 객체의 text.format에는 여전히 요청의 최상위 수준에서 지정한 원래 형식이 표시됩니다. 모델이 요청을 거부했는지, 응답이 불완전한지 확인한 뒤 가장 최근의 형식 업데이트에 지정한 스키마로 답변을 파싱하세요.

형식을 업데이트할 때마다 기존 형식 전체가 교체됩니다. 새 형식은 이후 턴에도 계속 적용되며, reasoning.effort만 변경해도 그대로 유지됩니다. 일반 텍스트로 돌아가려면 {"type":"configuration_update","text":{"format":{"type":"text"}}}를 추가하세요. 업데이트에서 지정할 수 있는 형식은 json_schema와 text뿐입니다.

대화 기록을 직접 다시 전송할 때는 각 업데이트를 원래 위치에 두세요. 컨텍스트 압축을 명시적으로 실행한 후에는 변경했던 설정을 각각 다시 지정하세요. 자세한 내용은 설정 업데이트 호환성을 참고하세요.

구조화된 출력값의 거부 응답

사용자가 입력한 내용을 구조화된 출력값으로 처리할 때 OpenAI 모델은 간혹 안전상의 이유로 요청을 거부할 수 있습니다. 거부 응답은 response_format에 지정한 스키마를 따르지 않을 수 있으므로, API 응답에는 모델이 요청을 거부했음을 나타내는 refusal이라는 새 필드가 포함됩니다.

출력 객체에 refusal 속성이 있으면 UI에 거부 응답을 표시하거나, 응답을 처리하는 코드에 조건문을 추가해 거부된 요청을 별도로 처리할 수 있습니다.

class Step(BaseModel):
    explanation: str
    output: str


class MathReasoning(BaseModel):
    steps: list[Step]
    final_answer: str


response = client.responses.parse(
    model="gpt-6-astra",
    input=[
        {
            "role": "system",
            "content": "You are a helpful math tutor. Guide the user through the solution step by step.",
        },
        {"role": "user", "content": "how can I solve 8x + 7 = -23"},
    ],
    text_format=MathReasoning,
)

for output in response.output:
    if output.type != "message":
        continue

    for item in output.content:
        if item.type == "refusal":
            # If the model refuses to respond, you will get a refusal message
            print(item.refusal)
            continue

        if not item.parsed:
            raise Exception("Could not parse response")

        print(item.parsed)

모델이 요청을 거부했을 때의 API 응답 예시는 다음과 같습니다.

{
  "id": "resp_1234567890",
  "object": "response",
  "created_at": 1721596428,
  "status": "completed",
  "completed_at": 1721596429,
  "error": null,
  "incomplete_details": null,
  "input": [],
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4o-2024-08-06",
  "output": [{
    "id": "msg_1234567890",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "refusal",
        "refusal": "I'm sorry, I cannot assist with that request."
      }
    ]
  }],
  "usage": {
    "input_tokens": 81,
    "output_tokens": 11,
    "total_tokens": 92,
    "output_tokens_details": {
      "reasoning_tokens": 0,
    }
  },
}

팁과 권장 사항

사용자 입력 처리하기

애플리케이션에서 사용자 입력을 받는다면 입력 내용으로 유효한 응답을 만들 수 없을 때 어떻게 처리해야 하는지 프롬프트에 명시하세요.

모델은 항상 지정한 스키마를 따르려고 하므로 입력이 스키마와 전혀 관련이 없으면 내용을 지어낼 수 있습니다.

예를 들어 모델이 입력 내용이 작업에 적합하지 않다고 판단하면 매개변수 값을 비워 두거나 특정 문장을 반환하도록 프롬프트에 지시할 수 있습니다.

오류 처리하기

구조화된 출력값에도 잘못된 내용이 포함될 수 있습니다. 오류가 발견되면 지시를 조정하거나, 시스템 지침에 예시를 추가하거나, 작업을 더 간단한 하위 작업으로 나눠 보세요. 입력을 개선하는 방법은 프롬프트 엔지니어링 가이드를 참고하세요.

JSON 스키마와 타입 간 불일치 방지하기

SDK에서 스키마 헬퍼를 제공한다면 이를 사용하는 것을 적극 권장합니다. JSON 스키마와 프로그래밍 언어에서 정의한 타입이 서로 어긋나는 것을 방지할 수 있습니다.

JSON 스키마를 직접 지정하려면 JSON 스키마나 해당 데이터 객체가 수정될 때 이를 알리는 CI 규칙을 추가할 수 있습니다. 타입 정의에서 JSON 스키마를 자동 생성하거나, 반대로 JSON 스키마에서 타입 정의를 자동 생성하는 CI 단계를 추가하는 방법도 있습니다.

스트리밍

스트리밍을 사용하면 모델 응답이나 함수 호출 인수를 생성되는 대로 처리하고 구조화된 데이터로 파싱할 수 있습니다.

이렇게 하면 응답이 완료될 때까지 기다리지 않고 처리를 시작할 수 있습니다. JSON 필드를 하나씩 표시하거나 함수 호출 인수가 준비되는 즉시 처리할 때 특히 유용합니다.

구조화된 출력값을 스트리밍할 때는 SDK를 사용하는 것이 좋습니다.

from openai import OpenAI
from pydantic import BaseModel


class EntitiesModel(BaseModel):
    attributes: list[str]
    colors: list[str]
    animals: list[str]


client = OpenAI()

with client.responses.stream(
    model="gpt-6-astra",
    input=[
        {"role": "system", "content": "Extract entities from the input text"},
        {
            "role": "user",
            "content": "The quick brown fox jumps over the lazy dog with piercing blue eyes",
        },
    ],
    text_format=EntitiesModel,
) as stream:
    for event in stream:
        if event.type == "response.refusal.delta":
            print(event.delta, end="")
        elif event.type == "response.output_text.delta":
            print(event.delta, end="")
        elif event.type == "response.error":
            print(event.error, end="")
        elif event.type == "response.completed":
            print("Completed")  # print(event.response.output)

    final_response = stream.get_final_response()
    print(final_response)

지원되는 스키마

구조화된 출력값은 JSON 스키마 문법의 일부를 지원합니다.

지원하는 타입

구조화된 출력값은 다음 타입을 지원합니다.

  • 문자열
  • 숫자
  • 불리언
  • 정수
  • 객체
  • 배열
  • 열거형
  • anyOf

지원하는 속성

속성의 타입을 지정할 때 다음 제약 조건도 함께 설정할 수 있습니다.

string에서 지원하는 속성

  • pattern — 문자열이 일치해야 하는 정규 표현식입니다.
  • format — 미리 정의된 문자열 형식을 지정합니다. 현재 지원하는 형식은 다음과 같습니다.
    • date-time
    • time
    • date
    • duration
    • email
    • hostname
    • ipv4
    • ipv6
    • uuid

number에서 지원하는 속성

  • multipleOf — 숫자는 지정한 값의 배수여야 합니다.
  • maximum — 숫자는 지정한 값보다 작거나 같아야 합니다.
  • exclusiveMaximum — 숫자는 지정한 값보다 작아야 합니다.
  • minimum — 숫자는 지정한 값보다 크거나 같아야 합니다.
  • exclusiveMinimum — 숫자는 지정한 값보다 커야 합니다.

array에서 지원하는 속성

  • minItems — 배열의 항목 수는 지정한 값 이상이어야 합니다.
  • maxItems — 배열의 항목 수는 지정한 값 이하여야 합니다.

다음은 타입별 제약 조건을 사용하는 예시입니다.

 
{
    "name": "user_data",
    "strict": true,
    "schema": {
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "The name of the user"
            },
            "username": {
                "type": "string",
                "description": "The username of the user. Must start with @",
                "pattern": "^@[a-zA-Z0-9_]+$"
            },
            "email": {
                "type": "string",
                "description": "The email of the user",
                "format": "email"
            }
        },
        "additionalProperties": false,
        "required": [
            "name", "username", "email"
        ]
    }
}

이러한 제약 조건은 파인튜닝된 모델에서 아직 지원되지 않습니다.

스키마의 루트는 객체여야 하며 anyOf를 사용할 수 없습니다

스키마의 최상위 요소는 객체여야 하며, 이 위치에서는 anyOf를 사용할 수 없습니다. 예를 들어 Zod에서 판별 유니온을 사용하면 최상위에 anyOf가 생성됩니다. 따라서 다음과 같은 코드는 작동하지 않습니다.

import { z } from "zod";
import { zodResponseFormat } from "openai/helpers/zod";

const BaseResponseSchema = z.object({
  /* ... */
});
const UnsuccessfulResponseSchema = z.object({
  /* ... */
});

const finalSchema = z.discriminatedUnion("status", [
  BaseResponseSchema,
  UnsuccessfulResponseSchema,
]);

// Invalid JSON Schema for Structured Outputs
const json = zodResponseFormat(finalSchema, "final_schema");

모든 필드는 required로 지정해야 합니다

구조화된 출력값을 사용하려면 모든 필드 또는 함수 매개변수를 required로 지정해야 합니다.

{
    "name": "get_weather",
    "description": "Fetches the weather in the given location",
    "strict": true,
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The location to get the weather for"
            },
            "unit": {
                "type": "string",
                "description": "The unit to return the temperature in",
                "enum": ["F", "C"]
            }
        },
        "additionalProperties": false,
        "required": ["location", "unit"]
    }
}

모든 필드는 필수이며 모델은 각 매개변수의 값을 반환합니다. 선택적 매개변수처럼 동작하게 하려면 null을 포함하는 유니온 타입을 사용할 수 있습니다.

{
    "name": "get_weather",
    "description": "Fetches the weather in the given location",
    "strict": true,
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The location to get the weather for"
            },
            "unit": {
                "type": ["string", "null"],
                "description": "The unit to return the temperature in",
                "enum": ["F", "C"]
            }
        },
        "additionalProperties": false,
        "required": [
            "location", "unit"
        ]
    }
}

객체의 중첩 깊이 및 크기 제한

스키마 전체에서 객체 속성은 최대 5,000개까지, 중첩은 최대 10단계까지 허용됩니다.

문자열의 총길이 제한

스키마에서 모든 속성 이름, 정의 이름, enum 값, const 값의 문자열 길이 합계는 120,000자를 넘을 수 없습니다.

열거형 크기 제한

스키마의 모든 열거형 속성을 통틀어 열거형 값은 최대 1,000개까지 지정할 수 있습니다.

문자열 값을 갖는 열거형 속성 하나에 값이 250개를 초과하면 그 값들의 문자열 길이 합계는 15,000자를 넘을 수 없습니다.

객체에는 항상 additionalProperties: false를 설정해야 합니다

additionalProperties는 객체에 JSON 스키마에서 정의하지 않은 키와 값을 추가로 포함할 수 있는지 결정합니다.

구조화된 출력값은 지정된 키와 값만 생성하므로 이 기능을 사용하려면 개발자가 additionalProperties: false를 설정해야 합니다.

{
    "name": "get_weather",
    "description": "Fetches the weather in the given location",
    "strict": true,
    "schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The location to get the weather for"
            },
            "unit": {
                "type": "string",
                "description": "The unit to return the temperature in",
                "enum": ["F", "C"]
            }
        },
        "additionalProperties": false,
        "required": [
            "location", "unit"
        ]
    }
}

키 순서

구조화된 출력값을 사용하면 결과의 키는 스키마에 지정된 순서대로 출력됩니다.

아직 지원하지 않는 타입별 키워드

  • 스키마 조합: allOf, not, dependentRequired, dependentSchemas, if, then, else

파인튜닝된 모델에서는 다음 키워드도 지원하지 않습니다.

  • 문자열: minLength, maxLength, pattern, format
  • 숫자: minimum, maximum, multipleOf
  • 객체: patternProperties
  • 배열: minItems, maxItems

strict: true를 지정해 구조화된 출력값을 활성화한 상태에서 지원하지 않는 JSON 스키마로 API를 호출하면 오류가 반환됩니다.

anyOf의 각 하위 스키마는 지원 범위 내에서 유효한 JSON 스키마여야 합니다

다음은 지원되는 anyOf 스키마의 예시입니다.

{
    "type": "object",
    "properties": {
        "item": {
            "anyOf": [
                {
                    "type": "object",
                    "description": "The user object to insert into the database",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "The name of the user"
                        },
                        "age": {
                            "type": "number",
                            "description": "The age of the user"
                        }
                    },
                    "additionalProperties": false,
                    "required": [
                        "name",
                        "age"
                    ]
                },
                {
                    "type": "object",
                    "description": "The address object to insert into the database",
                    "properties": {
                        "number": {
                            "type": "string",
                            "description": "The number of the address. Eg. for 123 main st, this would be 123"
                        },
                        "street": {
                            "type": "string",
                            "description": "The street name. Eg. for 123 main st, this would be main st"
                        },
                        "city": {
                            "type": "string",
                            "description": "The city of the address"
                        }
                    },
                    "additionalProperties": false,
                    "required": [
                        "number",
                        "street",
                        "city"
                    ]
                }
            ]
        }
    },
    "additionalProperties": false,
    "required": [
        "item"
    ]
}

스키마 정의 지원

하위 스키마를 한 번 정의하면 스키마 곳곳에서 참조할 수 있습니다. 다음은 간단한 예시입니다.

{
    "type": "object",
    "properties": {
        "steps": {
            "type": "array",
            "items": {
                "$ref": "#/$defs/step"
            }
        },
        "final_answer": {
            "type": "string"
        }
    },
    "$defs": {
        "step": {
            "type": "object",
            "properties": {
                "explanation": {
                    "type": "string"
                },
                "output": {
                    "type": "string"
                }
            },
            "required": [
                "explanation",
                "output"
            ],
            "additionalProperties": false
        }
    },
    "required": [
        "steps",
        "final_answer"
    ],
    "additionalProperties": false
}

재귀 스키마 지원

다음은 #로 루트를 다시 참조하는 재귀 스키마의 예시입니다.

{
    "name": "ui",
    "description": "Dynamically generated UI",
    "strict": true,
    "schema": {
        "type": "object",
        "properties": {
            "type": {
                "type": "string",
                "description": "The type of the UI component",
                "enum": ["div", "button", "header", "section", "field", "form"]
            },
            "label": {
                "type": "string",
                "description": "The label of the UI component, used for buttons or form fields"
            },
            "children": {
                "type": "array",
                "description": "Nested UI components",
                "items": {
                    "$ref": "#"
                }
            },
            "attributes": {
                "type": "array",
                "description": "Arbitrary attributes for the UI component, suitable for any element",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "The name of the attribute, for example onClick or className"
                        },
                        "value": {
                            "type": "string",
                            "description": "The value of the attribute"
                        }
                    },
                    "additionalProperties": false,
                    "required": ["name", "value"]
                }
            }
        },
        "required": ["type", "label", "children", "attributes"],
        "additionalProperties": false
    }
}

다음은 재귀 참조를 명시적으로 지정한 스키마의 예시입니다.

{
    "type": "object",
    "properties": {
        "linked_list": {
            "$ref": "#/$defs/linked_list_node"
        }
    },
    "$defs": {
        "linked_list_node": {
            "type": "object",
            "properties": {
                "value": {
                    "type": "number"
                },
                "next": {
                    "anyOf": [
                        {
                            "$ref": "#/$defs/linked_list_node"
                        },
                        {
                            "type": "null"
                        }
                    ]
                }
            },
            "additionalProperties": false,
            "required": [
                "next",
                "value"
            ]
        }
    },
    "additionalProperties": false,
    "required": [
        "linked_list"
    ]
}

JSON 모드

JSON 모드는 구조화된 출력값의 기본적인 형태입니다. JSON 모드는 모델이 유효한 JSON을 출력하도록 보장하며, 구조화된 출력값은 모델 출력이 지정한 스키마까지 따르도록 보장합니다. 사용하려는 환경에서 구조화된 출력값을 지원한다면 이 기능을 사용하는 것이 좋습니다.

JSON 모드를 활성화하면 일부 예외적인 경우를 제외하고 모델이 유효한 JSON을 출력합니다. 이러한 예외는 애플리케이션에서 감지해 적절히 처리해야 합니다.

Responses API에서 JSON 모드를 활성화하려면 text.format을 { "type": "json_object" }로 설정하세요. 함수 호출을 사용하면 JSON 모드가 항상 활성화됩니다.

중요한 유의 사항은 다음과 같습니다.

  • JSON 모드를 사용할 때는 시스템 메시지 등 대화에 포함된 메시지에서 모델에 JSON을 생성하라고 반드시 지시해야 합니다. 명시적으로 지시하지 않으면 모델이 공백 문자를 계속 생성해 토큰 한도에 도달할 때까지 요청이 끝나지 않을 수 있습니다. 이 지시가 누락되는 것을 방지하기 위해 API는 컨텍스트 어디에도 “JSON”이라는 문자열이 없으면 오류를 반환합니다.
  • JSON 모드는 출력이 유효한 JSON이고 오류 없이 파싱된다는 점만 보장합니다. 특정 스키마를 따르도록 보장하려면 구조화된 출력값을 사용하세요. 사용할 수 없다면 검증 라이브러리로 출력이 원하는 스키마를 따르는지 확인하고 필요에 따라 요청을 다시 보내세요.
  • 모델이 완전한 JSON 객체를 출력하지 못하는 예외 상황을 애플리케이션에서 감지하고 처리해야 합니다(아래 참고).

참고 자료

구조화된 출력값에 대해 더 알아보려면 다음 자료를 참고하세요.