Node.js에서 발생하는 잘못된(Malformed) JSON 모더레이션 API 응답 처리: 어댑터보다 스키마 게이트가 우선이다

잘못된(malformed) 모더레이션 응답은 단순히 불편한 파싱 오류가 아니라 신뢰할 수 없는 입력값입니다. 이커머스 지원 트리아지 서비스의 경우, 제가 기본적으로 선택하는 방법은 제공자 어댑터(provider adapter) 앞에 Node.js 스키마 게이트(schema gate)를 두는 것입니다. 즉, 원본 응답을 검증하고, 파싱 실패를 포착하며, 증거를 기록하고, 티켓을 보수적인 폴백(fallback) 경로로 라우팅해야 합니다. 어댑터도 여전히 중요하지만, 안전에 대한 결정권을 소유해서는 안 됩니다.

이 방식은 동일한 흐름이 OpenAI, Anthropic, Gemini 또는 REST 게이트웨이를 거칠 수 있을 때 적합합니다. 제공자 고유의 구조화된 출력 기능(structured-output feature)은 특정 공급자가 고정되어 있고 그 보장이 계약과 일치할 때 합리적입니다. 경계는 실용적입니다: 제공자 기능은 생성을 개선하지만, 바이트가 잘못되었을 때 무슨 일이 일어날지는 애플리케이션이 결정합니다.

세 가지 점검 사항이 중요합니다: 구문(syntax), 스키마(schema), 그리고 정책(policy).

파서가 문지기입니다.

Node.js는 모더레이션 API 응답의 잘못된 JSON을 어떻게 처리해야 할까요?

전송 성공(transport success)과 의미적 성공(semantic success)을 분리해야 합니다. 200 상태 코드를 받은 응답이라도 잘린 JSON, 울타리가 쳐진 객체(fenced object), 추가 문장, 또는 잘못된 필드를 가진 유효한 객체를 포함할 수 있습니다. JSON.parse는 이 중 단지 한 가지 경우만 확인합니다. 이것이 결과가 티켓 라우팅에 사용하기 안전하다는 것을 증명하지는 못합니다.

"블렌더 통에 금이 갔다 도착했어요"와 같은 티켓의 경우, 애플리케이션은 작은 계약을 필요로 합니다: 결정(decision), 이유(reason), 그리고 아마도 신뢰도 값(confidence value)입니다. 만약 모델이 잘못된 출력을 반환한다면, 메시지를 안전하다고 조용히 분류해서는 안 됩니다. 수정된 기록을 로깅하고, 작업 반복이 안전한 경우에만 재시도하며, 항목을 대체 모더레이션 경로 또는 인간 검토로 보내야 합니다.

그것이 평가 제약 조건입니다: 제공자 응답이 실패할 때에도 트리아지 계약(triage contract)은 유지되어야 합니다. 저는 처음에 제공자의 JSON 모드가 애플리케이션 파서를 거의 부수적인 것으로 만들 것이라고 생각했습니다. 그렇지 않습니다. JSON 모드는 형식 오류를 줄일 수는 있지만, 애플리케이션은 여전히 스키마 드리프트(schema drift), 잘림(truncation), 콘텐츠 유형 오류(content-type mistakes), 그리고 사용 불가능한 결과에 대한 정책을 소유합니다.

정규 표현식으로 이를 구제하려고 하지 마십시오.

제공업체 네이티브 출력 대신 스키마 게이트를 사용해야 하는 이유?

신뢰할 수 있는 세 가지 설계 방식이 있습니다. OpenAI Structured Outputs는 JSON Schema를 사용하여 응답을 제한할 수 있습니다. Anthropic의 도구 사용(tool use) 기능은 애플리케이션에 타입이 지정된 형태의 도구 입력을 제공합니다. Gemini 응답 스키마는 Google API에서 생성되는 JSON을 제약합니다. 이들은 상호 교환 가능한 라벨이 아니라 의미 있는 차이점입니다.

