Connettore n8n - Documentazione di Entity Enricher

Connettore n8n

Il nodo community di Entity Enricher per n8n consente di creare pipeline di arricchimento automatizzate con un editor visuale drag-and-drop. Consente di connettersi a oltre 400 app senza scrivere codice.

Installazione

Installa il nodo community nella tua istanza n8n:

npm install n8n-nodes-entity-enricher

Oppure installatelo tramite l'interfaccia di n8n: andate su Impostazioni → Community Nodes e cercate n8n-nodes-entity-enricher.

Prerequisiti

Chiave API— Crea una chiave di accesso dell'organizzazione in Entity Enricher. Consulta la documentazione sulle chiavi API per i dettagli. Il formato della chiave è ent_XXXXXXXXXXXX.

URL di base— L'URL della vostra istanza di Entity Enricher (ad es. https://entityenricher.ai o il vostro URL self-hosted).

Configurazione credenziale— In n8n, creare una credenziale Entity Enricher API con la propria API key e l'URL di base. Tutti i nodi utilizzeranno questa credenziale. Una chiave di accesso dell'organizzazione opera in modo indipendente da qualsiasi account utente — l'opzione consigliata per flussi di lavoro service-to-service duraturi.

OAuth2 (alternativa)— Preferisce connettersi con il proprio account? Creare invece una credenziale Entity Enricher OAuth2 API: copiare l'URL di reindirizzamento OAuth mostrato da n8n, registrare un client OAuth con esso in Entity Enricher in API Keys → App connesse → Client OAuth (ruolo owner), incollare l'ID client in n8n e fare clic su Connetti il mio account. La connessione agisce con il ruolo dell'utente ed è revocabile in qualsiasi momento in App connesse. Selezionare la credenziale sul nodo tramite il parametro Autenticazione.

Operazioni disponibili

Il connettore espone 18 operazioni suddivise in 7 categorie di risorse:

Risorsa	Operazione	Descrizione
Enrichment	Enrich Entity	Arricchisci una singola entità — è sufficiente scegliere uno schema; il modello e la strategia migliori della tua organizzazione vengono selezionati automaticamente. Trasmette i risultati tramite SSE con avanzamento in tempo reale.
Enrichment	Enrich Entity Advanced	Arricchisci una singola entità con pieno controllo su modelli, fusion, strategia, classificazione e output strutturato.
Enrichment	Batch Enrich	Arricchisci tutti gli elementi in input come un unico batch con modello e strategia automatici. Elaborazione parallela con monitoraggio dell'avanzamento per singola entità.
Enrichment	Batch Enrich Advanced	Arricchisci tutti gli elementi in input come un unico batch con il set completo di parametri.
Schema	List Schemas	Elenca gli schema salvati disponibili per la selezione nei flussi di lavoro di arricchimento.
Schema	Get Schema Details	Recupera il contenuto completo dello schema con le proprietà chiave estratte per uno schema specifico.
Schema	Generate Sample	Genera 1..N oggetti JSON di esempio realistici di un unico tipo di entità in un solo job — il punto di ingresso del ciclo di creazione dello schema. La lingua è impostata su auto per impostazione predefinita, dedotta dalle parole della sua richiesta.
Schema	Generate Schema	Genera e salva automaticamente uno schema JSON — ogni elemento in ingresso è un campione dello stesso tipo di entità: unione dei campi, nullable dove un campo manca in alcuni campioni, valori reali osservati come esempi. Un'opzione Lingua imposta la lingua in cui lo schema descrive se stesso.
Record	List Records	Interrogate i record di arricchimento con filtri per tipo ed esito. Risultati impaginati.
Record	Get Record	Recupera un risultato di arricchimento specifico tramite ID con output strutturato completo.
Record	Sync Records to Database	Invia un output di enrichment memorizzato (o trasformato) al database sync del relativo schema — nuovamente convalidato rispetto al contratto pubblicato e quindi sottoposto al gate di ammissione.
Fusion	Merge Results	Fondi i risultati di più record di arricchimento con arbitraggio LLM opzionale.
Attachment	Add Attachment	Carica uno o più file binari dell'elemento di input (singola richiesta multipart) e restituisce un elemento per ciascun ID attachment.
Attachment	Delete Attachment	Elimina un allegato tramite ID — un comodo passaggio di pulizia post-arricchimento.
Database Sync	List Database Syncs	Elenca i database sync registrati su uno schema, con il conteggio dei delta in sospeso.
Database Sync	Fetch Deltas	Recupera la successiva finestra FIFO di delta del database (SQL + JSON), con la possibilità di metterli in lease per la conferma.
Database Sync	Acknowledge Deltas	Conferma i delta applicati fino a un ID: rilascia il lease e, in base alle opzioni di sync, elimina le copie consegnate.
Configuration	Get Options	Recupera modelli, lingue, strategie e limiti del piano disponibili per la configurazione dinamica.

