구조화된 출력 (Structured Outputs)
구조화된 출력 (Structured Outputs)
AI가 만든 결과를 프로그램이 그대로 처리해야 할 때, 응답이 늘 같은 형태로 오지 않으면 파싱부터 어려워져요. 구조화된 출력은 모델의 JSON 출력을 강제로 일관된 스키마에 맞추는 Cerebras Inference API의 기능이에요.
왜 유용할까요
구조화된 출력은 AI가 생성한 데이터를 프로그램적으로 처리해야 하는 애플리케이션에서 특히 유용해요. 장점은 이렇게 정리할 수 있어요.
- 변동성 감소 — 미리 정의한 필드에 맞춰 출력이 늘 일관돼요.
- 타입 안전성 — 올바른 데이터 타입을 강제해서 불일치를 막아줘요.
- 파싱과 통합이 쉬워짐 — 추가 처리 없이 애플리케이션에서 바로 쓸 수 있어요.
스트릭트 모드 (Strict Mode)
스트릭트 모드는 모델의 출력이 내가 제공한 JSON 스키마와 정확히 일치함을 보장해요. strict를 true로 설정하면 Cerebras가 토큰 수준에서 제한 디코딩(constrained decoding)을 적용해서 스키마를 지키도록 강제하고, 잘못된 출력은 만들어질 수 없어요.
스트릭트 모드를 쓰지 않으면 이런 문제가 생길 수 있어요.
- 파싱에 실패하는 잘못된 형태의 JSON
- 누락된 필수 필드
16대신"16"같은 잘못된 데이터 타입- 스키마에 정의되지 않은 추가 필드
스트릭트 모드를 쓰면 얻는 건 이래요.
- 보장된 유효 JSON
- 스키마 준수 — 모든 필드가 사양과 일치
- 타입 안전성 — 모든 속성의 데이터 타입이 정확
- 재시도 불필요 — 스키마 위반에 대한 오류 처리가 사라짐
스트릭트 모드 켜기
response_format 설정 안에서 strict를 true로 지정해요.
스트릭트 모드 스키마 요구사항
스트릭트 모드를 쓸 때는 스키마의 모든 객체에 additionalProperties: false를 설정해야 해요. 이건 반드시 지켜야 하는 요구사항이에요.
스키마 참조와 정의
JSON 스키마 안에서 $ref와 $defs를 함께 쓰면 재사용 가능한 스키마 컴포넌트를 정의할 수 있어요. 반복을 피하고 더 유지보수하기 쉬운 스키마를 만들 때 유용해요.
지원되는 스키마
구조화된 출력은 JSON Schema의 일부를 지원해요. 모든 스키마는 다음 규칙을 따라야 해요.
- 루트는 객체 — 최상위 스키마는
"type": "object"여야 해요. - 추가 속성 금지 — 스키마의 모든 객체에
"additionalProperties": false를 설정해야 해요.
지원되는 기능은 이러해요.
- 중첩 구조 — 중첩 속성을 가진 복잡한 객체
- 필수 필드 — 반드시 존재해야 하는 필드 지정
- 열거형 (값 제약) —
enum키워드로 필드가 가질 수 있는 정확한 리터럴을 화이트리스트로 지정 - 스키마 참조 —
$ref와$defs로 재사용 가능한 컴포넌트 정의 - 튜플 검증 — 배열에
prefixItems와 함께items: false사용 - 숫자 제약 —
minimum,maximum,exclusiveMinimum,exclusiveMaximum,multipleOf로number와integer값 제한
스트릭트 모드에서 지원하지 않는 JSON Schema 기능도 있어요. 아래의 제약·한계·미지원 기능에 대한 자세한 내용은 지원 스키마 섹션에서 확인할 수 있어요.
키 순서
생성된 JSON 출력의 키는 스키마에 정의한 순서대로 나타나요.
Pydantic과 Zod 활용하기
JSON 스키마를 손으로 짜는 대신, Python에서는 Pydantic, JavaScript에서는 Zod를 써서 스키마를 만들 수 있어요. Pydantic의 model_json_schema와 Zod의 zodToJsonSchema 메서드가 JSON 스키마를 생성해 주고, 그걸 API 호출에 그대로 사용하면 돼요.
JSON 모드 (JSON Mode)
JSON 모드는 구조화된 출력의 대안으로, 특정 스키마를 강제하지 않고 JSON 응답을 생성해요. 모델이 프롬프트 맥락을 바탕으로 어떤 필드를 포함할지 결정해요. response_format 파라미터를 json_object로 설정하고, 메시지에 JSON 형식으로 응답하라는 지시를 포함하면 돼요.
구조화된 출력은 스키마 준수를 보장하고, JSON 모드는 보다 자유로운 JSON 생성을 제공한다는 점에서 차이가 있어요.
정리하면
JSON 스키마 기반의 구조화된 출력은 AI 생성 결과가 일관되고 예측 가능한 형태를 유지하게 해줘요. 예상치 못한 데이터 구조나 누락된 필드에 신경 쓰지 않고 프로그램적으로 처리하는 안정적인 애플리케이션을 만들기 좋아요.