본문으로 건너뛰기

LLM 구조화 출력: JSON Schema로 믿을 수 있는 응답 만들기

구조화 출력과 function calling으로 LLM 응답을 파서블한 JSON으로 만드는 스키마 설계와 실패 처리를 정리합니다.

· 2분 읽기
share

LLM 구조화 출력: JSON Schema로 믿을 수 있는 응답 만들기

개요

LLM 출력을 그대로 믿고 쓰다 보면 “대부분 JSON인데 가끔 아닌” 지옥을 만납니다. 구조화 출력(structured output)은 응답을 지정한 JSON Schema로 제한하는 기능으로, 자연어 출력을 파싱하던 시절의 불확실성을 상당히 없애줍니다. 실무에서 배운 스키마 설계와 실패 처리를 정리합니다.

구조화 출력과 function calling

두 접근이 결국 같은 문제를 해결합니다. LLM이 “문장”이 아니라 “정의된 형태”로 응답하게 하는 것입니다. function calling은 도구 호출 인자를 스키마에 맞춰 채우고, 구조화 출력은 최종 응답 자체를 스키마에 맞춥니다. OpenAI API는 response_format의 JSON Schema 지정으로, Anthropic API는 도구 정의로 이런 제약을 걸 수 있습니다.

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "사용자 리뷰를 분석해 JSON으로 응답하세요."},
        {"role": "user", "content": "배송은 빨랐지만 사이즈가 아주 작아요."},
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "review_analysis",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "sentiment": {"type": "string", "enum": ["positive", "negative", "mixed"]},
                    "topics": {
                        "type": "array",
                        "items": {"type": "string", "enum": ["shipping", "quality", "size", "price", "etc"]}
                    }
                },
                "required": ["sentiment", "topics"],
                "additionalProperties": False,
            },
        },
    },
)

strict: true와 additionalProperties: false 조합이 핵심입니다. 스키마를 지켰다는 보장을 받으려면 모든 프로퍼티를 required에 넣고, 선택적 값은 "기타" 같은 enum 항목으로 표현하는 편이 안전합니다.

스키마 설계 원칙

  • 문자열 자유도를 줄인다: 카테고리는 enum으로, 숫자는 범위를 문서화한다
  • 프롬프트로 뜻을 보강한다: 스키마는 형태만 제약한다. 각 필드의 의미는 프롬프트에 설명한다
  • 배타적 분류가 아니게 나눈다: 하나의 항목이 두 카테고리에 걸리면 판단이 흔들린다

실패 처리

구조화 출력은 형태를 보장하지만 내용의 참을 보장하지 않습니다. 그래서 응답 후 검증 레이어를 둡니다. 런타임 검증은 zod 같은 스키마 라이브러리가 편합니다.

import { z } from 'zod';

const ReviewAnalysis = z.object({
  sentiment: z.enum(['positive', 'negative', 'mixed']),
  topics: z.array(z.enum(['shipping', 'quality', 'size', 'price', 'etc'])),
});

export function parseAnalysis(raw: string) {
  const json = JSON.parse(raw);          // 형태 보장이 없는 경로에서는 필수
  const result = ReviewAnalysis.safeParse(json);
  if (!result.success) {
    return { ok: false as const, error: result.error };
  }
  return { ok: true as const, data: result.data };
}

ok 필드로 성공/실패를 명시적으로 나누면 호출 쪽에서 재시도·로깅·폴백 분기가 깔끔해집니다. 재시도는 실패 사유를 다음 요청에 함께 실어주는 식으로 개선하는 게 효과적이었습니다.

마무리

LLM 응답을 신뢰하려면 “부탁”이 아니라 “제약”이 필요합니다. 스키마로 형태를 묶고, 프롬프트로 의미를 채우고, 런타임 검증으로 마지막 문을 닫는 3단 구조가 지금의 제 기본값입니다.

Related