Claude 구조화 출력으로 JSON 깨짐 없애는 법

Claude JSON 깨짐은 tool use의 input_schema로 출력 형태를 정의하고 tool_choice로 도구 호출을 강제하면 거의 막을 수 있습니다. 설계법을 정리했습니다.

조회 55
Claude 구조화 출력으로 JSON 깨짐 없애는 법

핵심 요약

  • input_schema로 출력 스키마를 정의하고 tool_choice로 호출을 강제한다
  • 강제 호출 시 tool_use 블록의 input만 꺼내 쓰면 파싱이 끝난다
  • 엄격 모드는 지원 스키마 제약이 있어 의미 검증은 코드와 사람이 맡는다

Claude의 JSON 깨짐은 두 가지로 거의 막을 수 있습니다. 하나는 tool use의 input_schema로 출력 형태를 정의하는 것이고, 다른 하나는 tool_choice로 그 도구 호출을 강제하는 것입니다. Anthropic Tool use 문서에 따르면 input_schema를 쓰면 모델이 스키마에 맞는 JSON 인자를 만들도록 유도할 수 있습니다. tool_choice로 특정 도구를 강제하면 자유 텍스트 응답이 섞이는 일도 줄어듭니다. 이 글은 "이번 주 블로그 주제 5개 선정" 같은 반복 업무를 이 두 가지로 파이프라인에 넣는 설계를 정리합니다.

왜 JSON이 깨지는가

프롬프트에 "JSON으로만 답해 줘"라고 쓰는 방식은 확률적으로 동작합니다. 응답 앞에 "네, 아래와 같습니다" 같은 문장이 붙을 수 있습니다. 코드블록 펜스가 감싸지거나 필드명이 바뀔 수도 있습니다. 파서 입장에서는 모두 예외입니다. 그래서 재시도 로직이나 정규식 후처리가 계속 늘어납니다.

Anthropic의 출력 일관성 문서는 이 문제를 프롬프트 설계 관점에서 다룹니다. 원하는 출력 형식을 구체적으로 정의하라는 것이 핵심입니다. 다만 프롬프트만으로는 형식 준수를 보장하지 못합니다. 스키마를 API 파라미터로 넘기는 방식이 더 안정적인 이유입니다.

tool use로 스키마를 강제하는 구조

발상은 단순합니다. 모델에게 "답변을 써 줘"라고 하지 않고 "submit_topics 도구를 호출해 줘"라고 요청합니다. 도구의 input_schema가 곧 출력 스키마가 됩니다. 응답에서는 텍스트 대신 tool_use 블록의 input만 꺼내 쓰면 됩니다.

import anthropic

client = anthropic.Anthropic()

tool = {
    "name": "submit_topics",
    "description": "선정한 블로그 주제 후보를 제출한다.",
    "input_schema": {
        "type": "object",
        "properties": {
            "topics": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "title": {"type": "string"},
                        "category": {"type": "string",
                                     "enum": ["AI기술", "클라우드", "보안"]},
                        "priority": {"type": "integer"},
                        "reason": {"type": "string"}
                    },
                    "required": ["title", "category", "priority", "reason"],
                    "additionalProperties": False
                }
            }
        },
        "required": ["topics"],
        "additionalProperties": False
    }
}

resp = client.messages.create(
    model=MODEL,  # 사용 중인 모델 ID
    max_tokens=1024,
    tools=[tool],
    tool_choice={"type": "tool", "name": "submit_topics"},
    messages=[{"role": "user", "content": "이번 주 주제 5개를 골라 줘: ..."}],
)

data = next(b.input for b in resp.content if b.type == "tool_use")

여기서 enum이 실용적입니다. 카테고리를 자유 문자열로 두면 "AI", "인공지능", "AI기술"이 섞입니다. 목록으로 제한하면 이후 분기 처리가 쉬워집니다.

tool_choice로 자유 텍스트 차단

tool_choice를 지정하지 않으면 모델이 도구를 쓸지 말지 스스로 판단합니다. 그 경우 설명 문장만 돌아오거나 텍스트가 먼저 오고 도구 호출이 뒤따를 수 있습니다. Anthropic 문서에 따르면 특정 도구를 강제하면 자유 텍스트가 섞이는 것을 줄일 수 있습니다. 코드에서는 tool_use 블록을 찾는 한 줄로 파싱이 끝납니다.

방식 출력 형태 파싱 위험
프롬프트로 "JSON만" 요청 텍스트 앞뒤 문장, 펜스, 필드 변형
도구 정의만 하고 자동 선택 텍스트 또는 tool_use 도구 미호출 가능
도구 정의 + tool_choice 강제 tool_use 블록 낮음