Nodo trigger

Il pacchetto include anche un nodo Entity Enricher Trigger separato: un trigger webhook che avvia un workflow in occasione di eventi dello schema, registrando automaticamente la propria sottoscrizione:

Risultato dell'arricchimento— Si attiva a ogni arricchimento completato dello schema selezionato (con o senza database sync).

Rifiutato per il salvataggio nel database— Si attiva quando un arricchimento non supera il gate di ammissione di un database sync: il payload indica quali campi obbligatori mancavano.

Delta del database disponibili— Si attiva quando nuovi delta SQL sono pronti per un database sync. Con "Fetch Deltas on Fire" abilitato il nodo recupera e riserva i delta in attesa, emettendo un elemento per delta destinato a un successivo passaggio Acknowledge Deltas. Un database alimentato da più schemi invia una notifica per ciascuno schema — ognuna guida il proprio flusso di lavoro — quindi selezioni lo schema collegato che questo trigger deve ascoltare.

Insieme alle operazioni Database Sync, il trigger mantiene un database esterno allineato dal solo n8n: consulti la documentazione di Database Sync.

Arricchimento di entità singola

Il flusso di lavoro più semplice: attivazione su nuovi dati, arricchimento di una singola entità e invio del risultato alla destinazione. Il nodo attende il completamento dell'intero arricchimento prima di passare l'output strutturato a valle.

Flusso di lavoro di esempio — enrichment di una singola entità:

Configurazione del nodo — operazione Enrich Entity:

Configurazione

Le operazioni predefinite Enrich Entity e Batch Enrich mostrano solo gli elementi essenziali: schema, caricamento file, lingue e ricerca web. Entity Enricher viene eseguito automaticamente con il modello migliore della tua organizzazione — il tuo modello predefinito fissato oppure il modello con il punteggio benchmark più alto — e seleziona la strategia di enrichment in base allo schema. Le operazioni Enrich Entity Advanced e Batch Enrich Advanced espongono l'intero set di opzioni riportate di seguito.

Seleziona uno schema dal menu a discesa dinamico, scegli uno o più modelli e fornisci i dati dell'entità come campi chiave-valore. Il nodo popola automaticamente i campi chiave di ricerca in base allo schema selezionato.

Le impostazioni opzionali includono strategia (a passaggio singolo o multi-competenza), lingue per l'output multilingue, modello di classificazione per la verifica del tipo di entità, modello di arbitrato per la risoluzione dei conflitti multi-modello e gli interruttori schema di risposta / output strutturato rigoroso che impongono un output conforme allo schema sui modelli compatibili.

Per fornire documenti di origine all'enrichment, attivare Upload Input Binary Files: il nodo carica i file binari dell'elemento di input come attachment in un'unica richiesta (tutti oppure solo quelli indicati in Binary Fields to Upload) e, con Delete Uploaded Attachments After Enrichment (attivo per impostazione predefinita), li elimina al termine dell'enrichment — senza bisogno di passaggi Add Attachment / Delete Attachment separati. In alternativa, fornire un campo Attachment IDs (UUID separati da virgola provenienti da precedenti chiamate Add Attachment) per riutilizzare in molti enrichment i documenti caricati una sola volta; le due origini possono essere combinate. Disponibile anche su Batch Enrich, dove i file vengono raccolti da tutti gli elementi di input e si applicano a ogni entity del job. Se tra l'origine dei file e il nodo di enrichment è presente un nodo Edit Fields, abilitarne l'interruttore Include Other Input Fields — in caso contrario rimuove i dati binari.

Arricchimento in batch

