검증, 재시도, 사람의 검토를 갖춘 반복 가능한 n8n 데이터 추출 워크플로 만들기
구조화된 출력 검증, 일시적 오류 재시도, 불확실한 레코드의 검토 전달, 고정 테스트 사례를 통한 평가를 지원하는 n8n 추출 워크플로를 설계합니다.
요약 · TL;DR
n8n에서 추출, 검증, 부수 효과 처리를 분리하세요. 모든 결과를 명시적인 계약에 따라 검증하고, 복구 가능한 오류만 정해진 횟수 내에서 재시도하며, 불확실하거나 중요한 레코드는 확정하기 전에 사람에게 검토를 요청하세요.
핵심 요점
- 추출 결과는 스키마 및 비즈니스 규칙 검사를 통과하기 전까지 신뢰할 수 없는 입력으로 취급하세요.
- 재시도 횟수를 제한하고 일시적 오류와 유효하지 않은 모델 출력을 구분하세요.
- 모호한 레코드나 중요한 작업에는 사람의 검토를 활용하고, 검토자에게 제안된 값을 정확히 보여 주세요.
- 예상 출력과 명시적인 통과 기준이 포함된 고정 테스트 세트를 유지해 변경 사항을 일관되게 비교하세요.
목차 (7)
n8n 추출 워크플로를 더 신뢰할 수 있게 하려면 스키마 검증, 횟수가 제한된 복구, 사람의 검토라는 세 가지 관문을 분리하는 것이 좋습니다. AI가 생성한 응답을 데이터베이스 업데이트나 외부 메시지로 바로 전달하지 마세요. 먼저 응답의 구조가 예상과 맞는지 확인한 뒤, 자동으로 처리해도 안전한지 판단하세요.
이 설계는 예시일 뿐이며, 테스트를 거친 워크플로 내보내기 파일이 아닙니다. 노드 레이블과 사용할 수 있는 옵션은 n8n 버전에 따라 다를 수 있습니다. n8n 공식 가이드에는 AI Agent에 연결된 일부 도구의 사람 승인 절차가 설명되어 있지만, 모든 추출 레코드에 적용할 수 있는 범용 승인 단계는 다루지 않습니다. n8n: 도구에 대한 사람 참여형 승인.
범위를 좁혀 추출 계약 정의하기
레코드 유형 하나를 선택하고 후속 노드에 꼭 필요한 항목을 정확히 정의하세요. 예를 들어 송장 필드를 추출한다면 다음과 같은 결과를 만들 수 있습니다.
{
"invoice_number": "INV-1042",
"invoice_date": "2025-02-14",
"total": 128.50,
"currency": "USD"
}
각 필수 필드와 허용되는 데이터 유형, 누락되거나 불확실한 값을 표현하는 방법을 정하세요. 신뢰할 수 있는 계약 대신 notes처럼 모호한 필드를 사용하지 마세요. 이 예시에서는 다음과 같은 규칙을 적용할 수 있습니다.
invoice_number: 비어 있지 않은 문자열.invoice_date: 유효한 ISO 날짜(YYYY-MM-DD).total: 0 이상인 유한한 숫자.currency: 대문자 세 글자.- 알 수 없는 값: 계약에서 허용하는 경우에만
null을 사용하며, 절대 추측하지 않습니다.
이는 예시 비즈니스 규칙이지 n8n이 요구하는 사항은 아닙니다. 원본 문서와 대상 시스템에 맞는 규칙을 설정하세요.
워크플로를 단계별로 구성하기
실용적인 워크플로는 다음 순서로 진행할 수 있습니다.
- 트리거 및 가져오기: 문서나 레코드를 받고 원본 식별자를 보존합니다.
- 추출: 선택한 추출 단계에서 계약에 지정된 필드만 요청합니다. 선택한 노드나 모델이 지원한다면 구조화된 출력을 요구하되, 결과는 직접 검증해야 합니다.
- 파싱 및 검증: 응답을 파싱할 수 있는지, 모든 필드가 데이터 유형과 비즈니스 규칙을 충족하는지 확인합니다.
- 분기: 유효하고 위험도가 낮은 레코드는 다음 단계로 보냅니다. 유효하지 않거나 모호한 레코드는 검토 경로로 보냅니다. 일시적인 서비스 오류는 별도로 처리합니다.
- 확정: 검증을 마치고 필요한 경우 사람의 승인을 받은 다음에만 대상 시스템에 기록합니다.
- 결과 기록: 원본 식별자, 추출 결과, 검증 오류, 시도 횟수, 최종 결정을 저장합니다. 보존 정책에서 허용하지 않는 한 민감한 문서 내용은 로그에 남기지 마세요.
파싱 후 Code 노드에서 기본 검사를 수행할 수 있습니다. 앞선 노드에 맞게 입력 속성과 null 처리 정책을 조정하세요.
const item = $input.first().json;
const data = item.extraction; // Set this to the parsed extraction object.
const errors = [];
if (!data || typeof data !== 'object' || Array.isArray(data)) {
errors.push('Extraction must be a JSON object');
} else {
if (typeof data.invoice_number !== 'string' || !data.invoice_number.trim()) {
errors.push('invoice_number must be a non-empty string');
}
if (typeof data.invoice_date !== 'string' ||
!/^\d{4}-\d{2}-\d{2}$/.test(data.invoice_date) ||
Number.isNaN(Date.parse(`${data.invoice_date}T00:00:00Z`))) {
errors.push('invoice_date must be a valid YYYY-MM-DD date');
}
if (typeof data.total !== 'number' || !Number.isFinite(data.total) || data.total < 0) {
errors.push('total must be a finite, non-negative number');
}
if (typeof data.currency !== 'string' || !/^[A-Z]{3}$/.test(data.currency)) {
errors.push('currency must be three uppercase letters');
}
}
return [{ json: { ...item, valid: errors.length === 0, validation_errors: errors } }];
이 검사는 구조와 간단한 제약 조건을 확인할 뿐, 송장 값이 사실과 일치하는지는 검증하지 않습니다. 형식이 올바르더라도 금액을 잘못 읽었을 수 있으므로 원본과 대조하거나 신뢰도 정책 또는 사람의 검토를 적용해야 합니다.
적절한 오류만 재시도하고, 한도를 두세요
요청 제한이나 일시적인 연결 오류처럼 잠깐 후에는 해결될 수 있는 오류에 대해 작고 명시적인 재시도 한도를 설정하세요. 가능한 경우 노드의 재시도 설정을 사용하거나, 시도 횟수와 대기 시간을 포함한 제어된 루프를 만드세요. 특정 설정에 의존하기 전에 사용 중인 n8n 버전에서 오류와 재시도가 어떻게 처리되는지 확인하세요.
스키마 오류를 네트워크 문제처럼 무조건 재시도하지 마세요. 예를 들어 추출 단계에 동일한 필드를 유효한 JSON으로 다시 반환해 달라고 요청하는 등, 횟수가 제한된 수정 시도는 유용할 수 있습니다. 다만 이를 별도의 명확한 한도로 관리하세요. 응답이 계속 유효하지 않다면 검토로 보내거나 실패로 표시하세요. 무한 루프가 발생하지 않도록 하세요.
retryable_error, invalid_output, needs_review처럼 결과를 구분해 기록하세요. 이렇게 하면 워크플로 실행을 더 쉽게 진단할 수 있고, 유효하지 않은 레코드를 추출 성공으로 오인하지 않게 됩니다.
적절한 판단 지점에 사람을 참여시키기
레코드 검토를 요청할 때는 검토자에게 원본 참조, 제안된 값, 검증 경고와 명확한 승인/수정/거부 선택지를 제공하세요. 레코드를 기록하기 전에 워크플로가 결정을 기다리도록 하고, 시간 초과나 거부 시 어떻게 처리할지 정하세요. 구체적인 대기 및 재개 방식은 사용하는 검토 채널과 n8n 노드에 따라 다릅니다.
n8n에서 문서화한 AI Agent의 사람 검토 기능은 방식이 다릅니다. 선택한 도구는 에이전트가 실행하기 전에 승인을 요구할 수 있습니다. 워크플로가 일시 중지되고 검토자는 제안된 도구 호출을 승인하거나 거부할 수 있으며, 호출할 도구와 매개변수를 확인할 수 있습니다. 가이드에는 Slack, Telegram, n8n Chat 등의 채널이 나와 있으며, $tool.name과 $tool.parameters를 사용해 맥락을 제공할 수 있다고 설명합니다. 거부의 의미와 에이전트가 어떻게 대응해야 하는지 시스템 프롬프트에 설정하세요. 레코드 수정과 같은 작업을 에이전트가 실행하려는 경우 이 기능을 활용하되, 추출 필드 검증을 대신하는 용도로 사용하지 마세요. 자세한 내용은 공식 설정 가이드를 참조하세요.
고정 사례로 평가를 반복 가능하게 만들기
일반적인 입력, 형식이 잘못된 입력, 모호한 입력을 포함하는 작은 테스트 픽스처 세트를 만드세요. 각 사례에 대해 예상 필드, 예상 검증 결과, 사람의 검토가 필요한지를 기록합니다. 프롬프트, 스키마, 파싱 로직 또는 모델 구성을 변경할 때마다 동일한 사례를 실행하세요.
| 테스트 사례 | 예상 결과 | 통과 조건 |
|---|---|---|
| 모든 필드가 있는 명확한 송장 | 유효한 추출 | 모든 필수 필드가 픽스처와 일치하고 검증을 통과함 |
| 송장 날짜 누락 | 유효하지 않거나 명시적으로 허용된 null | 날짜를 지어내지 않고 설정된 정책을 따름 |
| 합계가 숫자가 아닌 텍스트로 표시됨 | 유효하지 않은 출력 | 레코드가 쓰기 단계에 도달하지 않음 |
| 문서에 그럴듯한 합계가 두 개 있음 | 사람의 검토 | 모호성이 해소될 때까지 자동 확정하지 않음 |
| 일시적인 요청 실패 | 횟수가 제한된 재시도 | 시도가 설정된 한도에서 멈추고 실패가 기록됨 |
| 검토자가 제안된 업데이트를 거부함 | 쓰기 없음 | 거부가 기록되고 워크플로가 거부 경로를 따름 |
테스트를 실행하기 전에 최대 시도 횟수, null을 허용할 필드, 검토가 필요한 오류, 쓰기를 차단하는 조건을 정하세요. 필드별 정확히 일치한 결과를 보고하고, 유효하지 않은 사례, 검토된 사례, 거부된 사례, 실패한 사례의 수를 집계하세요. 작은 픽스처 세트는 회귀 테스트를 위한 검사이지, 모든 문서 유형에서 추출이 작동한다는 증거는 아닙니다.
문제 해결 체크리스트
- 유효한 JSON인데도 실패함: 파서가 객체를 반환하는지 JSON 문자열을 반환하는지 확인하고, 검증 단계가 올바른 속성을 읽는지 살펴보세요.
- 잘못된 값이 통과함: 비즈니스 규칙과 원본에 근거한 검사를 추가하세요. JSON 데이터 유형만으로는 사실 여부를 확인할 수 없습니다.
- 재시도해도 같은 오류가 반복됨: 일시적 오류와 결정적인 스키마 오류를 분리하고 시도 횟수를 제한하세요.
- 검토자가 판단하기 어려움: 원본 참조와 제안된 값을 모두 제공하고 가능한 선택지를 명확히 제시하세요.
- 거부한 작업이 실행됨: 승인 결과 뒤에 쓰기 단계를 배치하고, 거부를 별도의 픽스처로 테스트하세요.
- 실행할 때마다 결과가 달라짐: 입력, 프롬프트, 스키마, 평가 기준을 고정하고 관련 워크플로 구성 변경 사항을 기록하세요.
결론
n8n의 안정성은 추출 이후의 처리를 제어하는 데서 나옵니다. 범위가 좁은 계약에 따라 검증하고, 정해진 횟수 내에서만 재시도하며, 레코드가 모호하거나 작업이 중요한 경우 사람의 판단을 받으세요. 고정 테스트 세트를 사용하면 이러한 제어를 관찰하고 반복적으로 확인할 수 있습니다.
FAQ
n8n의 AI Agent 사람 검토 기능이 추출 데이터를 검증하나요?
아니요. 문서화된 기능은 선택한 AI Agent 도구 호출을 승인 또는 거부할 수 있도록 일시 중지합니다. 추출 필드는 저장하거나 작업에 사용하기 전에 별도로 검증하세요.
유효하지 않은 모델 출력을 재시도해야 하나요?
일시적인 오류로 취급해 재시도해서는 안 됩니다. 횟수가 제한된 수정 시도를 허용할 수는 있지만, 이를 일시적인 서비스 오류에 대한 재시도와 분리하고 계속 유효하지 않은 출력은 검토 또는 실패 처리로 보내세요.
추출 평가에서는 무엇을 테스트해야 하나요?
유효한 레코드, 누락되거나 형식이 잘못된 필드, 모호한 원본 값, 재시도 가능한 오류, 검토자의 거부를 다루는 고정 예시를 사용하세요. 실행 전에 예상 결과와 통과 조건을 정의하세요.
스키마 검증을 통과한 뒤 추출 워크플로가 바로 기록해도 되나요?
해당 사용 사례에서 스키마 유효성만으로 충분한 경우에만 가능합니다. 데이터 유형이 올바른 결과도 사실과 다를 수 있으므로, 중요한 레코드나 모호한 레코드에는 원본 대조 또는 사람의 검토가 필요할 수 있습니다.
관련 글
Guides
n8n에서 복구 가능한 데이터 추출 워크플로 구축하기
레코드를 검증하고 일시적 실패를 재시도하며, 중복 쓰기 없이 예외를 담당자에게 전달하는 n8n 추출 워크플로를 설계합니다.
Guides
n8n에서 개인정보를 고려한 데이터 추출 워크플로 구축하기
구조화된 출력을 검증하고, 실패를 안전하게 처리하며, 민감한 작업을 사람의 검토로 연결하는 n8n 추출 워크플로를 설계합니다.
Guides
JSON Schema 검증으로 신뢰할 수 있는 n8n 데이터 추출 워크플로 구축하기
구조화된 모델 출력을 검증하고, 일시적인 오류는 재시도하며, 불확실하거나 유효하지 않은 레코드는 사람의 검토로 보내는 n8n 추출 파이프라인을 설계합니다.
Guides
저장소 변경 사항 검토와 검증을 위한 안정적인 n8n 워크플로 구축
저장소 변경 사항에서 구조화된 정보를 추출하고, 결과를 검증하며, 일시적 오류는 재시도하고, 테스트를 확인한 뒤 위험한 작업은 사람에게 검토를 요청하는 n8n 워크플로를 설계합니다.