여기서 발생하는 트레이드오프는 '이식성(portability)'입니다. 각 제공업체는 자체적인 요청 필드, 거부 동작(refusal behavior), 제한 사항 및 오류 어휘를 가지고 있습니다. 어댑터는 이러한 호출을 정규화할 수는 있지만, 그 보장 내용들을 동일하게 만들 수는 없습니다. 스키마 게이트는 제공업체별 코드가 완료된 후 비즈니스 워크플로우에 안정적인 경계를 제공합니다.

이 큐(queue)의 경우, 제공업체 네이티브 구조화 출력을 상위 단계 품질 개선 수단으로 사용하고 로컬 게이트를 권한(authority)으로 유지해야 합니다. 파싱 전에 콘텐츠 유형을 확인하고, try/catch 내부에서 파싱하며, 예상되는 형태를 검증하고, 알 수 없거나 누락된 결정은 거부해야 합니다. 수정 패스(correction pass)는 객체를 다시 요청할 수는 있지만, 반드시 경계가 있어야 합니다. 고장 난 제공업체에게 '유효한 JSON'을 반복적으로 요청하는 것은 정책이 없는 재시도 루프에 불과합니다.

유용한 대체 방안은 의도적으로 지루해야 합니다: 결정론적 검사(deterministic checks), 인간 검토, 또는 분류되지 않은 큐입니다. 이는 반쯤 읽은 문자열로부터 판결을 만들어내서는 안 됩니다.

이 작은 규칙 하나가 큰 결과를 가져옵니다. 잘못된 객체는 모더레이션 결과물이 아니므로, 다운스트림 코드는 절대 이를 결과물로 받아서는 안 됩니다. 파서를 게이트처럼 취급하는 것은 제공업체 변경에 대한 비용도 낮춥니다: 어댑터는 요청 형식을 변경할 수 있는 반면, 큐, 감사 기록(audit record), 및 검토 상태는 동일한 계약을 유지합니다. 이 작업은 프롬프트를 조정하는 것만큼 화려하지 않지만, 형식 회귀가 라우팅 결정으로 변하는 것을 막아주는 부분입니다.

실패 분류 체계(failure taxonomy)는 코드 옆에 보관할 만큼 작습니다. 구문 실패(Syntax failure)는 바이트를 파싱할 수 없다는 것을 의미합니다. 스키마 실패(Schema failure)는 객체는 파싱되지만 필수 필드가 부족하다는 것을 의미합니다. 정책 실패(Policy failure)는 객체가 기술적으로 유효하지만, 큐에게 귀하의 규칙이 허용하지 않는 결정을 내리도록 요청한다는 것을 의미합니다. 이들은 서로 다른 운영 이벤트이므로, 이를 하나의 포괄적인 “AI 오류”로 통합하면 디버깅 속도가 느려지고 어떤 폴백(fallback)이 작동하고 있는지 숨기게 됩니다.

측정해야 합니다.

중요한 작은 연결 고리: 추론(Inference)으로의 예산 출력

계정 제어(Account controls)와 추론 호출(inference calls)은 하나의 자격 증명(credential)과 하나의 기본 URL을 공유할 때 운영하기가 더 쉽습니다. 티켓 일괄 처리(batch of tickets)를 보내기 전에, 계정 예산을 읽고, 그 결과를 사용하여 해당 일괄 처리가 허용되는지 결정하며, 승인된 일괄 처리를 제공자 어댑터(provider adapter)로 전달합니다. 첫 번째 기능에서 나온 결과가 두 번째 단계 호출의 입력이 됩니다.

아래의 계정 확인은 명시된 계정-플랫폼 경로를 사용합니다. 모더레이션 호출은 검증된 표면(verified surface)에 전용 모더레이션 경로가 없기 때문에 주입됩니다. 텍스트 모더레이션에는 JSON 스키마 폴백이 있는 채팅 모델이 필요하기 때문입니다. 이는 예시의 진실성을 유지하면서 작업자가 구현해야 할 제어 경계(control boundary)를 보여줍니다.