강제 호출에서는 모델이 사고 과정을 텍스트로 풀어낼 자리가 없습니다. 판단 근거가 필요하면 reason 같은 필드를 스키마에 넣는 편이 낫습니다. 이 필드는 사람이 결과를 검토할 때도 도움이 됩니다.

최신 구조화 출력 기능과 스키마 제약

input_schema로 유도하는 방식과 별개로, Claude Platform에는 스키마 준수를 더 엄격하게 다루는 구조화 출력 기능이 있습니다. Claude Platform 구조화 출력 문서에 따르면 JSON 출력(output_config.format)과 엄격한 도구 사용(strict: true)이 있고, 둘은 표준 JSON Schema 중 일부만 지원합니다. 같은 문서에 따르면 다음 항목은 지원하지 않습니다.

  • 재귀 스키마
  • false 이외의 additionalProperties
  • 문자열 길이 제약(minLength, maxLength)
  • 0 또는 1을 넘는 minItems 같은 배열 제약

지원하지 않는 기능을 쓰면 문서상 400 오류와 상세 내용이 반환됩니다. 요청당 strict: true 도구는 문서 기준 최대 20개입니다. 엄격 모드에서는 모든 객체에 additionalProperties: false를 지정해야 합니다. Google Cloud 문서는 여기에 더해 모든 속성을 required에 나열하라고 안내합니다. 같은 문서에 따르면 엄격 모드가 아니면 "2"와 2처럼 타입이 어긋나거나 필수 필드가 빠질 수 있습니다.

지원 모델 목록은 문서가 갱신되므로 도입 전에 공식 문서의 최신 표를 확인하세요. 제약 때문에 못 쓰는 규칙은 필드 설명(description)에 적어 두는 방법이 있습니다. 공식 문서에 따르면 Python SDK의 transform_schema()가 지원하지 않는 제약을 설명으로 옮겨 주며, Pydantic 모델도 받습니다.

실천 가이드

반복 업무를 자동화할 때는 아래 순서가 무난합니다.

  1. 출력 항목을 먼저 표로 정리하고 필드명, 타입, 허용값을 정합니다. 정해진 값은 enum으로 닫습니다.
  2. 도구 하나에 스키마를 담고 tool_choice로 강제 호출합니다.
  3. 모든 객체에 additionalProperties: false를 넣고 required를 빠짐없이 채웁니다. 엄격 모드 전환에도 그대로 쓸 수 있습니다.
  4. 스키마가 보장하지 못하는 의미 검증은 코드에서 합니다. 예를 들면 우선순위 중복, 이미 쓴 주제와의 중복, 제목 길이 같은 것입니다. 문자열 길이 제약은 엄격 모드 스키마에서 지원하지 않으므로 코드 검증이 필요합니다.
  5. 새 스키마는 소량 입력으로 먼저 돌려 보고 실패 유형을 기록한 뒤 스키마와 설명을 고칩니다.

스키마는 형태를 보장할 뿐 내용의 정확성을 보장하지 않습니다. 주제 선정처럼 판단이 들어가는 일은 최종 선택을 사람이 확인하는 단계를 남겨 두세요. 파싱 오류가 사라진 자리에서는 내용 품질에만 집중하면 됩니다.

자주 묻는 질문

Q. 프롬프트로 JSON만 답하라고 하면 왜 안 되나요?

프롬프트 방식은 확률적으로 동작해 앞뒤 설명 문장, 코드블록 펜스, 필드명 변형이 섞일 수 있습니다. 스키마를 API 파라미터로 넘기는 방식이 더 안정적입니다.

Q. tool_choice를 지정하지 않으면 어떻게 되나요?

모델이 도구를 쓸지 스스로 판단하므로 설명 문장만 돌아오거나 텍스트가 먼저 오고 도구 호출이 뒤따를 수 있습니다. 특정 도구를 강제하면 자유 텍스트가 섞이는 것을 줄일 수 있습니다.

Q. 엄격한 구조화 출력에서 지원하지 않는 스키마 기능은 무엇인가요?

문서에 따르면 재귀 스키마, false 이외의 additionalProperties, minLength·maxLength 같은 문자열 길이 제약, 0 또는 1을 넘는 minItems가 지원되지 않습니다. 이를 쓰면 400 오류가 반환되므로 해당 규칙은 description이나 코드 검증으로 처리해야 합니다.

참고 자료

이 글은 웹 검색으로 확인한 위 출처를 바탕으로 AI(claude-sonnet-5-5)가 작성했습니다. 수치·가격은 출처 원문에서 다시 확인하세요.

#Anthropic API#Claude#input_schema#JSON#tool use#tool_choice#구조화 출력