Cambiare il modello di embedding di Agent Zero significa modificare lo slot di embedding all'interno di un Model Preset e fare clic su Save — e quando la modifica cambia il provider o il nome del modello, l'accesso successivo reindicizza la memoria, perché un indice FAISS è dimensionato per la larghezza di output di un singolo modello e i vettori già presenti su disco sono stati scritti dal modello precedente. La guida all'installazione di Agent Zero indica la conseguenza in una sola riga — «Changing the embedding_llm will re-index all of A0's memory» — e non fornisce alcuna procedura, durata o modo per tornare indietro. Questa pagina colma quella lacuna partendo dal codice sorgente: cosa fa realmente la ricostruzione automatica, i due percorsi in cui non viene attivata silenziosamente, come verificare che i vecchi ricordi vengano ancora recuperati e come tornare indietro. Kunavo non offre alcun modello di embedding, quindi quello slot va acquistato altrove; gli slot che Kunavo può prezzare sono quello principale e quello di utilità.
Due numeri di versione da tenere distinti innanzitutto. Il framework è alla versione v2.12, pubblicata il 9 settembre 2026 secondo l'articolo di rilascio ufficiale del progetto. Il numero più evidente nel README è A0 Launcher v1.7, ovvero l'installer desktop separato in agent0ai/a0-launcher: associarlo al framework è un errore di un'intera versione principale. Inoltre, nella versione v2.x i campi dei modelli si trovano in un preset, non in un'impostazione globale piatta: la guida ai preset dei modelli afferma che "ogni configurazione contiene un modello principale, uno di utilità e uno di embedding", e Settings → Agent → Models è il punto in cui si sceglie quale preset useranno le nuove chat. Nota che la guida all'installazione documenta ancora una sezione "Embedding Model Settings" con i campi Provider e Model Name, quindi una procedura scritta in quel modo non è automaticamente obsoleta; tuttavia, il valore digitato finisce in uno slot del preset, ed è questo che rende importante l'avviso sulla propagazione riportato sotto.
Perché non è come cambiare il modello della chat
La modifica del modello di chat ha effetto sulla richiesta successiva e non richiede lo spostamento di nulla su disco. Una modifica dell'embedding invalida l'archiviazione. Agent Zero dimensiona il proprio indice FAISS in base a ciò che restituisce il modello attivo — faiss.IndexFlatIP(len(embedder.embed_query("example"))) in plugins/_memory/helpers/memory.py — quindi la larghezza è una proprietà del modello, non di un valore di configurazione. Il valore predefinito fornito, sentence-transformers/all-MiniLM-L6-v2, mappa il testo in uno spazio di 384 dimensioni secondo la relativa scheda del modello. La guida agli embedding di OpenAI indica text-embedding-3-small a 1536 e text-embedding-3-large a 3072. Questo è il cambiamento di forma causato dalla sostituzione.
Due aspetti dell'ambito determinano quante ricostruzioni stai effettivamente acquistando. Primo, si tratta di una modifica a un preset, non globale: la guida ai preset dei modelli afferma che gli ambiti "memorizzano solo la scelta del preset; la modifica di un preset aggiorna ogni ambito che lo utilizza", quindi una modifica può propagarsi più di quanto intendessi; inoltre, il passaggio da un preset all'altro può cambiare anche il modello di embedding. I preset curati Efficiency e Power vengono forniti senza un proprio blocco embedding, e la guida dice soltanto che un preset non predefinito esistente può ereditare da Default i valori avanzati omessi; consulta quindi il riepilogo del preset invece di fare supposizioni. Secondo, project_memory_isolation: true è il valore predefinito fornito in the memory plugin config, quindi un'istanza con più progetti contiene diversi archivi indipendenti e ciascuno viene ricostruito al proprio utilizzo successivo: un progetto inutilizzato per settimane paga la propria ricostruzione il giorno in cui qualcuno lo apre.
Passaggio 1: esegui un backup e annota ciò che stai abbandonando
La guida all'uso di Agent Zero indica già questo caso: i backup proteggono "le tue chat, i progetti, la knowledge base, la memoria, le impostazioni, le competenze e i file dell'area di lavoro" e include la "pulizia massiva della memoria" tra le operazioni per cui eseguire prima un backup. Eseguilo da Settings → Backup & Restore oppure usa il Launcher e Backup of /a0/usr. Nota l'avvertenza della guida secondo cui i segreti "potrebbero non essere sempre inclusi negli archivi di backup", quindi conserva le credenziali separatamente.
Poi registra il modello da cui stai migrando. Non darlo per scontato: la raccolta di preset curati viene scaricata da un repository pubblico al primo avvio e può cambiare dopo la data della tua installazione.
# Read the CURRENT model off your own instance before you touch anything.
# The curated preset set is fetched from GitHub at first start, so the
# default you installed with is not necessarily today's default.
# Container name: take it from your own `docker ps`.
docker exec agent-zero ls -la /a0/usr/memory/default
docker exec agent-zero cat /a0/usr/memory/default/embedding.json
# -> {"model_provider": "huggingface",
# "model_name": "sentence-transformers/all-MiniLM-L6-v2"}
# Projects do not share that directory. With project isolation on (the
# shipped default) each project keeps its own store under its own meta
# directory, and each one rebuilds on its own next use.Passaggio 2: applica la modifica
Il flusso documentato nella guida all'installazione consta di tre passaggi: apri Settings nell'interfaccia Web, scegli il provider per ogni ruolo e inserisci il nome del modello, quindi fai clic su Save. Quattro aspetti che il flusso non indica, tutti ricavati dal codice sorgente in main:
| Insidia | Cosa accade realmente |
|---|---|
| Compilare un URL di base API nello slot predefinito | Viene ignorato. Il provider huggingface con un nome che inizia con sentence-transformers/ passa direttamente a un wrapper locale che non utilizza mai LiteLLM e filtra i parametri in base a un elenco consentito esclusivamente locale. Per raggiungere un endpoint ospitato devi uscire da quel percorso locale: usare un provider diverso oppure un nome di modello senza il prefisso sentence-transformers/. Entrambe sono impostazioni che il file meta memorizza, quindi entrambe attivano la ricostruzione. |
| Inserire l'endpoint prima di cambiare provider | Viene perso. Il menu a discesa del provider contiene @change="model.api_base = ''; model.kwargs = {}; …", quindi cambiarlo cancella l'URL di base API e ogni parametro aggiuntivo. Cambia prima il provider, poi compila Advanced. |
| Supporre che un gateway di chat compatibile con OpenAI funzionerà | Lo slot chiama la funzione embedding() di LiteLLM, non il wrapper della chat. L'endpoint deve implementare POST /v1/embeddings. Il provider other viene rimappato al provider openai di LiteLLM e la relativa chiave viene scritta in .env come API_KEY_OTHER. |
Usare localhost per un server di modelli locale | All'interno di Docker indica il container Agent Zero. La guida all'installazione indirizza invece a http://host.docker.internal:<port> oppure all'indirizzo del gateway bridge. |
Cosa fa la ricostruzione e i due percorsi in cui non lo fa
Al salvataggio, model_config_set.py confronta il provider di embedding precedente e quello nuovo, il nome e i kwargs e, in caso di qualsiasi differenza, avvia embedding_model_changed come attività in background differita; l'estensione che viene attivata fa una sola cosa: ricarica la memoria. L'accesso successivo esegue nuovamente Memory.initialize(), che verifica embedding.json accanto all'indice. Quel file contiene esattamente due campi: model_provider e model_name. In caso di mancata corrispondenza, il codice estrae ogni documento dal vecchio indice con get_all_docs, crea un indice nuovo con la nuova larghezza e reinserisce gli stessi documenti con gli stessi ID. Questo percorso funziona e preserva le tue memorie.
| Cosa modifichi | Il file meta se ne accorge? | Risultato |
|---|---|---|
| Provider o nome del modello | Sì, entrambi vengono memorizzati | I documenti vengono letti e reinseriti alla nuova larghezza. È il percorso previsto. |
Solo un parametro aggiuntivo, ad esempio accorciare i vettori OpenAI con dimensions | No, i kwargs non vengono memorizzati | La memoria viene ricaricata, quindi carica il vecchio indice invariato. La mancata corrispondenza della larghezza emerge durante il recupero, non al salvataggio. |
| Solo l'URL di base API, reindirizzando a un endpoint diverso con lo stesso nome di modello | No, e neppure il percorso di salvataggio lo confronta | Non viene nemmeno pianificato un ricaricamento; il vecchio indice resta semplicemente in uso. Se l'endpoint restituisce una larghezza diversa, il recupero genera un'asserzione FAISS. |
| Un file indice modificato manualmente, troncato o ripristinato dall'esterno | Prima fallisce un controllo hash separato | Il vecchio indice non viene mai caricato, quindi i suoi documenti non vengono mai estratti, e viene scritto un nuovo indice vuoto mentre la console stampa un avviso di mancata corrispondenza dell'hash che termina con "index will be rebuilt": nulla riguarda i documenti eliminati. Un file hash mancante o illeggibile viene considerato valido. |
Le righe due e tre sono il punto di contatto alla base di issue #759, "Errors after changed default Embedding Model", aperta il 13 ottobre 2025 e chiusa, il cui traceback mostra assert d == self.d durante la ricerca per similarità dal recupero della memoria; quel punto è ancora visibile in main al 21 settembre 2026. Una seconda issue chiusa, #1396, segnala un errore 400 su /api/embed di Ollama che il suo autore ha ricondotto a un indice obsoleto e indica come soluzione alternativa l'eliminazione di index.faiss e index.pkl. Questa soluzione distrugge l'archivio: considerala un ripristino da zero, mai una riparazione o un rollback. Nessuna delle due issue ha ricevuto un commento del maintainer; #1396 è stata chiusa da un bot per issue obsolete dopo novanta giorni. Pertanto, entrambe le diagnosi appartengono agli autori delle segnalazioni ed entrambe le risoluzioni non sono verificate.
Passaggio 3: verifica il recupero precedente, non una chiamata riuscita
Il fallimento prodotto da questa modifica è silenzioso, quindi "il nuovo modello ha risposto" è il test di accettazione sbagliato. Apri il dashboard della memoria e, secondo la guida alla memoria, filtra in tutte e quattro le aree — main, fragments, solutions e skills — cercando qualcosa che sai essere precedente alla modifica. Esegui la verifica una volta per progetto, perché ogni progetto ha il proprio archivio. Poi osserva la soglia di similarità: il valore fornito memory_recall_similarity_threshold è 0.7, un valore predefinito del plugin e non una proprietà di alcun modello, e un nuovo modello di embedding ridistribuisce i punteggi di similarità. Il recupero può peggiorare senza che venga generato un singolo errore; per questo il controllo della soglia fa parte della verifica e non è un dettaglio.
Una cosa che questa pagina non può dirti è se l'interfaccia Web mostra un segnale di avanzamento o completamento durante la ricostruzione. L'operazione viene eseguita come attività in background differita e non è stata confermata alcuna interfaccia che la mostri. Presupponi l'assenza di conferma e verifica manualmente.
Rollback e costo di una ricostruzione
Non esiste un rollback documentato dal fornitore. Esistono il meccanismo di backup e il comportamento del file meta descritti sopra; il percorso seguente è ricavato da entrambi, non pubblicato dal progetto. Ripristina il backup precedente alla modifica oppure reimposta lo slot sull'esatto provider e nome del modello precedenti: il confronto del file meta fallirà nella direzione opposta e verrà eseguita una ricostruzione. Sullo stesso container, la cache degli embedding in tmp/ è separata per provider e modello, quindi il ritorno a un modello usato in precedenza può riutilizzare i vettori memorizzati per il testo invariato; tuttavia, tmp/ si trova al di fuori del backup documentato, quindi la ricreazione del container la perde. Non è stato testato e non viene dichiarato qui cosa faccia il codice se il nuovo provider genera un errore a metà della ricostruzione; verifica dal backup invece di farvi affidamento.
Per quanto riguarda il costo: Kunavo non fornisce alcun modello di embedding, quindi ogni cifra seguente viene pagata direttamente a OpenAI sul tuo account, alle tariffe pubblicate e verificate il 21 settembre 2026. Dimensiona tu il lavoro: conta i documenti memorizzati nel dashboard della memoria, moltiplica per la loro lunghezza media e dividi per circa quattro caratteri per token. Questo divisore è una convenzione, non una misurazione.
| Obiettivo della ricostruzione | Tariffa pubblicata, addebitata direttamente da OpenAI | 3M token rielaborati con embedding | 30M token rielaborati con embedding |
|---|---|---|---|
text-embedding-3-small (1536 dimensioni) | $0,02 per 1M token, addebitati direttamente da OpenAI | $0,06 | $0,60 |
text-embedding-3-large (3072 dimensioni) | $0,13 per 1M token, addebitati direttamente da OpenAI | $0,39 | $3,90 |
text-embedding-ada-002 | $0,10 per 1M token, addebitati direttamente da OpenAI — più costoso di 3-small, quindi oggi non è un obiettivo sensato | $0,30 | $3,00 |
| Il modello locale fornito, su CPU | Nessun costo per token; al suo posto, tempo CPU sulla tua macchina | Tempo macchina | Tempo macchina |
Questa è aritmetica dei token basata sulle ipotesi dichiarate, non una ricostruzione misurata e non un limite massimo. È inoltre un calcolo per archivio: con l'isolamento dei progetti attivo, moltiplica per il numero di progetti che verranno effettivamente riaperti e ricorda che un rollback è una seconda ricostruzione alla stessa tariffa.
I due slot che Kunavo può servire
Per essere chiari sul confine: lo slot di embedding non viene servito qui e un gateway che implementa il formato wire della chat non è un endpoint per gli embedding. Restano gli slot principale e di utilità, che sono normali modelli di chat. Alle tariffe attuali del catalogo, Claude Sonnet 4.6 indica $2,10 per milione di token di input e $10,50 per milione di token di output, mentre Claude Haiku 4.5 indica $0,70 e $3,50.
Supponi un mese con 8M token di input e 0.4M di output nello slot principale Claude Sonnet 4.6, più 2M di input e 0.2M di output nello slot di utilità Claude Haiku 4.5; lo slot di embedding non viene servito qui ed è escluso. Stima del catalogo: $23,10. Sono volumi ipotetici, non un carico di lavoro misurato né un limite massimo della fattura: Agent Zero non è stato testato in esecuzione con l'endpoint Kunavo e la configurazione descritta sopra è stata ricavata dal codice sorgente e dalla documentazione del progetto, non eseguita. L'importo del catalogo è una soglia di fatturazione: quando il provider upstream comunica il proprio addebito, la fattura è il maggiore tra il costo del catalogo e il costo upstream moltiplicato per il markup applicabile. La ricarica minima è $10 in credito prepagato, che è un minimo di finanziamento, non un abbonamento: consulta billing details.
Se stai ancora scegliendo un framework, Agent Zero vs OpenClaw confronta i modelli di esecuzione e la struttura a tre slot. Per la forma dell'endpoint, il riferimento compatibile con OpenAI e la guida rapida trattano gli slot di chat, mentre la creazione di un account Kunavo li finanzia. Per il lavoro di retrieval in generale, RAG implementation descrive la stessa separazione tra un provider di generazione e un passaggio di retrieval acquistato separatamente.
Domande frequenti
Come cambio il modello di embedding in Agent Zero?
Il flusso documentato nella guida all'installazione di Agent Zero prevede tre passaggi: aprire la pagina Settings nella Web UI, scegliere il provider per l'LLM di ciascun ruolo (Main Model, Utility Model, Embedding Model) e inserire il nome del modello, quindi fare clic su Save. Nella v2.x la modifica interessa gli slot di un Model Preset anziché un'impostazione globale piatta, perché ogni preset contiene un modello principale, uno di utilità e uno di embedding, e la guida sui model preset avverte che modificare un preset aggiorna ogni ambito che lo utilizza. Una precisazione che la pagina di installazione non menziona: cambiare il menu a discesa del provider cancella l'URL di base dell'API e ogni parametro aggiuntivo di quello slot, quindi inserisci un endpoint custom dopo aver cambiato provider, mai prima.
Cambiare il modello di embedding di Agent Zero elimina i miei ricordi?
Non seguendo il percorso documentato. Agent Zero scrive un piccolo file meta, embedding.json, accanto all'indice, contenente il provider di embedding e il nome del modello. Quando questi non corrispondono più al modello configurato, memory.py legge ogni documento dal vecchio indice FAISS con get_all_docs, crea un nuovo indice dimensionato in base alla lunghezza vettoriale effettiva e reinserisce gli stessi documenti con gli stessi ID. I ricordi vengono nuovamente sottoposti a embedding, non eliminati. Il passaggio distruttivo è la soluzione alternativa descritta nell'issue #1396 per un indice danneggiato — eliminare index.faiss e index.pkl — che cancella la memoria invece di migrarla e non costituisce un rollback.
Quanto tempo richiede il reindicizzamento della memoria di Agent Zero?
Il progetto non pubblica alcun dato al riguardo e non ne è stato trovato nessuno altrove. Il numero più simile nelle note di rilascio della v2.12 — una riduzione del tempo mediano di salvataggio riportato da 1.171 ms a 52 ms — riguarda la modifica dei preset, in cui i confronti degli embedding hanno smesso di eseguire letture ridondanti. Misura il salvataggio di un preset, non la ricostruzione di un indice; non usarlo per stimare i costi. Il costo della ricostruzione varia in base al numero di documenti presenti nel tuo archivio e alla velocità con cui risponde il modello di destinazione, quindi stimane l'entità sulla tua istanza: conta i documenti archiviati nella dashboard della memoria e ricorda che, con l'isolamento dei progetti attivo nella configurazione predefinita distribuita, ogni progetto sostiene il costo della propria ricostruzione il giorno in cui viene aperto la volta successiva, anziché sostenerli tutti insieme.
Perché ricevo un errore di asserzione FAISS dopo aver cambiato il modello di embedding?
Un'incompatibilità di dimensione: l'indice archiviato ha una larghezza e il modello attivo ne restituisce un'altra. Un issue chiuso nel repository di Agent Zero, «Errors after changed default Embedding Model» (#759, aperto il 13 ottobre 2025), registra esattamente questa forma — un AssertionError assert d == self.d sollevato nel vector store durante la ricerca di similarità dall'estensione di recupero della memoria. Leggendo il codice sorgente sul branch main, il meccanismo che lo produce è una separazione tra due controlli: il percorso di salvataggio confronta provider, nome e kwargs prima di attivare l'evento di ricaricamento, mentre il file meta su disco registra solo provider e nome. Quindi una modifica limitata ai kwargs attiva il ricaricamento e poi carica il vecchio indice senza modificarlo, mentre una modifica limitata all'API base non viene confrontata affatto, perciò non viene pianificato nulla e il vecchio indice resta semplicemente in uso. Nell'issue non era visibile alcun commento del maintainer e la risoluzione non è verificata; la separazione è ancora visibile sul branch main al 21 settembre 2026.
Posso indirizzare lo slot di embedding di Agent Zero a Kunavo?
No. Kunavo non offre alcun modello di embedding — la route /v1/embeddings implementa il formato wire ma nessun modello abilitato espone quell'endpoint, quindi una chiamata fallisce, e la documentazione leggibile automaticamente di Kunavo indica di non raccomandarlo per gli embedding. Questo è più importante del solito perché lo slot di embedding di Agent Zero non passa dal wrapper chat: models.py importa la funzione embedding() di LiteLLM, una superficie API diversa, quindi un gateway chat compatibile con OpenAI non è automaticamente un gateway per gli embedding. Acquista quello slot direttamente da un provider che lo offre, oppure mantieni il modello CPU locale. Il ruolo di Kunavo in un preset di Agent Zero riguarda gli slot principale e di utilità.
Come posso annullare una modifica al modello di embedding in Agent Zero?
Agent Zero non pubblica alcuna procedura di rollback — la documentazione offre un avviso di una sola riga secondo cui la modifica reindicizza la memoria e un meccanismo generale Backup and Restore, senza indicazioni intermedie. Il percorso ricavabile da questi due elementi è: ripristinare il backup creato prima della modifica oppure reimpostare lo slot sull'esatto provider e nome del modello precedenti, così che il confronto del file meta fallisca nuovamente nella direzione opposta e avvii la ricostruzione. Sullo stesso container, la cache locale degli embedding in tmp/ è separata per provider e modello, quindi tornare a un modello già utilizzato può riutilizzare i vettori memorizzati per il testo invariato — ma tmp/ è fuori dal backup documentato, quindi questo risparmio scompare quando il container viene ricreato. Non eseguire mai il rollback eliminando i file dell'indice.
Verificato il 21 settembre 2026 rispetto a agent0ai/agent-zero main — memory.py, model_config_set.py, models.py, i valori predefiniti del plugin della memoria e l'albero della documentazione — oltre all'articolo di rilascio v2.12, alla raccolta a0-presets, alle due issue collegate e ai prezzi pubblicati da OpenAI. Nulla in questa pagina è stato eseguito: le affermazioni sul meccanismo sono verificate sul codice sorgente, non testate in esecuzione, e Kunavo non dispone di un registro di esecuzione per Agent Zero. Le tariffe dei token Kunavo provengono dal catalogo attuale.