7.3 JSON Mode 응답 강제 구조화
프롬프트를 통해 LLM의 출력을 제어한다는 것은 결국 "원하는 형태로 출력되도록 모델을 안내"하는 작업입니다. Chat Completions API는 기본적으로 자유 텍스트를 생성하지만, 많은 실제 응용 시나리오에서는 응답이 특정한 JSON 형식으로 구성되기를 기대합니다. 예를 들어, 응답이 아래와 같이 키-값 쌍으로 구조화되기를 원할 수 있습니다.
{
"summary": "이 문서는 기후 변화의 원인과 영향을 설명합니다.",
"keywords": ["기후 변화", "온실가스", "지구 온난화"]
}이런 요구를 반영하기 위해 OpenAI는 GPT-4 Turbo 모델을 포함한 최신 모델들에 ‘JSON mode’라는 옵션을 제공하며, 이를 사용하면 모델이 반환하는 응답 형태를 명시적으로 JSON으로 강제할 수 있습니다.
7.3.1 JSON Mode란?
JSON mode는 GPT의 응답이 반드시 JSON 객체가 되도록 강제하는 출력 제약 옵션입니다. Chat Completions API의 호출 시, response_format 파라미터를 "json"으로 설정함으로써 이 기능을 활용할 수 있습니다.
기본 호출 형태 예시:
response = client.chat.completions.create(
model="gpt-4-1106-preview",
messages=[
{"role": "system", "content": "You are a data extraction assistant. Always output JSON."},
{"role": "user", "content": "Extract the name and age from this sentence: Sarah is 35 years old."},
],
response_format="json" # 키 포인트
)이 설정을 하면 모델은 반드시 유효한 JSON 응답만 반환하고, JSON 이외의 포맷은 거부하게 됩니다. 메시지에서 출력 형식을 지시하는 것과 달리, 이건 엔진 레벨의 출력 제한입니다.
7.3.2 일반 프롬프트 대비 JSON Mode의 차이
출력 제약
구조 없음
JSON으로만 출력 강제
오류 가능성
포맷 불일치, 누락, JSON 파싱 오류
JSON이 아니면 오류 발생
유효성 검증
후처리 필요
API 차원에서 JSON 유효성보장
활용 사례
자연어 응답 등 자유로운 응답
구조화된 응답, API 응답 구성 등
7.3.3 JSON Mode의 한계 및 특징
✅ 강제 JSON: 모델은 반드시 유효한 JSON 객체를 반환해야 합니다. 문자열 같은 유사 JSON은 허용되지 않습니다.
❌ 자연스러운 언어 섞기 불가: JSON 밖의 자유텍스트는 허용되지 않습니다. 예: "Sure, here is the JSON:" 같은 프리앰블 문장이 들어가면 실패합니다.
⚠️ 모델 버전 요구 주의: GPT-4 Turbo 계열(예: gpt-4-1106-preview, gpt-3.5-turbo-1106) 이상만 JSON mode를 지원합니다. 구버전에서는 동작하지 않습니다.
7.3.4 JSON Mode 활용 실전 예제
예제 1: 문서 정보 추출기 구성
사용자 입력 텍스트에서 문서 요약, 키워드, 감정 점수 등을 추출합니다.
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
model="gpt-4-1106-preview",
response_format="json",
messages=[
{"role": "system", "content": "You are an assistant that extracts metadata from documents. Output key-value pairs in JSON only."},
{"role": "user", "content": "아래 텍스트에서 핵심 정보만 추출해줘: 오늘 삼성전자는 주가가 3% 상승하며 반도체 시장의 회복 신호를 보였습니다."}
]
)
print(response.choices[0].message.content)🔎 예상 출력 결과:
{
"summary": "삼성전자의 주가가 3% 상승하며 반도체 시장의 회복 신호가 나타남.",
"company": "삼성전자",
"change": "+3%",
"sector": "반도체"
}예제 2: 사용자 입력을 명령어 구문으로 파싱
기술적 명령 인식을 위한 JSON 대응 구조 생성
response = client.chat.completions.create(
model="gpt-4-1106-preview",
response_format="json",
messages=[
{
"role": "system",
"content": "너는 문장을 명령어로 분석하는 봇이야. 입력을 명확한 JSON 포맷으로 분석해. 자유 텍스트를 포함하면 안 돼."
},
{
"role": "user",
"content": "메모장에서 '일정 정리하기.txt' 파일 열고, 오늘 해야 할 일부터 정리해줘."
}
]
)
print(response.choices[0].message.content)🔎 예상 출력:
{
"command": "open_file",
"application": "메모장",
"filename": "일정 정리하기.txt",
"action": "정리",
"note_type": "오늘의 할 일"
}7.3.5 JSON Mode 실수 방지 팁
✅ 필수 메시지 안내
System 메시지에 반드시 “JSON으로만 응답”을 명확히 포함시키세요.
⚠️ 프롬프트 내 출력 샘플
JSON 예시는 포함하되, 언어적 설명 없이 최소한으로 포함시키세요.
⚠️ Chat UI 사용 주의
Playground나 ChatGPT에서는 response_format 옵션이 동작하지 않습니다. REST 또는 SDK 환경에서만 테스트해야 합니다.
❌ 포함 불가 표현
아래 표현이 응답에 포함되지 않도록 유의하세요: “Sure, here is the response:”, “Output:” 등 불용 문자열
✅ JSON 유효성 검사
반환된 output을 json.loads()로 파싱하거나 유효성 검사기를 통해 확인하세요.
7.3.6 JSON Mode vs Function Calling vs 일반 출력 비교
출력 제약
없음
JSON 구조로 제한
함수 정의된 JSON 구조로 제한
후처리 필요
있음
보통 없음
없음 (Python 객체화 가능)
장점
자유로운 표현 가능
post-processing 없이 사용
정형 데이터 자동 실행 연동 용이
단점
구조 불일치 위험
model별 제한 / 설명 불가
복잡한 schema 정의 필요
활용 예
블로그 생성, 이메일 작성 등
데이터 추출, 명령어 변환
API 호출, DB 검색 등
7.3.7 JSON Mode와 Embedding, Function Call의 조합 활용
JSON 출력은 다른 기능과도 잘 결합할 수 있습니다.
✅ JSON + Embedding: 문서 분류 결과를 구조적으로 보관한 후, 해당 JSON을 Embedding으로 벡터화해 검색 키로 활용
✅ JSON + Function Call: JSON 출력 구조를 그대로 함수 호출 파라미터로 변환하여 서버 측 함수 호출 자동화 가능
7.3.8 예외 처리: JSON 오류가 발생했을 때
혹시라도 JSON Mode에서 유효한 JSON 형식이 아닌 출력이 발생할 경우, OpenAI는 아래와 같은 오류를 반환합니다.
{
"error": {
"message": "The model response was not valid JSON.",
"type": "invalid_response_format"
}
}이런 오류가 발생하는 경우:
모델이 출력 포맷을 지키지 않은 경우
Chat API 응답이 타임아웃되거나 분할된 경우
메시지에서 지시가 애매하거나 샘플 JSON이 잘못된 경우
🛠 해결 방법:
system 메시지를 더 명확히 작성 (예: "DO NOT say anything except valid JSON")
JSON 예제 간소화 및 핵심 키만 강조
적절한 샘플 입력과 출력 예를 포함해 few-shot 학습 유도
마치며
JSON Mode는 단순히 출력 포맷을 바꾸는 기능이 아니라, GPT API를 실제 프로그램 로직에서 신뢰성 있게 활용하기 위한 핵심 도구입니다. Function Calling이 콜 가능한 명령 중심이라면, JSON Mode는 일종의 구조화된 "응답 컨벤션"을 구성하는 방식입니다. 이를 통해 챗봇, 데이터 추출, 명령어 파싱, 분석 리포트 생성 등 수많은 서비스가 보다 안정적인 구조로 만들어질 수 있습니다. JSON Mode를 적절하게 활용한다면, LLM 기반 애플리케이션의 신뢰성은 획기적으로 높아질 것입니다.
Last updated