JSON Schema 검증으로 신뢰할 수 있는 n8n 데이터 추출 워크플로 구축하기
구조화된 모델 출력을 검증하고, 일시적인 오류는 재시도하며, 불확실하거나 유효하지 않은 레코드는 사람의 검토로 보내는 n8n 추출 파이프라인을 설계합니다.
요약 · TL;DR
견고한 데이터 추출 워크플로에서는 모델 출력을 신뢰할 수 없는 입력으로 취급합니다. 범위가 명확한 JSON 계약을 정의하고, 파싱한 결과를 어디에든 저장하기 전에 검증합니다. 일시적인 오류만 재시도하고, 해결되지 않았거나 영향이 큰 사례는 담당자에게 보냅니다.
핵심 요점
- 예측 가능한 JSON 객체 하나를 요청한 다음, 모델과 별도로 검증합니다.
- 일시적인 API 오류와 형식이 잘못되었거나 불완전한 추출 결과를 구분합니다.
- 재시도 횟수를 제한하고 원본 레코드를 보존해 재실행 시 중복이 생기지 않게 합니다.
- 중대한 결과를 초래할 수 있는 작업에 앞서 사람의 검토를 거치는 것이 특히 중요합니다. n8n은 선택한 AI Agent 도구에 대한 승인을 지원합니다.
- 원본, 추출 결과, 검증 오류, 재시도 횟수, 검토자 결정을 감사 추적에 남깁니다.
목차 (7)
설계 원칙: 실행 전에 검증하기
모델이 보기에는 유효한 JSON을 반환했다고 해서 데이터가 완전하고, 올바른 타입이며, 안전하게 사용할 수 있다는 뜻은 아닙니다. n8n에서 데이터 추출을 명확한 계약을 갖춘 파이프라인으로 구성하세요. 원본 레코드를 수집하고, 구조화된 결과를 요청한 뒤, 이를 파싱하고 검증합니다. 그런 다음 계속 진행하거나 재시도하거나 검토를 요청합니다. 모델 출력을 데이터베이스 업데이트나 외부 메시지 전송에 바로 연결하지 마세요.
이 글에서는 송장과 비슷한 레코드를 설명을 위한 예시로 사용합니다. 스키마와 노드 구성은 예시이며, 테스트를 거쳤거나 특정 버전에 맞춘 n8n 내보내기 파일이 아닙니다. 사용 중인 n8n 버전에서 제공되는 노드 옵션과 선택한 모델 엔드포인트가 지원하는 출력 형식을 확인하세요.
1. 먼저 출력 계약 정의하기
다음 단계에 실제로 필요한 필드만 스키마에 포함하세요. 필수 필드를 명시하고, 안정적인 타입을 사용하며, 정보가 누락되었을 때 어떻게 표현할지 정합니다. 예를 들어 송장 날짜가 없다면 날짜를 지어내거나 자유 형식으로 설명하는 대신 null로 표현해야 합니다.
{
"type": "object",
"additionalProperties": false,
"required": ["invoice_number", "invoice_date", "currency", "total"],
"properties": {
"invoice_number": { "type": "string", "minLength": 1 },
"invoice_date": { "type": ["string", "null"] },
"currency": { "type": "string", "minLength": 3, "maxLength": 3 },
"total": { "type": "number", "minimum": 0 }
}
}
스키마는 구조 규칙을 표현하지만, 추출된 합계가 원본 문서와 일치하는지 확인해 주지는 않습니다. 날짜가 올바르게 파싱되는지, 통화 코드가 허용 목록에 있는지 확인하는 등 도메인 검사를 별도로 추가하세요. 예상하지 못한 값을 조용히 변환하지 마세요. 텍스트 금액을 숫자로 변환하는 것이 유용할 수 있지만, 변환 사실을 기록하고 모호한 형식은 거부해야 합니다.
2. n8n 워크플로를 단계별로 구성하기
실용적인 캔버스 구성은 다음과 같습니다.
- 트리거 및 원본 가져오기: 파일, 레코드 또는 웹훅 페이로드를 받습니다. 안정적인 원본 ID를 부여하고, 원본 텍스트나 그 참조를 보관합니다.
- 추출 요청: 텍스트와 간결한 지침을 선택한 모델에 보냅니다. 정의된 객체만 반환하도록 요청하고, 불확실하거나 없는 값은 계약에 지정된 방식으로 표현해야 한다고 명시합니다.
- 파싱 및 검증: 응답을 JSON으로 파싱한 다음 필수 키, 타입, 허용 값, 비즈니스 규칙을 확인합니다. 설정에서 사용할 수 있는 스키마 검증 노드를 쓰거나, 의도적으로 설치하고 테스트한 검증기가 포함된 Code 노드를 사용합니다. 모든 n8n 환경에서 특정 검증 패키지를 사용할 수 있다고 가정하지 마세요.
- 결과에 따라 분기: 유효한 레코드는 대상 시스템으로 보냅니다. 재시도할 수 있는 오류는 횟수를 제한한 재시도 경로로 보내고, 지속적인 검증 실패와 모호한 사례는 검토 대상으로 보냅니다.
- 결과 기록: 원본 ID, 상태, 추출된 객체, 검증 오류, 시도 횟수, 최종 결정을 저장합니다.
검증 단계는 모델 요청과 분리하세요. 프롬프트 지침은 응답 품질을 높일 수 있지만, 검증을 대신하지는 않습니다.
3. 적절한 오류만 재시도하기
재시도는 일시적인 전송 오류, 요청 제한 또는 서비스 측 오류에 도움이 됩니다. 송장 번호 누락이나 반복적으로 스키마를 위반하는 응답은 재시도로 해결되지 않습니다. 재시도 횟수를 낮게 설정하고, 노드에서 지원하는 경우 시도 사이에 지연을 둡니다. n8n 버전에서 사용할 수 있는 재시도 제어 기능을 확인하세요. 설정과 동작은 노드마다 다를 수 있습니다.
서로 다른 결과는 별도 경로로 분기하세요.
- 일시적인 요청 오류: 제한 횟수까지 재시도한 뒤, 이후 조사할 수 있도록 레코드를 실패 상태로 표시합니다.
- 유효하지 않은 JSON: 유용하다면 동일한 필드와 계약을 요청하는 통제된 수정 시도를 한 번 허용합니다. 새 응답을 다시 검증하고, 수정이 성공했다고 가정하지 마세요.
- 스키마 또는 비즈니스 규칙 실패: 무한 반복하는 대신 검토 대상으로 보냅니다.
- 유효한 결과: 워크플로를 다시 실행해도 중복으로 저장되지 않도록 원본 ID를 사용해 대상 시스템으로 보냅니다.
재시도로 되돌릴 수 없는 후속 작업이 반복 실행되어서는 안 됩니다. 모델 추출과 데이터 쓰기를 별도 단계로 두고, 가능한 경우 쓰기 작업을 멱등하게 만드세요.
4. 위험을 줄일 수 있는 곳에 사람의 검토 추가하기
값이 모호하거나 검증 규칙을 통과하지 못했거나 다음 작업에 의미 있는 결과가 따를 수 있다면 사람의 검토가 유용합니다. 검토자에게 원본, 제안된 필드, 구체적인 검증 오류와 함께 승인, 수정 또는 거부할 수 있는 명확한 선택지를 제공하세요. 검토자의 결정과 수정 내용도 보존합니다.
n8n 문서에는 AI Agent에 연결된 일부 도구에 대한 사람의 승인 기능이 설명되어 있습니다. 워크플로가 일시 중지되면 검토자가 제안된 도구 호출을 승인하거나 거부할 수 있으며, 승인된 경우에만 도구가 실행됩니다. Slack, Telegram, n8n Chat 등 지원되는 채널을 통해 승인을 요청할 수 있습니다. 문서에서는 검토자에게 제안된 도구와 매개변수를 보여주기 위해 $tool.name 및 $tool.parameters를 사용하는 방법도 설명합니다. 이는 AI Agent 도구 호출에 대한 승인 기능이며, 그 자체로 모든 추출 레코드를 검토할 수 있는 범용 인터페이스는 아닙니다. 레코드 단위 검토가 필요하면 배포 환경에 맞는 사람 검토 작업과 재개 경로를 구성하세요.
출처: n8n 문서: 도구에 대한 사람 개입.
5. 근거를 바탕으로 문제 해결하기
유효한 레코드가 반복해서 거부된다면 스키마를 바꾸기 전에 원본 응답과 검증기 오류를 확인하세요. 응답에 Markdown 코드 펜스나 불필요한 설명이 포함되어 있는지, null을 허용하는 필드가 누락되었는지, 숫자가 문자열로 인코딩되었는지 확인합니다. 재시도 후 중복 레코드가 생성된다면 쓰기 작업을 검증 뒤로 옮기고 안정적인 원본 식별자를 사용하세요. 검토자가 빠르게 결정을 내리지 못한다면 JSON 객체만 보내지 말고, 문제가 되는 각 필드를 뒷받침하는 정확한 원본 부분을 포함하세요.
통과율을 높이려고 스키마를 느슨하게 만들지 마세요. 계약 변경은 실제 후속 단계의 요구사항을 반영해야 하며, 필드 누락, 형식이 잘못된 문서, 값이 서로 충돌하는 사례 등 대표적인 입력으로 변경의 영향을 테스트해야 합니다.
재사용 가능한 배포 체크리스트
- 필수 필드, null 처리, 타입, 추가 필드 정책을 정의했습니다.
- 후속 쓰기 전에 파싱, 스키마 검사, 도메인 검사를 수행합니다.
- 재시도 횟수를 제한하고, 정상적으로 복구될 가능성이 있는 오류에만 적용합니다.
- 재처리로 인해 중대한 작업이 실수로 중복 실행되지 않습니다.
- 검토자에게 원본, 제안 값, 에스컬레이션 사유를 제공합니다.
- 거부된 출력이 감춰지지 않도록 조사에 필요한 정보를 로그에 보존합니다.
신뢰할 수 있는 패턴은 간단합니다. 추출하고, 검증하고, 분기한 뒤, 마지막으로 실행합니다. 스키마는 구조 문제를 잡고, 제한된 재시도는 일시적인 오류를 처리하며, 사람의 검토는 자동화가 조용히 해결해서는 안 되는 모호성과 위험을 다룹니다.
FAQ
모델에 JSON을 요청하면 스키마에 맞는 출력이 보장되나요?
아니요. 응답을 신뢰할 수 없는 입력으로 취급하세요. 워크플로에서 사용하기 전에 파싱하고 필수 필드, 타입, 비즈니스 규칙을 검증해야 합니다.
추출한 JSON이 검증에 실패하면 n8n에서 재시도해야 하나요?
제한 없이 자동 재시도해서는 안 됩니다. 한 번의 수정 시도는 유용할 수 있지만, 스키마 실패가 반복되면 무한 재시도하는 대신 에스컬레이션하거나 조사 대상으로 표시하는 것이 일반적으로 바람직합니다.
n8n의 사람 개입 승인 기능으로 추출 레코드를 검토할 수 있나요?
인용된 n8n 기능은 AI Agent가 호출하는 도구를 승인하거나 거부합니다. 이 기능 자체는 일반적인 레코드 검토 인터페이스를 제공하지 않습니다. 추출 사례에 적합한 사람 검토 작업과 재개 경로를 구현해야 합니다.
검토자에게 무엇을 보여줘야 하나요?
원본이나 관련 발췌문, 제안된 구조화 필드, 검증 오류 또는 불확실성, 그리고 명확한 승인·수정·거부 선택지를 보여주세요.
관련 글
Guides
n8n에서 복구 가능한 데이터 추출 워크플로 구축하기
레코드를 검증하고 일시적 실패를 재시도하며, 중복 쓰기 없이 예외를 담당자에게 전달하는 n8n 추출 워크플로를 설계합니다.
Guides
n8n에서 개인정보를 고려한 데이터 추출 워크플로 구축하기
구조화된 출력을 검증하고, 실패를 안전하게 처리하며, 민감한 작업을 사람의 검토로 연결하는 n8n 추출 워크플로를 설계합니다.
Guides
검증, 재시도, 사람의 검토를 갖춘 반복 가능한 n8n 데이터 추출 워크플로 만들기
구조화된 출력 검증, 일시적 오류 재시도, 불확실한 레코드의 검토 전달, 고정 테스트 사례를 통한 평가를 지원하는 n8n 추출 워크플로를 설계합니다.
Guides
검증된 출처와 사람 검토를 갖춘 n8n 문서 Q&A 워크플로 구축하기
문서에서 근거를 추출하고, 구조화된 답변을 검증하며, 안전하게 재시도하고, 불확실한 결과는 사람에게 검토를 요청하는 n8n 워크플로를 설계합니다.