구조화된 출력 (Structured Output)

구조화된 출력(Structured Output)은 AI가 자유로운 문장 대신 미리 정한 JSON 스키마에 맞춰 값을 내놓게 하는 기능입니다. 응답을 데이터베이스나 API로 넘길 때 해석 규칙을 줄여 주므로, 분류·추출·자동화처럼 결과 모양이 고정된 업무에서 중요합니다.

JSON 문법, 스키마 적합성, 사실 정확성

구조화된 출력을 이해할 때는 세 가지 검사를 나눠야 합니다. 첫째, JSON 문법이 올바른지 봅니다. 따옴표나 쉼표가 빠지지 않아 파서가 읽을 수 있는 상태입니다. 둘째, 결과가 스키마에 맞는지 확인합니다. 필수 필드가 있고, 숫자 자리에 문자열이 들어오지 않으며, 허용하지 않은 필드가 추가되지 않아야 합니다. JSON Schema 공식 안내는 스키마를 데이터에 적용할 제약 조건으로 설명합니다. 셋째, 값의 사실이 맞는지 검사합니다. 문법과 스키마를 모두 통과한 {"invoice_total": 87000}도 실제 청구서 금액이 78,000원이라면 틀린 결과입니다.

Claude의 구조화 출력 공식 문서는 JSON 출력과 엄격한 도구 사용을 스키마로 제약합니다. 이 보장은 결과 모양에 관한 것입니다. 청구서에서 공급자명, 결제일, 합계 금액을 뽑는다면 각 필드의 타입과 필수 여부는 안정시킬 수 있지만, 원문 판독이 정확했는지는 별도 규칙으로 대조해야 합니다. 금액 합산, 날짜 범위, 상품 코드 존재 여부 같은 업무 규칙도 애플리케이션이 다시 확인하는 편이 안전합니다.

도구 호출과 최종 JSON은 쓰임이 다릅니다

도구 호출의 구조화 데이터는 모델이 어떤 작업을 요청하는지 나타내는 입력 인수입니다. 예를 들어 lookup_order에 order_id를 넣어 호출하겠다는 뜻이며, 실제 조회는 모델이 아니라 애플리케이션이나 서버가 수행합니다. Anthropic의 도구 사용 설명처럼 클라이언트 도구는 tool_use를 받은 프로그램이 실행하고, 결과를 tool_result로 돌려줘야 다음 단계가 이어집니다. 엄격한 스키마는 주문 번호의 타입과 필드 구성을 지켜 주지만, 조회 성공이나 주문 존재까지 보장하지는 않습니다.

최종 출력용 JSON은 호출 지시가 아니라 애플리케이션이 소비할 결과물입니다. 상담 기록에서 고객 의도, 긴급도, 담당 부서를 뽑아 티켓 시스템에 저장할 때 적합합니다. 실행해야 할 외부 동작이 있으면 도구 호출을 고르고, 분석 결과를 일정한 모양으로 받으려면 최종 JSON 형식을 고릅니다. 한 요청에서 둘을 함께 쓸 수도 있습니다. 주문 조회 도구를 실행한 뒤, 조회 결과를 status, eta, next_action 필드로 정리하는 흐름입니다.

실패와 거절을 정상 흐름에 넣어야 합니다

구조화된 출력을 사용해도 스키마 형식을 벗어나는 응답이 생길 수 있습니다. 안전상의 이유로 요청을 거절하거나 출력 길이 제한에 걸려 응답이 잘리면 JSON이 완성되지 않을 수 있습니다. 호출 코드는 본문을 바로 파싱하기 전에 종료 이유를 확인하고, 거절은 사용자에게 설명하며, 잘린 출력은 조건을 조정해 재시도해야 합니다. 도구 실행 중 네트워크 오류나 권한 오류가 생긴 경우에도 스키마에 맞는 호출이 성공한 실행을 뜻하지 않으므로 오류 결과를 모델에 돌려주거나 사람에게 넘기는 경로가 필요합니다.

스키마를 설계할 때는 꼭 필요한 필드만 필수로 두고, 값이 없을 수 있으면 null 같은 상태를 명시합니다. 설명 필드에는 어떤 근거로 값을 채워야 하는지 적고, 자유로운 해설이 필요한 부분은 짧은 문자열 필드로 남깁니다. 중첩과 선택지가 지나치게 많으면 스키마 컴파일이나 모델 판단이 어려워질 수 있습니다. 구조화된 출력이 잘 맞는지는 “항상 JSON이 필요한가”, “틀린 값을 잡을 후속 검사가 있는가”, “거절과 도구 오류를 처리하는가”로 판단하면 됩니다.