AI API를 사용해 서비스를 만들다 보면 반복적으로 마주치는 문제가 있다. 모델이 준 답변이 JSON 스키마를 어기거나, 툴 호출 형식이 맞지 않아 파싱 오류가 발생하는 상황이다. 장애와 디버깅은 대부분 이 지점에서 시작된다.
이번에 공개된 Claude Developer Platform의 Structured Outputs는 이 문제를 정면으로 해결하기 위한 기능이다. Sonnet 4.5와 Opus 4.1 모델에서 베타로 제공되며, 개발자가 정의한 JSON 스키마 또는 툴 형식을 모델이 반드시 지키도록 보장한다. 그 결과, 에러 없이 안정적인 LLM 응답을 얻을 수 있는 개발 환경이 가능해졌다.
이 글에서는 Structured Outputs가 어떤 기능인지, 왜 중요한지, 실제로 어떤 변화를 가져오는지 정리해본다.
반응형
(adsbygoogle = window.adsbygoogle || []).push({});
1. 왜 ‘구조 보장’이 필요한가?
LLM 기반 애플리케이션은 예측 가능한 구조를 기반으로 동작한다. 그런데 모델이 생성하는 응답은 종종 다음과 같은 문제를 일으킨다.
JSON 스키마를 맞추지 못해 파싱 실패
key가 누락되거나 타입이 달라 downstream 오류 발생
툴 호출 형식 불일치로 인해 에이전트 또는 API 통신 실패
이를 잡기 위해 리트라이 로직과 정규식 패칭 코드를 반복 작성
이런 작은 구조 오류 하나가 서비스 전체 장애로 이어지는 경우도 많다. 따라서 LLM이 반드시 정해진 구조를 지키는 기능은 개발자가 가장 간절하게 원하는 부분이었다.
2. Structured Outputs란 무엇인가?
Structured Outputs는 Claude가 응답을 생성할 때 개발자가 정의한 JSON 스키마 또는 툴 정의에 100% 맞추도록 보장하는 기능이다.
핵심은 단순히 "형식을 최대한 지키려 노력"하는 수준이 아니라, 스키마 불일치를 허용하지 않는다는 점이다.
이로 인해 다음과 같은 효과가 있다.
스키마 불일치로 인한 오류 제거
툴 호출 실패 제거
다운스트림 시스템이 안정적으로 작동
디버깅 및 리트라이 비용 대폭 감소
즉, 구조화된 데이터를 필수 요소로 사용하는 서비스라면 가장 신뢰할 수 있는 방식이 된다.
3. 어떤 문제를 실제로 해결하나
Structured Outputs는 특히 다음과 같은 상황에서 강력한 효과를 발휘한다.
데이터 추출
문서 이미지에서 특정 값을 추출해 DB에 넣는 등, 형식이 조금만 틀어져도 오류가 발생하는 경우가 많다. Structured Outputs는 정확한 스키마에 맞춰 응답을 생성해 안정성을 보장한다.
멀티 에이전트 아키텍처
다수의 에이전트가 LLM을 거쳐 서로 데이터를 주고받을 때, 형식 불일치는 곧 전체 워크플로우의 실패로 이어진다.
OpenRouter는 Structured Outputs 도입 후 에이전트 간 통신이 안정적으로 돌아간다고 밝히기도 했다.
복잡한 검색 및 필드 매칭
검색 툴이나 필터링 기능처럼 여러 필드가 정확히 채워져야 하는 기능에서도 도움된다.
필드 값 누락, 오탈자, 타입 오류가 사라진다.
4. 어떻게 사용하는가? (JSON 방식 vs Tool 방식)
Structured Outputs는 두 가지 방식으로 사용할 수 있다.
1) JSON 스키마 방식
API 요청 시 JSON 스키마를 정의하면, Claude는 반드시 그 구조에 맞는 데이터를 반환한다.
예시:
{
"type": "object",
"properties": {
"title": {"type": "string"},
"tags": {"type": "array", "items": {"type": "string"}}
},
"required": ["title", "tags"]
}
이 스키마를 정의하면, Claude는 title과 tags가 반드시 포함된 정확한 구조로 응답을 생성한다.
2) Tool 방식
툴 호출을 정의하면 Claude는 그 함수 입력 형식에 맞춰 출력을 자동 생성한다.