Claude의 구조화된 출력(Structured Outputs) 기능 소개
Anthropic이 Claude 개발자 플랫폼에서 '구조화된 출력(Structured Outputs)' 기능을 공개 베타로 발표했습니다. 이 기능은 Claude Sonnet 4.5 및 Opus 4.1 모델에서 우선 지원되며, API를 통해 모델의 응답이 개발자가 정의한 특정 JSON 스키마나 도구(Tool) 정의를 100% 준수하도록 보장합니다.
소프트웨어 엔지니어로서 LLM(대규모 언어 모델)을 실제 애플리케이션이나 서비스에 연동해 본 경험이 있다면, 모델이 항상 일관된 형식으로 응답을 생성하도록 만드는 것이 얼마나 어려운 일인지 공감하실 것입니다. 간단한 챗봇을 넘어 데이터를 추출하거나, 외부 API와 연동하거나, 여러 에이전트가 통신하는 복잡한 워크플로우를 구축할 때, LLM의 응답이 예상한 JSON 형식을 벗어나는 경우는 치명적인 오류로 이어질 수 있습니다. 예를 들어, JSON 객체의 키(key) 이름이 달라지거나, 값이 누락되거나, 형식이 맞지 않으면 파싱(parsing) 오류가 발생하여 전체 시스템이 중단될 수 있습니다.
지금까지 개발자들은 이러한 문제를 해결하기 위해 복잡한 프롬프 엔지니어링을 사용하거나(예: "반드시 JSON 형식으로만 응답해 주세요..."), 응답을 받은 후에 정규식(Regex) 또는 별도의 파싱 로직을 구현하여 데이터를 검증하고, 오류 발생 시 재시도(retry) 로직을 수행하는 방어적인 코드를 작성해야 했습니다. 이는 개발 과정을 복잡하게 만들고 시스템의 불안정성을 높이는 주요 원인이었습니다.
Anthropic의 새로운 '구조화된 출력' 기능은 이러한 '마지막 마일(last mile)' 문제를 정면으로 해결합니다. 이 기능은 모델에게 형식을 '요청'하는 것이 아니라, 응답 자체가 정의된 스키마를 '강제로' 따르도록 제어합니다. 이를 통해 개발자는 모델 성능에 영향을 주지 않으면서도 스키마 관련 파싱 오류를 원천적으로 제거할 수 있게 되어, 훨씬 더 안정적이고 예측 가능한 프로덕션 레벨의 AI 애플리케이션을 구축하는 데 집중할 수 있습니다.
함수 호출(Tool Use) 기능과의 비교
'구조화된 출력'이라는 개념은 다른 LLM 플랫폼에서 제공하는 '함수 호출(Function Calling)' 또는 'JSON 모드'와 유사하게 들릴 수 있지만, Anthropic의 접근 방식은 이 둘을 통합하고 보완하는 특징을 가집니다.
기존 프롬프트 엔지니어링과의 차이점
가장 큰 차이점은 '부드러운 안내(soft guidance)'가 아닌 '엄격한 제약(hard constraint)'이라는 점입니다. 기존에는 프롬프트를 통해 "이름, 이메일 주소를 JSON 형식으로 추출해 줘"라고 요청했습니다. 모델은 대부분 이 요청을 따르지만, 때로는 JSON 앞뒤에 추가적인 설명 문장을 붙이거나, 형식이 미묘하게 다른 텍스트를 생성할 위험이 있었습니다. 하지만 '구조화된 출력' 기능은 모델의 생성 프로세스 자체에 개입하여, 최종 출력물이 정의된 스키마와 일치하지 않으면 아예 생성이 완료되지 않도록 보장합니다.
함수 호출(Tool Use)과의 관계
Anthropic의 '구조화된 출력' 기능은 '함수 호출(Tool Use)' 기능과 별개가 아니라, 오히려 이 기능을 더욱 강력하게 만드는 핵심 요소입니다. 이 기능은 두 가지 방식으로 작동합니다.
- 직접적인 JSON 출력 (
output_format): 사용자의 요청에 대해 모델이 특정 JSON 스키마를 따르는 응답을 직접 생성해야 할 때 사용합니다. 예를 들어, 비정형 텍스트에서 정보를 추출하여 JSON 객체로 반환받는 경우입니다. - 엄격한 도구 사용 (
strict: true): 모델이 특정 작업을 수행하기 위해 개발자가 정의한 '도구(tool)'를 호출해야 할 때 사용합니다. 이 옵션을 활성화하면, 모델이 생성하는 도구 호출 요청(예: 함수 이름과 매개변수)이 개발자가 사전에 정의한 스키마와 100% 일치함을 보장합니다.
즉, 이 기능은 모델이 도구를 호출할 때 발생하는 형식 오류를 방지하는 동시에, 도구 호출 없이 순수한 JSON 데이터만을 안정적으로 받아보는 용도로도 사용할 수 있게 해줍니다.
'구조화된 출력'의 주요 기능 및 작동 방식
'구조화된 출력' 기능의 핵심은 '신뢰성'입니다. 개발자는 더 이상 모델의 응답 형식을 검증하고 처리하기 위한 복잡한 오류 처리 로직이나 재시도 메커니즘을 구현할 필요가 없습니다. 이는 코드베이스를 단순화하고, 불필요한 API 호출을 줄여 비용 효율성을 높이는 데 기여합니다.
-
JSON 모드 (
output_format활용): 모델의 최종 응답 자체가 특정 JSON 스키마를 따르도록 강제하는 방식입니다. API 요청 시output_format파라미터를 사용하여 원하는 JSON 스키마를 정의하면, Claude는 해당 스키마 구조에 완벽하게 일치하는 JSON 객체를 포함한 응답을 반환합니다.
특히 Python 개발자에게 익숙한 Pydantic이나 TypeScript 개발자에게 익숙한 Zod와 같은 스키마 정의 라이브러리와의 연동성이 뛰어납니다. 개발자는 이미 사용 중인 Pydantic 모델이나 Zod 스키마를 정의하기만 하면, Anthropic SDK가 이를 자동으로 JSON 스키마로 변환하여 API 요청에 포함시켜 줍니다. -
엄격한 도구 사용 (
strict: true활용): 이 방식은 모델이 에이전트처럼 작동하여 여러 도구 중 하나를 선택하고 호출해야 하는 'Tool Use' 시나리오에서 사용됩니다.tool_choice파라미터와 함께strict: true플래그를 설정하면, Claude는 반드시 정의된 도구 중 하나를 호출하며, 이때 전달하는 매개변수(arguments)가 해당 도구의 스키마 정의를 완벽하게 준수하도록 보장합니다.
이는 여러 AI 에이전트가 서로 통신하거나, 데이터베이스 쿼리 또는 외부 API와 같이 엄격한 입력 형식이 요구되는 시스템과 연동할 때 발생할 수 있는 치명적인 오류를 방지해 줍니다.
주요 활용 사례
'구조화된 출력' 기능은 AI 모델의 응답 형식이 중요한 모든 프로덕션 환경에서 유용하게 사용될 수 있습니다. 예를 들어, 다음과 같은 활용 사례들이 있을 수 있습니다:
-
데이터 추출 (Data Extraction): 송장, 이력서, 이메일과 같은 비정형 텍스트에서 이름, 날짜, 금액, 주소 등 특정 정보를 일관된 형식의 JSON으로 추출할 수 있습니다. 추출된 데이터는 즉시 데이터베이스에 저장하거나 다운스트림 시스템에서 활용할 수 있습니다.
-
다중 에이전트 아키텍처 (Multi-agent Architectures): 복잡한 작업을 수행하기 위해 여러 AI 에이전트가 협력하는 시스템에서, 에이전트 간의 통신은 매우 중요합니다. 한 에이전트가 다른 에이전트가 파싱할 수 없는 형식으로 메시지를 보내면 전체 워크플로우가 실패합니다. '구조화된 출력'은 에이전트 간의 통신 메시지가 항상 규정된 스키마를 따르도록 보장하여 시스템 전체의 안정성을 높입니다.
-
API 및 시스템 연동 (API Integration): LLM을 사용하여 외부 API를 호출하거나 데이터베이스 쿼리를 생성할 때, 요청 파라미터는 매우 엄격한 형식과 타입을 요구합니다. 이 기능을 사용하면 모델이 생성하는 API 요청 페이로드(payload)나 SQL 쿼리 구조가 항상 유효함을 보장받을 수 있습니다.
Anthropic의 구조화된 출력(Structured Output) 기능 오픈 베타 블로그
구조화된 출력(Structured Output) 기능 관련 개발 문서
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 