Read Original
#Frontend

사람도 기계도 읽는 규약: 예측 가능한 AI 제품 만들기

사람도 기계도 읽는 규약: 예측 가능한 AI 제품 만들기
01

Summary

제멋대로인 AI 출력, '스키마' 하나로 100% 통제하는 법

OpenAI Structured Outputs와 Zod를 활용해 예측 가능한 AI 제품을 설계하는 실전 가이드

LLM이 내뱉는 무작위한 결과값 때문에 골머리를 앓고 계신가요? 본 아티클은 단순한 프롬프트 지시를 넘어, 스키마를 통해 생성 단계부터 데이터 형식을 강제하고 런타임 검증까지 연결하는 '단일 규약' 전략을 제시합니다. 이미지 분해 도구 'Prism Lens'의 개발 사례를 통해 비용 절감과 신뢰성 확보라는 두 마리 토끼를 잡은 노하우를 확인해 보세요.

  • 01프롬프트 지시만으로는 부족한 AI 출력의 한계를 스키마 강제로 해결
  • 02OpenAI Structured Outputs(strict) 도입으로 스키마 준수율 100% 달성
  • 03Zod 스키마 하나로 생성, 검증, 타입을 동시에 관리하는 '단일 규약' 아키텍처
  • 04신뢰 경계(Trust Boundary) 설정을 통한 AI 영역과 일반 로직의 깔끔한 분리
  • 05분류 로직 최적화로 API 호출 횟수를 최대 90% 이상 획기적으로 절감

RECOMMENDATION

LLM의 응답 불안정성으로 프로덕션 배포를 고민하거나 AI API 비용 최적화가 필요한 엔지니어에게 강력히 추천합니다. 특히 런타임 타입 안정성을 중시하는 프론트엔드 개발자라면 Zod와 연동한 스키마 설계 기법을 실무에 바로 적용해 보시기 바랍니다.

The Problem

AI 모델에 JSON 형식을 지정하더라도 프롬프트 지시만으로는 스키마를 벗어난 예외적인 값이 출력되는 등 결과의 예측 가능성이 떨어지는 문제가 발생했습니다. 단순히 런타임에서 예외 처리를 하는 방식은 데이터의 오류를 근본적으로 막지 못하고 잘못된 의미가 시스템 내부로 유입되는 한계가 있었습니다.

The Solution

OpenAI의 Structured Outputs(strict 모드)를 도입하여 생성 단계에서부터 Zod 기반의 JSON 스키마를 강제함으로써 모델이 정의된 목록 외의 값을 생성하지 못하도록 차단했습니다. 또한, 스키마 검증(parse)을 기준으로 AI 영역과 일반 코드 영역 사이의 '신뢰 경계'를 설정하여 내부 로직이 무결한 데이터만 처리하도록 아키텍처를 구조화했습니다.

The Result

OpenAI 자체 평가 기준 스키마 준수율을 40%에서 100%로 끌어올렸으며, 기하학적 정보 기반의 분류 로직 개선을 통해 이미지 분해 시 발생하는 API 호출 횟수를 기존 대비 약 90% 이상(최대 40회에서 1~2회로) 절감하는 성과를 거두었습니다.

Trade-off

엄격한 스키마 강제는 모델의 유연한 응답을 제한할 수 있으며, Zod 스키마를 JSON Schema로 변환하고 관리하는 추가적인 공수가 필요합니다. 본문에서는 언급되지 않았으나 strict 모드 사용 시 지원되지 않는 JSON Schema 키워드에 대한 제약 사항이 존재할 수 있습니다.

03

Key Concepts

Concept · 01

OpenAI Structured Outputs

모델이 제공된 JSON 스키마를 100% 준수하여 응답하도록 보장하는 OpenAI의 API 기능입니다.

  • strict 모드를 활성화하여 모델이 스키마에 정의되지 않은 값을 생성하지 못하도록 강제합니다.
  • 프롬프트 지시 방식보다 훨씬 높은 데이터 정확도와 구조적 일관성을 제공합니다.
Concept · 02

Zod

TypeScript-first 스키마 선언 및 런타임 검증을 지원하는 라이브러리입니다.

  • 코드 레벨에서 데이터의 형태를 정의하고, AI의 출력값이 이 형태에 맞는지 검증하는 런타임 게이트 역할을 합니다.
  • 정의된 스키마를 JSON Schema로 변환하여 OpenAI API에 전달하는 매개체로 사용되었습니다.
Concept · 03

신뢰 경계 (Trust Boundary)

시스템 내부에서 외부의 검증되지 않은 데이터가 안전한 데이터로 변환되는 명확한 지점입니다.

  • schema.parse()가 실행되는 지점을 경계로 삼아, 그 이후의 앱 로직은 데이터의 무결성을 의심하지 않고 수행됩니다.
  • AI의 불확실성을 특정 지점에 가두어 전체 시스템의 예측 가능성을 높이는 핵심 전략입니다.