Firmato ma orientabile: il divario di integrità testo-vettore nella RAG offline

Codice, dati e risultati per il paper Signed but Steerable: Measuring and Closing the Text-Vector Integrity Gap in Offline Retrieval-Augmented Generation (G. Feretzakis, A. Papaspyridis, securagen.ai).

Archiviato su Zenodo: 10.5281/zenodo.23945569 (tutte le versioni; release v1.0.2, citata nel paper: 10.5281/zenodo.23948839). L'identificatore arXiv del paper sarà aggiunto quando sarà disponibile.

Cosa è presente

• ragtrust/ libreria condivisa, inclusa codeverify.py, il verificatore di riferimento a livello di codice usato per ogni risultato di verifica del codice (ambiguità decisa solo dalla ricomputazione del verificatore; accettazione basata solo sui vicini; canonicalizzazione).
• desktop/ esperimenti eseguiti sul desktop: scoring di astensione (E1) e la sua verifica su MS MARCO, l'attacco di desincronizzazione dei vettori e la legge del margine (E7), i margini BEIR, l'esposizione del database vettoriale, la dimostrazione FAISS, la verifica a livello di codice e il determinismo delle pipeline float.
• device/ esperimenti eseguiti sulla CPU del Raspberry Pi 5: potatura del contesto (E2), il costo della verifica accanto al modello linguistico (E4), embedding lato dispositivo e fedeltà INT8 (E5), l'attacco end-to-end (E7) e gli aggiornamenti dei pack (E8).
• analysis/ analisi, i controlli di precisione e unità, e make_figures.py, che rigenera le figure.
• data/ il corpus derivato da SQuAD, le finestre, le domande e i vettori; results/ gli output per esperimento; tests/ i test unitari; remote/ gli helper per pilotare il Pi dal desktop (adattare i nomi host).
• PROTOCOL.md ipotesi fissate prima della raccolta dati e il registro delle deviazioni e delle analisi esplorative. I numeri degli esperimenti seguono il protocollo; E3 ed E6 non fanno parte di questa release.
• pins.json revisioni fissate di modelli e strumenti.

Avvio rapido

• Test: python tests/test_codeverify.py.
• Ambiente desktop: bash desktop/setup_desktop.sh; figure: python analysis/make_figures.py.
• Esperimenti sul dispositivo: un Raspberry Pi 5, Python con device/requirements_device.txt, e llama.cpp al commit in pins.json.

Esecuzione degli esperimenti sul dispositivo

Sul Raspberry Pi, dopo cp device/config.env.example device/config.env (adattare i percorsi) e aver installato device/requirements_device.txt in venv_device:

• Generazione E2 ed E7: bash device/inner_generate.sh avvia llama-server ed esegue k3_full (prime 60 domande, controllo di riproducibilità), k5_ce3, k10_ce3, k10_ce5, k5_bi3, k5_ce3 con il selettore INT8 online, e le configurazioni E7; solo la configurazione end-to-end CPU-INT8: bash device/run_e7_cpu_int8.sh. Le varianti k5_ce3w, k3_ce3 e k3_ce3w si eseguono con python device/e2_generate.py --config <name> mentre llama-server è in esecuzione (avviato come in device/inner_generate.sh). Una configurazione viene saltata quando esiste results/e2/status_<name>.json; spostare quei file altrove per rigenerare i risultati rilasciati.
• E4: python device/e4_contention.py; E5: python device/e5_reindex.py --backends ort-fp32,ort-int8 --batch 32 (la dimensione del batch dei risultati rilasciati: l'INT8 dinamico dipende dal batch, e batch di 64 producono vettori diversi); E8: python device/e8_device_verify.py --vector-backend ort-fp32.
• Dal desktop, remote/pi_sync.sh copia il repository sul Pi e remote/pi_fetch.sh recupera i risultati.

Dove si trovano i numeri del paper

• Legge del margine su SQuAD (Tabella 2): results/e7/margin_law_squad.json; altri corpora e Fig. 1: results/e7/beir_margins.json e results/e7/margins/; esposizione alla soglia di riferimento CPU-INT8: results/e7/cpu_int8_exposure.json; controlli di precisione numerica e delle unità: results/e7/margin_precision_check.json; calibrazione della soglia di riferimento INT8 (quantile esatto, finestre oneste al di sotto di essa, ri-codifica bit per bit con batch 32): results/e5/int8_calibration_check.json (analysis/e5_int8_calibration_check.py).
• Store compressi: results/e7/vecdb_quant.json; audit FAISS e attacco eseguito: results/e7/faiss_integrity.json; budget residuo: results/e7/guard_budget.json.
• End to end sul dispositivo: results/e7/analysis.json (risposte corrette e rifiuti) e results/e7/e2e_checks.json (stesse domande, budget angolare, payload nel contesto top-3).
• Potatura del contesto (E2): results/e2/decomposition.json; costo accanto al modello linguistico (E4): results/e4/.
• Figure: results/figures/fig_margin_law.pdf (Fig. 1) e results/figures/fig_vdb.pdf (Fig. 2), rigenerate da analysis/make_figures.py.

Non incluso

• Pesi dei modelli e grafi ONNX esportati (licenze): scaricati e ricostruiti dagli script alle revisioni fissate.
• Dati BEIR e MS MARCO e vettori derivati (licenze): scaricati dagli script.
• File vettoriali di grandi dimensioni e cache, rigenerati dagli script: results/e7/squad_question_vectors.npz (analysis/margin_law_squad.py) e results/e7/proxy_vectors.npz (analysis/margin_law.py).
• Input intermedi rigenerati o scaricati dagli script: results/e7/vecs/ (scritti da desktop/beir_margins.py), results/e7/scale_*.npy (scritti dagli script di verifica del codice), data/beir/ e artifacts/models/ (scritti da desktop/export_onnx.py).
• Log di esecuzione.

Alcuni script di analisi caricano cache che hanno creato essi stessi con numpy.load(..., allow_pickle=True); caricare tali file solo dalle proprie esecuzioni, mai da fonti non attendibili.

Risorse di terze parti

Modelli, dataset e le relative licenze sono elencati in DATA_LICENSES.md. Si prega inoltre di citare SQuAD 2.0 (Rajpurkar et al., 2018), BEIR (Thakur et al., 2021), MS MARCO (Bajaj et al., 2016), BGE-M3 (Chen et al., 2024) e Sentence-BERT (Reimers e Gurevych, 2019) quando si utilizzano le parti corrispondenti.

Note

• FAISS si comporta come progettato per tutto il tempo: fornisce formati di archiviazione e ricerca, non audit di integrità. Il modello di minaccia è un editore o scrittore compromesso dei vettori archiviati, non un difetto di alcuna libreria o prodotto.
• Questo è codice di ricerca, fornito così com'è e senza garanzia (vedere LICENSE).
• Raspberry Pi è un marchio di Raspberry Pi Ltd. Gli altri nomi di prodotto sono marchi dei rispettivi proprietari.

Licenza

Copyright 2026 securagen.ai P.C. MIT per il codice e i nostri risultati; i dati derivati da SQuAD, i file dei risultati che contengono testo SQuAD e le risposte generate mantengono CC BY-SA 4.0; vedere LICENSE e DATA_LICENSES.md per i dettagli e per i termini degli altri dataset e modelli.