Mengubah model embedding Agent Zero berarti mengedit slot embedding di dalam Model Preset lalu mengeklik Save — dan ketika pengeditan tersebut mengubah provider atau nama model, akses berikutnya akan mengindeks ulang memori, karena indeks FAISS berukuran sesuai lebar output satu model dan vektor yang sudah ada di disk ditulis oleh model lama. Panduan instalasi Agent Zero sendiri menyatakan konsekuensinya dalam satu baris — "Changing the embedding_llm will re-index all of A0's memory" — dan tidak memberikan prosedur, durasi, maupun cara untuk kembali. Halaman ini mengisi celah tersebut dari sumbernya: apa yang sebenarnya dilakukan pembangunan ulang otomatis, dua jalur yang membuatnya tidak terpicu secara diam-diam, cara memverifikasi bahwa memori lama masih dapat ditemukan, dan cara untuk kembali. Kunavo tidak menyediakan model embedding, jadi slot tersebut dibeli di tempat lain; slot yang dapat diberi harga oleh Kunavo adalah slot utama dan utilitas.
Dua nomor versi perlu dibedakan terlebih dahulu. Framework ini berada di v2.12, diterbitkan pada 9 September 2026 menurut artikel rilis milik proyek. Nomor yang paling menonjol dalam README adalah A0 Launcher v1.7, yaitu installer desktop terpisah di agent0ai/a0-launcher — mengaitkannya dengan framework berarti salah satu major line penuh. Dan dalam v2.x, kolom model berada pada preset, bukan pengaturan global datar: panduan model-presets menyatakan bahwa "setiap setup berisi model utama, utilitas, dan embedding", dan Settings → Agent → Models adalah tempat Anda memilih preset yang digunakan chat baru. Perhatikan bahwa panduan instalasi masih mendokumentasikan bagian "Embedding Model Settings" dengan kolom Provider dan Model Name, sehingga panduan yang ditulis dengan cara tersebut tidak otomatis kedaluwarsa — tetapi nilai yang Anda ketik diterapkan pada slot preset, dan itulah yang membuat peringatan propagasi di bawah ini penting.
Mengapa ini berbeda dari mengganti model chat
Perubahan model chat berlaku pada permintaan berikutnya dan tidak ada apa pun di disk yang perlu dipindahkan. Perubahan embedding membatalkan validitas penyimpanan. Agent Zero mengukur indeks FAISS dari apa pun yang dikembalikan model aktif — faiss.IndexFlatIP(len(embedder.embed_query("example"))) di plugins/_memory/helpers/memory.py — sehingga lebar merupakan properti model, bukan nilai konfigurasi. Default yang dikirimkan, sentence-transformers/all-MiniLM-L6-v2, memetakan teks ke ruang 384 dimensi menurut kartu modelnya. Panduan embedding OpenAI menetapkan text-embedding-3-small pada 1536 dan text-embedding-3-large pada 3072. Itulah perubahan bentuk yang ditimbulkan oleh pergantian model.
Dua fakta tentang scope menentukan berapa banyak pembangunan ulang yang sebenarnya Anda beli. Pertama, ini adalah pengeditan preset, bukan pengeditan global: panduan model-presets menyatakan bahwa scope "hanya menyimpan pilihan preset; mengedit preset akan memperbarui setiap scope yang menggunakannya", sehingga satu pengeditan dapat menyebar lebih jauh dari yang Anda maksud — dan berpindah antar-preset juga dapat mengubah model embedding. Preset Efficiency dan Power terkurasi dikirimkan tanpa blok embedding sendiri, dan panduan hanya menyatakan bahwa preset non-default yang sudah ada mungkin mewarisi nilai lanjutan yang dihilangkan dari Default, jadi baca ringkasan preset, jangan berasumsi. Kedua, project_memory_isolation: true adalah default yang dikirimkan dalam konfigurasi plugin memori, sehingga instance dengan banyak proyek memiliki beberapa penyimpanan independen dan masing-masing melakukan pembangunan ulang pada penggunaan berikutnya — proyek yang tidak disentuh selama berminggu-minggu membayar pembangunan ulangnya pada hari seseorang membukanya.
Langkah 1: buat backup, dan catat apa yang Anda tinggalkan
Panduan penggunaan Agent Zero sudah menyebut kasus ini: backup melindungi "chat, proyek, pengetahuan, memori, pengaturan, skill, dan file workspace Anda", dan mencantumkan "pembersihan memori massal" sebagai salah satu hal yang perlu dibackup sebelumnya. Buat backup dari Settings → Backup & Restore, atau gunakan Backup Launcher atas /a0/usr. Perhatikan catatan panduan sendiri bahwa rahasia "mungkin tidak selalu disertakan dalam arsip backup", jadi simpan kredensial secara terpisah.
Kemudian catat model yang Anda migrasikan. Jangan berasumsi — koleksi preset terkurasi diunduh dari repositori publik saat pertama kali dijalankan dan dapat berubah setelah tanggal instalasi Anda.
# 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.Langkah 2: lakukan perubahan
Alur yang didokumentasikan dalam panduan instalasi terdiri dari tiga langkah: buka Settings di Web UI, pilih provider untuk setiap peran dan tulis nama modelnya, lalu klik Save. Empat hal yang tidak diberitahukan alur tersebut kepada Anda, semuanya dibaca dari sumber di main:
| Jebakan | Apa yang sebenarnya terjadi |
|---|---|
| Mengisi API base URL pada slot default | Diabaikan. Provider huggingface dengan nama yang diawali sentence-transformers/ langsung masuk ke wrapper lokal yang tidak pernah menyentuh LiteLLM dan menyaring parameter menjadi daftar izin khusus lokal. Untuk mencapai endpoint ter-host, Anda harus meninggalkan jalur lokal tersebut — gunakan provider berbeda, atau nama model tanpa prefiks sentence-transformers/. Keduanya merupakan kolom yang disimpan file meta, sehingga keduanya memicu pembangunan ulang. |
| Memasukkan endpoint sebelum mengganti provider | Hilang. Dropdown provider membawa @change="model.api_base = ''; model.kwargs = {}; …", sehingga pengubahannya menghapus API base URL dan setiap parameter tambahan. Ganti provider terlebih dahulu, lalu isi Advanced. |
| Mengasumsikan gateway chat yang kompatibel dengan OpenAI akan berfungsi | Slot tersebut memanggil fungsi embedding() milik LiteLLM, bukan chat wrapper. Endpoint harus menerapkan POST /v1/embeddings. Provider other dipetakan ulang ke provider openai milik LiteLLM, dan kuncinya ditulis ke .env sebagai API_KEY_OTHER. |
Menggunakan localhost untuk server model lokal | Di dalam Docker, itu berarti container Agent Zero. Panduan instalasi mengarahkan Anda ke http://host.docker.internal:<port> atau alamat gateway bridge sebagai gantinya. |
Apa yang dilakukan pembangunan ulang — dan dua jalur yang tidak memicunya
Saat Save, model_config_set.py membandingkan provider embedding, nama dan kwargs sebelumnya dan yang baru, lalu pada setiap perbedaan memulai embedding_model_changed sebagai tugas latar belakang yang ditunda; ekstensi yang dipicunya hanya melakukan satu hal, yaitu memuat ulang memori. Akses berikutnya menjalankan kembali Memory.initialize(), yang memeriksa embedding.json di samping indeks. File tersebut hanya menyimpan dua bidang — model_provider dan model_name. Jika terjadi ketidakcocokan, kode mengambil setiap dokumen dari indeks lama dengan get_all_docs, membuat indeks baru dengan lebar baru, lalu memasukkan kembali dokumen yang sama dengan id yang sama. Jalur tersebut berfungsi dan mempertahankan memori Anda.
| Apa yang Anda ubah | Apakah file meta mengetahuinya? | Hasil |
|---|---|---|
| Provider atau nama model | Ya — keduanya disimpan | Dokumen dibaca dan dimasukkan kembali dengan lebar baru. Jalur yang dimaksudkan. |
Hanya parameter tambahan, misalnya memendekkan vektor OpenAI dengan dimensions | Tidak — kwargs tidak disimpan | Memori dimuat ulang, lalu indeks lama dimuat tanpa perubahan. Ketidakcocokan lebar muncul saat recall, bukan saat penyimpanan. |
| Hanya API base URL, dengan mengarahkan ke endpoint berbeda di bawah nama model yang sama | Tidak — dan jalur penyimpanan juga tidak membandingkannya | Bahkan tidak ada reload yang dijadwalkan; indeks lama tetap digunakan. Jika endpoint tersebut menjawab dengan lebar berbeda, recall memunculkan assertion FAISS. |
| File indeks yang diedit manual, terpotong, atau dipulihkan dari luar | Pemeriksaan hash terpisah gagal terlebih dahulu | Indeks lama tidak pernah dimuat, sehingga dokumennya tidak pernah dibaca, dan indeks kosong baru ditulis sementara konsol mencetak peringatan ketidakcocokan hash yang diakhiri dengan "index will be rebuilt" — tidak ada keterangan mengenai dokumen yang dibuang. File hash yang hilang atau tidak dapat dibaca dianggap valid. |
Baris dua dan tiga adalah celah di balik issue #759, "Errors after changed default Embedding Model", yang dibuka pada 13 Oktober 2025 dan telah ditutup, dengan traceback yang menunjukkan assert d == self.d selama pencarian kemiripan dari memory recall; celah tersebut masih terlihat di main per 21 September 2026. Issue tertutup kedua, #1396, melaporkan status 400 pada /api/embed milik Ollama yang menurut penulisnya disebabkan indeks lama, dan memberikan solusi berupa penghapusan index.faiss dan index.pkl. Solusi tersebut menghancurkan penyimpanan; perlakukan sebagai reset, bukan perbaikan atau rollback. Tidak ada issue yang mendapat komentar maintainer — #1396 ditutup oleh bot issue-kedaluwarsa setelah sembilan puluh hari — sehingga kedua diagnosis tersebut merupakan pendapat pelapor sendiri dan kedua resolusinya belum terverifikasi.
Langkah 3: verifikasi recall lama, bukan pemanggilan yang berhasil
Kegagalan yang dihasilkan perubahan ini berlangsung diam-diam, sehingga "model baru memberikan jawaban" adalah uji penerimaan yang keliru. Buka dasbor memori dan, menurut panduan memori, filter di keempat area — main, fragments, solutions dan skills — lalu cari sesuatu yang Anda tahu sudah ada sebelum perubahan. Lakukan sekali untuk setiap proyek, karena setiap proyek memiliki penyimpanannya sendiri. Kemudian perhatikan ambang kemiripan: memory_recall_similarity_threshold yang dikirimkan adalah 0.7, default per-plugin, bukan properti model mana pun, dan model embedding baru mendistribusikan ulang skor kemiripan. Recall dapat menurun tanpa satu pun kesalahan muncul, sehingga kontrol ambang adalah bagian dari verifikasi, bukan detail.
Satu hal yang tidak dapat diberitahukan halaman ini: apakah Web UI menampilkan sinyal kemajuan atau penyelesaian saat pembangunan ulang berlangsung. Proses tersebut dijalankan sebagai tugas latar belakang yang ditunda, dan tidak ada permukaan untuknya yang berhasil dikonfirmasi. Anggap tidak ada konfirmasi dan lakukan verifikasi secara manual.
Rollback, dan biaya pembangunan ulang
Tidak ada rollback yang didokumentasikan vendor. Yang tersedia adalah mekanisme backup ditambah perilaku file meta di atas, dan jalur di bawah ini dirangkai dari keduanya, bukan diterbitkan oleh proyek. Pulihkan backup sebelum perubahan; atau kembalikan slot ke provider dan nama model sebelumnya secara persis, yang membuat perbandingan file meta gagal ke arah sebaliknya dan memicu pembangunan ulang. Pada container yang sama, cache embedding di bawah tmp/ diberi namespace berdasarkan provider dan model, sehingga kembali ke model yang pernah digunakan dapat memakai ulang vektor yang di-cache untuk teks yang tidak berubah — tetapi tmp/ berada di luar backup yang didokumentasikan, sehingga pembuatan ulang container akan menghilangkannya. Apa yang dilakukan kode jika provider baru mengalami kesalahan di tengah pembangunan ulang tidak diuji dan tidak dinyatakan di sini; verifikasi dari backup, jangan mengandalkannya.
Mengenai biaya: Kunavo tidak menyediakan model embedding, sehingga setiap angka di bawah ini dibayarkan langsung kepada OpenAI dari akun Anda sendiri, dengan tarif yang diterbitkannya dan diperiksa pada 21 September 2026. Ukur sendiri pekerjaannya — hitung dokumen yang tersimpan di dasbor memori, kalikan dengan panjang rata-ratanya, lalu bagi dengan kira-kira empat karakter per token. Pembagi tersebut adalah konvensi, bukan pengukuran.
| Target pembangunan ulang | Tarif yang diterbitkan, ditagihkan langsung kepada OpenAI | 3M token dibuatkan embedding ulang | 30M token dibuatkan embedding ulang |
|---|---|---|---|
text-embedding-3-small (1536 dimensi) | $0,02 per 1M token, ditagihkan langsung kepada OpenAI | $0,06 | $0,60 |
text-embedding-3-large (3072 dimensi) | $0,13 per 1M token, ditagihkan langsung kepada OpenAI | $0,39 | $3,90 |
text-embedding-ada-002 | $0,10 per 1M token, ditagihkan langsung kepada OpenAI — lebih mahal daripada 3-small, sehingga bukan target yang masuk akal saat ini | $0,30 | $3,00 |
| Model lokal yang dikirimkan pada CPU | Tidak ada biaya per token; sebagai gantinya, waktu CPU pada mesin Anda sendiri | Waktu mesin | Waktu mesin |
Ini adalah perhitungan token berdasarkan asumsi yang dinyatakan, bukan pembangunan ulang yang diukur dan bukan batas maksimum. Ini juga berlaku per penyimpanan: dengan isolasi proyek aktif, kalikan dengan jumlah proyek yang benar-benar akan dibuka kembali, dan ingat bahwa rollback adalah pembangunan ulang kedua dengan tarif yang sama.
Dua slot yang dapat dilayani Kunavo
Agar batasnya jelas: slot embedding tidak dilayani di sini, dan gateway yang menerapkan format wire chat bukan endpoint embedding. Yang tersisa adalah slot utama dan utilitas, yaitu model chat biasa. Dengan tarif katalog aktif, Claude Sonnet 4.6 mencantumkan $2,10 per satu juta token input dan $10,50 per satu juta token output, sedangkan Claude Haiku 4.5 mencantumkan $0,70 dan $3,50.
Anggap satu bulan dengan 8M token input dan 0.4M token output pada slot utama Claude Sonnet 4.6, ditambah 2M token input dan 0.2M token output pada slot utilitas Claude Haiku 4.5; slot embedding tidak dilayani di sini dan dikecualikan. Perkiraan katalog: $23,10. Itu adalah volume asumsi, bukan beban kerja yang diukur atau batas maksimum tagihan — Agent Zero belum diuji saat runtime terhadap endpoint Kunavo, dan penyiapan yang dijelaskan di atas dibaca dari sumber serta dokumentasi proyek, bukan dijalankan. Jumlah katalog adalah batas bawah penagihan: ketika upstream melaporkan biayanya, tagihan adalah nilai yang lebih besar antara biaya katalog dan biaya upstream dikalikan markup yang berlaku. Top-up minimum adalah kredit prabayar $10, yang merupakan minimum pendanaan, bukan langganan — lihat detail penagihan.
Jika Anda masih memilih framework, Agent Zero vs OpenClaw membandingkan model eksekusi dan tata letak tiga slot. Untuk bentuk endpoint itu sendiri, referensi yang kompatibel dengan OpenAI dan panduan memulai cepat mencakup slot chat, dan pembuatan akun Kunavo mendanainya. Untuk pekerjaan retrieval secara umum, implementasi RAG membahas pemisahan yang sama antara provider generasi dan langkah retrieval yang dibeli secara terpisah.
Pertanyaan umum
Bagaimana cara mengubah model embedding di Agent Zero?
Alur yang didokumentasikan dalam panduan instalasi Agent Zero terdiri dari tiga langkah: buka halaman Settings di Web UI, pilih provider untuk LLM pada setiap peran (Main Model, Utility Model, Embedding Model) dan tulis nama modelnya, lalu klik Save. Dalam v2.x, perubahan tersebut diterapkan pada slot Model Preset, bukan pada pengaturan global datar, karena setiap preset berisi model utama, utilitas, dan embedding, dan panduan model-presets memperingatkan bahwa mengedit preset akan memperbarui setiap scope yang menggunakannya. Satu hal yang tidak disebutkan halaman instalasi: mengubah dropdown provider akan menghapus API base URL dan setiap parameter tambahan pada slot tersebut, jadi masukkan endpoint kustom setelah mengganti provider, jangan sebelumnya.
Apakah mengubah model embedding Agent Zero menghapus memori saya?
Tidak melalui jalur yang didokumentasikan. Agent Zero menulis file meta kecil, embedding.json, di samping indeks, yang menyimpan provider embedding dan nama model. Ketika keduanya tidak lagi cocok dengan model yang dikonfigurasi, memory.py membaca setiap dokumen dari indeks FAISS lama dengan get_all_docs, membuat indeks baru berukuran sesuai panjang vektor aktif, lalu memasukkan kembali dokumen yang sama dengan id yang sama. Memori dibuatkan embedding ulang, bukan dihapus. Langkah destruktifnya adalah solusi yang ditulis dalam issue #1396 untuk indeks yang rusak — menghapus index.faiss dan index.pkl — yang merupakan penghapusan memori, bukan migrasi, dan bukan rollback.
Berapa lama reindeks memori Agent Zero berlangsung?
Proyek ini tidak menerbitkan angkanya, dan tidak ditemukan angka tersebut di tempat lain. Angka yang paling mirip dalam catatan rilis v2.12 — median waktu penyimpanan yang dilaporkan turun dari 1.171 ms menjadi 52 ms — berkaitan dengan pengeditan preset, ketika perbandingan embedding berhenti melakukan pembacaan redundan. Angka itu mengukur penyimpanan preset, bukan pembangunan ulang indeks; jangan gunakan untuk membuat anggaran. Biaya pembangunan ulang bergantung pada jumlah dokumen dalam penyimpanan Anda dan kecepatan model target dalam merespons, jadi ukur dari instance Anda sendiri: hitung dokumen tersimpan di dasbor memori, dan ingat bahwa dengan isolasi proyek pada default yang dikirimkan, setiap proyek membayar pembangunan ulangnya sendiri pada hari proyek tersebut dibuka berikutnya, bukan semuanya sekaligus.
Mengapa saya mendapatkan kesalahan assertion FAISS setelah mengubah model embedding?
Ketidakcocokan dimensi: indeks tersimpan memiliki lebar tertentu dan model aktif mengembalikan lebar lain. Issue yang telah ditutup di repositori Agent Zero, "Errors after changed default Embedding Model" (#759, dibuka 13 Oktober 2025), mencatat bentuk kesalahan yang persis sama — AssertionError assert d == self.d yang muncul di vector store selama pencarian kemiripan dari ekstensi memory recall. Dari pembacaan sumber pada main, mekanismenya muncul dari celah antara dua pemeriksaan: jalur penyimpanan membandingkan provider, nama, dan kwargs sebelum memicu event reload, sedangkan file meta di disk hanya mencatat provider dan nama. Jadi perubahan yang hanya menyentuh kwargs memicu reload lalu memuat indeks lama tanpa perubahan, sementara perubahan yang hanya menyentuh API base tidak dibandingkan sama sekali, sehingga tidak ada yang dijadwalkan dan indeks lama tetap digunakan. Tidak terlihat komentar maintainer dalam issue tersebut dan resolusinya belum terverifikasi; celah ini masih terlihat di main per 21 September 2026.
Bisakah saya mengarahkan slot embedding Agent Zero ke Kunavo?
Tidak. Kunavo tidak menyediakan model embedding — rute /v1/embeddings menerapkan format wire tetapi tidak ada model aktif yang membawa endpoint tersebut, sehingga pemanggilan gagal, dan dokumentasi machine-readable Kunavo sendiri menyatakan agar tidak merekomendasikannya untuk embedding. Hal ini lebih penting dari biasanya karena slot embedding Agent Zero tidak melalui chat wrapper: models.py mengimpor fungsi embedding() milik LiteLLM untuk slot tersebut, yang merupakan permukaan API berbeda, sehingga gateway chat yang kompatibel dengan OpenAI tidak otomatis menjadi gateway embedding. Beli slot tersebut langsung dari provider yang menyediakannya, atau tetap gunakan model CPU lokal. Peran Kunavo dalam preset Agent Zero adalah slot utama dan utilitas.
Bagaimana cara melakukan rollback perubahan model embedding di Agent Zero?
Agent Zero tidak menerbitkan prosedur rollback untuk hal ini — dokumentasinya hanya menawarkan peringatan satu baris bahwa perubahan akan mengindeks ulang memori, serta mekanisme Backup and Restore umum, tanpa apa pun di antaranya. Jalur yang dirangkai dari keduanya adalah: pulihkan backup yang Anda buat sebelum perubahan, atau kembalikan slot ke provider dan nama model sebelumnya secara persis agar perbandingan file meta kembali gagal ke arah sebaliknya dan memicu pembangunan ulang. Pada container yang sama, cache embedding lokal di bawah tmp/ diberi namespace berdasarkan provider dan model, sehingga kembali ke model yang pernah digunakan dapat memakai ulang vektor yang di-cache untuk teks yang tidak berubah — tetapi tmp/ berada di luar backup yang didokumentasikan, sehingga penyimpanan itu hilang ketika container dibuat ulang. Jangan pernah melakukan rollback dengan menghapus file indeks.
Diperiksa pada 21 September 2026 berdasarkan agent0ai/agent-zero main — memory.py, model_config_set.py, models.py, default plugin memori, dan pohon dokumentasi — serta artikel rilis v2.12, koleksi a0-presets, dua issue tertaut, dan harga yang dipublikasikan OpenAI. Tidak ada bagian halaman ini yang dijalankan: klaim mekanisme diverifikasi dari sumber, bukan diuji saat runtime, dan Kunavo tidak memiliki catatan eksekusi untuk Agent Zero. Tarif token Kunavo berasal dari katalog aktif.