GuidesOneMux

Создайте повторяемый сценарий извлечения данных в n8n: валидация, повторы и проверка человеком

Спроектируйте сценарий извлечения данных в n8n, который проверяет структурированный результат, повторяет попытки при временных сбоях, отправляет сомнительные записи на проверку и оценивается на фиксированном наборе тестов.

AI

Кратко · TL;DR

Разделите в n8n извлечение данных, проверку и побочные действия. Проверяйте каждый результат по явному контракту, повторяйте попытки только при устранимых сбоях и в пределах заданного лимита, а сомнительные или значимые записи отправляйте на проверку человеку до их фиксации.

Главное

  • Считайте результат извлечения недоверенными данными, пока он не пройдёт проверку схемы и бизнес-правил.
  • Задайте лимит повторных попыток и различайте временные ошибки и некорректный вывод модели.
  • Для неоднозначных записей и значимых действий используйте проверку человеком; показывайте проверяющим точные предлагаемые значения.
  • Подготовьте фиксированный набор тестов с ожидаемыми результатами и явными критериями прохождения, чтобы последовательно сравнивать изменения.
В этой статье (7)

Сценарию извлечения данных в n8n проще доверять, если в нём предусмотрены три отдельных этапа контроля: валидация схемы, ограниченное восстановление после сбоев и проверка человеком. Не направляйте ответ, сгенерированный ИИ, напрямую на обновление базы данных или отправку внешнего сообщения. Сначала проверьте, соответствует ли он ожидаемой структуре, а затем решите, безопасно ли обрабатывать его автоматически.

Это примерная схема, а не проверенный экспорт сценария. Названия узлов и доступные параметры могут различаться в разных версиях n8n. В официальном руководстве n8n описано подтверждение человеком для отдельных инструментов, подключённых к AI Agent; там не описан универсальный этап подтверждения для каждой извлечённой записи. n8n: Human-in-the-loop for tools.

Начните с чёткого контракта извлечения

Выберите один тип записей и точно определите, какие данные нужны последующим узлам. Например, извлечение полей счёта-фактуры может возвращать:

{
  "invoice_number": "INV-1042",
  "invoice_date": "2025-02-14",
  "total": 128.50,
  "currency": "USD"
}

Определите, какие поля обязательны, какие типы данных допустимы и как представлять отсутствующие или сомнительные значения. Не используйте расплывчатое поле вроде notes вместо надёжного контракта. Для этого примера правила могут быть такими:

  • invoice_number: непустая строка.
  • invoice_date: корректная дата в формате ISO (YYYY-MM-DD).
  • total: конечное число, большее или равное нулю.
  • currency: три заглавные буквы.
  • Неизвестные значения: используйте null, только если это допускает контракт; никогда не угадывайте.

Это примеры бизнес-правил, а не требования n8n. Настройте правила в соответствии с вашими исходными документами и целевой системой.

Разбейте сценарий на отдельные этапы

Практический сценарий может состоять из следующих шагов:

  1. Запуск и получение данных: Получите документ или запись и сохраните идентификатор источника.
  2. Извлечение: Попросите выбранный узел извлечения вернуть только поля, указанные в контракте. Если узел или модель поддерживает структурированный вывод, используйте его, но всё равно самостоятельно проверяйте результат.
  3. Разбор и валидация: Убедитесь, что ответ можно разобрать и что каждое поле соответствует своему типу и бизнес-правилам.
  4. Разветвление: Передавайте дальше корректные записи с низким уровнем риска. Некорректные или неоднозначные записи направляйте на проверку. Временные ошибки сервисов обрабатывайте отдельно.
  5. Фиксация: Записывайте данные в целевую систему только после валидации и, когда это необходимо, подтверждения человеком.
  6. Запись результата: Сохраняйте идентификатор источника, извлечённый результат, ошибки валидации, число попыток и окончательное решение. Не записывайте содержимое документов, содержащих конфиденциальные данные, если это не разрешено вашей политикой хранения.

Узел 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.

Описанная в документации функция проверки человеком для AI Agent в n8n работает иначе: для выбранных инструментов можно потребовать подтверждение до их выполнения агентом. Сценарий приостанавливается, и проверяющий может одобрить или отклонить предложенный вызов инструмента; ему видны инструмент и его параметры. В руководстве перечислены такие каналы, как Slack, Telegram и n8n Chat, а также отмечено, что для передачи контекста можно использовать $tool.name и $tool.parameters. Настройте системный промпт так, чтобы он объяснял значение отказа и то, как агенту следует на него реагировать. Используйте эту функцию, когда агент собирается выполнить действие, например изменить запись, — она не заменяет валидацию извлечённых полей. См. официальное руководство по настройке.

Сделайте оценку повторяемой с помощью фиксированного набора тестов

Создайте небольшой набор тестовых примеров с обычными, некорректными и неоднозначными входными данными. Для каждого примера укажите ожидаемые поля, ожидаемый результат валидации и необходимость проверки человеком. Повторяйте тесты при каждом изменении промпта, схемы, логики разбора или конфигурации модели.