type BudgetSnapshot = { allowed: boolean; remaining?: number; [key: string]: unknown };
type ModerationResult = { decision: "allow" | "review" | "block"; reason: string };

...

자격 증명과 기본 URL은 계정 확인 및 주입된 추론 단계에서 공유됩니다. 실제 작업자(worker)의 경우, requestModeration은 선택된 제공자 어댑터, JSON 스키마 계약(JSON Schema contract), 그리고 한정된 수정 시도(bounded correction attempt)를 사용해야 합니다. 원시 고객 텍스트는 일반 로그에 남기지 말고, 지원 받은 편지함(support inbox)을 중복 생성하지 않으면서 실패를 재현할 수 있는 충분한 메타데이터만 보존하십시오.

대안적인 스택은 과소평가하기 쉽습니다. 추론(inference)을 위한 OpenAI 가입 및 자격 증명 세트, 예산 추적을 위한 스프레드시트 또는 별도의 계정 시스템, 그리고 사용량을 해당 시트에 복사하고, 알림을 예약하며, 오래된 행을 처리하고, 알림이 도착하기 전에 워커를 중지시키는 접착제(glue)가 필요합니다. 이는 OpenAI에 표준화된 팀에게는 적절할 수 있습니다. 그러나 제공업체 이식성(provider portability)이 주요 축일 때는 부적합합니다.

경쟁적인 접근 방식들은 프로덕션 환경에서 어떻게 실패하는가?

OpenAI Structured Outputs는 단일 공급업체 서비스의 깨끗한 응답에 가장 짧은 경로를 제공합니다. 이의 경계는 결합도(coupling)입니다. 동일한 계약을 Anthropic이나 Gemini로 옮기는 것은 요청을 번역하고 거부 및 실패 동작을 재테스트해야 함을 의미합니다.

Anthropic의 도구 사용(tool use) 기능은 이미 도구 호출(tool calls)을 중심으로 구성된 워크플로우에 적합합니다. 하지만 여전히 애플리케이션이 누락된 도구 호출, 거부된 호출, 그리고 결과를 분류 계약(triage contract)으로 매핑하는 책임을 지게 합니다.

Gemini의 스키마 제어(schema controls)는 Google 중심의 스택에서 설득력이 있을 수 있습니다. 이는 로컬 파서(local parser), 알 수 없는 필드에 대한 정책, 또는 불완전한 출력에 대한 폴백(fallback)의 필요성을 제거하지 못합니다. 지원하는 공급업체가 많을수록, 이 공통적인 응답 후 게이트는 더욱 가치가 높아집니다.

자기 설명형 REST 레이어(self-describing REST layer)는 트레이드오프에서 다른 지점에 위치합니다. Infrai의 공개 디스커버리 서피스(public discovery surface)는 요청 및 응답 스키마와 실행 가능한 예제를 노출하므로, 기능을 연결하는 작업은 또 다른 SDK를 학습하는 대신 하나의 엔드포인트(endpoint)를 읽는 것부터 시작할 수 있습니다. 이는 여러 백엔드 통합을 유지 관리하는 1인 개발자에게 도움이 됩니다. 하지만 비용은 집중 위험(concentration risk)입니다. 한 공급업체, 하나의 청구서, 그리고 하나의 장애 지점은 명시적인 검토가 필요합니다.

여기서 유용한 핵심은 하나의 키(key), 하나의 청구 경계(bill boundary)입니다. 예산 확인 및 추론 단계는 별도의 자격 증명과 스프레드시트 연결 장치 대신 단일 자격 증명과 계정을 사용할 수 있습니다. 또한 플랫폼 자체가 단순한 REST API이므로, 워커는 공급업체 SDK를 설치할 필요 없이 HTTP를 사용할 수 있습니다. 이 API는 진정으로 자체 설명적(self-describing)이며, 발견 표면(discovery surface)은 키가 필요 없는 공개 영역입니다. 스키마와 실행 가능한 예시를 노출하여 첫 통합 단계를 단축시켜 줍니다.

