Documentazione dell'API

Basi e autenticazione

Base URL: https://api.agilev.agile.software

Ogni richiesta autenticata porta la chiave in un'intestazione. Sono equivalenti:

Authorization: Bearer agv_…
X-Api-Key: agv_…

Ogni chiave ha ambito (embed, rerank), limite al minuto e quota mensile di caratteri. Vedi i tuoi consumi con GET /v1/usage: una chiave vede solo i propri.

E la chiave da dove arriva. Si chiede una licenza — il modulo è sulla pagina di AgileV, e i tre piani con quota e limite al minuto stanno in Piani — e le chiavi stanno sotto la licenza: si ruota una chiave senza toccare il contratto, e si sospende un contratto senza cambiare la chiave. Chi vuole chiamare il modulo da un programma trova la rotta in POST /v1/richieste-licenza.

Una chiave può essere di una persona digitale, e allora ogni richiesta dice a nome di chi calcola (dall'11/10/2026). È una cosa in più, non un cambio: le chiavi di oggi non sono di nessuna persona e non devono fare niente — stesso corpo, stessi vettori, stessa cache, stessa fattura. Quando invece la chiave viene emessa per una persona (il caso delle persone digitali dello store), quella persona la mette il motore su ogni richiesta: non dovete scrivere niente nel corpo, e il campo persona lo potete mandare solo per dire la sua — con un nome diverso dal suo è 403 PERSONA_UNKNOWN (dal 12/10/2026: fino all'11 il campo era obbligatorio e senza era 400 PERSONA_MISSING). E al contrario: una chiave che non è di nessuna persona che manda quel campo riceve 403 PERSONA_UNKNOWN invece di un 200, perché calcolare, mettere in cache e fatturare a nome di un soggetto che nessuno ha dichiarato è la cosa che questa regola esiste per impedire.

Endpoint

GET/health — stato del servizio

Senza chiave. loaded dice se i modelli sono in memoria; subito dopo un riavvio può essere false per una ventina di secondi. contract è la versione del contratto in esecuzione, novita dove leggere cosa è cambiato: confrontateli con l'ultima lettura per sapere se c'è qualcosa da valutare.

/health risponde anche quando il servizio è pieno di lavoro, ed è una promessa nuova del contratto 1.2 (29/9): questa rotta non passa dalla fila in cui stanno le richieste di calcolo, quindi vale come controllo di vita anche sotto carico. Prima non era vero, e non per poco: con 48 richieste di calcolo insieme /health non rispondeva affatto per decine di secondi (misurato sul servizio 1.1: sonde da 10 s tutte scadute, 20 s di silenzio di fila nel caso peggiore, in 5 giri su 5), quindi chi lo usava per vedere se il servizio era vivo leggeva «morto» su un servizio che stava lavorando. Se avete una vigilanza che chiama /health, dal 1.2 potete crederle; e se vi risponde ok:true mentre le vostre richieste sono lente, non è un guasto: è la fila, e la fila si legge nei tempi, non nella salute.

{"ok":true,"loaded":true,"model":"bge-m3","service":"agilev","dim":1024,
 "contract":"1.2","novita":"https://agilev.agile.software/novita.html",
 "coda":{"stato":"libera","posti":40,"occupati":0,"in_attesa":0}}

