구조화된 출력

프로그램이 파싱하고 검증하기 쉬운 구조화된 데이터를 모델이 반환하도록 합니다.

Structured Output은 모델이 원하는 데이터 구조로 결과를 반환하도록 하여 프로그램의 필드 추출, 데이터베이스 저장 또는 후속 워크플로 처리를 돕습니다. 지원 요청 분류, 양식 정보 추출, 콘텐츠 검토 결과 및 정형 분석 보고서 등에 사용합니다.

Structured Output과 Tool Calling은 서로 다른 문제를 해결합니다

구조화된 답변이 필요하면 Structured Output을 사용하고, 모델이 함수를 선택하여 애플리케이션에 실행을 요청해야 한다면 Tool Calling을 사용합니다. 도구 매개변수에도 Schema 제약을 적용할 수 있지만 이는 도구 호출 루프에 속합니다.

적합한 출력 방식 선택

방식	해결하는 문제	클라이언트의 추가 처리
프롬프트에서 JSON 요청	전용 필드가 없는 모델에 기본 제약을 제공합니다	JSON 추출, 파싱, 검증 및 실패 시 재시도
JSON Object	유효한 JSON 객체 출력을 요청합니다	필드, 타입 및 업무 규칙 검증
JSON Schema	요청에 목표 구조를 제공합니다	모델 지원 범위, 거부, 잘림 및 검증 실패 처리

JSON Object, JSON Schema 및 엄격한 준수의 지원 여부는 현재 모델과 프로토콜에 따라 달라집니다. 요청이 200을 반환했다는 이유만으로 지정한 Schema가 적용되었다고 판단해서는 안 됩니다.

작고 명확한 Schema 정의

다음 구조는 고객 문의를 지원 요청으로 분류하는 데 사용합니다:

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account"]
    },
    "priority": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "summary": {
      "type": "string"
    }
  },
  "required": ["category", "priority", "summary"],
  "additionalProperties": false
}

필드 이름은 안정적이고 이해하기 쉬워야 하며 열거 값은 업무 코드와 일치해야 합니다. 처음부터 지나치게 깊은 중첩, 많은 선택 분기 또는 해석하기 어려운 정규식 제약을 사용하지 않습니다.

Chat Completions로 구조화된 결과 받기

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "API 키를 사용할 수 없습니다. 이 문의를 분류해 주세요."
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "category": {
              "type": "string",
              "enum": ["billing", "technical", "account"]
            },
            "priority": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3
            },
            "summary": {"type": "string"}
          },
          "required": ["category", "priority", "summary"],
          "additionalProperties": false
        }
      }
    }
  }'

strict는 목표 형식의 일부이지만 사용 가능 여부는 모델에 따라 달라집니다. 전체 필드는 Chat Completions Reference를 확인합니다.

프로토콜별 필드 위치

Chat은 response_format에서 json_object 또는 json_schema를 선택합니다. JSON Schema를 사용할 때 Schema는 response_format.json_schema.schema에 있습니다.

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "schema": {"type": "object"}
    }
  }
}

이 구조를 다른 프로토콜에 그대로 복사해서는 안 됩니다. 사용 전에 각각 Responses Reference와 Gemini Generate Content Reference를 확인합니다.

파싱 후에도 검증 필요

type SupportTicket = {
  category: 'billing' | 'technical' | 'account';
  priority: number;
  summary: string;
};

function parseTicket(raw: string): SupportTicket {
  const value: unknown = JSON.parse(raw);

  if (
    typeof value !== 'object' ||
    value === null ||
    !('category' in value) ||
    !('priority' in value) ||
    !('summary' in value)
  ) {
    throw new Error('구조화된 결과에 필수 필드가 없습니다');
  }

  return value as SupportTicket;
}

위 예시는 최소 검사만 보여줍니다. 운영 프로젝트는 업무 데이터 모델과 일치하는 Schema 검증기를 사용하고 열거 값, 길이, 수치 범위 및 필드 간 규칙을 확인해야 합니다.

불완전하거나 유효하지 않은 결과 처리

현상	처리 방법
일반 텍스트 반환	모델의 목표 형식 지원 여부, 필드 위치 및 SDK의 요청 변경 여부를 확인합니다
JSON 파싱 실패	민감 정보를 제거한 응답과 종료 이유를 저장하고 업무 정책에 따라 제한적으로 재시도합니다
필수 필드 누락	검증 실패로 처리하며 기본값으로 중요한 데이터 누락을 조용히 숨기지 않습니다
출력 잘림	출력 예산을 조정하거나 Schema를 단순화하며 누락된 JSON을 추측하여 결합하지 않습니다
모델의 답변 거부	거부를 별도로 처리하고 거부 텍스트를 업무 객체로 취급하지 않습니다
Schema 파싱은 가능하지만 업무상 유효하지 않음	업무 검증으로 명확한 오류를 반환하거나 수동 처리로 전환합니다

운영 전 확인 사항

Schema와 애플리케이션의 타입 정의는 같은 원본에서 생성하거나 동기화합니다.
모델 변경 전에 프로토콜, Schema 하위 집합 및 엄격 모드 지원을 다시 확인합니다.
파싱 실패, 거부, 잘림 및 빈 출력에는 독립된 처리 분기가 있습니다.
데이터베이스에 저장하거나 업무 작업을 실행하기 전에 구조화된 결과를 다시 검증합니다.
로그에는 문제 해결에 필요한 마스킹된 정보만 저장합니다.

먼저 모델 목록에서 모델을 확인한 후 해당 API 레퍼런스에서 전체 필드를 확인합니다. 요청이 실패하면 오류 및 문제 해결을 참고합니다.