KSCOLD LogoKSCOLD
Blog
Feed
Product
Admin Night
Vault
Guestbook
Info

Vault 목록

Structured Output 정규화

연결된 노트와 함께 읽기

Structured Output 정규화

2026년 8월 28일

Structured Output 정규화

  • with_structured_output이 항상 스키마 인스턴스를 돌려주지 않는다. provider·모델·버전에 따라 반환 모양이 최소 네 가지다.
  • 이 경계가 없으면 유효한 모델 출력이 ValidationError로 버려진다 — 토큰을 쓰고도 Fail-soft 경로로 빠진다.

들어오는 네 가지 모양

모양언제
Schema 인스턴스정상
다른 BaseModel래퍼가 감싼 경우
envelope dict {raw, parsed, parsing_error}include_raw=True
message dict / AIMessage — content에 JSON 문자열Ollama가 파싱을 건너뛴 경우

정규화 함수

Python

model_validate와 model_validate_json을 나눠 쓰는 게 핵심이다. 앞은 dict를, 뒤는 JSON 문자열을 받는다.

지켜야 할 선 — 의미를 보정하지 않는다

의미를 보정하지 않는다. schema 필드 검증에 실패한 envelope의 content JSON을 같은 schema로 다시 검증할 뿐이며, 그래도 안 맞으면 원래 예외를 그대로 낸다.

MERMAID

허용되는 것: 모양(shape) 정규화 — 껍데기를 벗겨 같은 스키마로 다시 검증. 금지되는 것: 값 추측 — 빠진 필드 채우기, 정규식으로 값 뽑기, 기본값으로 대체.

정규식으로 억지로 값을 만들어 내면 모델이 안 한 판단을 코드가 한 것이 된다. 그게 실행을 유발하면 원인 추적이 불가능해진다 (Guardrails).

진단 정보를 남긴다

Python

원문을 통째로 로그에 남기지 않고 길이 + sha256 만 남긴다. 같은 실패가 반복되는지는 해시로 알 수 있고, 민감 정보는 안 남는다.

한 줄 정리

정규화는 모양만 통일하고 의미는 절대 만들지 않는 경계다. 실패는 진단 가능한 형태로 호출자에게 넘긴다.

관련

  • with_structured_output
  • Structured Output
  • Pydantic v2 메서드 사전
  • JSON Schema
  • Ollama
  • Fail-soft
  • Guardrails
  • AI Pipeline Error Normalization
  • hashlib과 결정적 ID

Synapse Map Insight

def coerce_structured_output(raw: object, schema: type[ModelT]) -> ModelT: """structured output의 provider별 반환 모양을 schema 인스턴스로 정규화한다.""" if isinstance(raw, schema): return raw if isinstance(raw, BaseModel): raw = raw.model_dump() if isinstance(raw, dict): if _is_include_raw_envelope(raw): parsed = raw.get("parsed") if parsed is not None: return coerce_structured_output(parsed, schema) return coerce_structured_output(raw.get("raw"), schema) try: return schema.model_validate(raw) except ValidationError: # 파싱되지 않은 message envelope — content의 JSON 본문을 다시 검증 content = raw.get("content") if isinstance(content, str) and content.strip(): normalized, _ = canonicalize_missing_json_values(content) return schema.model_validate_json(normalized) raise content = getattr(raw, "content", None) if isinstance(content, str) and content.strip(): normalized, _ = canonicalize_missing_json_values(content) return schema.model_validate_json(normalized) raise TypeError("structured output이 schema 인스턴스, dict, JSON content 중 어느 모양도 아님")
raise ValueError( "structured output provider envelope rejected" f": parser={error_type or 'unknown'}" f": detail={error_text or '<empty>'}" f": raw_content_chars={diagnostics['raw_content_chars']}" f": raw_content_sha256={diagnostics['raw_content_sha256']}" ) from exc