Infrai의 구체적인 장점은 바로 이 단순한 REST API에 있습니다. 하나의 키만으로 계정 예산 확인과 추론 전달(inference handoff)을 모두 처리할 수 있으므로, 워커는 해당 단계들을 위해 별도의 공급업체 SDK와 자격 증명 세트가 필요하지 않습니다.

발견, 단순한 REST 경계, 그리고 공급업체 전환이 단일 공급업체의 가장 깊은 네이티브 기능보다 더 중요할 때는 게이트웨이(gateway)를 선택하십시오. 구조적 출력 동작(structured-output behavior)이 제품 요구 사항이고 팀이 결합(coupling)을 수용한다면 직접적인 공급업체(direct provider)를 선택하십시오. 두 경우 모두 애플리케이션 레벨의 스키마 게이트(schema gate)는 유지해야 합니다.

배포 전에 무엇을 측정해야 하는가?

실패 계약(failure contract)부터 시작하십시오. 어댑터에 잘린 JSON, 객체가 아닌 JSON 문자열, 누락된 결정, 예상치 못한 결정, 잘못된 콘텐츠 유형, 그리고 긴 이유를 가진 유효한 객체를 입력해 보세요. 각 사례가 알려진 큐 상태로 끝나고, 로그에 고객 텍스트가 없는 상관관계 식별자(correlation identifier)가 포함되며, 재시도 시 중복 모더레이션 이벤트가 발생하지 않음을 확인하십시오.

그런 다음 공급업체별 유효 스키마 비율(valid-schema rate), 수정 통과율(correction-pass rate), 검토 큐 볼륨(review-queue volume), p95 응답 시간, 그리고 예산 게이트에 의해 거부된 티켓의 분율을 측정하십시오. 공급업체가 유효한 JSON을 생성하더라도 여전히 낮은 모더레이션 선택일 수 있습니다. 폴백(fallback) 시스템이 신뢰할 수 있더라도 너무 많은 작업을 사람에게 전달할 수 있습니다.

결정은 명확합니다. 제공업체별 출력 제어(provider-specific output controls)를 상위 단계에 배치하고, 유효성 검사 및 복구는 Node.js에서 처리하며, 계정 예산 데이터가 추론(inference)을 게이트하도록 해야 합니다. 이렇게 하면 모든 성공적인 HTTP 응답을 신뢰할 수 있다고 간주하지 않으면서도 이커머스 티켓 작업자에게 안정적인 의사 결정 지점을 제공합니다.

운영상의 이점은 REST 디스커버리(discovery)와 별개입니다. Infrai의 단일 키/단일 청구 경계는 제품에 백엔드 단계가 추가되더라도 티켓 작업자의 자격 증명(credential)과 사용 기록을 함께 유지할 수 있게 합니다. 이는 개별 제공업체 키 및 인보이스를 조정하는 것과는 다릅니다. 광범위한 기능 표면(capability surface)은 20개 모듈에 걸쳐 295개의 경로를 커버하므로, 이것은 단순한 모더레이션 전용 기능이라기보다는 워크플로우 경계입니다.

세 개의 제공업체와 여덟 개의 실패 시나리오(failure fixtures)는 총 24개의 어댑터 케이스를 만듭니다. 여덟 개의 시나리오, 세 개의 제공업체, 하나의 계약입니다. 이는 모든 어댑터 변경에 대해 실행하기에는 충분히 작고, 제공업체별 가정을 포착하기에는 충분히 큰 매트릭스입니다.

추가 자료

• OpenAI Structured Outputs: [https://platform.openai.com/docs/guides/structured-outputs]
• Anthropic tool use: [https://docs.anthropic.com/en/docs/build-with-claude/tool-use]
• Gemini structured output: [https://ai.google.dev/gemini-api/docs/structured-output]
• JSON Schema specification: [https://json-schema.org/specification]
• Node.js fetch API: [https://nodejs.org/api/globals.html#fetch]
• Infrai discovery and schema conventions: public API discovery documentation