Elabora tutti gli elementi di input come un unico batch. Ideale per l'enrichment di elenchi da fogli di calcolo, database o risposte API. Tutte le entity vengono elaborate in parallelo con limitazione della frequenza per provider.

Configurazione del nodo — operazione Batch Enrich:

Configurazione del nodo Entity Enricher per l'arricchimento in batch

Come funziona la modalità batch

Raccolta degli elementi — Il nodo raccoglie tutti gli elementi in ingresso dal nodo precedente (ad es. righe di un foglio di calcolo).
Avvia lavoro batch — Tutte le entità vengono inviate tramite POST /api/batch/start ed elaborate in parallelo.
Avanzamento in streaming — Il nodo consuma lo stream SSE finché tutte le entità non vengono completate o non viene raggiunto il timeout.
Risultati di output — Un elemento di output per ogni entity con i dati strutturati arricchiti, pronti per l'elaborazione a valle.

Funzionalità principali

Operazioni semplici e avanzate

Le operazioni predefinite Enrich Entity e Batch Enrich mostrano solo schema, caricamento file, lingue e ricerca web — il modello e la strategia migliori vengono selezionati automaticamente. Le operazioni Advanced offrono pieno controllo su modelli, fusion, strategia e output strutturato.

Menu a discesa dinamici

I selettori di schema, modello, lingua e strategia recuperano le opzioni dalla tua istanza Entity Enricher al momento della configurazione.

Streaming SSE

Le operazioni di arricchimento consumano lo stream SSE in tempo reale, attendendo il completamento prima di restituire i risultati al nodo successivo.

Continuazione automatica

Quando la classificazione preliminare rileva una discrepanza, il connettore prosegue automaticamente (i flussi di lavoro n8n non sono interattivi).

Timeout configurabile

Timeout predefinito di 300 secondi per chiamata di arricchimento, regolabile per nodo per schemi di grandi dimensioni o modelli lenti.

Supporto multi-modello

Seleziona più modelli per enrichment. Quando vengono utilizzati 2+ modelli, i risultati vengono fusi automaticamente.

Pulisci output per impostazione predefinita

Per impostazione predefinita, l'output contiene solo i campi dati arricchiti. Attiva "Includi metadati di arricchimento" per aggiungere costo, token, dettagli della fusione e ID dei record.

Output per modello

Facoltativamente, restituisce i risultati dei singoli modelli insieme al risultato fuso per un confronto a valle.

Consapevolezza dei limiti del piano

I menu a discesa del modello e della lingua mostrano i limiti del piano quando configurati. Gli errori HTTP 402 dovuti all'applicazione delle quote vengono presentati come messaggi chiari e utilizzabili, con i dettagli dei limiti. L'output dei metadati include i limiti attuali del piano per l'instradamento a valle.

Lo utilizzi da un AI Agent, oppure parta da un esempio

Uno strumento per agenti AI

Il nodo Entity Enricher può essere collegato come tool a un AI Agent di n8n, in modo che l'agente decida autonomamente quando arricchire un'entità o recuperare uno schema nel corso della conversazione. Il nodo trigger non è volutamente disponibile in questa modalità: un trigger avvia un workflow, non è qualcosa che un agente richiama.

Sei workflow importabili

Il pacchetto include file di workflow già pronti: arricchimento singolo, batch, da documento ad arricchimento, da immagine a campione a schema, da campioni a schema e svuotamento di un feed delta in PostgreSQL. Importarne uno e inserire le proprie credenziali, anziché configurarlo da zero.

Idee per workflow

Pattern comuni per la creazione di pipeline di arricchimento con n8n:

Arricchimento CRM— Attivate l'azione su nuovi contatti HubSpot/Salesforce, arricchiteli con i dati aziendali, aggiornate il record nel CRM.

Pipeline per fogli di calcolo— Legge le entità da Google Sheets, esegue l'arricchimento in batch e scrive i risultati in un nuovo foglio.

Enrichment a cascata— Concatena più passaggi di arricchimento con logica condizionale: usa prima un modello veloce, poi ripeti l'arricchimento sugli errori con un modello più capace.

Aggiornamento pianificato— Esegui secondo una pianificazione cron per ri-arricchire i record obsoleti con i modelli AI più recenti.

Basato su webhook— Esponi un endpoint webhook che accetta i dati di un'entity, la arricchisce e restituisce il risultato in modo sincrono.