n8n에서 복구 가능한 데이터 추출 워크플로 구축하기
레코드를 검증하고 일시적 실패를 재시도하며, 중복 쓰기 없이 예외를 담당자에게 전달하는 n8n 추출 워크플로를 설계합니다.
요약 · TL;DR
n8n에서 구조화된 레코드를 추출하고, 일시적 실패와 유효하지 않은 데이터를 구분하며, 중단 후 안전하게 복구하기 위한 실용적인 설계입니다.
핵심 요점
- 후속 시스템에 쓰기 전에 추출된 필드를 검증하고, 유효하지 않은 레코드는 반복 재시도하지 말고 검토 대상으로 전달합니다.
- 일시적 실패에는 횟수가 제한된 재시도를 사용하고, 재시도 기록을 지속 저장하며, 한도에 도달했을 때 명확한 에스컬레이션 경로를 마련합니다.
- 원자적인 멱등성 메커니즘으로 후속 시스템 쓰기를 보호하고, 결과가 불확실하면 재시도 전에 확인 및 대조합니다.
- 위험한 에이전트 주도 작업에는 n8n의 AI Agent 도구 승인을 사용하고, 추출된 데이터를 수정할 때는 별도의 검토 경로를 구축합니다.
목차 (8)
복구 원칙부터 정하기
n8n에서 운영 환경용 추출 워크플로를 만들 때는 각 문서를 독립적으로 복구할 수 있도록 설계합니다. 문서 식별 정보와 처리 상태를 저장하고, 쓰기 전에 추출된 필드를 검증하며, 해소될 가능성이 있는 실패만 재시도하고, 해결되지 않은 사례는 담당자에게 전달합니다. 성공적인 워크플로는 단순히 다시 실행되는 데 그치지 않습니다. 레코드를 모르는 사이에 중복 생성하거나 누락하지 않고 다시 실행할 수 있어야 합니다.
아래 예시는 송장 데이터를 추출해 승인된 레코드를 대상 시스템에 쓰는 방식입니다. 이 예시는 설명을 위한 설계이며 테스트된 워크플로가 아닙니다. 노드 옵션과 연동 방식은 n8n 버전과 대상 시스템에 따라 다르므로 사용 중인 환경에서 확인하세요.
사전 준비와 워크플로 구성
n8n 인스턴스, 문서 소스와 추출 서비스에 대한 접근 권한, 지속 저장이 가능한 데이터베이스 또는 동등한 상태 저장소, 검증된 레코드를 저장할 대상 시스템, 검토 채널이 필요합니다. 원본 문서와 검토 메시지에는 민감도에 맞춰 접근을 제한하세요.
다음과 같은 논리적 순서를 사용합니다.
- 트리거 및 등록: 문서 참조를 수신합니다. 안정적인 소스 ID와 문서 버전을 사용해 지속 저장되는 작업을 생성하거나 기존 작업을 찾습니다.
- 추출: 문서를 가져와 선택한 추출기에 구조화된 필드를 요청합니다.
- 검증: 반환된 데이터를 명시적인 규약에 따라 검사합니다.
- 분기: 유효한 레코드는 쓰기 경로로, 유효하지 않은 레코드는 검토 대기열로 보냅니다.
- 쓰기 및 결과 대조: 안정적인 멱등성 키로 쓰기를 수행한 뒤 대상 시스템의 ID와 결과를 기록합니다.
- 복구: 별도의 예약 워크플로가 재시도 시점이 된 작업이나 운영상 정한 시간 한도를 넘어 멈춰 있는 작업을 찾습니다.
트리거 실행 ID는 추적에 유용하지만 재실행 간에 문서를 식별하는 안정적인 수단은 아닙니다. 소스 시스템의 문서 ID와 버전 또는 콘텐츠 다이제스트를 함께 사용하는 편이 좋습니다. 자동 재처리를 활성화하기 전에 수정된 문서에 새 버전을 부여하는 방식을 정의하세요.
쓰기 전에 추출된 레코드 검증하기
이 예시에서는 invoice_id, currency, amount_minor를 필수로 지정합니다. 검증 중 부동소수점 반올림을 피하려면 금액을 센트와 같은 통화의 최소 단위로 표현하세요. 이 규약은 추출기가 이미 해당 통화의 규칙에 따라 금액을 변환했다고 가정합니다. 실제 구현에서는 지원되는 통화인지, 변환이 적절한지도 확인해야 합니다.
추출 단계 뒤에 Code 노드를 배치합니다. 다음 예시 JavaScript는 입력된 각 항목을 검사하고, 잘못된 데이터에서 예외를 발생시키는 대신 검토 가능한 결과를 반환합니다. 노드가 입력된 모든 항목을 처리하도록 구성하고, 노드 실행 전에 각 항목의 JSON이 추출된 레코드인지 확인하세요.
return $input.all().map((item) => {
const record = item.json;
const errors = [];
if (typeof record.invoice_id !== 'string' || !record.invoice_id.trim()) {
errors.push('invoice_id must be a non-empty string');
}
if (typeof record.currency !== 'string' || !/^[A-Z]{3}$/.test(record.currency)) {
errors.push('currency must be a three-letter uppercase code');
}
if (!Number.isSafeInteger(record.amount_minor) || record.amount_minor < 0) {
errors.push('amount_minor must be a non-negative safe integer');
}
return {
json: {
record,
validation: { valid: errors.length === 0, errors },
},
};
});
그 뒤에 validation.valid를 확인하는 IF 노드를 배치합니다. 작업 ID와 소스 참조는 항목에 포함하거나 상태 저장소에서 조회하는 방식으로 이 출력과 함께 유지하세요. 정규식은 통화 코드의 형식만 검사하며, 실제로 지원되는 통화인지는 확인하지 않습니다. 쓰기 전에 공급업체 일치 여부와 중복 송장 탐지 같은 업무 규칙 검사도 추가하세요.
항목으로 파싱할 수 없는 형식 오류 응답에는 별도의 오류 경로가 필요합니다. 추출 실패가 발생할 때마다 검증 노드가 사용 가능한 레코드를 받는다고 가정하지 마세요. 안전한 진단 정보를 저장하고, 지속적으로 발생하는 파싱 실패는 검토 대상으로 전달합니다.
재시도 및 에스컬레이션 규칙 정의하기
재시도 판단 기준을 명확히 정하세요. 다음은 시작점이 되는 정책이며, 모든 서비스가 이 상태 코드를 같은 방식으로 사용한다는 보장은 아닙니다.
| 실패 유형 | 초기 조치 | 한도 도달 또는 조사 후 조치 |
|---|---|---|
| 시간 초과, 연결 실패 또는 일시적 서비스 오류 | 대기 시간에 제한을 두고 지터를 적용해 재시도합니다. 문서화된 재시도 대기 시간이 제공되면 이를 따릅니다. | 운영자 조사가 필요하도록 표시합니다. |
| 요청 속도 제한 | 서비스 지침에 따라 대기하고, 필요한 경우 동시성을 줄입니다. | 정해진 서비스 시간 내에 작업을 진행할 수 없으면 에스컬레이션합니다. |
| 필드 누락 또는 업무 규칙 검증 실패 | 동일한 요청을 무한히 반복하지 말고 레코드와 오류를 검토 대상으로 전달합니다. | 수정된 레코드를 쓰기 전에 다시 검증합니다. |
| 인증 또는 권한 오류 | 자동 재시도를 중단하고 운영자에게 알립니다. | 자격 증명 또는 권한을 수정한 뒤 재개합니다. |
| 결과를 알 수 없는 쓰기 시간 초과 | 다시 쓰기 전에 안정적인 작업 키로 대상 시스템을 확인합니다. | 결과를 여전히 알 수 없으면 수동으로 확인 및 대조합니다. |
예를 들어 전체 추출 시도 횟수를 최대 3회로 제한하고, 시도 사이에 각각 약 1분과 5분을 기다리며 지터를 추가할 수 있습니다. 시도 횟수, 마지막 오류 범주, 다음 시도 가능 시각, 최종 처리 결과를 지속 저장하세요. 서비스 제공자가 지정한 대기 시간을 이 예시의 대기 시간보다 우선할지도 결정해야 합니다. 노드 수준 재시도와 예약 재시도를 함께 사용할 때는 두 횟수를 모두 고려하세요. 그렇지 않으면 실제 시도 횟수가 정책 한도를 초과할 수 있습니다.
필요한 경우 n8n에서 제공하는 오류 처리 및 재시도 설정을 사용하되, 실행 로그만을 대기열로 삼아서는 안 됩니다. 예약 복구 워크플로는 지속 저장된 작업 상태를 조회하고 처리 가능한 작업을 원자적으로 점유해 두 작업자가 같은 작업을 동시에 처리하지 못하게 해야 합니다. 배포 환경에서 정확한 노드 설정과 데이터베이스 잠금 동작을 확인하세요.
복구해도 안전하도록 쓰기 설계하기
대상 시스템에 처음 쓰기 전에 소스 문서의 식별 정보와 버전에서 도출한 안정적인 작업 키를 지속 저장합니다. 재시도할 때마다 동일한 키를 다시 사용하세요. 대상 시스템은 고유성을 강제하거나 멱등성 키를 원자적으로 처리해야 합니다. 기존 레코드를 확인한 다음 별도로 삽입하는 방식은 작업자가 동시에 실행될 때 취약합니다.
대상 시스템에 이러한 기능이 없다면 원자적인 고유성 제약 조건을 갖춘 중간 저장소와 결과 대조 프로세스를 사용하세요. 다만 이것만으로는 별도 시스템에서의 효과가 정확히 한 번만 발생한다고 보장할 수 없습니다. 대상 시스템에서는 쓰기가 성공했지만 처리 과정에서 응답을 받지 못할 수 있기 때문입니다. 이 경우 재시도 전에 안정적인 외부 참조로 대상 시스템을 조회하거나, 안정적으로 조회할 수 없다면 운영자에게 전달하세요.
received, extracting, review_required, ready_to_write, write_unknown, completed와 같은 상태를 추적합니다. 진행 중인 작업에는 임대 기간 또는 마감 시한을 설정하고, 복구 과정에서 만료된 임대 상태를 확인하도록 합니다. 쓰기 성공을 확인한 후에만 대상 레코드 ID를 저장하세요. 로그에 불필요한 문서 내용을 노출하지 않으면서도 운영자가 발생한 일을 설명할 수 있도록 시도 이력과 상태 전환을 유지합니다.
적절한 지점에 담당자 검토 추가하기
추출 결과가 유효하지 않으면 소스 참조, 제안된 필드, 검증 오류, 작업 ID를 포함하는 검토 작업을 생성합니다. 인증된 사용자가 수정 내용을 승인하거나 작업을 거부할 수 있는 방법을 제공하세요. 수정 시에는 변경한 사람과 시간을 저장하고, 검증을 다시 실행한 뒤 동일한 보호된 쓰기 경로를 사용합니다. 처리되지 않은 검토에는 에스컬레이션 담당자와 시간 제한을 정하고, 응답이 없다는 이유로 승인된 것으로 간주하지 마세요.
별도의 n8n 기능은 AI Agent가 도구를 호출할 때 적용됩니다. n8n의 human-in-the-loop 문서에 따르면 선택한 도구 호출을 일시 중지하고 제안된 도구와 매개변수를 검토자에게 보여준 뒤 승인 또는 거부를 받을 수 있습니다. Agent의 Tools 패널에서 담당자 검토 단계를 추가하고, 지원되는 채널을 구성한 다음, 승인이 필요한 도구를 연결하세요. 문서는 또한 어떤 도구에 승인이 필요한지와 거부를 어떻게 처리할지를 에이전트의 시스템 프롬프트에 명시할 것을 권장합니다.
이 도구 승인은 스키마 검증이나 범용 레코드 수정 대기열을 대체하지 않습니다. 승인된 도구는 AI가 제안한 입력으로 실행됩니다. 검토자가 추출된 필드를 변경해야 한다면 별도의 수정 경로를 사용하고, 쓰기 전에 다시 검증하세요.
출시 전 운영 점검
- 필드 누락, 형식이 잘못된 추출 응답, 요청 속도 제한, 만료된 자격 증명, 검토 거부 상황을 테스트합니다.
- 대상 시스템에 쓰기는 성공했지만 응답을 받지 못한 상황을 시뮬레이션하고, 복구 과정이 무작정 다시 삽입하지 않고 결과를 대조하는지 확인합니다.
- 동시에 실행되는 복구 작업자가 같은 작업을 점유할 수 없는지, 재시도 한도에 모든 재시도 계층이 포함되는지 확인합니다.
- 오래된 검토 작업, 재시도 횟수 소진, 만료된 임대 상태, 알 수 없는 쓰기 결과에 대해 알림을 설정합니다. 운영자가 소스를 찾아 각 작업을 안전하게 재개하거나 종료할 수 있는지도 확인합니다.
보수적인 재시도 한도와 검토 규칙으로 시작한 뒤 관찰된 실패 범주를 바탕으로 조정하세요. 자동화 범위를 넓히더라도 검증과 멱등성 경계는 유지해야 합니다.
출처
- n8n: Human-in-the-loop for tools — 도구 승인 동작, 설정, 채널 및 에이전트 프롬프트 지침.
FAQ
n8n 워크플로에서 스키마 검증에 실패한 레코드를 재시도해야 하나요?
일반적으로 동일한 입력과 설정으로 재시도해서는 안 됩니다. 검토 또는 정해진 수정 프로세스로 전달한 뒤, 수정된 레코드를 쓰기 전에 검증하세요. 원인이 일시적이라면 별도로 횟수를 제한한 재추출 정책이 적절할 수 있습니다.
n8n 담당자 검토가 추출된 데이터를 자동으로 검증하나요?
아니요. 문서에 설명된 AI Agent 도구 검토 기능은 제안된 도구 호출을 사람이 승인하거나 거부하도록 요청합니다. 스키마 검증과 레코드 수정 프로세스는 별도로 워크플로를 설계해야 합니다.
시간 초과 후 워크플로에서 중복 쓰기를 방지하려면 어떻게 해야 하나요?
안정적인 작업 키를 재사용하고 대상 시스템이 이를 원자적으로 강제하도록 하세요. 결과를 알 수 없다면 재시도 전에 대상 시스템과 대조하고, 결과를 확인할 수 없으면 에스컬레이션합니다.
관련 글
Guides
n8n에서 개인정보를 고려한 데이터 추출 워크플로 구축하기
구조화된 출력을 검증하고, 실패를 안전하게 처리하며, 민감한 작업을 사람의 검토로 연결하는 n8n 추출 워크플로를 설계합니다.
Guides
검증된 출처와 사람 검토를 갖춘 n8n 문서 Q&A 워크플로 구축하기
문서에서 근거를 추출하고, 구조화된 답변을 검증하며, 안전하게 재시도하고, 불확실한 결과는 사람에게 검토를 요청하는 n8n 워크플로를 설계합니다.
Guides
JSON Schema 검증으로 신뢰할 수 있는 n8n 데이터 추출 워크플로 구축하기
구조화된 모델 출력을 검증하고, 일시적인 오류는 재시도하며, 불확실하거나 유효하지 않은 레코드는 사람의 검토로 보내는 n8n 추출 파이프라인을 설계합니다.
Guides
검증, 재시도, 사람의 검토를 갖춘 반복 가능한 n8n 데이터 추출 워크플로 만들기
구조화된 출력 검증, 일시적 오류 재시도, 불확실한 레코드의 검토 전달, 고정 테스트 사례를 통한 평가를 지원하는 n8n 추출 워크플로를 설계합니다.