La risposta breve
Riconoscere una volta, leggere più volte. Leggere un documento è di gran lunga l'operazione più costosa di un campo IA, quindi esattamente un campo legge gli allegati e scrive un foglio di lavoro strutturato — JSON, in un campo di testo lungo. Ogni altro campo è un economico lettore di solo testo puntato su un percorso all'interno di quel foglio di lavoro. Venti valori estratti costano una lettura di documenti più venti letture di testo, e ogni valore deriva dalla stessa lettura anziché da venti letture indipendenti che non concordano.
Il vincolo che determina tutto il resto: un processo legge un'istantanea del record acquisita al suo avvio, quindi un campo IA non può vedere ciò che un altro campo IA ha scritto nello stesso processo. Ogni dipendenza da IA a IA è quindi un confine tra processi — un passaggio IA per processo, concatenato al completamento.
Il problema di business
Un rivenditore acquista dai fornitori e rivende ai clienti finali. Ogni trattativa porta con sé due documenti: il preventivo del fornitore — quanto costa la merce — e il preventivo dell'azienda al cliente — a quanto verrà venduta. Il margine della trattativa è la differenza, e si trova in quei due PDF.
In pratica nessuno lo calcolava al momento della trattativa. Il campo del margine nel CRM era precompilato con una percentuale predefinita, e il numero reale emergeva settimane dopo, alla fatturazione. Ogni report sulla pipeline, ogni previsione e ogni proiezione delle provvigioni nel frattempo si basava su una stima di cui nessuno aveva motivo di fidarsi.
Ciò che l'azienda voleva era semplice da formulare:
- il costo effettivo del venduto e il margine effettivo, calcolati dai documenti, nel momento in cui i preventivi vengono allegati;
- un audit trail visibile — da quale documento proviene ogni cifra e come si è arrivati al calcolo;
- un segnale esplicito quando i documenti non consentono una risposta affidabile, anziché un numero sbagliato presentato con sicurezza;
- nessun nuovo inserimento di dati per il team di vendita.
Le complicazioni sono la parte interessante. I due documenti raramente corrispondono uno a uno. Un preventivo quadro del fornitore può coprire una capacità molto superiore a quella che la trattativa vende effettivamente, quindi confrontare i totali dei documenti produce un margine del tutto sbagliato — il confronto corretto scala in base alla quantità effettivamente venduta. I documenti riportano più di un totale generale, e quello giusto non è sempre il più alto. I nomi delle aziende compaiono su entrambi i documenti, quindi il lato acquisto e il lato vendita vanno distinti in base al ruolo e non al nome. E una società sorella in un altro paese fa sembrare un acquisto infragruppo un acquisto da terzi.
Perché l'approccio ovvio non funziona
L'istinto è diretto: decidere quali venti valori si vogliono, creare venti campi IA, puntarli tutti sui documenti del record, scrivere un prompt per ciascuno e premere Update Fields. Fallisce in quattro modi distinti, e solo il primo è evidente.
Sono venti letture di documenti, non una
Leggere un PDF è l'operazione costosa — misurata in circa 23 secondi per un insieme di due documenti, contro circa 11 secondi per una lettura di solo testo. Venti campi che aprono ciascuno gli stessi documenti moltiplicano per venti la parte più lenta del lavoro, per informazioni già estratte diciannove volte.
I numeri non concordano tra loro
Peggio che lento. Ogni campo ricava di nuovo, in modo indipendente, le cifre di base, e su un insieme di documenti non banale non arrivano tutti alla stessa risposta. Si finisce con un costo del venduto da un campo e un margine da un altro che non sono coerenti tra loro, e senza modo di capire quale sia sbagliato.
Non c'è un ordine garantito
I campi attivati dal pulsante Update Fields vengono eseguiti senza una sequenza definita. Qualsiasi campo pensato per basarsi sull'output di un altro è una corsa, e sembrerà funzionare al primo test per poi fallire in modo intermittente per sempre.
Un campo non può vedere ciò che un campo affiancato ha appena scritto
Comportamento della piattaforma. Un processo di automazione legge un'istantanea del record acquisita al suo avvio. Un campo IA non può vedere ciò che un campo IA precedente ha scritto all'interno dello stesso processo — legge in silenzio il valore precedente. Tra processi diversi funziona correttamente.
È il vincolo architetturale più importante dell'intero progetto, e fallisce in silenzio: il valore che legge è un valore reale, solo quello vecchio.
Modello dati — riconoscere una volta, leggere più volte
Un solo campo si occupa della lettura. Tutto il resto legge l'output di quel campo.
- Un campo foglio di lavoro — testo lungo — ha i documenti attivati come fonte di dati. Il suo prompt gli dice di restituire un unico oggetto JSON e nient'altro. È l'unico campo che apre mai un PDF.
- I campi lettori — uno per ogni valore che si vuole in un vero campo tipizzato — hanno i documenti disattivati. Ciascuno legge il foglio di lavoro ed estrae un percorso da esso.
- I campi formula gestiscono l'aritmetica tra i valori riconosciuti. Sono sempre aggiornati e non possono disallinearsi, cosa che invece farebbe un terzo campo IA incaricato delle somme.
La regola dei livelli. Un campo legge i documenti oppure legge un campo foglio di lavoro — mai entrambi. Un lettore lasciato con l'accesso ai documenti attivo ricaverà di nuovo i valori dalla fonte e contraddirà il foglio di lavoro che doveva analizzare. Disattivi esplicitamente i documenti su ogni lettore.
Perché JSON e non righe con etichetta
Non esiste un tipo di campo JSON, ma un campo di testo lungo il cui prompt dice
"restituire solo questo oggetto JSON, nessun testo prima o dopo" produce in
modo affidabile JSON valido. Si annida, contiene array, e un lettore può essere puntato
su un percorso come totals.cost_of_sale anziché su un prefisso di riga.
Anche un output piatto KEY: value funziona e va bene dove è già collaudato,
ma JSON è la scelta predefinita migliore per il lavoro nuovo.
Livelli di dipendenza
Ogni campo appartiene a un livello determinato da ciò di cui ha bisogno, non da una preferenza. Nell'implementazione di riferimento:
| Livello | Campi | Legge |
|---|---|---|
| L0 | Classificazione dei documenti | i PDF |
| L1 | Stato dell'insieme di documenti | L0 |
| L2 | 10 lettori di identificazione + il calcolo + una verifica incrociata indipendente | L0 / i documenti |
| L3 | Il foglio di lavoro descrittivo | L2 |
| L4 | 3 lettori di importi + 4 lettori descrittivi | L2, L3 |
Il campo di stato in L1 è deliberatamente da solo nel proprio livello. È il filtro che decide se l'insieme di documenti sia utilizzabile — e tenerlo separato è ciò che evita di spendere dodici chiamate IA su un insieme che non avrebbe mai prodotto una risposta.
Configurazione a livello di campo
Cosa può e non può scrivere un campo IA
Il server elenca i propri tipi supportati:
| Supportati | Non supportati |
|---|---|
currency, email, float, input (testo su una riga), integer, phone, text_area, url |
date, dropdown, checkbox, lookup |
Due conseguenze di cui tenere conto nel progetto fin dall'inizio. Una data riconosciuta deve essere registrata come testo — non c'è modo di far compilare a un campo IA un vero campo data. E un valore di tipo enumerativo deve essere un campo di testo il cui prompt vincola l'output a un elenco fisso di codici, con i report che raggruppano sulla stringa risultante anziché sulle opzioni di un menu a tendina. Lo stesso vincolo si fa sentire sul lato dell'importazione: un valore di menu a tendina senza un'opzione corrispondente arriva vuoto e segnala successo.
Scrivere lo schema JSON in un prompt
L'editor dei prompt interpreta i prompt come HTML ed elimina in silenzio tutto ciò
che sta tra parentesi angolari. Esprima lo schema con valori letterali "", 0,
[] e null — mai con <placeholders>.
Nell'implementazione di riferimento una singola modifica dall'interfaccia ha distrutto 23 segnaposto su 26 nel contratto di output di un prompt, lasciando etichette spoglie e frammenti alterati. Tutte le regole in prosa sono sopravvissute, quindi il danno era invisibile senza un diff. Conservi i prompt in un sistema di controllo di versione al di fuori della piattaforma e faccia un diff dopo ogni modifica apportata tramite l'interfaccia.
Campi formula per l'aritmetica
- Le formule semplici non supportano alcuna chiamata di funzione — aritmetica su riferimenti a campi e valori letterali, niente di più. I nomi di funzione vengono rifiutati in fase di analisi.
- Le formule avanzate supportano le funzioni, ma il campo deve essere creato come campo a formula calcolata. Applicare a posteriori una formula avanzata a un campo numerico esistente viene accettato, viene pubblicato, si rilegge intatto — e non calcola mai, perché il campo mantiene la sua natura di colonna memorizzata. Lo crei; non lo converta.
- Non divida mai per un valore riconosciuto. Un campo numerico vuoto viene letto come zero senza alcuna protezione, quindi una formula percentuale genera una divisione per zero su ogni record non ancora elaborato.
La presenza nel modulo è funzionale
Un campo IA può leggere solo un campo che si trova nel modulo di modifica dell'entità. Un campo che esiste, è pubblicato, ha l'anteprima nell'interfaccia attivata e si legge perfettamente tramite l'API è invisibile a un lettore IA se non è collocato nel modulo. Il lettore non scrive assolutamente nulla — nemmeno il valore di riserva specificato dal suo stesso prompt.
Le prove: due campi foglio di lavoro presenti nel modulo avevano tutti e quindici i loro lettori funzionanti; un foglio di lavoro appena creato e non presente nel modulo aveva tutti e tre i suoi lettori che scrivevano zero a ogni esecuzione. I diff della configurazione campo per campo mostravano che i lettori funzionanti e quelli che fallivano erano identici in ogni attributo. L'intera correzione è stata aggiungere il campo al modulo.
Lo stesso vale per i campi calcolati, che fuori dal modulo non calcolano affatto. E un campo formula appena aggiunto resta vuoto su ogni record preesistente finché quel record non viene scritto di nuovo — aggiorni un campo al suo stesso valore per forzare il ricalcolo.
Automazione e logica
L'implementazione di riferimento esegue dodici processi. Non è un eccesso di ingegnerizzazione; è la conseguenza diretta del vincolo dell'istantanea descritto nel §2. Significa però che la disciplina di denominazione e di responsabilità descritta nel Blueprint 011, su come mantenere gestibili le automazioni, si applica fin dal primo processo.
Un nodo IA per livello di dipendenza
Il completamento del nodo è l'unico segnale che dice "questo livello è terminato". Suddividere un livello su due nodi concatenati produce due segnali di completamento indipendenti, e quello che termina per primo attiva troppo presto i passaggi a valle. Quindi ogni campo di un livello va in un unico nodo — nell'implementazione di riferimento un nodo contiene dodici campi e un altro ne contiene sette. È una regola di correttezza, non di ordine.
Concatenare al completamento, non tramite nodi figli
Da quando i campi IA sono diventati asincroni, il nodo di azione IA stesso dispone di una proprietà di attivazione di processo che scatta al completamento della scrittura. È ormai l'unico modo sicuro per raggiungere qualsiasi cosa legga ciò che il nodo ha scritto.
Un normale nodo figlio non attende più l'IA. Un trigger figlio scatta mentre i campi sono ancora in fase di scrittura, e il processo a valle legge il valore precedente — in silenzio. Il log di esecuzione rende visibile la distinzione: il nodo viene prima riportato come scheduled, poi come riuscito con un conteggio dei campi, e solo allora compare la riga del trigger.
Fonte sulla concatenazione dei processi. Centro assistenza di Coevera, Automatizer — triggering a process from another process: gli utenti possono creare «processi più snelli e poi concatenarli in un flusso di lavoro unificato». Quella pagina tratta solo la concatenazione dei processi, non i nodi IA né il momento in cui terminano.
Un processo è un unico percorso lineare
Le condizioni possono diramarsi, ma una volta all'interno di una catena di azioni non è più possibile restringerla — e un nodo di azione può avere esattamente un figlio, quindi non c'è nemmeno una diramazione a partire da un'azione.
La trappola: il secondo ramo di una condizione viene memorizzato, convalidato, si rilegge identico byte per byte e risulta integro — e non viene mai eseguito. Non saltato: mai valutato, senza alcuna riga nel log di esecuzione. Tutto ciò che è condizionale dopo la prima azione deve diventare un altro processo raggiunto da un nodo trigger.
Dove un completamento deve raggiungere più processi a valle, attiva un router — un processo i cui unici nodi sono una catena di nodi trigger. Poiché ogni sottoprocesso filtra sé stesso e un filtro falso arresta quel processo, concatenare in serie processi che si filtrano da soli funziona, e l'ordine conta quando uno successivo legge ciò che uno precedente ha scritto.
Un'ulteriore regola strutturale: il primo nodo di qualsiasi processo deve essere un nodo filtro. Un'azione alla radice viene memorizzata correttamente, risulta integra e mostra un'area di lavoro vuota senza alcun errore.
Tecniche di prompt che hanno fatto una differenza misurabile
- Controlli l'aritmetica nei suoi esempi svolti. Una percentuale di margine è stata sbagliata per settimane perché l'esempio all'interno del prompt indicava un risultato leggermente errato. Il modello copiava fedelmente un esempio sbagliato, non arrotondava con negligenza.
- Un'autoverifica deve imporre un numero ricavato in modo indipendente. "Rimoltiplicare la percentuale e confrontare" ha funzionato. "Sommare l'elenco e confrontarlo con il totale" veniva soddisfatto scrivendo due volte il valore atteso, e ha nascosto due errori reali.
- Sostituisca il giudizio con trigger meccanici. Un livello di affidabilità descritto in prosa veniva assegnato in modo incoerente; ricavarlo da una tabella esplicita basata sull'elenco dei flag lo ha reso affidabile.
- Incorpori l'errore osservato come controesempio. Ogni correzione che ha tenuto cita l'output errato effettivo che doveva prevenire.
- Faccia stampare al modello il suo ragionamento dove lei ha bisogno di verificarlo. Un blocco intermedio di scomposizione ha trasformato un numero che variava in modo non riproducibile tra un'esecuzione e l'altra in uno diagnosticabile all'interno di una singola esecuzione.
- Le tolleranze sui controlli mal condizionati devono essere proporzionali. Una tolleranza assoluta fissa su un controllo che moltiplica la differenza tra due percentuali quasi uguali ha prodotto falsi verdetti di disaccordo su trattative dimostrabilmente esatte.
Limiti e compromessi
Le modalità di errore segnalano tutte successo
È questo il tema. Quasi ogni modo in cui questo progetto va storto appare sano dall'esterno.
| Sintomo | Causa effettiva | Come riconoscerla |
|---|---|---|
| Il nodo registra successo, updated 0 fields | Esaurimento dei crediti IA | Colpisce alla fine di una catena, perché i nodi precedenti hanno speso gli ultimi crediti. Si presenta esattamente come "l'ultimo passaggio è guasto". |
| Il nodo registra successo, updated 0 fields | Un campo indicato dal prompt non è nel modulo | Altri nodi IA nella stessa esecuzione hanno scritto correttamente. |
| Il lettore restituisce un valore plausibile ma non aggiornato | Istantanea dello stesso processo, oppure un nodo figlio che non ha atteso una scrittura asincrona | Il valore è un valore precedente reale, non un errore. |
| Il ramo non viene mai eseguito, nessun errore | Il secondo ramo di una condizione — memorizzato, convalidato, mai valutato | Nel log di esecuzione non c'è alcuna riga di valutazione che lo riguardi. |
| Campo formula sempre vuoto | Non è nel modulo, oppure una formula avanzata applicata a posteriori anziché creata | Il diff della configurazione rispetto a un campo formula funzionante li mostra identici. |
| Campo segnalato come mancante subito dopo un'esecuzione | Lettura effettuata prima che l'ultima scrittura si stabilizzasse | La stessa lettura, qualche istante dopo, restituisce il valore. |
L'ostacolo che ha dato forma all'intero progetto
In origine gli AI Smart Fields venivano eseguiti in modo sincrono e bloccavano il database durante l'esecuzione. Un passaggio di riconoscimento completo bloccava lo spazio per due-cinque minuti. In uno spazio condiviso con una dozzina di utenti questo non è distribuibile, e l'implementazione è stata tenuta fuori dalla produzione proprio per questo motivo — era corretta e inutilizzabile allo stesso tempo.
Il problema è stato risolto dal rilascio asincrono, e la catena è stata rielaborata sui trigger di completamento il giorno stesso del rilascio. Vale la pena documentarlo anziché eliminarlo in silenzio: è il motivo per cui l'architettura ha questa forma, e rieseguire entrambi i casi di test dopo la rielaborazione ha prodotto cifre identiche a quelle originali sincrone — ed è così che si sa che è cambiata l'infrastruttura e nient'altro.
Altri vincoli incontrati in questa implementazione
- Le operazioni batch sono limitate a 100 record.
- Le formule avanzate non possono essere convalidate tramite l'API — nomi di funzione inventati vengono accettati senza obiezioni, e i valori calcolati non vengono restituiti da una normale lettura del record. Si fidi solo dell'editor delle formule nell'interfaccia.
- L'esecuzione è riservata agli amministratori. Un token di accesso personale può configurare tutto ma non eseguire nulla; l'esecuzione manuale dei processi richiede un utente reale.
- I processi a livello di spazio sono di sola lettura tramite l'API. Gli aggiornamenti vengono rifiutati con un errore di autorizzazione, quindi il lavoro sui processi richiede una finestra in cui siano a livello personale.
- Rinominare un campo non lo rinomina nel modulo — il modulo conserva una propria copia di ogni etichetta.
- I limiti di tipo di file, dimensione e volume dei documenti non sono pubblicati. Li verifichi empiricamente per il suo insieme di documenti.
- L'esecuzione asincrona è leggermente più lenta dall'inizio alla fine — circa 3½ minuti contro 2–3 in modalità sincrona per la stessa catena, perché ogni passaggio attende un evento di completamento. Non blocca più lo spazio, che era l'intero scopo.
Il compromesso tra costo e dettaglio
Dei 22 campi IA dell'implementazione di riferimento, solo sei sono portanti — lo stato, due totali di importi, la percentuale di margine, il livello di affidabilità e l'elenco dei flag. Gli altri 16 sono lettori descrittivi che compilano il record per le persone. Eliminarli dimezza all'incirca il tempo di esecuzione, a scapito dei dettagli riconosciuti sul record. Meglio saperlo prima di presumere che l'intera catena sia necessaria.
Verifica
Il log di esecuzione è l'unico resoconto onesto di ciò che è stato eseguito. Le riletture della configurazione, gli stati di successo e gli indicatori di integrità mentono tutti nei modi specifici catalogati nel §6. Legga il log delle attività del processo dopo ogni esecuzione.
Ciò che è stato effettivamente verificato:
- Numero di campi per nodo, a ogni esecuzione. Un nodo che deve scrivere dodici campi deve registrarne dodici. È il controllo più importante, perché un campo la cui scrittura fallisce in silenzio mantiene il suo valore precedente e corretto — così un'esecuzione su un record non azzerato può sembrare perfetta pur essendo non aggiornata.
- Azzerare e rieseguire da vuoto. Ogni campo IA impostato a null prima di un passaggio completo, così che nessun valore possa essere ereditato da un'esecuzione precedente.
- Due insiemi di documenti contrastanti dall'inizio alla fine — una semplice coppia uno a uno e una coppia quadro in cui il preventivo del fornitore copre molto più di quanto la trattativa venda. La seconda è quella che dimostra il progetto, perché lì il confronto dei totali dei documenti dà una risposta gravemente sbagliata.
- Ogni lettore confrontato con il proprio foglio di lavoro di origine, non solo controllato per plausibilità.
- Un campo di verifica incrociata indipendente che legge direttamente i documenti e ricava la stessa cifra per un'altra via, con lo scostamento mostrato sul record. Due numeri ricavati in modo indipendente che concordano sono una prova; un numero che sembra sensato non lo è.
- Ordine dei trigger confermato dal log — che il router abbia attivato le sue destinazioni nell'ordine da cui dipende un filtro a valle.
- Riesecuzione dopo la rielaborazione asincrona e confronto con i dati di test sincroni. Cifre identiche hanno dimostrato che è cambiata l'infrastruttura e non la logica.
Cosa segnalerebbe una regressione: un nodo che registra meno campi di quanti ne contenga il suo livello; un lettore che restituisce un valore in contraddizione con il foglio di lavoro che legge; lo scostamento della verifica incrociata che si allarga; il riconoscimento che produce un output sicuro su un insieme di documenti che avrebbe dovuto essere scartato come inutilizzabile.
Domande frequenti
L'IA può leggere un PDF allegato a un record del CRM e compilare i campi a partire da esso?
Sì. In Coevera CRM gli AI Smart Fields possono usare i documenti allegati al record come fonte di dati e scrivere un valore estratto in un campo. L'approccio ingenuo — un campo IA per ogni valore, ciascuno dei quali legge i documenti — è costoso e incoerente, perché leggere un documento è di gran lunga l'operazione più costosa e ogni campo ricava di nuovo, in modo indipendente, le cifre di base. Il pattern affidabile è riconoscere una volta, leggere più volte: un campo legge i documenti e scrive un foglio di lavoro strutturato in JSON in un campo di testo lungo, e ogni altro campo è un economico lettore di solo testo puntato su un percorso all'interno di quel foglio di lavoro. Un'estrazione di venti valori passa da venti letture di documenti a una lettura di documenti più venti letture di testo.
In quali tipi di campo può scrivere un AI Smart Field?
Il server elenca come tipi supportati currency, email, float, input (testo su una riga), integer, phone, text_area e url. I campi a discesa, data, casella di controllo e lookup non possono essere scritti da un AI Smart Field. Una data riconosciuta deve essere registrata come testo, e un valore di tipo enumerativo deve essere un campo di testo il cui prompt vincola l'output a un elenco fisso di codici, con i report che raggruppano sulla stringa.
Perché il mio campo IA segnala successo ma non scrive nulla?
Ci sono due cause comuni ed entrambe segnalano successo. La prima è la presenza nel modulo: un AI Smart Field può leggere solo un campo collocato nel modulo di modifica dell'entità. Un campo che esiste, è pubblicato e si legge senza problemi tramite l'API è invisibile a un lettore IA se è fuori dal modulo — il lettore non scrive assolutamente nulla, nemmeno il valore di riserva specificato dal suo stesso prompt. La seconda è l'esaurimento dei crediti IA, che registra il nodo come riuscito con zero campi aggiornati. Le distingua in base al fatto che altri nodi IA nella stessa esecuzione abbiano scritto correttamente: se sì, sospetti la presenza nel modulo; se gli errori si concentrano alla fine di una catena, sospetti i crediti.
Un campo IA può leggere ciò che un altro campo IA ha appena scritto?
Non all'interno dello stesso processo di automazione. Un processo legge un'istantanea del record acquisita al suo avvio, quindi un campo IA non può vedere ciò che un campo IA precedente ha scritto nello stesso processo — legge in silenzio il valore precedente. Ogni dipendenza da IA a IA deve quindi essere un confine tra processi: un passaggio IA per processo, con il processo successivo attivato al completamento. Da quando sono stati rilasciati i campi IA asincroni, il nodo di azione IA stesso dispone di una proprietà di attivazione di processo che scatta al completamento della scrittura; un normale nodo figlio non attende l'IA e leggerà dati non aggiornati.