Separare conoscenza, ricerca e adapter
Separare conoscenza, ricerca e adapter — Creare e consegnare un piccolo portale AI privato. Moduli con confini espliciti; Recupero lessicale controllato; Un adapter con modalità dichiarata. Esercitazione pratica: Separare conoscenza, ricerca e adapter.
Versione demo. I materiali sono in fase di revisione editoriale.
Argomenti trattati
- Moduli con confini espliciti
- Recupero lessicale controllato
- Un adapter con modalità dichiarata
Moduli con confini espliciti
Crea moduli senza avviare server incompleto. knowledge.json dati, knowledge.mjs recupero autorizzato, model.mjs adapter, service.mjs contratto, app.mjs HTTP, server.mjs avvio. public solo UI. Permette test senza browser e cambio adapter senza segreti frontend. Il modello riceve passaggi scelti, non tutto knowledge. Prima autorizzazione, poi rilevanza: titoli privati possono trapelare. Tre documenti richiedono JSON, non database vettoriale per chiamarlo RAG. Collezioni maggiori richiedono indici diversi mantenendo controllo prima dei passaggi. Documenta architettura iniziale senza scala promessa. Nessun modulo accetta percorsi server arbitrari dall’utente.
portal-lab/
knowledge.json
knowledge.mjs
model.mjs
auth.mjs
service.mjs
app.mjs
server.mjs
public/index.html
public/app.js
test/app.test.mjs
Recupero lessicale controllato
Salva knowledge.mjs. visible seleziona propri/shared; retrieve verifica docIds con identico404 per ignoti e altrui. Poi confronta token da tre caratteri con pochi stopword inglesi. È ricerca lessicale didattica, non semantica: receipt trova receipt, refund può non trovare returns. Massimo due passaggi di500 caratteri con version/source senza owner. Troncamento può perdere contesto: raccolte maggiori richiedono chunking, la fixture breve no. Verifica payroll→[] e Alice con budget esplicito→404. Nessuna corrispondenza non prova assenza nel mondo, solo mancanza di supporto autorizzato. Nessun percorso utente viene letto: backend passa documenti noti.
// knowledge.mjs
export const visible = (docs,user) => docs.filter(d => d.owner===user || d.owner==="shared");
const words = text => (text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []);
export function retrieve(docs,user,question,docIds) {
const allowed = visible(docs,user);
let selected = allowed;
if (docIds !== undefined) {
if (!Array.isArray(docIds) || docIds.length<1 || docIds.length>2 || docIds.some(id=>typeof id!=="string"))
throw Object.assign(new Error("BAD_DOCUMENT_SELECTION"),{status:400});
if (docIds.some(id=>!allowed.some(d=>d.id===id)))
throw Object.assign(new Error("DOCUMENT_NOT_FOUND"),{status:404});
selected = allowed.filter(d=>docIds.includes(d.id));
}
const stop = new Set(["the","and","what","does","how","for","with"]);
const terms = [...new Set(words(question).filter(t=>t.length>=3 && !stop.has(t)))];
return selected.map(d=>({d,score:terms.filter(t=>new Set(words(d.text)).has(t)).length}))
.filter(x=>x.score>0).sort((a,b)=>b.score-a.score || a.d.id.localeCompare(b.d.id))
.slice(0,2).map(({d})=>({id:d.id,title:d.title,version:d.version,source:d.source,text:d.text.slice(0,500)}));
}
Un adapter con modalità dichiarata
Salva model.mjs come adapter estrattivo deterministico. Non usa rete né risponde oltre passaggi: restituisce frasi autorizzate e citazioni. Verifica UI, contratto e accesso. Non confrontarlo con LLM per velocità o comprensione: non genera un modello. Passaggi vuoti danno insufficient_sources. «Apri altri file» nel documento resta testo: non ci sono strumenti. Un futuro modello locale mantiene interfaccia e contesto autorizzato con valutazione separata di qualità/iniezioni. ID citazione valido non dimostra verità generata. Lo stub cita letteralmente, ma fixture e versione contano. Mostra mode accanto alla risposta per non confondere test e capacità AI dimostrata.
// model.mjs
export async function answerWithModel({passages}) {
if (!passages.length) return {status:"insufficient_sources",text:"No supporting source.",citations:[],mode:"stub-extractive"};
return {status:"answered",text:passages.map(p=>p.text).join("\n"),
citations:passages.map(p=>({id:p.id,version:p.version,source:p.source})),mode:"stub-extractive"};
}
Esercitazione pratica
Separare conoscenza, ricerca e adapter
Vai alla lezione