Best Practices per lo Sviluppo di Applicazioni AI/RAG su Dati Botanici
Pratiche raccomandate per sviluppatori che costruiscono sistemi di recupero informazioni, classificatori e agenti conversazionali su dati floristici e botanici.
> Informazione a scopo educativo - non sostituisce la consulenza di un esperto. Per qualsiasi applicazione in ambito scientifico, medico o legale legata alle piante, consultare un botanico qualificato.
Validare ogni nome scientifico contro GBIF o POWO prima di inserirlo nel corpus
Ogni nome scientifico di pianta nel corpus deve essere verificato contro GBIF (/v1/species/match?name=...&kingdom=Plantae) o POWO (powo.science.kew.org/api/2/search?q=...). I nomi non trovati in nessuna delle due fonti non devono essere usati. Includere nel record del corpus il usageKey GBIF o l'ID POWO come campo di provenienza. Questo previene la propagazione di nomi inventati o obsoleti nel RAG.
Da fare: GET /v1/species/match?name=Fagus+sylvatica&kingdom=Plantae → verifica che matchType != "NONE" e status == "ACCEPTED".
Da non fare: inserire nel corpus nomi latini generati da LLM senza verifica esterna.
Usare il nome scientifico come chiave primaria, con alias verso i nomi comuni
Nei sistemi di recupero multi-lingua, la chiave primaria di ogni entità botanica deve essere il nome scientifico (in forma normalizzata: Genere + epiteto specifico + autore abbreviato). I nomi comuni (in 18 lingue o più) sono memorizzati come alias. Questo garantisce che una query in italiano ("quercia farnia") e una in tedesco ("Stieleiche") risolvano alla stessa entità (_Quercus robur_ L.) senza ambiguità.
Da fare: costruire una tabella plant_aliases con colonne scientific_name, language, common_name.
Da non fare: usare il nome comune come chiave primaria nei vettori di embedding.
Aggiungere un disclaimer esplicito su ogni chunk che descrive proprietà di piante
Ogni chunk del corpus che menziona proprietà (in senso lato: ecologiche, tossicologiche, medicinali, alimentari) di piante deve contenere il disclaimer educativo. Anche una sola frase sul fatto che una specie sia "tossica per ingestione" deve essere accompagnata da un disclaimer in-chunk, non solo nella documentazione di sistema. Il disclaimer garantisce che anche un retriever che estrae il singolo chunk preservi il contesto di sicurezza.
> Informazione a scopo educativo - non sostituisce la consulenza di un esperto.
Da fare: aggiungere il disclaimer come prima o ultima frase di ogni chunk contenente tossic|medicinal|edibil|commestibil.
Da non fare: mettere il disclaimer solo nella pagina di overview del pack.
Separare gli artefatti premium dagli artefatti free nel filesystem
Gli artefatti premium (eval.jsonl, corpus.jsonl, data.jsonl, prompts/, schema.sql) devono essere nella directory knowledge-packs-premium/, mai in frontend/public/. Il gate strutturale find frontend/public/content/knowledge-packs/ deve restituire output vuoto prima di ogni commit. Questa separazione garantisce che il contenuto a pagamento non sia scaricabile pubblicamente.
Da fare: verificare con find prima di ogni commit del dominio.
Da non fare: usare un unico albero di directory per free e premium.
Costruire il corpus con chunk auto-sufficienti di 300–600 caratteri
Ogni riga del corpus.jsonl deve essere un chunk testuale auto-sufficiente: un paragrafo o una definizione che abbia senso senza contesto esterno. La dimensione ottimale per la botanica è 300–600 caratteri (circa 80–120 parole), compatibile con il retrieval coseno MiniLM-L6-v2 (dim 384) e con la finestra di contesto dei modelli LLM usati come judge. Chunk troppo corti perdono contesto; chunk troppo lunghi diluiscono il segnale semantico.
Da fare: dividere gli artefatti in chunk per paragrafo o per definizione; aggiungere sempre il campo source_url nel corpus.
Da non fare: inserire interi artefatti come singolo chunk.
Garantire che ogni risposta eval.jsonl sia completamente entailed dai contexts
Ogni entry di eval.jsonl deve avere il campo answer entailed (logicamente deducibile) dai soli contexts forniti. Questo è il requisito RAGAS Faithfulness. Per la botanica, una risposta che cita un nome scientifico deve essere supportata da almeno un context che contenga quel nome. Verificare con eval_pack.py (RAGAS Faithfulness, soglia ≥ 0.5 su campione).
Da fare: per ogni QA pair, controllare manualmente che l'answer si ritrovi nel context prima di eseguire RAGAS. Da non fare: inserire answer con informazioni non presenti nei contexts (anche se tecnicamente corrette).
Aggiornare periodicamente i dati di distribuzione GBIF con API pull programmati
I dati di distribuzione di GBIF cambiano: nuove occorrenze vengono registrate, le segnalazioni di specie invasive si aggiornano, le revisioni tassonomiche cambiano i sinonimi. Per applicazioni di biodiversità production, impostare un job periodico (es. mensile) che aggiorna i record GBIF per le specie chiave del corpus. Usare l'endpoint GBIF Occurrence Download con filtri per aggiornamenti successivi a una data specifica (lastInterpreted).
Da fare: usare l'API GBIF con modifiedSince per pull incrementali.
Da non fare: caricare un dump GBIF una sola volta e non aggiornarlo mai.
Gestire la polisemia dei nomi comuni con entity linking verso GBIF
Molti nomi comuni sono ambigui: "noce" può riferirsi a _Juglans regia_ L. (noce comune europeo) o _Juglans nigra_ L. (noce nero nordamericano). "Lavanda" può indicare _Lavandula angustifolia_ Mill. o _Lavandula latifolia_ Medik. (entrambe su GBIF). Un sistema RAG botanico deve implementare entity linking: quando l'utente usa un nome comune, il sistema risolve l'entità scientifica più probabile dato il contesto geografico e la domanda. L'API GBIF /v1/species/suggest?q= fornisce candidati con usageKey.
Da fare: implementare un entity linker che mappa nome comune → candidati GBIF → scelta in base al contesto. Da non fare: usare il nome comune come query diretta nel retrieval senza disambiguazione.
Strutturare le prompt di sistema con regole esplicite di no-fabbricazione
Le prompt di sistema per agenti botanici devono includere regole esplicite: "Non inventare nomi scientifici. Se non conosci il nome latino, dichiara l'incertezza. Non dare indicazioni su commestibilità, tossicità o uso medicinale senza citare una fonte. Ogni nome scientifico deve essere verificabile su GBIF o POWO." Queste regole riducono significativamente il failure mode delle specie inventate.
Da fare: includere le regole di no-fabbricazione in ogni system prompt del dominio botanica. Da non fare: usare solo le istruzioni "sei un esperto di botanica" senza vincoli espliciti.
Monitorare la copertura del corpus sulle famiglie botaniche principali
Il corpus RAG deve avere copertura bilanciata sulle principali famiglie di piante presenti nel territorio di interesse. Per la flora italiana, le famiglie più ricche di specie sono Asteraceae (>800 specie), Fabaceae, Poaceae, Orchidaceae, Rosaceae. Un corpus sbilanciato (es. 80% Orchidaceae) produce retrieval di bassa qualità per domande su altre famiglie. Monitorare la distribuzione per famiglia con query aggregata su GBIF.
Da fare: verificare la distribuzione per famiglia con group_by family in fase di analisi del corpus.
Da non fare: costruire il corpus solo dalle specie più "famose" (es. solo piante medicinali o specie coltivate).
Usare il formato DarwinCore per lo scambio di dati floristici
Il formato Darwin Core (DwC) è lo standard internazionale per la condivisione di dati di biodiversità. I campi chiave per la botanica includono scientificName, scientificNameAuthorship, taxonRank, family, decimalLatitude, decimalLongitude, eventDate, institutionCode. GBIF e la maggior parte degli erbari digitali esportano in DwC. Usare DwC come formato di scambio garantisce l'interoperabilità con i sistemi di aggregazione globale.
Da fare: usare i campi DwC standardizzati nell'interfaccia di importazione del corpus. Da non fare: creare un formato proprietario per i dati di occorrenza.
Implementare un cache layer per le chiamate API GBIF e POWO
Le API GBIF e POWO hanno rate limit (GBIF: 1000 req/min per utente non autenticato). Per applicazioni che eseguono molte risoluzioni di nomi (es. indicizzazione di un erbario digitale), implementare un cache layer (Redis o SQLite) che memorizzi i risultati per 30+ giorni. I dati tassonomici cambiano raramente; i dati di occorrenza cambiano più frequentemente. Configurare TTL diversi per le due categorie.
Da fare: cache TTL 30 giorni per dati tassonomici; 7 giorni per occorrenze. Da non fare: chiamare GBIF API per ogni richiesta utente in produzione senza caching.