AgileV — la prova dal posto

Per chi: i prodotti che consumano AgileV (nis2, lg231, trpg, taxai, aiepod, il core quando passerà). Dove si esegue: sul tuo box, non su agilev-01.

Dal box di AgileV si vede che il servizio risponde e quanto ci mette. Non si vede se dal tuo box, con la tua chiave, attraverso la tua rete, i vettori che ricevi oggi sono ancora quelli con cui hai costruito il tuo indice. Questa è quella prova, in un comando.

Come si prende ed esegue

curl -s https://artefatti.agile.software/agilev-prova-dal-posto.html \
  | sed -n 's/^#B64 //p' | tr -d '\n' | base64 -d > agilev-prova-dal-posto.sh
sha256sum agilev-prova-dal-posto.sh    # atteso: adb7eeafd59e6e2d608c6d2b5f12ed997afafa0b839c8cffabcf10fc8b707dad

# la chiave in un file, mai sulla riga di comando (finirebbe in `ps` e nella storia della shell)
umask 077; printf '%s' "$AGILEV_API_KEY" > /tmp/agilev.key      # oppure incollala tu nel file

bash agilev-prova-dal-posto.sh --chiave /tmp/agilev.key ; rm -f /tmp/agilev.key

La stessa riga vale su https://agilev.agile.software/prova-dal-posto.html (dopo l'allineamento del sito) e sulla copia negli artefatti, che è identica byte per byte. Serve solo bash, curl e python3: nessuna libreria da installare. Per provare la configurazione senza consumare niente (niente richieste, niente fattura): --niente-consumo. Se ti serve solo la riga da rimandare indietro: --riga.

Che cosa controlla

Controllo	Perché
nome, TCP, TLS, scadenza del certificato	la rete e il bordo, visti da te
`/health`, `/v1/models`	modelli caricati, contratto in linea, bge-m3 a 1024
401 KEY_MISSING e 401 KEY_INVALID	gli errori sono quelli documentati: il tuo client può fidarsi
`/v1/usage`	chi sei, i tuoi ambiti, il tuo limite al minuto, i tuoi consumi del mese (leggerli è gratis)
coseno col vettore custodito	il controllo che conta: se scende sotto 0,9999 i vettori non sono più quelli del tuo indice. È il guasto più silenzioso che AgileV possa avere e si vede solo da qui
ripetibilità e cache	la stessa frase dà lo stesso vettore bit per bit, e la seconda volta è quasi gratis
`/embed` storico, `/v1/rerank`	i due formati che qualcuno di voi usa già
intestazioni `X-RateLimit-*`	col contratto 1.2; con la 1.1 in linea oggi il controllo è «saltato», non un allarme
tempi da qui	mediana e massimo dal tuo box, andata e ritorno compresi
i contatori si muovono di quello che hai speso	la fattura conta quello che hai davvero mandato

Che cosa NON fa

Non legge i tuoi dati e non li manda da nessuna parte: spedisce tre frasi fisse scritte nel file.
Non stampa mai la tua chiave, e non la fa comparire in ps (viaggia in un file di intestazioni 0600).
Non scrive nulla fuori da una cartella temporanea 0700, che cancella uscendo.
In modalità piena spende 7 richieste di poche decine di caratteri, contate nei tuoi consumi.

Che cosa rimandare ad AgileV

L'ultima riga, quella che comincia con RIGA:. Nient'altro — e mai la chiave. Per esempio:

dico agilev "RIGA: agilev-prova-dal-posto trpg 2026-09-28T19:00Z contratto=1.1 controlli=17 KO=0 coseno=1.000000 mediana=0.214s"

Se un controllo è KO, mandaci anche quella riga (non stampa dati tuoi). Se il KO è VETTORI CAMBIATI: fermati e avvisa subito, non reindicizzare.

Quando rifarla

Dopo ogni deploy di AgileV annunciato su agilev.agile.software/novita.html — il primo è il passaggio al contratto 1.2 — e prima di una reindicizzazione grossa.

Pagina generata da server/agilev-prova-pagina.py sul box di AgileV. Lo script sta nel repo in server/agilev-prova-dal-posto.sh e, dopo l'allineamento del sito, anche su https://agilev.agile.software/esempi/agilev-prova-dal-posto.sh.

this page in English