Cambiar el modelo de embeddings de Agent Zero implica editar la ranura de embeddings dentro de un preset de modelo y hacer clic en Guardar; cuando esa edición cambia el proveedor o el nombre del modelo, el siguiente acceso vuelve a indexar la memoria, porque un índice FAISS tiene el tamaño correspondiente al ancho de salida de un solo modelo y los vectores ya almacenados fueron escritos por el modelo anterior. La propia guía de instalación de Agent Zero indica la consecuencia en una sola línea: «Cambiar el embedding_llm volverá a indexar toda la memoria de A0», y no ofrece ningún procedimiento, duración ni forma de volver atrás. Esta página cubre ese vacío a partir de la fuente: qué hace realmente la reconstrucción automática, las dos rutas en las que no se activa silenciosamente, cómo verificar que las memorias antiguas siguen apareciendo y cómo regresar. Kunavo no ofrece ningún modelo de embeddings, por lo que esa ranura se compra en otro lugar; las ranuras que Kunavo puede tarifar son la principal y la de utilidad.
Primero hay que distinguir dos números de versión. El framework está en v2.12, publicado el 9 de septiembre de 2026 según el artículo de lanzamiento del propio proyecto. El número más destacado del README es A0 Launcher v1.7, que corresponde al instalador de escritorio independiente de agent0ai/a0-launcher; asociarlo con el framework es equivocarse por toda una línea principal. Además, en v2.x los campos de modelo están en un preset, no en una configuración global plana: la guía de presets de modelo dice que «cada configuración contiene un modelo principal, uno de utilidad y uno de embeddings», y Settings → Agent → Models es donde se elige qué preset usarán los chats nuevos. Ten en cuenta que la guía de instalación todavía documenta una sección «Embedding Model Settings» con los campos Provider y Model Name, así que una explicación escrita de esa forma no está automáticamente desactualizada; pero el valor que escribes termina en una ranura del preset, y por eso importa la advertencia de propagación que aparece más abajo.
Por qué esto no equivale a cambiar el modelo de chat
Un cambio de modelo de chat se aplica en la siguiente solicitud y no es necesario mover nada en el disco. Un cambio de embeddings invalida el almacenamiento. Agent Zero dimensiona su índice FAISS a partir de lo que devuelve el modelo activo: faiss.IndexFlatIP(len(embedder.embed_query("example"))) en plugins/_memory/helpers/memory.py; por tanto, el ancho es una propiedad del modelo, no de un valor de configuración. El valor predeterminado incluido, sentence-transformers/all-MiniLM-L6-v2, asigna el texto a un espacio de 384 dimensiones según su ficha de modelo. La guía de embeddings de OpenAI sitúa text-embedding-3-small en 1536 y text-embedding-3-large en 3072. Ese es el cambio de forma que provoca una sustitución.
Dos aspectos de alcance determinan cuántas reconstrucciones estás comprando realmente. Primero, esto es una edición de preset, no una edición global: la guía de presets de modelo dice que los ámbitos «solo almacenan la selección del preset; editar un preset actualiza todos los ámbitos que lo utilizan», de modo que una sola edición puede propagarse más de lo que pretendías; además, cambiar de preset también puede cambiar el modelo de embeddings. Los presets seleccionados Efficiency y Power se distribuyen sin un bloque de embeddings propio, y la guía solo dice que un preset existente distinto del predeterminado puede heredar del predeterminado los valores avanzados omitidos; por eso debes leer el resumen del preset en lugar de suponer. Segundo, project_memory_isolation: true es el valor predeterminado incluido en la configuración del complemento de memoria, así que una instancia con varios proyectos mantiene varios almacenes independientes y cada uno se reconstruye por separado en su siguiente uso; un proyecto que no se ha tocado durante semanas paga su reconstrucción el día que alguien lo abre.
Paso 1: haz una copia de seguridad y anota lo que vas a dejar
La guía de uso de Agent Zero ya contempla este caso: las copias de seguridad protegen «tus chats, proyectos, conocimientos, memoria, configuración, habilidades y archivos del espacio de trabajo», y enumera la «limpieza masiva de memoria» entre las operaciones para las que conviene hacer una copia previa. Haz una desde Settings → Backup & Restore o usa la Launcher para crear una copia de seguridad de /a0/usr. Ten presente la propia advertencia de la guía: los secretos «pueden no incluirse siempre en los archivos de copia de seguridad», así que conserva las credenciales por separado.
Después, registra el modelo desde el que vas a migrar. No lo des por supuesto: la colección de presets seleccionados se descarga de un repositorio público durante el primer inicio y puede cambiar después de la fecha de instalación.
# 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.Paso 2: realiza el cambio
El flujo documentado en la guía de instalación consta de tres pasos: abre Settings en la interfaz web, elige el proveedor para cada función y escribe el nombre del modelo; haz clic en Save. Hay cuatro cosas que ese flujo no te dice, todas leídas de la fuente en main:
| Trampa | Lo que sucede realmente |
|---|---|
| Rellenar una URL base de API en la ranura predeterminada | Se ignora. El proveedor huggingface con un nombre que comienza por sentence-transformers/ entra directamente en un envoltorio local que nunca toca LiteLLM y filtra los parámetros hasta dejar solo una lista de permitidos local. Para llegar a un endpoint alojado hay que abandonar esa ruta local: usar otro proveedor o un nombre de modelo sin el prefijo sentence-transformers/. Cualquiera de los dos es un campo que el metarchivo almacena, por lo que cualquiera de ellos activa la reconstrucción. |
| Introducir el endpoint antes de cambiar el proveedor | Se pierde. El menú desplegable del proveedor contiene @change="model.api_base = ''; model.kwargs = {}; …", por lo que cambiarlo borra la URL base de API y todos los parámetros adicionales. Cambia primero el proveedor y después completa Advanced. |
| Suponer que funcionará una puerta de enlace de chat compatible con OpenAI | La ranura llama a la función embedding() de LiteLLM, no al envoltorio de chat. El endpoint debe implementar POST /v1/embeddings. El proveedor other se reasigna al proveedor openai de LiteLLM, y su clave se escribe en .env como API_KEY_OTHER. |
Usar localhost para un servidor de modelos local | Dentro de Docker, eso significa el contenedor de Agent Zero. La guía de instalación te dirige a http://host.docker.internal:<port> o a la dirección de la puerta de enlace puente. |
Qué hace la reconstrucción y las dos rutas en las que no se produce
Al guardar, model_config_set.py compara el proveedor y el nombre de embeddings anteriores y nuevos, así como los kwargs, y ante cualquier diferencia inicia embedding_model_changed como tarea en segundo plano diferida; la extensión que activa hace una sola cosa: recargar la memoria. El siguiente acceso vuelve a ejecutar Memory.initialize(), que comprueba embedding.json junto al índice. Ese archivo contiene exactamente dos campos: model_provider y model_name. Si no coinciden, el código extrae todos los documentos del índice antiguo con get_all_docs, crea un índice nuevo con el ancho nuevo y vuelve a insertar los mismos documentos con los mismos identificadores. Esa ruta funciona y conserva tus memorias.
| Lo que cambias | ¿Lo detecta el metarchivo? | Resultado |
|---|---|---|
| Proveedor o nombre del modelo | Sí; ambos se almacenan | Los documentos se extraen y se vuelven a insertar con el nuevo ancho. Es la ruta prevista. |
Solo un parámetro adicional, por ejemplo acortar los vectores de OpenAI con dimensions | No; los kwargs no se almacenan | La memoria se recarga y después carga sin cambios el índice antiguo. El desajuste de ancho aparece al recuperar, no al guardar. |
| Solo la URL base de API, redirigiendo a otro endpoint con el mismo nombre de modelo | No; la ruta de guardado tampoco la compara | Ni siquiera se programa una recarga; el índice antiguo simplemente sigue en uso. Si ese endpoint responde con un ancho diferente, la recuperación genera una aserción de FAISS. |
| Un archivo de índice editado manualmente, truncado o restaurado desde fuera | Primero falla una comprobación de hash independiente | El índice antiguo nunca se carga, por lo que sus documentos nunca se extraen, y se escribe un índice vacío nuevo mientras la consola muestra una advertencia de discrepancia de hash que termina con «index will be rebuilt»; no se dice nada sobre los documentos descartados. Un archivo de hash ausente o ilegible se considera válido. |
Las filas dos y tres son la unión que subyace al issue #759, «Errors after changed default Embedding Model», abierto el 13 de octubre de 2025 y cerrado, cuyo traceback muestra assert d == self.d durante la búsqueda de similitud al recuperar memoria; esa unión sigue visible en main a fecha del 21 de septiembre de 2026. Otro issue cerrado, #1396, informa de un 400 en /api/embed de Ollama que su autor atribuyó a un índice obsoleto, y propone como solución eliminar index.faiss y index.pkl. Esa solución destruye el almacén; considérala un reinicio, nunca una reparación ni una reversión. Ninguno de los dos issues recibió un comentario de un mantenedor; #1396 fue cerrado por un bot de issues obsoletos después de noventa días, así que ambos diagnósticos son de los propios informantes y ambas resoluciones no están verificadas.
Paso 3: verifica la recuperación antigua, no una llamada exitosa
El fallo que produce este cambio es silencioso, así que «el modelo nuevo respondió» es una prueba de aceptación equivocada. Abre el panel de memoria y, según la guía de memoria, filtra en las cuatro áreas: main, fragments, solutions y skills; busca algo que sepas que es anterior al cambio. Hazlo una vez por proyecto, porque cada proyecto tiene su propio almacén. Después observa el umbral de similitud: el memory_recall_similarity_threshold incluido es 0.7, un valor predeterminado por complemento y no una propiedad de ningún modelo, y un modelo de embeddings nuevo redistribuye las puntuaciones de similitud. La recuperación puede degradarse sin que se produzca un solo error, por lo que el control del umbral forma parte de la verificación y no es un detalle.
Hay algo que esta página no puede decirte: si la interfaz web muestra alguna señal de progreso o finalización mientras se ejecuta la reconstrucción. Se ejecuta como una tarea en segundo plano diferida y no se confirmó ninguna interfaz para ella. Supón que no habrá confirmación y verifica manualmente.
Reversión y coste de una reconstrucción
No existe una reversión documentada por el proveedor. Lo que existe es el mecanismo de copia de seguridad junto con el comportamiento del metarchivo descrito arriba, y la ruta siguiente se deduce de ambos, no está publicada por el proyecto. Restaura la copia de seguridad previa al cambio o vuelve a establecer en la ranura el proveedor y el nombre exactos del modelo anterior; esto hace que la comparación del metarchivo falle en la otra dirección y se reconstruya. En el mismo contenedor, la caché de embeddings bajo tmp/ está dividida por proveedor y modelo, de modo que volver a un modelo usado anteriormente puede reutilizar vectores almacenados para texto sin cambios; pero tmp/ está fuera de la copia de seguridad documentada, por lo que recrear el contenedor la pierde. No se probó ni se indica aquí qué hace el código si el proveedor nuevo falla a mitad de una reconstrucción; verifica desde la copia de seguridad en lugar de confiar en ello.
En cuanto al coste: Kunavo no ofrece ningún modelo de embeddings, así que todas las cifras siguientes se pagan directamente a OpenAI en tu propia cuenta, según sus tarifas publicadas comprobadas el 21 de septiembre de 2026. Calcula tú mismo el trabajo: cuenta los documentos almacenados en el panel de memoria, multiplícalos por su longitud media y divide entre aproximadamente cuatro caracteres por token. Ese divisor es una convención, no una medición.
| Objetivo de reconstrucción | Tarifa publicada, facturada directamente por OpenAI | 3M tokens vueltos a insertar | 30M tokens vueltos a insertar |
|---|---|---|---|
text-embedding-3-small (1536 dimensiones) | $0.02 por 1M de tokens, facturados directamente por OpenAI | $0.06 | $0.60 |
text-embedding-3-large (3072 dimensiones) | $0.13 por 1M de tokens, facturados directamente por OpenAI | $0.39 | $3.90 |
text-embedding-ada-002 | $0.10 por 1M de tokens, facturados directamente por OpenAI; más caro que 3-small, por lo que hoy no es un objetivo sensato | $0.30 | $3.00 |
| El modelo local incluido en la CPU | Sin cargo por token; en su lugar, tiempo de CPU de tu propia máquina | Tiempo de máquina | Tiempo de máquina |
Esto es aritmética de tokens bajo los supuestos indicados, no una reconstrucción medida ni un límite máximo. También se calcula por almacén: con el aislamiento de proyectos activado, multiplica por el número de proyectos que realmente volverán a abrirse y recuerda que una reversión es una segunda reconstrucción a la misma tarifa.
Las dos ranuras que Kunavo puede ofrecer
Para dejar claro el límite: la ranura de embeddings no se ofrece aquí, y una puerta de enlace que implementa el formato de comunicación de chat no es un endpoint de embeddings. Lo que queda son las ranuras principal y de utilidad, que son modelos de chat normales. Según las tarifas vigentes del catálogo, Claude Sonnet 4.6 enumera $2.10 por millón de tokens de entrada y $10.50 por millón de salida, y Claude Haiku 4.5 enumera $0.70 y $3.50.
Supón un mes con 8M de tokens de entrada y 0.4M de salida en una ranura principal Claude Sonnet 4.6, más 2M de entrada y 0.2M de salida en una ranura de utilidad Claude Haiku 4.5; la ranura de embeddings no se ofrece aquí y queda excluida. Estimación del catálogo: $23.10. Esos son volúmenes supuestos, no una carga de trabajo medida ni un límite de facturación; Agent Zero no se ha probado en ejecución contra el endpoint de Kunavo, y la configuración descrita arriba se leyó del código fuente y la documentación del proyecto en lugar de ejecutarse. El importe del catálogo es un suelo de facturación: cuando el proveedor ascendente informa de su cargo, la factura es el mayor entre el coste del catálogo y el coste del proveedor ascendente multiplicado por el margen aplicable. La recarga mínima es de $10 en crédito prepago, que es un mínimo de financiación, no una suscripción; consulta los detalles de facturación.
Si todavía estás eligiendo un framework, Agent Zero vs OpenClaw compara los modelos de ejecución y la disposición de tres ranuras. Para la forma del endpoint, la referencia compatible con OpenAI y la guía de inicio rápido cubren las ranuras de chat, y crear una cuenta de Kunavo las financia. Para el trabajo de recuperación en general, Implementación de RAG cubre la misma separación entre un proveedor de generación y un paso de recuperación comprado por separado.
Preguntas frecuentes
¿Cómo cambio el modelo de embeddings en Agent Zero?
El flujo documentado en la guía de instalación de Agent Zero consta de tres pasos: abre la página Settings en la Web UI, elige el proveedor del LLM para cada rol (Main Model, Utility Model, Embedding Model) y escribe el nombre del modelo; después, haz clic en Save. En v2.x, esa edición se realiza en las ranuras de un Model Preset y no en un ajuste global plano, porque cada preset contiene un modelo principal, uno de utilidad y uno de embeddings, y la guía de model-presets advierte que editar un preset actualiza todos los ámbitos que lo utilizan. Hay una salvedad que la página de instalación no menciona: cambiar el menú desplegable del proveedor borra la URL base de la API y todos los parámetros adicionales de esa ranura, así que introduce un endpoint personalizado después de cambiar de proveedor, nunca antes.
¿Cambiar el modelo de embeddings de Agent Zero elimina mis memorias?
No siguiendo la ruta documentada. Agent Zero escribe un pequeño metarchivo, embedding.json, junto al índice, que contiene el proveedor y el nombre del modelo de embeddings. Cuando dejan de coincidir con el modelo configurado, memory.py lee todos los documentos del índice FAISS antiguo con get_all_docs, crea un índice nuevo dimensionado según la longitud vectorial activa y vuelve a insertar los mismos documentos con los mismos IDs. Las memorias se vuelven a incrustar, no se eliminan. El paso destructivo es la solución alternativa descrita en el issue #1396 para un índice dañado: eliminar index.faiss e index.pkl, lo que borra la memoria en lugar de migrarla y no constituye una reversión.
¿Cuánto tarda una reindexación de memoria de Agent Zero?
El proyecto no publica ninguna cifra al respecto y no se encontró ninguna en otro lugar. El número más parecido de las notas de lanzamiento de v2.12 —una reducción reportada de la mediana del tiempo de guardado de 1.171 ms a 52 ms— corresponde a la edición de presets, donde las comparaciones de embeddings dejaron de realizar lecturas redundantes. Mide guardar un preset, no reconstruir un índice; no hagas tu presupuesto con él. El coste de reconstrucción escala según el número de documentos que contiene tu almacén y la rapidez con la que responde el modelo objetivo, así que calcula su magnitud a partir de tu propia instancia: cuenta los documentos almacenados en el panel de memoria y recuerda que, con el aislamiento de proyectos activado por defecto en la versión distribuida, cada proyecto paga su propia reconstrucción el día en que se abre de nuevo, en lugar de hacerlo todos a la vez.
¿Por qué aparece un error de aserción de FAISS después de cambiar el modelo de embeddings?
Una discrepancia de dimensiones: el índice almacenado tiene un ancho y el modelo activo devuelve otro. Un issue cerrado del repositorio de Agent Zero, «Errors after changed default Embedding Model» (#759, abierto el 13 de octubre de 2025), registra exactamente ese patrón: una AssertionError de assert d == self.d lanzada en el almacén vectorial durante una búsqueda de similitud desde la extensión de recuperación de memoria. Al leer el código fuente de main, el mecanismo que lo produce es una unión entre dos comprobaciones: la ruta de guardado compara proveedor, nombre y kwargs antes de activar su evento de recarga, mientras que el metarchivo del disco solo registra proveedor y nombre. Por tanto, un cambio únicamente en kwargs activa la recarga y después carga el índice antiguo sin cambios, mientras que un cambio únicamente en la base de la API no se compara en absoluto, por lo que no se programa nada y el índice antiguo simplemente sigue utilizándose. No se veía ningún comentario de mantenedor en ese issue y la resolución no está verificada; la unión sigue siendo visible en main a fecha del 21 de septiembre de 2026.
¿Puedo asignar la ranura de embeddings de Agent Zero a Kunavo?
No. Kunavo no ofrece ningún modelo de embeddings: la ruta /v1/embeddings implementa el formato de comunicación, pero ningún modelo habilitado utiliza ese endpoint, por lo que una llamada falla, y la propia documentación legible por máquinas de Kunavo indica que no se debe recomendar para embeddings. Esto importa más de lo habitual aquí porque la ranura de embeddings de Agent Zero no pasa por el envoltorio de chat: models.py importa la función embedding() de LiteLLM para ella, una superficie de API diferente, así que una puerta de enlace de chat compatible con OpenAI no es automáticamente una puerta de enlace de embeddings. Compra esa ranura directamente a un proveedor que la ofrezca o conserva el modelo local de CPU. El papel de Kunavo en un preset de Agent Zero son las ranuras principal y de utilidad.
¿Cómo revierto un cambio de modelo de embeddings en Agent Zero?
Agent Zero no publica ningún procedimiento de reversión para esto: la documentación ofrece una advertencia de una sola línea de que el cambio vuelve a indexar la memoria y un mecanismo general de copia de seguridad y restauración, sin nada entre ambos. La ruta que se deduce de esas dos piezas es: restaura la copia que hiciste antes del cambio o vuelve a establecer en la ranura el nombre exacto del proveedor y del modelo anteriores, para que la comparación del metarchivo vuelva a fallar en la otra dirección y se reconstruya. En el mismo contenedor, la caché local de embeddings bajo tmp/ está dividida por proveedor y modelo, de modo que volver a un modelo usado anteriormente puede reutilizar los vectores almacenados para texto sin cambios; pero tmp/ está fuera de la copia de seguridad documentada, por lo que ese guardado desaparece cuando se recrea el contenedor. Nunca reviertas eliminando los archivos del índice.
Comprobado el 21 de septiembre de 2026 contra agent0ai/agent-zero main — memory.py, model_config_set.py, models.py, los valores predeterminados del complemento de memoria y el árbol de documentación — además del artículo de lanzamiento de v2.12, la colección a0-presets, los dos issues enlazados y los precios publicados por OpenAI. Nada de esta página se ejecutó: las afirmaciones sobre el mecanismo están verificadas en la fuente, no probadas en ejecución, y Kunavo no tiene ningún registro de ejecución para Agent Zero. Las tarifas de tokens de Kunavo proceden del catálogo vigente.