BroadRouter
시작하기

구조화된 출력(Structured output)

업데이트

구조화된 출력(structured output)은 모델의 응답을 개발자가 지정한 형식, 주로 JSON Schema에 맞추도록 제한해 코드가 안정적으로 파싱할 수 있게 하는 LLM API 기능입니다. 유효한 JSON만 보장하고 특정 구조는 보장하지 않는 JSON 모드보다 더 엄격합니다.

다른 이름: 구조화된 출력, 구조화 출력, JSON 스키마 출력, structured output, structured outputs, JSON schema output, response_format

코드는 예측 가능한 입력을 필요로 합니다. 구조화된 출력은 모델의 자유로운 텍스트를 프로그램이 믿고 쓸 수 있는 데이터로 바꿉니다.

작동 방식

제어 수준은 세 가지입니다.

방법 얻는 결과
프롬프트로 요청 보통 JSON이지만, 때때로 추가 텍스트가 붙거나 필드가 빠짐
JSON 모드 유효한 JSON, 구조는 자유
스키마를 지정한 구조화된 출력 스키마와 일치하는 JSON

OpenAI 형식에서 JSON 모드는 response_format: {"type": "json_object"}입니다. 구조화된 출력은 스키마를 전달합니다.

"response_format": {
  "type": "json_schema",
  "json_schema": {
    "name": "invoice",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "vendor": { "type": "string" },
        "total": { "type": "number" }
      },
      "required": ["vendor", "total"],
      "additionalProperties": false
    }
  }
}

OpenAI 레퍼런스는 json_schema 타입이 “ensures the model will match your supplied JSON schema.”(번역: 모델이 제공한 JSON 스키마와 일치하도록 보장한다)고 설명합니다. 많은 제공업체는 이를 제약 디코딩(constrained decoding)으로 구현합니다. 각 단계에서 모델이 생성할 수 있는 토큰을 제한해, 스키마를 깨는 출력이 아예 생성되지 않게 하는 방식입니다.

왜 중요한가

  • 파싱 오류 감소. 정보 추출 파이프라인, 분류기, 에이전트가 필드를 바로 읽을 수 있습니다.
  • 더 간단한 프롬프트. 긴 형식 지시문을 스키마가 대신합니다.
  • 완전한 보장은 아닙니다. OpenAI 가이드는 앱에서 여전히 거절, 불완전한 응답, 오류를 처리해야 한다고 말합니다. max_tokens에서 잘린 응답은 스키마와 상관없이 깨진 JSON입니다.

OpenAI 호환 API마다 지원 범위가 다릅니다. json_schema만 받는 곳, json_object만 받는 곳, 이 필드를 무시하는 곳이 있습니다. 의존하기 전에 확인하세요.

BroadNet Inference에서는

BroadNet 문서는 GLM 5.3과 Qwen3.8 27B에서 구조화된 출력을 지원한다고 안내합니다. 문서에 요청 파라미터 이름은 나와 있지 않으므로 사용하는 모델에서 response_format을 테스트하고, 어떤 경우든 오류 처리를 갖춘 JSON 파서를 유지하세요. LLM JSON 출력 검증 도구는 응답이 어디서 깨지는지 보여 주고 스키마와 대조해 검사합니다. 두 모델 모두 먼저 추론하므로 max_tokens에 생각용 토큰과 JSON을 모두 담을 여유를 두세요.

구조화된 출력은 비전 모델과 잘 어울립니다. 아랍어 청구서 가이드는 이미지를 보내고 필드를 JSON으로 요청합니다. 답변이 아니라 동작이 필요하다면 도구 호출을 쓰세요.

흔한 실수

  • strict 모드에서 additionalProperties: false를 빠뜨리거나, 모든 필드를 required에 나열하지 않는 것.
  • 파싱하기 전에 finish_reason을 확인하지 않는 것.

자주 묻는 질문

JSON 모드와 구조화된 출력은 어떻게 다른가요?

JSON 모드는 응답이 JSON으로 파싱된다는 것만 보장합니다. 스키마를 지정한 구조화된 출력은 정의한 필드, 타입, 필수 키까지 보장합니다. OpenAI 가이드는 스키마 준수를 보장하는 것은 Structured Outputs뿐이라고 설명합니다.

그래도 출력을 검증해야 하나요?

네. 응답이 거절이거나 max_tokens에서 잘릴 수 있고, 합계가 각 항목 금액의 합과 같아야 한다는 식의 비즈니스 규칙을 스키마로 모두 표현할 수도 없습니다.

구조화된 출력과 도구 호출 중 무엇을 써야 하나요?

최종 답변을 고정된 형식으로 받고 싶다면 구조화된 출력을 쓰세요. 모델이 코드에 어떤 작업을 요청한 뒤 이어서 진행해야 한다면 도구 호출을 쓰세요.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기