OpenAI API Structured model outputs 사용시 zod 관련 이슈

OpenAI ChatGpt

Structured model outputs

서론

Chatgpt API를 Node.js 환경에서 연동해야할 요청이 들어와 오랜만에 관련 API 를 연동하게 될 기회를 얻었습니다. 

몇년전과 달리 JSON 구조화하여 Response 해주는  Structured model outputs 기능이 2024년 8월부터 제공되고 있음을 확인했습니다. ( 단, 모든 모델은 아니고 gpt-4o 이상부터 가능) 

관련 링크 : https://platform.openai.com/docs/guides/structured-outputs#page-top

 

과거엔 프롬프트나 function Call, 단순 스크립트 처리 등을 통해 JSON을 출력했던 기억이 있었는데 이게 기능으로도 따로 제공하고 있었습니다. 

모델 출력이 무조건 JSON Schema 형식과 일치하도록 강제함으로써 신뢰성 높은 API 응답 보장하게 되어 좀 더 안정적으로 제공할 수 있을 것 같습니다.

하지만 Structured model outputs 또한 완벽하진 않기에 항상 안좋은 출력물이 나올 것을 대비하는건 크게 다르진 않을 것 같습니다만 결과적으로 안전필터가 하나 더 생긴 것 같아 다행입니다. 

잘만 되면 말이죠.

라이브러리는 참 잘만되면 최고인데 안되면 또 그것만큼 답답한게 없습니다. 

때문에 어렵지 않은거라면 왠만하면 만들어 쓰려고 노력은 하고 있지만 한정된 시간에 모든걸 만들 순 없다보니 라이브러리를 쓸 수 밖에 없죠.

이번 이슈의 경우 후자에 가깝습니다.

기본 예제대임에도 불구하고 안되다보니 원인파악 및 해결을 위한 시간이 꽤나 낭비된 상황이다보니 이를 기록하여 많은 분들에게 도움이 되었으면 합니다. 

해당 글에서는 업무에서 해당 기능을 적용하는 과정에서 발생된 이슈사항에 대해 안내드리고 이를 해결하기 위한 방안에 대해서도 공유드리고자 합니다. 

우선 사용법부터, 관련 내용부터 같이 확인하겠습니다. 

Quick Start

OpenAI 에서 제공하는 가장 기본 예제는 아래와 같습니다. 

import OpenAI from "openai";
import { zodTextFormat } from "openai/helpers/zod";
import { z } from "zod";

const openai = new OpenAI();

const CalendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const response = await openai.responses.parse({
  model: "gpt-4o-2024-08-06",
  input: [
    { role: "system", content: "Extract the event information." },
    {
      role: "user",
      content: "Alice and Bob are going to a science fair on Friday.",
    },
  ],
  text: {
    format: zodTextFormat(CalendarEvent, "event"),
  },
});

const event = response.output_parsed;

Python이였으면 클래스 내 맴버변수에 타입을 지정하는식으로 단순하지만, Javascript 진영 예제에서는 이를 대신하기위해 zod를 사용합니다. 

코드 자체는 단순합니다. 

기존 API 연동과의 차이점 총 두가지 입니다. 

1. openai.responses.create 를 사용하는게 아닌, openai.responses.parse를 사용합니다. 
2. parameter로 text.format을 지정합니다. 
   해당 과정에서 zod를 이용하여 JSON 타입을 지정합니다. 

위 코드의 실행을 위해 dependency 라이브러리를 설치합니다. 

latest 로 설치시 4버전대가 설치됩니다.

# PNPM
pnpm add openai zod

# YARN
yarn add openai zod

 

Zod

TypeScript/JavaScript용 스키마 선언 및 데이터 검증(Validation) 라이브러리

링크 : https://zod.dev

Intro | Zod

실행 및 이슈

const response = await openai.responses.parse 실행부분에서 에러 발생 

이슈 내용은 다음과 같습니다. 

{"status":400,"headers":{},"requestID":"req_1************","error":{"message":"Invalid schema for response_format 'event': schema must be a JSON Schema of 'type: \\"object\\"', got 'type: \\"string\\"'.","type":"invalid_request_error","param":"text.format.schema","code":"invalid_json_schema"},"code":"invalid_json_schema","param":"text.format.schema","type":"invalid_request_error"}

원인

text.format.schema에 JSON 형식으로 지정되어야 하는데 string으로 잘못된 타입으로 지정됨

근본적인 원인은 위에 명시된 내용이 맞지만, 기본 예제인데도 안되는건 문제가 되는게 맞죠.

현재 zodTextFormat이 SDK/버전 조합에 따라 잘못된 타입을 만들어 내는 이슈가 있음을 확인했습니다. 

https://github.com/openai/openai-node/issues/1597?utm_source=chatgpt.com

Responses API Structured Output - Invalid schema for response_format · Issue #1597 · openai/openai-node

 

해결

해결방안 3가지가 있습니다. 

첫번째 파이썬 사용

파이썬은 클래스 기반으로 빠르고 간결하게 구현이 가능합니다. 하지만 이번엔 Javascript 로 하기로 했으니 넘어가겠습니다. 

두번째 순정 JSON Schema 객체 구현

zodTextFormat 함수를 사용하지말고, format에 들어갈 순정 JSON Schema 객체를 직접 작성하면 해결될 수 있지만 나중에 수정이라도 일어난다면 저도 모르게 짜증이 날 것 같네요. 

혹여나 직접 객체구현을 원한다면 직접하는건 시간 투자가 많이 일어날 가능성이 높으므로 LLM의 도움을 받으시면 됩니다.

세번째 Major Version 낮춤 ( 권장 )

사실 빠르게 해결할 수 있는 다른 방안은 4버전이 아닌 3버전을 사용하는 겁니다. 

해당 4버전 이슈가 해결될때까진 안전하게 3버전을 사용하시는걸 사실상 권장드립니다. 

제가 사용하는 버전은 아래와 같습니다.

"zod": "^3.25.76"

 

3.25.76에서는 이상없이 잘 됨을 확인했습니다.