JSON Schema 기반 100% 규격 준수 구조화 출력(Structured Outputs) 실무 적용기
LLM이 임의의 텍스트 대신 백엔드 API 규격에 완벽히 들어맞는 타입 세이프 JSON을 반환하도록 보장하는 실전 가이드입니다.
홍은선 연구원
HongLabAI AI 엔지니어링 리드
📌실무 핵심 요약 (Key Engineering Takeaways)
- ✔JSON Schema(Zod)를 LLM response_format에 전달하면 문법 위반 토큰 생성이 원천 차단됨
- ✔복잡한 중첩 객체(Nested Objects)와 배열, Enum 값도 100% 보장
- ✔파싱 에러로 인한 재호출 비용 및 지연시간(Latency) 제로화
서비스 운영 환경에서 LLM의 가장 큰 골칫거리는 응답 형식의 불확실성입니다. 아무리 "JSON으로만 답해줘"라고 지시해도 줄바꿈, 백틱(```), 불필요한 서문이 포함되어 파싱 에러(JSON.parse SyntaxError)가 발생하는 경우가 잦습니다.
HongLabAI에서는 공식 Structured Outputs(JSON Schema 문법 제약)을 적용하여, 파싱 에러율을 0.00%로 낮춘 아키텍처를 프로덕션에 적용하고 있습니다.
이 방식은 토큰 샘플링 단계에서 허용되지 않는 토큰 생성을 수학적으로 차단(Constrained Decoding)하기 때문에 재시도 로직 비용을 90% 이상 절감할 수 있습니다.
🔄엔지니어링 아키텍처 흐름도 (Architecture Workflow)
import { z } from "zod";
import { generateObject } from "ai";
import { openai } from "@ai-sdk/openai";
// 1. 반환받을 출력 형태를 Zod 스키마로 선언
const ConsultationResultSchema = z.object({
feasibilityScore: z.number().min(0).max(100),
recommendedStack: z.array(z.string()),
estimatedWeeks: z.number(),
coreRisks: z.array(z.string()),
suggestedNextSteps: z.array(z.string()),
});
// 2. LLM 호출 시 스키마를 주입하여 100% 검증된 결과 도출
export async function analyzeProject(description: string) {
const { object } = await generateObject({
model: openai("gpt-4o-mini"),
schema: ConsultationResultSchema,
prompt: `다음 프로젝트 요구사항을 분석하고 기술적 타당성을 진단하세요: ${description}`,
});
return object; // 완벽한 타입 추론 보장!
}💬트리 구조 기술 토론 (2)
해당 주제에 관한 질의응답 및 피드백은 계층형 트리 댓글로 정리됩니다.
기존에 정규식으로 JSON만 발라내던 방식 쓰다가 스키마 강제로 바꾸고 나니 프로덕션 에러 로그가 완전히 사라졌습니다. 특히 Enum 강제 기능이 정말 유용하네요.
맞습니다! 특히 Vercel AI SDK의 generateObject와 결합하면 프론트엔드부터 DB까지 완전한 단일 타입 체인을 구축할 수 있어 생산성이 크게 올라갑니다.
혹시 deepseek나 로컬 vLLM 모델에서도 동일한 JSON Schema 제약이 가능한가요?
네! vLLM에서는 outlines 라이브러리를 내장하고 있어 `guided_json` 파라미터로 동일하게 Constrained Decoding을 지원합니다.