Тестовый случайОжидаемый результатКритерий прохождения
Счёт-фактура с чёткими значениями всех полейКорректно извлечённые данныеВсе обязательные поля совпадают с тестовыми данными, валидация пройдена
Дата счёта-фактуры отсутствуетНекорректный результат или допустимое значение nullДата не выдумана; соблюдается настроенная политика
Вместо числа в поле суммы указан текстНекорректный выводЗапись не передаётся на этап записи
На странице указаны две правдоподобные суммыПроверка человекомПока неоднозначность не устранена, автоматическая фиксация не выполняется
Временная ошибка запросаОграниченное число повторных попытокЧисло попыток не превышает заданный лимит; ошибка записана
Проверяющий отклонил предлагаемое обновлениеЗапись не выполняетсяОтказ зарегистрирован, сценарий следует предусмотренной ветке обработки отказа

До запуска тестов определите ограничения: максимальное число попыток, поля, для которых допустимо значение null, ошибки, требующие проверки, и условия, блокирующие запись. Отчёт должен показывать точность совпадения для каждого поля и количество некорректных, проверенных, отклонённых и неудачных случаев. Небольшой набор тестов помогает выявлять регрессии, но не доказывает, что извлечение будет работать для документов любого типа.

Контрольный список для устранения проблем

  • Корректный JSON не проходит проверку: выясните, возвращает ли парсер объект или строку JSON, и проверьте, что валидация обращается к нужному свойству.
  • Ошибочные значения проходят проверку: добавьте бизнес-правила и проверки по источнику; одних типов JSON недостаточно, чтобы подтвердить фактическую точность.
  • Повторы приводят к той же ошибке: отделите временные сбои от детерминированных ошибок схемы и ограничьте число попыток.
  • Проверяющие не могут принять решение: приложите ссылку на источник и все предлагаемые значения, чётко обозначив доступные варианты действий.
  • Отклонённое действие всё равно выполняется: поставьте запись за проверкой результата подтверждения и протестируйте отказ как отдельный тестовый случай.
  • Результаты меняются между запусками: сохраняйте неизменными входные данные, промпт, схему и критерии оценки; фиксируйте существенные изменения конфигурации сценария.

Заключение

Надёжность в n8n зависит от того, что происходит после извлечения данных: проверяйте результат по чёткому контракту, повторяйте попытки только в пределах установленного лимита и привлекайте человека, если запись неоднозначна или действие имеет значимые последствия. Фиксированный набор тестов позволяет наблюдать за работой этих механизмов и воспроизводить результаты.

Вопросы

Проверяет ли функция проверки человеком для AI Agent в n8n корректность извлечённых данных?

Нет. Описанная функция приостанавливает отдельные вызовы инструментов AI Agent, чтобы их можно было одобрить или отклонить. Извлечённые поля необходимо проверять отдельно, прежде чем сохранять их или выполнять на их основе действия.

Нужно ли повторять попытку, если модель вернула некорректные данные?

Не следует считать это временной ошибкой. Можно предусмотреть ограниченную попытку исправления, но отделить её от повторов при временных сбоях сервиса; если вывод по-прежнему некорректен, направить его на проверку или обработку ошибки.

Что следует проверять при оценке сценария извлечения данных?

Используйте фиксированные примеры с корректными записями, отсутствующими или некорректными полями, неоднозначными значениями в источнике, ошибками, допускающими повторную попытку, и отказом проверяющего. До запуска определите ожидаемые результаты и критерии прохождения.

Можно ли записывать данные сразу после успешной проверки схемы?

Только если для вашего сценария проверки схемы достаточно. Данные могут иметь правильные типы, но быть фактически неверными, поэтому для неоднозначных записей или значимых действий могут потребоваться сверка с источником или проверка человеком.

Похожие статьи

Guides

Как создать в n8n процесс извлечения данных с возможностью восстановления

Спроектируйте процесс извлечения данных в n8n, который проверяет записи, повторяет попытки при временных сбоях и направляет исключения на проверку человеку без создания дубликатов при записи.

阅读全文 →

Guides

Как создать workflow для извлечения данных в n8n с учетом конфиденциальности

Спроектируйте workflow извлечения данных в n8n, который проверяет структурированный результат, безопасно обрабатывает ошибки и направляет чувствительные действия на проверку человеку.

阅读全文 →

Guides

Надёжный сценарий извлечения данных в n8n с проверкой по JSON Schema

Настройте в n8n конвейер извлечения данных: проверяйте структурированный вывод модели, повторяйте запросы при временных сбоях, а сомнительные и некорректные записи отправляйте на проверку человеку.

阅读全文 →

Guides

Как создать надежный workflow в n8n для изменений в репозитории, проверок и согласования

Спроектируйте workflow в n8n, который извлекает структурированные данные об изменениях в репозитории, проверяет результат, повторяет запросы при временных сбоях, сверяет тесты и направляет рискованные действия на ручное согласование.

阅读全文 →