Modifier le modèle d’embedding d’Agent Zero signifie modifier l’emplacement d’embedding dans un Model Preset, puis cliquer sur Save — et lorsque cette modification change le fournisseur ou le nom du modèle, l’accès suivant réindexe la mémoire, car un index FAISS est dimensionné selon la largeur de sortie d’un modèle et les vecteurs présents sur le disque ont été écrits par l’ancien modèle. Le guide d’installation d’Agent Zero indique la conséquence en une seule ligne — « Changing the embedding_llm will re-index all of A0's memory » — sans fournir de procédure, de durée ni de moyen de revenir en arrière. Cette page comble cette lacune à partir du code source : ce que fait réellement la reconstruction automatique, les deux chemins où elle ne se déclenche discrètement pas, comment vérifier que les anciens souvenirs réapparaissent encore et comment revenir en arrière. Kunavo ne fournit aucun modèle d’embedding ; cet emplacement est donc acheté ailleurs. Les emplacements que Kunavo peut tarifer sont les emplacements principal et utilitaire.
Deux numéros de version à distinguer d'abord. Le framework est en v2.12, publié le 9 septembre 2026 selon l'article de publication du projet. Le numéro le plus visible dans le README est A0 Launcher v1.7, qui est l'installateur de bureau distinct de agent0ai/a0-launcher — l'associer au framework serait se tromper de toute une version majeure. Et dans v2.x, les champs de modèle se trouvent dans un préréglage plutôt que dans un paramètre global à plat : le guide des préréglages de modèles indique que « chaque configuration contient un modèle principal, un modèle utilitaire et un modèle d'embedding », et que Settings → Agent → Models est l'endroit où choisir le préréglage utilisé par les nouvelles conversations. Notez que le guide d'installation documente toujours une section « Embedding Model Settings » avec les champs Provider et Model Name ; un tutoriel rédigé ainsi n'est donc pas automatiquement obsolète — mais la valeur saisie est affectée à un emplacement du préréglage, ce qui explique l'importance de l'avertissement de propagation ci-dessous.
Pourquoi cela ne fonctionne pas comme le changement de modèle de conversation
Un changement de modèle de conversation prend effet à la requête suivante et rien ne doit être déplacé sur le disque. Un changement d'embedding invalide le stockage. Agent Zero dimensionne son index FAISS à partir de ce que renvoie le modèle actif — faiss.IndexFlatIP(len(embedder.embed_query("example"))) dans plugins/_memory/helpers/memory.py — la largeur est donc une propriété du modèle, et non d'une valeur de configuration. La valeur par défaut fournie, sentence-transformers/all-MiniLM-L6-v2, convertit le texte en un espace de 384 dimensions selon sa fiche de modèle. Le guide des embeddings d'OpenAI indique text-embedding-3-small à 1536 et text-embedding-3-large à 3072. C'est le changement de forme provoqué par un tel basculement.
Deux faits de portée déterminent le nombre réel de reconstructions que vous achetez. Premièrement, il s'agit d'une modification de préréglage, et non d'une modification globale : le guide des préréglages de modèles précise que les portées « stockent uniquement le choix du préréglage ; modifier un préréglage met à jour chaque portée qui l'utilise », de sorte qu'une seule modification peut se propager plus loin que prévu — et passer d'un préréglage à un autre peut également changer le modèle d'embedding. Les préréglages Efficiency et Power fournis n'ont pas leur propre bloc d'embedding, et le guide indique seulement qu'un préréglage existant autre que celui par défaut peut hériter des valeurs avancées omises de Default ; consultez donc le résumé du préréglage au lieu de supposer. Deuxièmement, project_memory_isolation: true est la valeur par défaut fournie dans la configuration du plugin de mémoire ; une instance multi-projets contient donc plusieurs stockages indépendants, chacun étant reconstruit à sa prochaine utilisation — un projet resté inutilisé pendant des semaines paie sa reconstruction le jour où quelqu'un l'ouvre.
Étape 1 : sauvegardez et notez ce que vous quittez
Le guide d'utilisation d'Agent Zero mentionne déjà ce cas : les sauvegardes protègent « vos conversations, projets, connaissances, mémoire, paramètres, compétences et fichiers de l'espace de travail », et il inclut le « nettoyage massif de la mémoire » parmi les éléments à sauvegarder au préalable. Faites-en une depuis Settings → Backup & Restore, ou utilisez la Launcher avec Backup of /a0/usr. Notez la propre réserve du guide : les secrets « peuvent ne pas toujours être inclus dans les archives de sauvegarde » ; conservez donc les identifiants séparément.
Enregistrez ensuite le modèle depuis lequel vous migrez. Ne le supposez pas : la collection de préréglages organisée est téléchargée depuis un dépôt public au premier démarrage et peut changer après la date de votre installation.
# 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.Étape 2 : effectuez la modification
Le processus documenté dans le guide d'installation comporte trois étapes : ouvrir Settings dans l'interface Web, choisir le fournisseur pour chaque rôle et saisir le nom du modèle, puis cliquer sur Save. Quatre éléments que ce processus ne vous indique pas, tous lus dans le code source sur main :
| Piège | Ce qui se passe réellement |
|---|---|
| Renseigner une URL de base d'API dans l'emplacement par défaut | Elle est ignorée. Le fournisseur huggingface avec un nom commençant par sentence-transformers/ bifurque directement vers un wrapper local qui ne touche jamais LiteLLM et réduit les paramètres à une liste blanche réservée au local. Pour atteindre un endpoint hébergé, il faut quitter ce chemin local — choisir un autre fournisseur ou utiliser un nom de modèle sans le préfixe sentence-transformers/. Dans les deux cas, il s'agit d'un champ enregistré par le fichier meta ; l'un comme l'autre déclenche donc la reconstruction. |
| Saisir l'endpoint avant de changer de fournisseur | Perdu. La liste déroulante des fournisseurs transporte @change="model.api_base = ''; model.kwargs = {}; …" ; la modifier efface l'URL de base de l'API et tous les paramètres supplémentaires. Changez d'abord de fournisseur, puis remplissez Advanced. |
| Supposer qu'une passerelle de conversation compatible avec OpenAI fonctionnera | L'emplacement appelle la fonction embedding() de LiteLLM, et non le wrapper de conversation. L'endpoint doit implémenter POST /v1/embeddings. Le fournisseur other est remappé vers le fournisseur openai de LiteLLM, et sa clé est écrite dans .env sous la forme API_KEY_OTHER. |
Utiliser localhost pour un serveur de modèles local | Dans Docker, cela désigne le conteneur Agent Zero. Le guide d'installation vous dirige vers http://host.docker.internal:<port> ou vers l'adresse de la passerelle relais. |
Ce que fait la reconstruction — et les deux chemins où elle ne se produit pas
Lors de l'enregistrement, model_config_set.py compare le fournisseur d'embedding précédent et le nouveau, le nom ainsi que les kwargs ; à la moindre différence, il lance embedding_model_changed comme tâche d'arrière-plan différée. L'extension déclenchée ne fait qu'une chose : recharger la mémoire. L'accès suivant réexécute Memory.initialize(), qui vérifie embedding.json à côté de l'index. Ce fichier contient exactement deux champs — model_provider et model_name. En cas de différence, le code extrait tous les documents de l'ancien index avec get_all_docs, crée un nouvel index à la nouvelle largeur et réinsère les mêmes documents avec les mêmes identifiants. Ce chemin fonctionne et préserve vos souvenirs.
| Ce que vous modifiez | Le fichier meta le détecte-t-il ? | Résultat |
|---|---|---|
| Fournisseur ou nom du modèle | Oui — les deux sont enregistrés | Documents extraits puis réinsérés à la nouvelle largeur. Le chemin prévu. |
Uniquement un paramètre supplémentaire, par exemple en raccourcissant les vecteurs OpenAI avec dimensions | Non — les kwargs ne sont pas enregistrés | La mémoire est rechargée, puis l'ancien index inchangé est chargé. Une incompatibilité de largeur apparaît lors de la récupération, et non lors de l'enregistrement. |
| Uniquement l'URL de base de l'API, redirigée vers un autre endpoint sous le même nom de modèle | Non — et le chemin d'enregistrement ne la compare pas non plus | Aucun rechargement n'est même planifié ; l'ancien index reste simplement utilisé. Si cet endpoint répond avec une largeur différente, la récupération déclenche une assertion FAISS. |
| Un fichier d'index modifié manuellement, tronqué ou restauré depuis l'extérieur | Une vérification de hachage distincte échoue en premier | L'ancien index n'est jamais chargé ; ses documents ne sont donc jamais extraits, et un nouvel index vide est écrit tandis que la console affiche un avertissement d'incompatibilité de hachage se terminant par « index will be rebuilt » — rien n'est dit sur les documents supprimés. Un fichier de hachage manquant ou illisible est considéré comme valide. |
Les deuxième et troisième lignes constituent le point de jonction derrière issue #759, « Errors after changed default Embedding Model », ouverte le 13 octobre 2025 et clôturée, dont la trace d'erreur montre assert d == self.d lors d'une recherche de similarité déclenchée par la récupération de mémoire ; ce point est toujours visible dans main au 21 septembre 2026. Une seconde issue clôturée, #1396, signale une erreur 400 sur /api/embed d'Ollama que son auteur attribue à un index obsolète, et propose de supprimer index.faiss et index.pkl comme solution de contournement. Cette solution détruit le stockage ; considérez-la comme une réinitialisation, jamais comme une réparation ou un retour arrière. Aucune des deux issues n'a reçu de commentaire d'un mainteneur — #1396 a été clôturée par un bot de gestion des issues obsolètes après quatre-vingt-dix jours — les deux diagnostics sont donc ceux de leurs auteurs et les deux résolutions restent non vérifiées.
Étape 3 : vérifiez l'ancienne récupération, et non la réussite d'un appel
L'échec produit par cette modification est silencieux ; « le nouveau modèle a répondu » est donc un mauvais test d'acceptation. Ouvrez le tableau de bord de la mémoire et, conformément au guide de la mémoire, filtrez dans les quatre zones — main, fragments, solutions et skills — en recherchant quelque chose dont vous savez que cela est antérieur à la modification. Faites-le une fois par projet, car chaque projet possède son propre stockage. Surveillez ensuite le seuil de similarité : le memory_recall_similarity_threshold fourni est 0.7, une valeur par défaut propre au plugin et non une propriété d'un modèle quelconque ; un nouveau modèle d'embedding redistribue les scores de similarité. La récupération peut se dégrader sans qu'une seule erreur soit levée, raison pour laquelle le contrôle du seuil fait partie de la vérification et n'est pas un détail.
Une chose que cette page ne peut pas vous dire : si l'interface Web affiche un signal de progression ou d'achèvement pendant la reconstruction. Celle-ci s'exécute comme une tâche d'arrière-plan différée et aucune interface permettant de la suivre n'a été confirmée. Partez du principe qu'aucune confirmation ne sera affichée et vérifiez manuellement.
Retour arrière et coût d'une reconstruction
Il n'existe aucun retour arrière documenté par le fournisseur. Ce qui existe est le mécanisme de sauvegarde ainsi que le comportement du fichier meta décrit ci-dessus ; le parcours ci-dessous est assemblé à partir de ces deux éléments et non publié par le projet. Restaurez la sauvegarde antérieure à la modification ; ou rétablissez exactement le fournisseur et le nom de modèle précédents dans l'emplacement, ce qui fera échouer la comparaison du fichier meta dans l'autre sens et déclenchera une reconstruction. Dans le même conteneur, le cache d'embeddings sous tmp/ est indexé par fournisseur et modèle ; le retour à un modèle déjà utilisé peut donc réutiliser les vecteurs mis en cache pour le texte inchangé — mais tmp/ se trouve en dehors de la sauvegarde documentée, et la recréation du conteneur le fait perdre. Le comportement du code si le nouveau fournisseur échoue au milieu d'une reconstruction n'a pas été testé et n'est pas indiqué ici ; vérifiez depuis la sauvegarde au lieu de vous y fier.
Côté coût : Kunavo ne fournit aucun modèle d'embedding ; chaque montant ci-dessous est donc payé directement à OpenAI sur votre propre compte, selon ses tarifs publiés vérifiés le 21 septembre 2026. Estimez vous-même la tâche : comptez les documents stockés dans le tableau de bord de la mémoire, multipliez par leur longueur moyenne et divisez par environ quatre caractères par token. Ce diviseur est une convention, pas une mesure.
| Cible de la reconstruction | Tarif publié, facturé directement par OpenAI | 3M tokens ré-encodés | 30M tokens ré-encodés |
|---|---|---|---|
text-embedding-3-small (1536 dimensions) | 0,02 $ par million de tokens, facturé directement par OpenAI | $0.06 | $0.60 |
text-embedding-3-large (3072 dimensions) | 0,13 $ par million de tokens, facturé directement par OpenAI | $0.39 | $3.90 |
text-embedding-ada-002 | 0,10 $ par million de tokens, facturé directement par OpenAI — plus cher que 3-small, et donc pas une cible pertinente aujourd'hui | $0.30 | $3.00 |
| Le modèle local fourni sur CPU | Aucun coût par token ; du temps CPU sur votre propre machine à la place | Temps machine | Temps machine |
Il s'agit d'un calcul de tokens fondé sur les hypothèses indiquées, pas d'une reconstruction mesurée ni d'un plafond. Il s'agit également d'un calcul par stockage : lorsque l'isolation des projets est activée, multipliez par le nombre de projets qui seront réellement rouverts, et rappelez-vous qu'un retour arrière constitue une deuxième reconstruction au même tarif.
Les deux emplacements que Kunavo peut fournir
Pour être clair sur la limite : l'emplacement d'embedding n'est pas fourni ici, et une passerelle qui implémente le format filaire de conversation n'est pas un endpoint d'embeddings. Il reste donc les emplacements principal et utilitaire, qui sont des modèles de conversation ordinaires. Aux tarifs actuels du catalogue, Claude Sonnet 4.6 indique $2.10 par million de tokens d'entrée et $10.50 par million de tokens de sortie, tandis que Claude Haiku 4.5 indique $0.70 et $3.50.
Supposons un mois avec 8M tokens d'entrée et 0,4M tokens de sortie sur un emplacement principal Claude Sonnet 4.6, ainsi que 2M tokens d'entrée et 0,2M tokens de sortie sur un emplacement utilitaire Claude Haiku 4.5 ; l'emplacement d'embedding n'est pas fourni ici et est exclu. Estimation du catalogue : $23.10. Il s'agit de volumes supposés, pas d'une charge de travail mesurée ni d'un plafond de facturation — Agent Zero n'a pas été testé en conditions réelles avec l'endpoint de Kunavo, et la configuration décrite ci-dessus a été lue dans le code source et la documentation du projet plutôt qu'exécutée. Le montant du catalogue est un plancher de facturation : lorsque l'amont communique son coût, la facture correspond au montant le plus élevé entre le coût du catalogue et le coût de l'amont multiplié par la majoration applicable. Le rechargement minimal est de $10 en crédit prépayé, ce qui constitue un minimum de financement et non un abonnement — voir les détails de facturation.
Si vous choisissez encore un framework, Agent Zero vs OpenClaw compare les modèles d'exécution et la structure à trois emplacements. Pour la forme de l'endpoint elle-même, la référence compatible avec OpenAI et le guide de démarrage rapide couvrent les emplacements de conversation, et la création d'un compte Kunavo les finance. Pour les travaux de récupération au sens large, l'implémentation RAG couvre la même séparation entre un fournisseur de génération et une étape de récupération achetée séparément.
Questions fréquentes
Comment modifier le modèle d’embedding dans Agent Zero ?
Le processus documenté dans le guide d’installation d’Agent Zero comporte trois étapes : ouvrir la page Settings dans l’interface web, choisir le fournisseur du LLM pour chaque rôle (Main Model, Utility Model, Embedding Model) et saisir le nom du modèle, puis cliquer sur Save. Dans la version v2.x, cette modification s’effectue sur les emplacements d’un Model Preset plutôt que dans un réglage global unique, car chaque preset contient un modèle principal, un modèle utilitaire et un modèle d’embedding ; le guide des model-presets avertit que modifier un preset met à jour chaque périmètre qui l’utilise. Une réserve que la page d’installation ne mentionne pas : modifier la liste déroulante du fournisseur efface l’URL de base de l’API et tous les paramètres supplémentaires de cet emplacement ; saisissez donc le point de terminaison personnalisé après avoir changé de fournisseur, jamais avant.
Modifier le modèle d’embedding d’Agent Zero supprime-t-il mes souvenirs ?
Pas selon le chemin documenté. Agent Zero écrit un petit fichier de métadonnées, embedding.json, à côté de l’index ; il contient le fournisseur et le nom du modèle d’embedding. Lorsqu’ils ne correspondent plus au modèle configuré, memory.py lit chaque document de l’ancien index FAISS avec get_all_docs, crée un nouvel index dont la taille dépend de la longueur réelle des vecteurs, puis réinsère les mêmes documents avec les mêmes identifiants. Les souvenirs sont ré-encodés, pas supprimés. L’étape destructive est la solution de contournement décrite dans l’issue #1396 pour un index défectueux — supprimer index.faiss et index.pkl — ce qui efface la mémoire au lieu d’effectuer une migration et ne constitue pas une restauration.
Combien de temps prend la réindexation de la mémoire d’Agent Zero ?
Le projet ne publie aucun chiffre à ce sujet, et aucune valeur n’a été trouvée ailleurs. Le nombre qui s’en rapproche le plus dans les notes de version v2.12 — une baisse du temps médian d’enregistrement rapporté, de 1 171 ms à 52 ms — concerne la modification des presets, lorsque les comparaisons d’embeddings ont cessé d’effectuer des lectures redondantes. Il mesure l’enregistrement d’un preset, pas la reconstruction d’un index ; ne l’utilisez pas pour établir votre budget. Le coût de reconstruction dépend du nombre de documents stockés et de la vitesse de réponse du modèle cible ; dimensionnez-le donc à partir de votre propre instance : comptez les documents stockés dans le tableau de bord de la mémoire et souvenez-vous qu’avec l’isolation des projets activée par défaut dans la version fournie, chaque projet paie sa propre reconstruction le jour où il est rouvert, plutôt que tous simultanément.
Pourquoi une erreur d’assertion FAISS apparaît-elle après avoir changé le modèle d’embedding ?
Il s’agit d’une incompatibilité de dimension : l’index stocké possède une largeur et le modèle actif en renvoie une autre. Une issue fermée du dépôt Agent Zero, « Errors after changed default Embedding Model » (#759, ouverte le 13 octobre 2025), décrit exactement cette situation — une AssertionError assert d == self.d déclenchée dans le magasin vectoriel pendant une recherche de similarité depuis l’extension de rappel de mémoire. La lecture du code sur main montre que le mécanisme provient d’une jonction entre deux vérifications : le chemin d’enregistrement compare le fournisseur, le nom et les kwargs avant de déclencher son événement de rechargement, tandis que le fichier de métadonnées sur disque n’enregistre que le fournisseur et le nom. Ainsi, une modification limitée aux kwargs déclenche le rechargement puis charge l’ancien index inchangé, tandis qu’une modification limitée à l’API base n’est pas comparée ; rien n’est donc planifié et l’ancien index reste simplement utilisé. Aucun commentaire de mainteneur n’était visible dans cette issue et la résolution n’est pas vérifiée ; cette jonction est toujours visible dans main au 21 septembre 2026.
Puis-je faire pointer l’emplacement d’embedding d’Agent Zero vers Kunavo ?
Non. Kunavo ne fournit aucun modèle d’embedding — la route /v1/embeddings implémente le format filaire, mais aucun modèle activé ne sert ce point de terminaison ; un appel échoue, et la documentation lisible par machine de Kunavo indique elle-même de ne pas le recommander pour les embeddings. C’est particulièrement important ici, car l’emplacement d’embedding d’Agent Zero ne passe pas par le wrapper de chat : models.py importe la fonction embedding() de LiteLLM, une autre surface d’API ; une passerelle de chat compatible OpenAI ne devient donc pas automatiquement une passerelle d’embeddings. Achetez cet emplacement directement auprès d’un fournisseur qui le sert, ou conservez le modèle CPU local. Dans un preset Agent Zero, Kunavo intervient sur les emplacements principal et utilitaire.
Comment annuler une modification du modèle d’embedding dans Agent Zero ?
Agent Zero ne publie aucune procédure d’annulation pour ce cas — la documentation offre un avertissement d’une ligne indiquant que la modification réindexe la mémoire, ainsi qu’un mécanisme général Backup and Restore, mais rien entre les deux. La procédure que l’on peut déduire de ces deux éléments est la suivante : restaurer la sauvegarde effectuée avant la modification, ou rétablir exactement le fournisseur et le nom du modèle précédents afin que la comparaison du fichier de métadonnées échoue de nouveau dans l’autre sens et déclenche une reconstruction. Dans le même conteneur, le cache local d’embeddings sous tmp/ est organisé par fournisseur et modèle ; revenir à un modèle déjà utilisé peut donc réutiliser les vecteurs mis en cache pour le texte inchangé — mais tmp/ ne fait pas partie de la sauvegarde documentée, et cette économie disparaît lorsque le conteneur est recréé. Ne revenez jamais en arrière en supprimant les fichiers d’index.
Vérifié le 21 septembre 2026 par rapport à agent0ai/agent-zero main — memory.py, model_config_set.py, models.py, les valeurs par défaut du plugin de mémoire et l'arborescence de documentation — ainsi qu'à l'article de publication v2.12, à la collection a0-presets, aux deux issues liées et aux tarifs publiés d'OpenAI. Rien sur cette page n'a été exécuté : les affirmations concernant le mécanisme sont vérifiées dans le code source, et non testées en conditions réelles ; Kunavo ne possède aucun compte rendu d'exécution pour Agent Zero. Les tarifs des tokens de Kunavo proviennent du catalogue en vigueur.