Lezione gratuita

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

Programma del corso

  1. Definire un portale privato e un risultato verificabile
  2. Separare conoscenza, ricerca e adapter
  3. Verificare identità e accesso nel backend
  4. Collegare HTTP, browser e risposte con fonti
  5. Limiti, registri e avvio controllato
  6. Test d’integrazione, ripristino e consegna