coda dice se il servizio è in fila, e ok non cambia mai per questo (29/9). Le richieste di calcolo occupano un posto in una fila da 40: un posto è preso da una richiesta che sta lavorando o che aspetta il suo turno sul modello. Quattro nomi: libera (sotto l'80 % dei posti), carica (oltre, ma un posto c'è), satura (nessun posto libero, o c'è già qualcuno in attesa: chi arriva aspetta), indecidibile (non siamo riusciti a leggere il contatore: vuol dire non lo sappiamo, non va tutto bene). Accanto al nome ci sono i numeri — posti, occupati, in_attesa — così il conto lo potete rifare voi. Misurato con 48 richieste insieme: 95 letture su 95 portano il campo, occupati 40, in_attesa 8; a servizio libero libera con 0 occupati.

Come leggerlo, e come non leggerlo: satura non è un guasto — ok resta true e il codice resta 200, per scelta, quindi se una vigilanza o un grep decide «vivo/morto» da ok continuate a leggere quello: un servizio in fila non va riavviato. Serve a leggere i vostri tempi (con la fila satura il tempo che misurate è attesa, non calcolo); il freno vero resta il 429 con Retry-After. È un'istantanea, non una media. E un campo assente non è libera: un servizio più vecchio di questo contratto non lo manda affatto, e allora il vostro controllo deve dire «non lo so».

GET/v1/models — modelli disponibili

Senza chiave. Elenca solo i modelli realmente disponibili su questa istanza.

{"object":"list","data":[
  {"id":"agilev-m3","object":"model","owned_by":"agile","dim":1024,
   "output_dtypes":["float","int8","uint8","binary","ubinary"],"max_tokens":8192,"sparse":true},
  {"id":"agilev-rerank","object":"model","owned_by":"agile"}]}

sparse: true dice che il modello sa restituire anche i pesi lessicali (return_sparse, contratto 1.2).

Il campo model — cosa fa oggi (e cosa cambierà, con preavviso)

Oggi nessun nome di modello viene rifiutato: il campo è registrato, non validato. Misurato il 28/9 su 36 casi (4 rotte × 9 nomi), sul codice 1.1 in produzione e sulla 1.2, con esito identico sulle due: zero 400. Il deploy della 1.2 non cambia una riga di questa tabella.

/embed non guarda il campo affatto: il formato storico ha solo texts e un model nel corpo viene scartato senza nemmeno essere contato. Una richiesta con un nome sconosciuto viene comunque servita e contata in fattura: la validazione è di forma, non di sostanza.

Come sapere se vi riguarda, senza chiedercelo (dal 29/9/2026): GET /v1/usage porta il campo model_unknown — quante volte la vostra chiave ha mandato un nome che non riconosciamo, per mese e per rotta. È gratis e si può guardare da un controllo automatico. Vuota è la risposta normale.

Quando diventerà 400 MODEL_UNKNOWN. Non presto: il 29/9 alle 03:2x, letto dai contatori di produzione, 4 delle 7 richieste di rerank riuscite dal riavvio del 27/9 portavano un nome non riconosciuto (il 28/9 erano 3 su 6). Prima di cambiare succederanno, in quest'ordine, tutte e quattro queste cose: (1) il contatore dei nomi sconosciuti resta a zero in modo stabile — e fino al 29/9 questa frase non era nemmeno misurabile, perché il contatore vive in memoria e ripartiva da zero a ogni riavvio: «stabilmente a zero» si otteneva riavviando. Ora il conto per chiave è sul disco; (2) il contatore diventa attribuibile — sapere che qualcuno sbaglia senza sapere chi avvisare non basta. Fatto il 29/9/2026: il servizio registra, per chiave e per rotta, quante richieste hanno portato un nome che non riconosce (solo numeri, mai il nome ricevuto, che è testo vostro); (3) la voce compare in Novità e arriva un messaggio diretto a ogni titolare di chiave, con almeno 30 giorni fra l'avviso e il cambio; (4) il cambio va in un deploy da solo, mai insieme ad altro.

POST/v1/embeddings — vettori (compatibile OpenAI)

Ambito embed. I vettori sono normalizzati: il prodotto scalare è già il coseno.

persona non è uno di questi: è un campo che la rotta applica, e per questo si rifiuta invece di ignorarlo. Vale sulle quattro rotte di calcolo — /v1/embeddings, /v1/rerank, /v1/tokenize e anche /embed. Se la vostra chiave non è di nessuna persona, non cambia niente: non mandate il campo e tutto resta com'era, inclusa la cache. Se è di una persona digitale, non dovete fare niente lo stesso: la persona per cui la chiave è stata emessa la mette il motore su ogni richiesta, e se il campo lo scrivete deve dire quella — una chiave vale per quella persona e nessun'altra. Il 403 dice PERSONA_UNKNOWN e non «non è la tua», perché dirvi che una persona esiste ma è di qualcun altro sarebbe già un dato di un'altra persona.

E tenant ha la stessa natura (dal 12/10/2026): anche lui è un campo che le quattro rotte di calcolo applicano, e per questo si rifiuta invece di ignorarlo. La differenza con persona è che un tenant ce l'hanno tutte le chiavi, quindi il campo lo può scrivere chiunque — ma solo per dire il proprio: un altro nome è 403 TENANT_UNKNOWN, «sconosciuto» e non «non è il vostro» per la stessa ragione di PERSONA_UNKNOWN. Se non lo scrivete, non cambia niente: il tenant è quello della vostra chiave e lo mette il motore, oggi come ieri. Non confondetelo con il tenant delle rotte di amministrazione qui sotto: là il campo c'era già e vale come prima.

Tutti questi rifiuti si contano come gli altri: li ritrovate in GET /v1/usage, campo rejected.

Sulle rotte di amministrazione (/admin/*) un campo in più non si elenca e basta: se è il nome che la rotta sorella usa per la stessa cosa — rate_per_min/limite_al_minuto, quota_chars_month/quota_mensile, tenant_id/tenant — la chiamata viene rifiutata con 400 FIELD_WRONG_NAME e il messaggio dice come si chiama il campo su quella rotta. Il motivo è che lì il danno era peggiore del silenzio: una chiave chiesta con limite_al_minuto: 300 nasceva a 120 e una chiesta con tenant_id nasceva nel nostro tenant, cioè fuori dalla fattura del cliente.

curl https://api.agilev.agile.software/v1/embeddings \
  -H "Authorization: Bearer $AGILEV_KEY" -H "Content-Type: application/json" \
  -d '{"model":"agilev-m3","input":["Il contratto scade il 30 settembre"]}'

{"object":"list","model":"agilev-m3","dtype":"float",
 "data":[{"object":"embedding","index":0,"embedding":[-0.0850,0.0054,…]}],
 "usage":{"prompt_tokens":8,"total_tokens":8,"chars":34,"truncated_texts":0,"cached_texts":0}}

L'ordine di data segue sempre l'ordine di input, e index lo conferma. usage.prompt_tokens è il conteggio reale del tokenizer; usage.chars è l'unità su cui si misura la quota.

usage.cached_texts (dal 7/10/2026): quanti testi di questa richiesta erano già nella nostra cache, cioè non sono passati dal modello. Sono fatturati come gli altri — la quota e il prezzo si misurano sui caratteri che ci spedite, usage.chars non cambia — e il campo serve a farvene accorgere. La cache è separata per cliente: «già visto» vuol dire visto da voi.

Pesi lessicali (return_sparse, contratto 1.2)

Perché esistono: sui testi con articoli numerati il solo vettore denso confonde «25-bis» con «25-ter» o «25-undevicies» (sul d.lgs. 231/2001 l'articolo citato è al primo posto in 1 caso su 28). I pesi lessicali contano i token, e le citazioni le risolvono; mescolati al denso (ricerca ibrida) la qualità complessiva sale da 0,63 a 0,76 di nDCG@10 sul nostro corpus di prova (normativa pubblica). I dettagli sono nelle novità.

{"object":"embedding","index":0,"embedding":[-0.0850,0.0054,…],
 "sparse_embedding":{"indices":[211,496,891,48287,110006,137164],
                     "values":[0.1351,0.2416,0.1561,0.2973,0.2951,0.2626]}}

• indices: identificatori dei token del tokenizer di bge-m3 (vocabolario XLM-R, 250.002 voci), ordinati crescenti, senza ripetizioni; values: un peso > 0 per ciascuno, 4 decimali. Stessa definizione dei «lexical weights» di FlagEmbedding.
• (Esempio vero per «Il contratto scade il 30 settembre»: i sei token sono il, 30, Il, settembre, contratto, scade; le parole di contenuto pesano di più.)
• Il vettore denso non cambia: return_sparse aggiunge, non sostituisce (scarto misurato sul modello vero: 1,5·10⁻⁸, l'ultimo bit del float32). I pesi sono sempre float: output_dtype ed encoding_format toccano solo il denso.
• Punteggio sparso fra domanda e documento = somma dei prodotti dei pesi sui token in comune. Ibrido: α · coseno_denso + (1-α) · sparso / max_sparso_della_domanda; α si sceglie sulle proprie domande (0,6 se contano le citazioni di articolo, 0,9 se sono quasi tutte in linguaggio naturale).
• Costa come un embedding normale (stessa quota a caratteri). Cache in RAM separata: impronte e pesi, mai testi, e separata per cliente come quella dei vettori densi.
• Esempi completi, testati (i primi due senza dipendenze oltre la libreria standard in Python o ext-curl/ext-json in PHP):
  • client di riferimento (da copiare nel progetto, nessuna dipendenza oltre la libreria standard / ext-curl): esempi/agilev_client.py, esempi/agilev_client.php e esempi/agilev_client.mjs (Node ≥ 18, dal 9/10/2026: fetch globale, ESM, zero dipendenze), stessa classe AgileV con embed(), rerank(), usage(), health(). Incorporano le regole di questa pagina così non vanno riscoperte: connessione riusata (keep-alive), lotti uno alla volta da 64 (massimo 128) con timeout 120 s, limiti controllati prima di spedire (mai un 413 per sbaglio), ritentativo solo su 429 RATE_LIMIT, 5xx e connessione caduta con attesa 1-2-4-8 s (tetto 30 s) oppure esattamente Retry-After quando il servizio lo manda (dal contratto 1.2 su ogni 429 RATE_LIMIT, fino a 60 s); una connessione riusata che il server ha chiuso nel frattempo (keep-alive scaduto) si rifà subito senza contarla come ritentativo; si frena prima del 429: quando una risposta dice X-RateLimit-Remaining: 0 la richiesta successiva aspetta X-RateLimit-Reset secondi prima di partire invece di partire e prendere un errore (misurato il 27/9 sulla 1.2: 5 richieste con una chiave da 2 al minuto, 429 ricevuti 2 → 0, stesso tempo totale perché la finestra è al minuto di orologio); niente ritentativi su 400/401/403/413 e QUOTA_EXCEEDED, al timeout il lotto si dimezza invece di essere ripetuto uguale, rerank sui primi 800 caratteri di ogni candidato, spezza() per i documenti lunghi (frammenti da 1.500 caratteri a righe/frasi/parole con 150 di sovrapposizione e l'intestazione ripetuta, identici in Python, PHP e Node). Provati contro il servizio 1.2 e contro un server finto che simula 429, 500, quota e timeout; non registrano nulla.
  • senza database vettoriale (vettori in MySQL o pgvector): esempi/ricerca_ibrida.py e esempi/ricerca_ibrida.php (stessa fusione, stessi punteggi al millesimo sugli stessi articoli). I pesi si conservano come mappa token → peso (JSON) accanto al denso; il punteggio si somma sui token in comune.
  • con LangChain (Python): esempi/agilev_langchain.py, tre classi provate contro il servizio 1.2: AgileVEmbeddings (Embeddings sopra /v1/embeddings, lotti da 64, input_type giusto per documenti e domande; con return_sparse=True prende anche i pesi lessicali nella stessa chiamata), AgileVSparseEmbeddings (i pesi nel formato SparseVector di langchain-qdrant: QdrantVectorStore(..., retrieval_mode=HYBRID, embedding=emb, sparse_embedding=emb.sparse()) costa una passata del modello per testo, non due) e AgileVRerank (BaseDocumentCompressor sopra /v1/rerank, per ContextualCompressionRetriever; legge di ogni candidato i primi 800 caratteri, il valore misurato). Dal 22/9 anche AgileVSpezza (split_text/create_documents/split_documents come un TextSplitter, ma sopra spezza() del client di riferimento, con l'intestazione presa da un campo dei metadati e ripetuta in ogni frammento: RecursiveCharacterTextSplitter non lo fa). Dipende solo da langchain-core (e da agilev_client.py nella stessa cartella per lo splitter); requests, se c'è, riusa la connessione TLS. Per LlamaIndex non serve un adattatore: OpenAILikeEmbedding(api_base="https://api.agilev.agile.software/v1", model_name="agilev-m3") copre il denso; per lo sparso e il rerank valgono i corpi REST qui sotto.
  • con Qdrant: esempi/qdrant_ibrido.py, ricetta REST copiabile in qualsiasi linguaggio (provata su Qdrant 1.19): una collection con due vettori per punto, denso (1024, Cosine) e lessicale (sparse vector: indices/values sono già nel formato di Qdrant), interrogata con prefetch + fusion (Qdrant fonde da solo) oppure con due query e α a mano.

  // PUT /collections/<nome>
  {"vectors":{"denso":{"size":1024,"distance":"Cosine"}},"sparse_vectors":{"lessicale":{}}}
  // PUT /collections/<nome>/points?wait=true   (embedding e sparse_embedding di /v1/embeddings, tali e quali)
  {"points":[{"id":1,"vector":{"denso":[…1024…],"lessicale":{"indices":[…],"values":[…]}},"payload":{"doc":"…"}}]}
  // POST /collections/<nome>/points/query   (la domanda passa da /v1/embeddings con return_sparse, come i documenti)
  {"prefetch":[{"query":[…denso…],"using":"denso","limit":50},
               {"query":{"indices":[…],"values":[…]},"using":"lessicale","limit":50}],
   "query":{"fusion":"rrf"},"limit":10,"with_payload":true}

  Chi ha già una collection col solo denso ne crea una nuova con i due vettori, reindicizza con return_sparse e sposta l'alias: il denso non cambia. Misurato su Qdrant 1.19 con il corpus delle novità: denso 0,63 → fusion: rrf 0,74 → α 0,6 a mano 0,76 (nDCG@10); dbsf 0,73. Partite da RRF, passate all'α se le citazioni sono il caso principale.

POST/v1/rerank — riordino per pertinenza

Ambito rerank. Un modello dedicato (cross-encoder) confronta la domanda con ogni documento: più preciso della sola somiglianza fra vettori, ma va usato su pochi candidati perché costa di più.

curl https://api.agilev.agile.software/v1/rerank \
  -H "Authorization: Bearer $AGILEV_KEY" -H "Content-Type: application/json" \
  -d '{"model":"agilev-rerank","query":"scadenza del contratto",
       "documents":["Il contratto scade il 30 settembre","Ricetta della carbonara",
                    "Termine dell accordo a fine mese"],"top_n":3}'

{"model":"agilev-rerank","results":[
  {"index":0,"relevance_score":0.9633},
  {"index":2,"relevance_score":0.8426},
  {"index":1,"relevance_score":0.0000}],"usage":{"total_tokens":38}}

I risultati arrivano già ordinati dal più pertinente; index si riferisce alla posizione nell'array documents che avete inviato. Con top_n ne ricevete solo i primi.

La query è un testo come i documents: stesso tetto di 32.000 caratteri (413 TEXT_TOO_LONG, e il messaggio dice quale dei due campi ha sforato), e si paga una volta per documento. Il conto, e il massimo che una richiesta può costarvi, sono in Limiti.

top_n si applica solo se è positivo. 0, assente o negativo vogliono dire «nessun limite»: ricevete tutti i documenti riordinati, e quando il valore c'era e non si è potuto applicare la risposta lo dice in ignored_values: ["top_n"]. È il caso di chi lo calcola — top_n = quanti_me_ne_servono - quanti_ne_ho_già — e arriva a zero o sotto: prima un -1 tagliava dalla coda (su 4 documenti ne tornavano 3, col peggiore buttato via) e un -4 ne faceva tornare zero, sempre con 200 e sempre con tutti i documenti addebitati. I documenti si pagano a uno a uno: il taglio fatelo voi sui punteggi, che arrivano tutti.

I campi obbligatori sono query e documents: input qui non esiste e una richiesta senza documents riceve 422. Il model, invece, oggi non fa fallire nulla: {"model":"agilev-m3", …} su /v1/rerank funziona e risponde "model":"agilev-rerank", perché il nome viene solo contato. Se un rerank non passa, il nome del modello non è la causa: guardate documents. Misurato il 28/9 sul codice 1.1 in produzione e sulla 1.2.

POST/v1/tokenize — contare i token prima di inviare

Ambito embed. Non consuma quota. Serve a sapere in anticipo se un testo verrà tagliato.

{"model":"agilev-m3","max_tokens":8192,
 "data":[{"index":0,"tokens":11,"characters":45,"truncated":false}],
 "usage":{"total_tokens":11}}

POST/embed — formato storico

Ambito embed. Contratto congelato per gli integratori della prima ora: {"texts":[…]} → {"vectors":[[…]],"model":"bge-m3","dim":1024}. Sempre float a 1024 dimensioni, ignora i parametri nuovi. Per il resto usate /v1/embeddings.

GET/v1/usage — i vostri consumi

Richieste, testi, caratteri e millisecondi per mese e operazione, più i limiti della chiave. Una chiave vede solo i propri consumi.

cached_texts (dal 7/10/2026): quanti di quei texts, in quel mese, li ha serviti la nostra cache — non sono passati dal modello e sono fatturati come gli altri. È il numero da guardare prima di chiederci una quota più alta: se è quasi uguale a texts, state spedendo molte volte gli stessi testi.

Su chiave revocata risponde 403 KEY_REVOKED, su chiave scaduta 403 KEY_EXPIRED. Il campo expires_at dice quando la chiave finisce (secondi epoch UTC; 0 = non scade): è il modo per accorgersi che una chiave di prova sta per finire prima che smetta di rispondere.

last_at e rejected: «ci stiamo ancora parlando?», dalle due parti (dal 10/10/2026). last_at è l'istante dell'ultima chiamata riuscita della chiave, su qualunque operazione (secondi epoch UTC; 0 = non ne ha mai fatta una), e lo stesso campo sta su ogni riga di usage, mese per mese. rejected è l'altra metà della stessa domanda: una riga per mese, operazione e code, con quante volte vi abbiamo respinto e quando l'ultima — i 403 (KEY_REVOKED, KEY_EXPIRED, SCOPE_NOT_ALLOWED e i codici del contratto) e i 429 (RATE_LIMIT, QUOTA_EXCEEDED). Lista vuota è la risposta normale; i due campi sono gratis come il resto della rotta e chi non li legge non vede cambiare niente.

"last_at":1791620771,
"rejected":[{"month":"2026-10","op":"embed","code":"RATE_LIMIT","requests":245,"last_at":1791619502}]

Servono perché i numeri del mese non dicono se un'integrazione si è fermata: una riga che non cresce è identica a un cliente che in quel mese non ha avuto lavoro, e un deploy che di notte parte con la chiave sbagliata vede i suoi 403 nell'istante in cui li prende e poi niente — fino al 10/10 quei rifiuti vivevano in RAM, aggregati per rotta e azzerati a ogni riavvio del servizio. Quattro limiti, detti prima che ci contiate sopra. I 401 (KEY_MISSING, KEY_INVALID) non ci sono e non ci saranno: arrivano da una chiave che non è nel nostro archivio, quindi non c'è nessuna chiave a cui addebitarli, e l'impronta di un segreto che non è nostro non è un dato che vogliamo conservare — una chiave sbagliata di un carattere si vede solo dal vostro lato. I numeri partono dal 10/10/2026 e non sono retroattivi: i mesi già scritti hanno last_at a 0 finché non arriva la prima chiamata riuscita. Su chiave revocata o scaduta questa rotta risponde 403, quindi la chiave che vorreste indagare è proprio quella che non vi apre più: i rifiuti sono per chiave e in quel caso restano visibili solo a noi, chiedeteceli; si leggono invece con la propria chiave i 429 e i 403 SCOPE_NOT_ALLOWED, perché su quelli la chiave resta buona. Le liste sono tagliate: ultimi 24 mesi per usage, 48 righe più recenti per rejected.

Chiavi di prova (ambito prova). Per far provare AgileV esistono chiavi con ambito prova: coprono /v1/embeddings, /embed, /v1/rerank e /v1/tokenize — cioè il servizio — e non coprono /metrics (sono numeri nostri, aggregati su tutti i clienti) né l'amministrazione delle chiavi. Hanno sempre una scadenza: una chiave di prova senza data di fine non viene accettata, e la regola sta nel servizio, non solo in chi la emette. Quando la data è passata ogni richiesta, compresa GET /v1/usage, risponde 403 KEY_EXPIRED.

In difetto, mai in eccesso (dal 29/9/2026). Se il nostro archivio dei consumi ha un guasto — disco pieno, file bloccato — la vostra richiesta viene servita lo stesso e quella riga di consumo si perde. Quindi i numeri qui, e la fattura che ne esce, possono essere più bassi del vero; non saranno mai più alti. Per lo stesso motivo, durante un guasto del genere una chiave a quota può sforare: preferiamo servirvi e perdere il conto piuttosto che negarvi una risposta per un numero che serve a noi. Prima del 29/9 andava al contrario: la risposta, già calcolata, veniva buttata via e ricevevate un 500. Durante un guasto prolungato l'attesa la paga una richiesta sola: al primo guasto smettiamo di provare a scrivere per 30 secondi, e allo scadere riprova una sola richiesta per vedere se l'archivio è tornato (misurato il 29/9: senza questa regola erano 8 richieste su 8 a fermarsi per 10 s a ogni risveglio, adesso 1 su 8).

model_unknown: la lista che deve restare vuota (dal 29/9/2026). Quante volte la vostra chiave ci ha mandato un campo model che non riconosciamo, per mese e per rotta, con l'ora dell'ultima volta (last_at, secondi Unix UTC):

"model_unknown":[{"month":"2026-09","op":"rerank","requests":4,"last_at":1790651460}]

Oggi quei nomi vengono serviti lo stesso e non vi succede nulla (vedi Il campo model); il giorno in cui arriverà 400 MODEL_UNKNOWN sarebbero errori. Nasce da una domanda di un cliente (28/9): il nome del modello lo mandiamo da una variabile d'ambiente, vogliamo accorgercene prima dei nostri clienti. Guardarlo non consuma né quota né richieste al minuto, quindi si può mettere in un controllo automatico: se la lista non è vuota, la vostra configurazione manda un nome che non conosciamo — i nomi validi sono quelli di /v1/models.

Quattro limiti, detti prima che ci contiate sopra. La lista vuota non vuol dire che la configurazione è giusta: "", null e il campo assente valgono come default e non vengono contati (se la vostra variabile d'ambiente è vuota, qui non si vede — si vede nel model della risposta). E /embed non guarda il campo affatto: chi usa il formato storico avrà sempre la lista vuota. Terzo limite, dal 29/9 e ce l'ha detto trpg misurandolo in casa: la lista è per chiave. Se un domani le vostre installazioni avranno una chiave loro, i nomi che mandano non compaiono sotto la vostra. E il primo limite, al rovescio, per chi ha un ripiego nel codice: se la vostra variabile vuota fa scattare un ?: 'nome-di-un-altro-fornitore', quel nome viene contato — quindi per voi la lista è più utile, non meno. Quarto limite, dal 29/9, e anche questo ce l'ha misurato trpg in casa propria: se il vostro codice legge la configurazione da $_SERVER invece che da getenv(), sotto un server web quel valore può essere assente (nel loro contenitore $_SERVER['LLM_API_URL'] è null sotto Apache, mentre getenv() e $_ENV portano il valore) — e allora non c'è nessun ripiego da contare: c'è una configurazione che sparisce quando il codice gira dentro il server web e funziona in ogni prova da riga di comando. Da noi si vede come un nome che manca, o come una chiave che non compare affatto nella lista. La forma da riconoscere: la stessa chiave che alterna il nome giusto e nessuna riga, senza che nessuno abbia toccato niente.

POST/v1/richieste-licenza — chiedere una licenza

Pubblica e senza chiave: è il modulo con cui si chiede una licenza, e chi lo compila per definizione non ha ancora niente. È l'unica rotta che scrive qualcosa senza autenticazione, quindi ha un limite per indirizzo: al massimo 5 richieste in un'ora, poi 429 RATE_LIMIT. Il modulo pronto sta sulla pagina di AgileV; qui c'è la rotta, per chi la vuole chiamare da un programma.

Risponde nella forma in cui le si parla: con application/x-www-form-urlencoded (un <form method="post"> senza enctype) torna una pagina col numero della richiesta; con application/json torna 201 e {"n":<numero>,"messaggio":"Richiesta registrata"}. Con ?lang=en risponde in inglese.

Tutti e quattro sono obbligatori. Gli errori: 400 BAD_BODY (corpo che non è né modulo né JSON), 400 CAMPO_MANCANTE, 413 CAMPO_TROPPO_LUNGO, 400 BAD_PLAN, 429 RATE_LIMIT e 503 NON_SALVATA. Il messaggio dice quale campo, e non ripete niente di quello che avete scritto.

Il 429 di questa rotta dice quando tornare, e non è il minuto (dal 20/10/2026). Il limite qui è 5 richieste in un'ora dallo stesso indirizzo, e la risposta porta Retry-After coi secondi che mancano all'ora nuova in UTC, da 1 a 3.600 — il momento esatto in cui il contatore si riapre, non una stima. Lo porta in entrambe le forme: la risposta JSON e la pagina del <form> della landing. Attenzione a una cosa, perché il code è lo stesso delle rotte con chiave ma la finestra no: se il vostro client taglia Retry-After a 60 s — la regola giusta là, e quella che applica il nostro client di riferimento — qui busserebbe fino a 60 volte dentro la stessa ora chiusa invece di una. Onorate il numero per intero.

Il 503 è l'unico posto in cui non ingoiamo un guasto dell'archivio. Su /v1/embeddings una richiesta viene servita anche se il contatore dei consumi non si lascia scrivere (in difetto, mai in eccesso): lì il servizio era già stato dato. Qui la scrittura è il servizio, e un «registrata n. 0» sopra una richiesta che non esiste sarebbe una persona che aspetta una risposta che nessuno darà. Se arriva un 503, riprovate: non è stata presa.

Formati dei vettori

Un vettore float occupa 4 KB. Se indicizzate milioni di frammenti, la memoria del database vettoriale diventa la voce di costo principale: potete chiedere i vettori già compressi.

La quantizzazione int8 usa una calibrazione fissa e documentata, non adattiva: vettori chiesti in momenti diversi restano confrontabili fra loro. Non cambierà sotto il nome agilev-m3.

Limiti

I due primi limiti non si raggiungono insieme con testo multibyte, e il tetto del corpo arriva prima. 128 testi da 32.000 caratteri sono dentro a tutto quello che c'è scritto qui sopra, ma in UTF-8 un carattere cinese, russo o greco pesa 2 o 3 byte: con testo CJK quella richiesta è di 24.576.545 byte, cioè 3,07 volte il tetto del corpo, e bastano 42 testi su 128 per superarlo (misurato al byte in gabbia). Chi indicizza in una di quelle lingue sbatte sul tetto del corpo restando dentro ai due limiti pubblicati: il 413 che riceve lo scrive il bordo e ha code BODY_TOO_LARGE, non BATCH_TOO_LARGE. Il conto da fare prima di spedire è in byte (len(json.dumps(corpo).encode("utf-8"))), non in caratteri; e il tetto è 8.000.000, non 8 MiB — chi dimensiona i lotti a 8.388.608 byte sbatte per 388.608 byte. Il client di riferimento manda lotti da 64 e non ci arriva nemmeno in cinese.

Quanto può costare al massimo una richiesta di /v1/rerank. Il conto di quella rotta è len(query) × numero di documenti + somma dei documenti: la domanda si paga una volta per documento, perché il cross-encoder legge la coppia (domanda, documento) una volta per documento. La query è stata per mesi il solo campo del contratto senza il tetto della riga qui sopra, ed era proprio quello moltiplicato: una domanda da 200.000 caratteri con 128 documenti passava con 200 e contava 25.601.280 caratteri, e il corpo più grande che il bordo accetta ne contava 1.023.750.400, cioè 249,94 volte i 4.096.000 che si calcolano dalle prime due righe. Con lo stesso tetto di un documento il massimo di una richiesta di rerank è 8.192.000 caratteri — due volte il tetto implicito e non duecentocinquanta: il suo per i documenti, e uno per la domanda ripetuta. Se lo superate ricevete 413 TEXT_TOO_LONG e il messaggio dice quale dei due campi (query o documents) ha sforato, perché su questa rotta quel 413 ha due origini. Nessun cliente ci è mai arrivato: chi usa il rerank più di tutti ha una domanda media sotto i cento caratteri, misurata dai nostri contatori.

Le due righe di mezzo hanno due numeri, non uno, quando la vostra chiave sta sotto una licenza (il livello arrivato il 30/9: un contratto, N chiavi sotto). La quota mensile e il limite al minuto sono numeri del contratto e le chiavi che ci stanno sotto li consumano insieme: una licenza da 5 al minuto serve 5 richieste al minuto, che ci sia una chiave sotto o dieci. Il rate_per_min della singola chiave resta un tetto suo e non viene allargato dal contratto; basta che morda uno dei due, e il messaggio dell'errore dice quale. Le chiavi senza licenza (tutte quelle emesse prima) hanno un numero solo, il loro.

Il mese è tagliato alle 00:00Z, e ve lo diciamo. La quota mensile riparte quando cambia l'etichetta AAAA-MM dell'orologio UTC, cioè al primo istante del mese nuovo: alle 00:00Z del giorno 1, che a Roma sono le 01:00 (le 02:00 con l'ora legale), non la vostra mezzanotte. Lo stesso orologio taglia la fattura e le etichette che GET /v1/usage vi rende. Non dipende dal fuso del nostro box né dal vostro: se avete lavori che consumano quota all'inizio del mese, l'istante da aspettare è quello.

L'ultima riga è quella che si legge male. Il limite per minuto non limita le richieste simultanee: una chiave da 120 al minuto può averne quaranta in volo nello stesso istante senza prendere un 429. Non guadagnate niente a farlo — il calcolo è uno alla volta, vedi Prestazioni — e fino al contratto 1.1 ci perdevate: lì ci sono i numeri misurati.

Errori

Ogni errore ha lo stesso corpo, con un codice stabile su cui potete ramificare.

{"error":{"code":"RATE_LIMIT","message":"massimo 300 richieste al minuto"}}

Quando riprovare, ve lo diciamo noi (dal contratto 1.2). Le risposte delle operazioni di calcolo (/v1/embeddings, /embed, /v1/rerank, /v1/tokenize) — le sole che chiamate voi; dal 20/10 le portano tutte le risposte autenticate, amministrazione compresa — portano tre intestazioni informative: X-RateLimit-Limit (richieste al minuto della vostra chiave), X-RateLimit-Remaining (quante ne restano in questo minuto) e X-RateLimit-Reset (secondi al minuto nuovo, da 1 a 60). Il 429 RATE_LIMIT porta in più Retry-After con lo stesso numero di secondi: la finestra è al minuto, quindi il valore è esatto e non c'è nulla da indovinare: aspettate quei secondi e riprovate (mai più di 60). Il 429 QUOTA_EXCEEDED porta Retry-After anche lui (dal 6/10), ma vuol dire un'altra cosa: sono i secondi che mancano al primo istante del mese nuovo in UTC — da 1 a 2.678.400 — cioè la distanza da quando la vostra quota riparte, non un tempo di attesa consigliato e non un invito a tenere la richiesta aperta. I numeri hanno la stessa intestazione e tre significati, e li distinguete dal code del corpo e dalla rotta: RATE_LIMIT su una rotta con chiave sono i secondi al minuto nuovo (mai più di 60), QUOTA_EXCEEDED i secondi al mese nuovo, e RATE_LIMIT sulla sola rotta pubblica — POST /v1/richieste-licenza, quella del modulo della landing — i secondi all'ora nuova in UTC, da 1 a 3.600 (dal 20/10/2026). Il terzo è il più facile da sbagliare proprio perché il code è lo stesso del primo: lì la finestra è l'ora e non il minuto, e un client che tagli Retry-After a 60 s busserebbe fino a 60 volte dentro la stessa finestra chiusa invece di una. Se la vostra regola è «onoro Retry-After e taglio a 60», guardate anche la rotta, non solo il code. Se vi serve tornare a lavorare prima, non aspettate: chiedete un aumento di quota col modulo della landing (POST /v1/richieste-licenza, pubblico e senza chiave). Il client di riferimento non ritenta su QUOTA_EXCEEDED e quel numero non lo legge. I rifiuti che arrivano prima del conto del minuto non portano intestazioni di rate, e la ragione è che non hanno speso niente: 401 KEY_MISSING, 401 KEY_INVALID e i sette 403 della chiave e del contratto (KEY_REVOKED, KEY_EXPIRED, SCOPE_NOT_ALLOWED, LICENSE_NOT_FOUND, LICENSE_SUSPENDED, LICENSE_EXPIRED, LICENSE_REVOKED). Due 403 invece le portano, e sono i soli due: TENANT_UNKNOWN e PERSONA_UNKNOWN — il tenant o la persona che avete scritto nel corpo non è quello della vostra chiave — perché arrivano dopo, quando il posto del minuto è già stato speso, e quel numero è vostro: leggetelo. Non è il numero di stato a dirvi se le intestazioni ci sono, è quando il rifiuto nasce: su un 403 guardate se ci sono invece di darlo per scontato. Misurato il 20/10/2026: sei richieste con una chiave da 6 al minuto, tre col tenant sbagliato — chi salta le intestazioni dei 403 vede spendere 3 posti su 6 e crede di averne 3 liberi quando ne ha 0, e la richiesta dopo si prende il 429 che quelle intestazioni esistono per evitare. X-RateLimit-Remaining serve a non prendere il 429: quando è 0, aspettate X-RateLimit-Reset secondi prima della richiesta successiva. Il client di riferimento lo fa da sé (contatore frenate). GET /v1/usage è fuori da questo conto: non porta le intestazioni di rate e, soprattutto, non consuma una delle vostre richieste al minuto — controllare i propri consumi è gratis e non vi avvicina al 429.

HTTP/1.1 429 Too Many Requests
Retry-After: 43
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 43

{"error":{"code":"RATE_LIMIT","message":"massimo 300 richieste al minuto"}}

Se il client lo scrivete voi: sei regole

Misurate, non consigliate a occhio: le abbiamo trovate addosso ai nostri client, dopo che trpg le ha trovate sul suo (28/9). Pagina autonoma da ricopiare: gli errori visti dal vostro client.

1. error e detail sono strutture, non stringhe. Concatenarle in un messaggio produce Array in PHP (con avviso) e il repr di un dizionario in Python: da trpg ogni nostro errore diventava la parola «Array», e KEY_MISSING/KEY_INVALID/RATE_LIMIT non arrivavano mai a chi legge — e non in un log, nella risposta della loro API a un utente. Costruite il messaggio con tre pezzi: stato HTTP, error.code, error.message.
2. Il 422 va gestito a parte: non ha code, quindi chi ramifica solo su error.code resta muto proprio sull'errore che si incontra per primo. Leggete detail[].loc e detail[].msg (vi dicono quale campo), mai detail[].input, che è l'eco dei vostri testi (vedi la riga 422 sopra).
3. 200 non vuol dire «i vettori sono tutti». Contate: data deve avere tanti elementi quanti i testi inviati e gli index devono essere 0…n-1; su /v1/rerank, results ne ha min(top_n, documents) quando top_n è positivo — altrimenti tutti, e la risposta lo dice in ignored_values — e ogni index sta nell'intervallo. Se ne arrivano meno e voi accoppiate con uno zip, indicizzate il testo sbagliato col vettore sbagliato e non ve ne accorgete (a trpg, un 200 di forma inattesa tornava come successo con zero vettori e NULL al chiamante, in silenzio).
4. Una lista vuota non è una risposta. Trovata da trpg in casa propria il 28/9, tirando il filo di un nostro avviso, ed è la più cattiva delle quattro perché non produce nessun errore e nessun risultato: la loro ricerca scartava in silenzio (un continue nudo, in due punti) ogni frammento con la dimensione diversa da quella della domanda, quindi un indice costruito con un modello e interrogato con un altro non dà errore, dà zero risultati e l'assistente risponde senza fonti. Misurato da loro in sola lettura: 0 risultati su 471 frammenti tutti scartati, nessuna traccia da nessuna parte. Quattro contromisure, tutte gratis. (a) All'avvio un GET /health (non vuole la chiave e non consuma nulla) e confrontate dim con la dimensione del vostro indice — è l'unica delle quattro che vale sull'indice che avete già, perché la dimensione si misura e non serve che qualcuno l'abbia dichiarata. Il nome no: in /health il campo model è il modello sottostante (bge-m3), mentre /v1/models e /v1/embeddings usano il nome di listino (agilev-m3). Sono due vocabolari e confrontarli dà un disallineamento a ogni avvio con il servizio sano — l'inciampo che trpg ci ha segnalato il 28/9 dopo aver messo in opera la (a). La controprova misurata: /v1/embeddings dice agilev-m3, /embed dice bge-m3, e i vettori sono identici bit per bit. E la lunghezza si conta sui float: con output_dtype binary/ubinary un vettore da 1024 arriva come 128 valori (1024 bit impacchettati) e con encoding_format: base64 come una stringa, quindi len(vettore) == dim regge solo su float. (b) Controllate il model della risposta, non quello della richiesta (/v1/embeddings → agilev-m3, /v1/rerank → agilev-rerank, /embed → bge-m3: il campo inviato oggi non è validato e /embed non lo guarda affatto) — e confrontatelo con quello che dichiara quella rotta, non con quello di un'altra: è il solo confronto di nomi che regge. (c) Mai un continue su una dimensione che non combacia — contatelo e alzate la voce. (d) Scrivete il modello accanto al frammento nel momento in cui costruite l'indice: è il corollario che trpg ci ha mandato la sera del 28/9, e l'hanno pagato — 442 frammenti di un fornitore e 29 dei nostri, tutti a 1024 valori, nessun campo che dica quale, e l'informazione non è mai stata dichiarata da nessuna parte. Costa niente oggi; ricavarlo domani si può — è la contromisura (e), misurata, a una chiamata per frammento: qui avevamo scritto «è impossibile domani» ed era falso. (e) Se il modello non l'avete scritto, ricavatelo: rifate l'embedding del testo del frammento e calcolate il coseno col vettore salvato. Stesso testo e nostro modello danno coseno 1 (scarto massimo 2,2·10^-12, e 3,9·10^-12 attraverso il nostro deploy); un altro spazio da 1024 valori dà |coseno| ≤ 0,10; magazzino int8 0,9998 e a un bit 0,75, testo ritoccato 0,9755 — separazione 7×, verdetto decidibile. Vale sull'indice che avete già: da quale fornitore viene un vettore già nel vostro indice.
5. Nessuna risposta deve uscire dal vostro client con codice «non so». È la regola del 29/9, e nasce dal contare quante forme può prendere una risposta nostra: cinque non hanno error.code (vedi Errori: quattro contate il 29/9, più il 413 del corpo troppo grande trovato il 5/10), e in tutte e cinque detail è una stringa, o il corpo non è nemmeno JSON, o non c'è corpo per niente — cioè cadono tutte nello stesso ramo del vostro lettore d'errore, quello che non sa cosa fare. Se lì mettete ?, chi vi chiama riceve un allarme che non si può smistare né contare, ed è lo stesso difetto della regola 1 vestito da caso limite. La risposta non è indovinare dal corpo — quei corpi non sono nostri e nessuno ha promesso cosa ci metterà dentro — ma dedurre il codice dallo stato HTTP, che è l'unica parte garantita: 404 → percorso sbagliato (colpa vostra, non ritentate), 405 → metodo sbagliato (non ritentate), 3xx → un rimando, quasi sempre una barra finale di troppo: toglietela, oppure seguite il Location (è assoluto e in https, conserva metodo e corpo e non consuma) — aggiunto l'1/10, 5xx senza forma → il bordo non è arrivato al servizio o il servizio è caduto senza forma (ritentate), tutto il resto → un codice che dica «senza codice» e riporti lo stato. Sono cinque comportamenti diversi e con ? erano uno solo. Secondo corollario: il corpo di quelle risposte non mettetelo nel messaggio. Una pagina d'errore di un proxy di mezzo può contenere qualunque cosa, e finirebbe nei vostri log etichettata come un errore di AgileV — è la stessa regola dell'eco del 422, applicata a corpi che non sono nostri.

6. La configurazione che sparisce dentro un server web. Regola del 29/9, e non ce l'ha insegnata un errore: ce l'ha insegnata trpg misurando in casa propria. La stessa variabile d'ambiente non si legge allo stesso modo in tutte le stanze: sotto Apache $_SERVER['LLM_API_URL'] è null mentre getenv() e $_ENV portano il valore (misura loro); da riga di comando è l'opposto — getenv() e $_SERVER portano il valore e $_ENV è vuoto (misura nostra, sul nostro box); e php-fpm con clear_env = yes, che è il predefinito, svuota l'ambiente del processo e lascia solo $_SERVER (documentazione, non una misura nostra). Chi legge una sola sorgente sta scommettendo sulla stanza, e quando perde non c'è nessun errore. Per AgileV la variabile che sparisce è l'indirizzo, e il ripiego è la produzione pubblica: se avete puntato il client su un fronte privato, i vostri testi escono su Internet in silenzio. Quattro contromisure: (a) leggete l'ambiente da tutte le sorgenti, in ordine dichiarato; (b) un valore presente ma vuoto è un errore che nomina la variabile, mai un ripiego; (c) dite sempre da dove arriva l'indirizzo, e della chiave la sorgente e mai il valore; (d) se l'indirizzo deve essere privato, la guardia va scritta nel codice — una guardia accesa da una variabile d'ambiente sparisce insieme a ciò che deve proteggere. Dettagli e numeri: la pagina delle sei regole.

Nei nostri quattro client di riferimento (agilev_client.py, agilev_client.php, agilev_client.mjs, agilev_langchain.py) le prime cinque regole sono applicate (le prime quattro dal 28/9, la quinta dal 29/9; nel client di Node e nel freno dell'adattatore LangChain dal 9/10/2026): ricopiateli, nessuna firma è cambiata. Il 422 diventa BAD_BODY con corpo della richiesta non valido - body.input: Field required, e un data mutilato o assente diventa BAD_RESPONSE con attesi 2 elementi in data, ricevuti 1. Dal 29/9 le quattro risposte senza la nostra forma escono con NOT_FOUND (404), BAD_METHOD (405), UPSTREAM_ERROR (5xx senza forma, ritentabile) e NO_CODE (il fondo della tabella: sconosciuto sì, muto no), e il corpo non entra nel messaggio. Questi sei codici li mette il client, non il servizio: non cercateli nelle nostre risposte. Misura: bench/misura-errori-client.py, 15 scene × 3 client (i tre di allora; il client di Node ha le sue 18 prove e le sei scene del suo banco) — righe senza un codice nostro da 15 a 3 il 28/9 e da 12 a 0 il 29/9, righe con l'eco dei vostri testi 0, vettori disallineati in silenzio 0. Stesso risultato catturando i corpi dal codice 1.1 in produzione e dalla 1.2: potete ricopiare i client oggi, non dipende dal nostro deploy. Dal 29/9 le sei regole sono applicate in tutti e SEI gli esempi che pubblichiamo (i tre client di allora più ricerca_ibrida.py, ricerca_ibrida.php, qdrant_ibrido.py), e dal 9/10/2026 sono SETTE col client di Node: l'indirizzo non finisce più in silenzio sul pubblico, un valore vuoto è un errore, e i client dicono da dove l'hanno preso. Chi non configura niente ha esattamente il comportamento di prima. Misura: bench/misura-indirizzo-che-sparisce.py — celle in silenzio 4 → 0, client che spedivano il testo senza chiave 2 → 0, celle non controllabili senza fare una richiesta 4 → 0; 22 mutazioni su 22 viste.

Prestazioni, e la cosa più utile che potete fare

Misure reali su un frammento breve: l'elaborazione dura circa 100 ms, ma una richiesta vista dall'esterno ne impiega circa 370. La differenza non è il modello: è la stretta di mano TLS, e si paga a ogni connessione nuova, non a ogni richiesta.

Riusate la connessione e vi riprendete quei ~250 ms su tutte le chiamate dopo la prima:

# Python
import httpx
client = httpx.Client(base_url="https://api.agilev.agile.software",
                      headers={"Authorization": f"Bearer {CHIAVE}"})   # riusatelo!

# PHP (Guzzle tiene la connessione viva da solo, se riusate il client)
$http = new GuzzleHttp\Client(['base_uri' => 'https://api.agilev.agile.software']);

# Node, con https.request
const agent = new https.Agent({ keepAlive: true });
# Node >= 18, con fetch: il keep-alive c'è già, la regola è non spegnerlo.
# Tutto il resto (lotti, freno, Retry-After, timeout) sta nel client: /esempi/agilev_client.mjs

Per indicizzare grandi quantità, mandate lotti (fino a 128 testi) invece di richieste singole: il costo fisso per chiamata si divide su tutti i testi del lotto.

Un testo già visto di recente viene servito da una cache in RAM (sole impronte, mai testi) senza ricalcolo. La cache è separata per cliente (dal 7/10/2026): un testo che ha fatto calcolare un altro cliente, per voi è un testo nuovo — fra clienti diversi non si riusa niente, né i vettori né il tempo di risposta. Le chiavi dello stesso cliente, comprese quelle ruotate, condividono la cache come sempre. Quanti dei vostri testi sono arrivati da lì lo dicono usage.cached_texts in ogni risposta e cached_texts in GET /v1/usage, mese per mese.

Timeout del client e lotti

Quaranta richieste insieme: cosa succedeva, e cosa succede. Mandarne molte in parallelo non è solo inutile, fino al contratto 1.1 era dannoso, e il numero è netto: le richieste in volo occupano i posti di una fila che ne ha quaranta, e la quarantunesima aspetta — /health compresa, perché era una rotta come le altre. Misurato il 29/9 con 48 richieste insieme, cinque giri per braccio, in gabbia e senza toccare la produzione: prima, sonde della salute perse in 5 giri su 5 durante il riscaldamento e in 3 su 5 a servizio caldo (fino a 20 s di silenzio), e 500 in 5 giri su 5 (RuntimeError: Already borrowed, nostro, su un servizio sano: due strade tokenizzavano lo stesso oggetto insieme). Dopo la correzione, sulla stessa scena: 0 sonde perse su 883 e 0 risposte non-200 su 480. Dal 1.2 quaranta richieste insieme sono dunque innocue; restano inutili, e la ragione è il paragrafo qui sotto. In produzione non era mai scattato perché a settembre il massimo misurato è stato 3 richieste in volo (log del bordo, 1.084 richieste): il caso da temere non era il traffico di ogni giorno, era il deploy annunciato, con i client che si sbloccano tutti nello stesso istante.

Il servizio calcola una richiesta alla volta (è limitato dalla CPU): un lotto di 10 frammenti da 1.400 caratteri costa circa 11 s da solo, e ogni lotto che arriva mentre un altro è in corso aspetta che quello finisca per intero (misurato: 2 lotti in parallelo 21 s, 4 lotti 42 s). Per indicizzare, quindi: un lotto alla volta, non in parallelo, con un timeout di almeno 120 s. Un timeout corto (30 s) su lotti grandi produce il caso peggiore: il client chiude, ritenta lo stesso lotto, e la coda si allunga di richieste identiche.

Documenti lunghi: spezzateli prima di spedirli. Il limite è 32.000 caratteri per testo (413 TEXT_TOO_LONG) e 8.192 token, ma la misura giusta per la ricerca è molto più piccola: frammenti da ~1.500 caratteri (circa 350-400 token in italiano; è la misura con cui abbiamo fatto tutte le prove sul corpus normativo), tagliati dove il testo si taglia da solo (a capo, fine frase, poi fra le parole), con le ultime frasi intere del frammento precedente ripetute in testa al successivo (~150 caratteri) così un concetto a cavallo del taglio resta intero in almeno uno dei due, e con l'intestazione del documento ripetuta in ogni frammento («Art. 25-septies Rubrica»: è ciò che permette di ritrovare un articolo citato per numero). Il client di riferimento lo fa per voi: spezza(testo, massimo=1500, sovrapposizione=150, intestazione="…") in Python e AgileV::spezza(...) in PHP producono gli stessi frammenti (provato sui 153 articoli del corpus: 468 frammenti, nessuno oltre 1.500 caratteri o 400 token, ogni frase ritrovata intera; l'articolo più lungo, 55.928 caratteri, che intero sarebbe un 413, diventa 44 frammenti calcolati in 40 s con una sola richiesta). Misura del 22/9 sui 153 articoli: con 1.000, 1.500 e 2.000 caratteri l'ibrido dà nDCG@10 0,766 / 0,754 / 0,779, cioè una o due query su 69 di differenza, nessun vincitore netto; 2.000/200 è la misura migliore e la più economica su normativa lunga (362 vettori invece di 460, stesso tempo di calcolo: il costo è per carattere, non per frammento), quindi chi indicizza articoli di legge può passare massimo=2000, sovrapposizione=200.

Dal contratto 1.2 una richiesta chiusa dal client prima che il calcolo cominci non viene calcolata né contata (CLIENT_GONE nei nostri log, mai nei vostri consumi); una già iniziata non si porta più a termine a vuoto: il calcolo procede a passaggi (una richiesta lunga ne ha parecchi: 4 testi da 32.000 caratteri sono 4 passaggi da ~45 s) e fra un passaggio e l'altro controlliamo se siete ancora collegati; se no ci fermiamo lì, la richiesta non è contata e i testi dei passaggi già fatti sono in cache, quindi il tentativo successivo riparte da dove era invece che da zero (provato: 4 testi lunghi, client chiuso a 70 s, servizio fermo al passaggio dopo, ritentativo con 2 testi presi dalla cache). Su /v1/rerank il controllo non dipende dai passaggi: un rerank fino a 16 documenti è un passaggio solo (ogni coppia domanda-documento è tagliata a 1.024 token, quindi il numero dei passaggi dipende dai documenti e non dalla loro lunghezza), e fra un passaggio e il successivo non ci sarebbe niente da controllare; perciò prima di scrivere il consumo guardiamo una volta se siete ancora collegati (prima del 6/10 non lo facevamo, e un rerank in un passaggio solo chiuso dal vostro client veniva contato). Il modo più semplice per rispettare tutto questo è copiare il client di riferimento (esempi/agilev_client.py / .php / .mjs): al timeout dimezza il lotto invece di ripeterlo, ritenta solo dove serve, riusa la connessione.

Migrare da Voyage o OpenAI

Con la libreria OpenAI cambiano tre righe:

from openai import OpenAI
c = OpenAI(base_url="https://api.agilev.agile.software/v1", api_key=AGILEV_KEY)
v = c.embeddings.create(model="agilev-m3", input=["testo"]).data[0].embedding   # 1024 numeri

input_type, truncation e output_dtype si scrivono con la stessa sintassi a cui siete abituati.

Usare i vettori in Qdrant

from qdrant_client import QdrantClient, models
client.create_collection(
    "documenti",
    vectors_config=models.VectorParams(size=1024, distance=models.Distance.COSINE),
)

I vettori sono già normalizzati, quindi coseno e prodotto scalare danno lo stesso ordinamento. Una ricetta che funziona bene: recuperate 30-50 candidati dall'indice, poi passateli a /v1/rerank e tenete i primi 3-5. Costa una chiamata in più e migliora sensibilmente ciò che finisce nel contesto del modello linguistico.

Quanto costa in tempo, perché il timeout va messo di conseguenza. Il rerank costa per carattere della coppia (domanda + documento), non per documento: misurato il 6/10 sui nostri contatori, ~2,1 ms per carattere. Quindi 30 candidati da 662 caratteri sono ~43 s, cioè dentro i 120 s che consigliamo e fuori da un timeout di 30 s — e il paragrafo «Timeout del client e lotti» parla di lotti di embedding, non di rerank. Le due leve, in ordine: accorciate i candidati (gli stessi 30 documenti tagliati a 200 caratteri costano ~13 s, e il reranker guarda comunque i primi ~1.024 token di ognuno) e alzate il timeout a 120 s. Tenerne 30-50 con un timeout di 30 s è il caso peggiore: il vostro client chiude, il nostro calcolo è già partito, e voi non vedete niente.

Da quale fornitore viene un vettore che è già nel vostro indice

Serve a chi ha un indice scritto in più riprese, o passato da un fornitore a un altro, senza un campo che dica quale modello ha scritto quale frammento. La prova: rifate l'embedding del testo del frammento e calcolate il coseno col vettore salvato. Stesso spazio → 1; spazio di un altro modello → 0, perché le sue coordinate sono scritte in una base arbitraria rispetto alla nostra. Funziona sull'indice che avete già, e non richiede che qualcuno abbia dichiarato niente.

Misurato il 28/9 col modello vero in gabbia di memoria su 64 frammenti nostri, zero richieste alla produzione — 13 scene, 0 KO: stesso testo 1,00000000 (anche scritto in un lotto diverso; scarto massimo dal coseno 1 2,2·10^-12, e 3,9·10^-12 perfino attraverso il nostro deploy 1.1 → 1.2, quindi il verdetto è lo stesso prima e dopo); magazzino float16 0,99999998 (tiene anche il verdetto esatto); magazzino int8 0,99983766; magazzino a un bit 0,75374678; testo ritoccato dopo 0,97554815; testo preparato dall'indicizzatore (titolo, prefisso, taglio) 0,75475971; altro frammento nostro 0,78578071; testo senza nulla in comune 0,23538498; altro spazio (rotazione ortogonale, permutazione delle coordinate, segni ribaltati, e con int8) fra −0,10105777 e +0,058. Fra i nostri e gli estranei ci sono 7 volte e in mezzo non c'è niente: il verdetto è decidibile.

Al posto di un fornitore esterno — che non usiamo e di cui non abbiamo i vettori — l'«altro spazio» è un'isometria del nostro: stessa dimensione, stessa norma, stessa geometria interna, base diversa. Un modello vero allenato per conto suo può solo essere meno allineato con noi di così, non più.

Quanti frammenti guardare, per accorgersi di una contaminazione con fiducia 95 %: 5 se gli estranei sono il 50 %, 14 al 20 %, 29 al 10 %, 59 al 5 %, 299 all'1 %. Il costo: ~0,26 s e i caratteri di un frammento da 400 caratteri; un indice da 471 frammenti si etichetta tutto in due minuti di servizio, una volta sola. Il tranello: se l'indicizzatore prepara il testo prima di mandarlo (titolo davanti, taglio, prefisso, minuscole), il vettore salvato è di quel testo e rifare l'embedding sul grezzo confronta due testi diversi — misurato, coseno 0,7548 nel caso peggiore: il verdetto sullo spazio resta «nostro», ma la soglia esatta 1e−6 non regge più su nessun frammento, e chi usa solo quella condanna un indice sano per intero. Rifate l'embedding passando per la stessa funzione dell'indicizzatore. Protocollo in sei passi, da riscrivere nel vostro linguaggio: la provenienza dei vettori.

Un deploy nostro muove i vettori che avete nell'indice?

Domanda giusta, e finora la risposta era «no» detto e non misurato. Misurata il 28/9 sul modello vero, per il passaggio 1.1 → 1.2.

La 1.2 divide le richieste grosse in più passaggi nel modello, a budget di token, per non finire in memoria esaurita: raggruppare i testi diversamente vuol dire padding diverso, e in virgola mobile gli ultimi bit possono cambiare. Le due strade sono state messe a confronto sullo stesso oggetto modello, così che l'unica variabile fosse il raggruppamento.

Cosa farne. La soglia che vi abbiamo dato per fermarvi è 0,9999, e ora si sa quanto margine ha: il deploy ne consuma quattro cento milionesimi. La regola diventa quindi più forte, non più debole — se la vostra misura del «dopo» scende sotto 0,9999, non è il cambio di raggruppamento: è un guasto vero, ed è nostro. Fermatevi e scriveteci. E per rendere la vostra misura più sensibile, congelate il riferimento su frasi corte, poche per richiesta: la richiesta sta in un passaggio solo e il confronto prima/dopo torna esatto bit per bit.

Misurato anche il costo: i lotti a budget non costano tempo (65,2 s → 64,4 s sui testi lunghi, 130,2 s → 131,8 s sul riordino). Tengono giù la memoria a parità di velocità e, ora si sa, a parità di vettori.