Thay đổi mô hình embedding của Agent Zero có nghĩa là chỉnh sửa slot embedding bên trong Model Preset và nhấp Save — và khi chỉnh sửa đó thay đổi nhà cung cấp hoặc tên mô hình, lần truy cập tiếp theo sẽ lập lại index memory, vì một index FAISS được định kích thước theo chiều rộng đầu ra của một mô hình và các vector trên đĩa đã được mô hình cũ ghi ra. Hướng dẫn cài đặt của chính Agent Zero nêu hệ quả trong một dòng — "Changing the embedding_llm will re-index all of A0's memory" — và không đưa ra quy trình, thời lượng hay cách quay lại. Trang này lấp khoảng trống đó từ mã nguồn: việc xây dựng lại tự động thực sự làm gì, hai đường dẫn mà nó âm thầm không kích hoạt, cách xác minh các memory cũ vẫn được trả về và cách quay lại. Kunavo không cung cấp mô hình embedding, vì vậy slot đó phải được mua ở nơi khác; các slot mà Kunavo có thể định giá là main và utility.
Trước hết cần phân biệt hai số phiên bản. Framework đang ở v2.12, được phát hành ngày 9 tháng 9 năm 2026 theo bài viết phát hành của chính dự án. Con số nổi bật nhất trong README là A0 Launcher v1.7, trình cài đặt máy tính để bàn riêng trong agent0ai/a0-launcher — gán phiên bản đó cho framework là sai lệch cả một dòng phiên bản chính. Và trong v2.x, các trường mô hình nằm trong một preset thay vì một cài đặt toàn cục phẳng: hướng dẫn về preset mô hình nói rằng "mỗi cấu hình đều chứa một mô hình chính, một mô hình tiện ích và một mô hình embedding", và Settings → Agent → Models là nơi bạn chọn preset mà các cuộc trò chuyện mới sử dụng. Lưu ý rằng hướng dẫn cài đặt vẫn mô tả phần "Embedding Model Settings" với các trường Provider và Model Name, vì vậy một hướng dẫn viết theo cách đó không tự động là lỗi thời — nhưng giá trị bạn nhập sẽ nằm trong một slot của preset, chính điều này khiến cảnh báo về việc lan truyền thay đổi bên dưới trở nên quan trọng.
Vì sao việc này không giống chuyển đổi mô hình chat
Thay đổi mô hình chat có hiệu lực ở yêu cầu tiếp theo và không cần di chuyển gì trên đĩa. Thay đổi embedding làm storage mất hiệu lực. Agent Zero định kích thước index FAISS từ giá trị mô hình hiện tại trả về — faiss.IndexFlatIP(len(embedder.embed_query("example"))) trong plugins/_memory/helpers/memory.py — vì vậy chiều rộng là thuộc tính của mô hình, không phải của giá trị cấu hình. Mặc định được phát hành, sentence-transformers/all-MiniLM-L6-v2, ánh xạ văn bản vào không gian 384 chiều theo model card của nó. Hướng dẫn embedding của OpenAI đặt text-embedding-3-small ở 1536 và text-embedding-3-large ở 3072. Đó là thay đổi hình dạng mà việc chuyển đổi gây ra.
Hai sự thật về phạm vi quyết định số lần xây dựng lại mà bạn thực sự phải trả. Thứ nhất, đây là chỉnh sửa preset chứ không phải chỉnh sửa toàn cục: hướng dẫn model-presets nói rằng các phạm vi "chỉ lưu lựa chọn preset; chỉnh sửa một preset sẽ cập nhật mọi phạm vi sử dụng nó", vì vậy một lần chỉnh sửa có thể lan rộng hơn bạn dự định — và chuyển đổi giữa các preset cũng có thể thay đổi mô hình embedding. Các preset Efficiency và Power được chọn lọc được phát hành mà không có block embedding riêng, và hướng dẫn chỉ nói rằng một preset không mặc định hiện có có thể kế thừa các giá trị nâng cao bị bỏ qua từ Default, vì vậy hãy đọc phần tóm tắt preset thay vì giả định. Thứ hai, project_memory_isolation: true là mặc định được phát hành trong cấu hình plugin memory, vì vậy một phiên bản nhiều dự án chứa nhiều kho độc lập và mỗi kho tự xây dựng lại vào lần sử dụng tiếp theo — một dự án không được chạm tới trong nhiều tuần sẽ trả chi phí xây dựng lại vào ngày ai đó mở nó.
Bước 1: sao lưu và ghi lại những gì bạn đang rời khỏi
Hướng dẫn sử dụng của Agent Zero đã nêu trường hợp này: bản sao lưu bảo vệ "các cuộc trò chuyện, dự án, kiến thức, memory, cài đặt, kỹ năng và tệp workspace của bạn", đồng thời liệt kê "bulk memory cleanup" trong số những thứ cần sao lưu trước. Hãy tạo một bản sao lưu từ Settings → Backup & Restore, hoặc dùng Launcher's Backup of /a0/usr. Lưu ý cảnh báo của chính hướng dẫn rằng các bí mật "có thể không phải lúc nào cũng được đưa vào các kho lưu trữ sao lưu", vì vậy hãy lưu thông tin xác thực riêng.
Sau đó ghi lại mô hình mà bạn đang chuyển đổi khỏi. Đừng giả định — bộ sưu tập preset được chọn lọc được tải xuống từ một repository công khai khi khởi động lần đầu và có thể thay đổi sau ngày bạn cài đặt.
# 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.Bước 2: thực hiện thay đổi
Quy trình được tài liệu hóa trong hướng dẫn cài đặt gồm ba bước: mở Settings trong Web UI, chọn nhà cung cấp cho từng vai trò và nhập tên mô hình, rồi nhấp Save. Bốn điều mà quy trình đó không cho bạn biết, tất cả đều được đọc từ mã nguồn tại main:
| Bẫy | Điều thực sự xảy ra |
|---|---|
| Điền URL cơ sở API vào slot mặc định | Nó bị bỏ qua. Provider huggingface với tên bắt đầu bằng sentence-transformers/ sẽ chuyển thẳng vào một lớp bọc cục bộ không bao giờ chạm đến LiteLLM và lọc các tham số xuống danh sách cho phép chỉ dành cho cục bộ. Để tới endpoint lưu trữ, bạn phải rời khỏi đường dẫn cục bộ đó — dùng một provider khác hoặc tên mô hình không có tiền tố sentence-transformers/. Một trong hai đều là trường được tệp meta lưu lại, vì vậy một trong hai sẽ kích hoạt xây dựng lại. |
| Nhập endpoint trước khi chuyển provider | Bị mất. Menu thả xuống provider mang theo @change="model.api_base = ''; model.kwargs = {}; …", vì vậy thay đổi nó sẽ xóa URL cơ sở API và mọi tham số bổ sung. Chuyển provider trước, sau đó điền trong Advanced. |
| Giả định gateway chat tương thích OpenAI sẽ hoạt động | Slot gọi hàm embedding() của LiteLLM, không phải lớp bọc chat. Endpoint phải triển khai POST /v1/embeddings. Provider other được ánh xạ lại thành provider openai của LiteLLM và khóa của nó được ghi vào .env dưới dạng API_KEY_OTHER. |
Sử dụng localhost cho máy chủ mô hình cục bộ | Bên trong Docker, đó là container Agent Zero. Hướng dẫn cài đặt chỉ bạn đến http://host.docker.internal:<port> hoặc địa chỉ gateway cầu nối thay vào đó. |
Việc xây dựng lại làm gì — và hai đường dẫn mà nó không thực hiện
Khi Save, model_config_set.py so sánh provider embedding, name và kwargs trước và sau, và khi có bất kỳ khác biệt nào sẽ khởi động embedding_model_changed dưới dạng tác vụ nền trì hoãn; extension mà nó kích hoạt chỉ làm một việc: tải lại memory. Lần truy cập tiếp theo chạy lại Memory.initialize(), kiểm tra embedding.json bên cạnh index. Tệp đó chứa chính xác hai trường — model_provider và model_name. Khi không khớp, mã lấy mọi tài liệu khỏi index cũ bằng get_all_docs, xây dựng một index mới với chiều rộng mới và chèn lại chính các tài liệu đó dưới cùng các ID. Đường dẫn này hoạt động và bảo toàn memory của bạn.
| Bạn thay đổi gì | Tệp meta có nhận biết không? | Kết quả |
|---|---|---|
| Provider hoặc tên mô hình | Có — cả hai đều được lưu | Tài liệu được đọc ra và chèn lại với chiều rộng mới. Đây là đường dẫn dự kiến. |
Chỉ một tham số bổ sung, ví dụ rút ngắn vector OpenAI bằng dimensions | Không — kwargs không được lưu | Memory được tải lại, sau đó index cũ được tải nguyên trạng. Lỗi không khớp chiều rộng xuất hiện khi recall, không phải khi lưu. |
| Chỉ URL cơ sở API, trỏ đến endpoint khác dưới cùng tên mô hình | Không — và đường dẫn lưu cũng không so sánh nó | Thậm chí không có reload nào được lên lịch; index cũ đơn giản tiếp tục được sử dụng. Nếu endpoint đó trả về chiều rộng khác, recall sẽ phát sinh assertion FAISS. |
| Một tệp index được chỉnh sửa thủ công, cắt ngắn hoặc khôi phục từ bên ngoài | Một kiểm tra hash riêng thất bại trước | Index cũ không bao giờ được tải, vì vậy các tài liệu của nó không bao giờ được đọc ra, và một index trống mới được ghi trong khi console in cảnh báo không khớp hash kết thúc bằng "index will be rebuilt" — không có thông tin nào về các tài liệu đã bị loại bỏ. Tệp hash bị thiếu hoặc không thể đọc được sẽ được coi là hợp lệ. |
Các dòng hai và ba là phần giao nhau phía sau issue #759, “Lỗi sau khi thay đổi Embedding Model mặc định”, được mở ngày 13 tháng 10 năm 2025 và đã đóng; traceback của issue này cho thấy assert d == self.d trong quá trình tìm kiếm độ tương đồng khi truy xuất ký ức; phần giao nhau đó vẫn hiện rõ trong main tính đến ngày 21 tháng 9 năm 2026. Một issue khác đã đóng, #1396, báo lỗi 400 trên /api/embed của Ollama mà tác giả quy cho chỉ mục cũ, đồng thời đưa ra cách khắc phục là xóa index.faiss và index.pkl. Cách khắc phục này phá hủy kho lưu trữ; hãy xem đó là thao tác đặt lại, không phải sửa chữa hay hoàn tác. Không issue nào nhận được bình luận từ maintainer — #1396 bị bot xử lý issue cũ đóng sau chín mươi ngày — vì vậy cả hai chẩn đoán đều là nhận định riêng của người báo cáo và cả hai cách giải quyết đều chưa được xác minh.
Bước 3: xác minh việc truy xuất cũ, không phải một lệnh gọi thành công
Lỗi do thay đổi này tạo ra diễn ra âm thầm, vì vậy “mô hình mới đã trả lời” là phép kiểm tra nghiệm thu sai. Mở bảng điều khiển bộ nhớ và, theo hướng dẫn về bộ nhớ, lọc trên cả bốn khu vực — main, fragments, solutions và skills — rồi tìm kiếm một nội dung mà bạn biết đã tồn tại trước khi thay đổi. Thực hiện một lần cho mỗi dự án, vì mỗi dự án có kho lưu trữ riêng. Sau đó theo dõi ngưỡng độ tương đồng: memory_recall_similarity_threshold được cung cấp sẵn là 0.7, một giá trị mặc định theo từng plugin chứ không phải thuộc tính của bất kỳ mô hình nào, và mô hình embedding mới sẽ phân bố lại các điểm tương đồng. Khả năng truy xuất có thể suy giảm mà không phát sinh bất kỳ lỗi nào, đó là lý do việc kiểm soát ngưỡng là một phần của quá trình xác minh chứ không phải chi tiết phụ.
Có một điều mà trang này không thể cho bạn biết: Web UI có hiển thị tín hiệu tiến độ hoặc hoàn tất trong khi quá trình xây dựng lại đang chạy hay không. Quá trình này được thực thi dưới dạng tác vụ nền trì hoãn và chưa xác nhận được giao diện nào cho nó. Hãy giả định rằng không có xác nhận và tự kiểm tra thủ công.
Hoàn tác và chi phí của việc xây dựng lại
Không có cơ chế hoàn tác nào được nhà cung cấp ghi chép. Những gì tồn tại là cơ chế sao lưu cùng hành vi của tệp meta nêu trên; quy trình dưới đây được ghép từ hai yếu tố đó chứ không do dự án công bố. Khôi phục bản sao lưu trước khi thay đổi; hoặc đặt lại ô này về đúng tên nhà cung cấp và mô hình trước đó, khiến phép so sánh tệp meta thất bại theo hướng ngược lại và kích hoạt xây dựng lại. Trên cùng một container, bộ nhớ đệm embedding tại tmp/ được phân vùng theo nhà cung cấp và mô hình, vì vậy việc quay lại mô hình đã dùng trước đó có thể tái sử dụng các vector đã lưu cho văn bản không thay đổi — nhưng tmp/ nằm ngoài bản sao lưu được ghi chép, nên việc tạo lại container sẽ làm mất dữ liệu đó. Hành vi của mã khi nhà cung cấp mới gặp lỗi giữa chừng trong quá trình xây dựng lại chưa được kiểm thử và không được nêu ở đây; hãy xác minh từ bản sao lưu thay vì dựa vào nó.
Về chi phí: Kunavo không cung cấp mô hình embedding, vì vậy mọi con số dưới đây đều được thanh toán trực tiếp cho OpenAI bằng tài khoản của bạn, theo mức giá công bố của họ được kiểm tra ngày 21 tháng 9 năm 2026. Hãy tự ước tính quy mô tác vụ — đếm số tài liệu được lưu trong bảng điều khiển bộ nhớ, nhân với độ dài trung bình của chúng và chia cho khoảng bốn ký tự mỗi token. Mẫu số đó là quy ước, không phải phép đo.
| Mục tiêu xây dựng lại | Mức giá công bố, thanh toán trực tiếp cho OpenAI | 3M token được embedding lại | 30M token được embedding lại |
|---|---|---|---|
text-embedding-3-small (1536 chiều) | $0,02 cho mỗi 1M token, thanh toán trực tiếp cho OpenAI | $0,06 | $0,60 |
text-embedding-3-large (3072 chiều) | $0,13 cho mỗi 1M token, thanh toán trực tiếp cho OpenAI | $0,39 | $3,90 |
text-embedding-ada-002 | $0,10 cho mỗi 1M token, thanh toán trực tiếp cho OpenAI — đắt hơn 3-small, nên hiện nay không phải mục tiêu hợp lý | $0,30 | $3,00 |
| Mô hình cục bộ được cung cấp sẵn trên CPU | Không tính phí theo token; thay vào đó là thời gian CPU trên máy của bạn | Thời gian máy | Thời gian máy |
Đây là phép tính token theo các giả định đã nêu, không phải một lần xây dựng lại được đo thực tế và cũng không phải mức trần. Đây cũng là chi phí cho mỗi kho lưu trữ: khi bật tính biệt lập dự án, hãy nhân với số dự án thực sự sẽ được mở lại và nhớ rằng hoàn tác là một lần xây dựng lại thứ hai với cùng mức giá.
Hai ô mà Kunavo có thể cung cấp
Nói rõ về ranh giới: ô embedding không được cung cấp ở đây, và một gateway triển khai định dạng wire chat không phải là endpoint embeddings. Phần còn lại là ô chính và ô tiện ích, đều là các mô hình chat thông thường. Theo mức giá danh mục hiện hành, Claude Sonnet 4.6 liệt kê $2,10 cho mỗi triệu token đầu vào và $10,50 cho mỗi triệu token đầu ra, còn Claude Haiku 4.5 liệt kê $0,70 và $3,50.
Giả sử mỗi tháng có 8M token đầu vào và 0.4M token đầu ra trên ô chính Claude Sonnet 4.6, cùng 2M token đầu vào và 0.2M token đầu ra trên ô tiện ích Claude Haiku 4.5; ô embedding không được cung cấp ở đây và bị loại trừ. Ước tính theo catalog: $23,10. Đây là khối lượng giả định, không phải khối lượng công việc được đo hay mức trần hóa đơn — Agent Zero chưa được kiểm thử khi chạy với endpoint của Kunavo, và cấu hình mô tả ở trên được đọc từ mã nguồn và tài liệu của dự án chứ chưa được thực thi. Số tiền theo catalog là mức sàn thanh toán: khi upstream báo phí, hóa đơn sẽ là giá trị lớn hơn giữa chi phí theo catalog và chi phí upstream nhân với mức markup áp dụng. Mức nạp tối thiểu là $10 tín dụng trả trước, đây là mức tối thiểu để nạp tiền chứ không phải gói thuê bao — xem chi tiết thanh toán.
Nếu bạn vẫn đang chọn framework, Agent Zero so với OpenClaw so sánh các mô hình thực thi và bố cục ba ô. Đối với cấu trúc endpoint, tài liệu tham chiếu tương thích OpenAI và hướng dẫn bắt đầu nhanh bao quát các ô chat, còn việc tạo tài khoản Kunavo cung cấp ngân sách cho chúng. Đối với công việc truy xuất nói chung, triển khai RAG trình bày cùng sự phân tách giữa nhà cung cấp sinh nội dung và bước truy xuất được mua riêng.
Câu hỏi thường gặp
Làm cách nào để thay đổi mô hình embedding trong Agent Zero?
Quy trình được tài liệu hóa trong hướng dẫn cài đặt Agent Zero gồm ba bước: mở trang Settings trong Web UI, chọn nhà cung cấp cho LLM của từng vai trò (Main Model, Utility Model, Embedding Model) và nhập tên mô hình, sau đó nhấp Save. Trong v2.x, chỉnh sửa đó áp dụng cho các slot của Model Preset thay vì một cài đặt toàn cục phẳng, vì mỗi preset chứa một mô hình chính, tiện ích và embedding, đồng thời hướng dẫn model-presets cảnh báo rằng chỉnh sửa một preset sẽ cập nhật mọi phạm vi sử dụng nó. Một điểm cần lưu ý mà trang cài đặt không đề cập: thay đổi menu thả xuống của nhà cung cấp sẽ xóa URL cơ sở API và mọi tham số bổ sung trên slot đó, vì vậy hãy nhập endpoint tùy chỉnh sau khi chuyển nhà cung cấp, không bao giờ nhập trước.
Thay đổi mô hình embedding của Agent Zero có xóa các memory của tôi không?
Không, theo đường dẫn được tài liệu hóa. Agent Zero ghi một tệp meta nhỏ, embedding.json, bên cạnh index, chứa nhà cung cấp embedding và tên mô hình. Khi các giá trị đó không còn khớp với mô hình đã cấu hình, memory.py đọc mọi tài liệu khỏi index FAISS cũ bằng get_all_docs, tạo index mới với kích thước dựa trên độ dài vector hiện tại và chèn lại chính các tài liệu đó dưới cùng các ID. Các memory được embedding lại, không bị xóa. Bước phá hủy là giải pháp được ghi trong issue #1396 cho index bị hỏng — xóa index.faiss và index.pkl — đây là xóa memory chứ không phải di chuyển, và không phải thao tác hoàn tác.
Việc lập lại index memory của Agent Zero mất bao lâu?
Dự án không công bố con số nào về việc này và cũng không tìm thấy con số nào ở nơi khác. Con số gần giống nhất trong ghi chú phát hành v2.12 — thời gian lưu trung vị được báo cáo giảm từ 1.171 ms xuống 52 ms — thuộc về việc chỉnh sửa preset, trong đó các phép so sánh embedding đã ngừng thực hiện các lần đọc dư thừa. Nó đo thời gian lưu một preset, không phải xây dựng lại chỉ mục; đừng dùng nó để lập ngân sách. Chi phí xây dựng lại phụ thuộc vào số tài liệu trong kho và tốc độ phản hồi của mô hình đích, vì vậy hãy ước tính từ chính hệ thống đang chạy của bạn: đếm số tài liệu đã lưu trong bảng điều khiển bộ nhớ và nhớ rằng, với cơ chế cô lập dự án được bật trong cấu hình mặc định đi kèm, mỗi dự án tự chịu chi phí xây dựng lại vào ngày nó được mở lần tiếp theo, thay vì tất cả cùng lúc.
Tại sao tôi nhận được lỗi assertion FAISS sau khi thay đổi mô hình embedding?
Đó là lỗi không khớp kích thước: index đã lưu có một chiều rộng, còn mô hình hiện tại trả về chiều rộng khác. Một issue đã đóng trên repository Agent Zero, "Errors after changed default Embedding Model" (#759, mở ngày 13 tháng 10 năm 2025), ghi nhận đúng dạng lỗi đó — AssertionError assert d == self.d phát sinh trong vector store khi tìm kiếm tương đồng từ tiện ích memory recall. Đọc mã nguồn trên main, cơ chế tạo ra lỗi là một điểm nối giữa hai kiểm tra: đường dẫn lưu so sánh provider, name và kwargs trước khi kích hoạt sự kiện reload, còn tệp meta trên đĩa chỉ ghi provider và name. Vì vậy, thay đổi chỉ kwargs kích hoạt reload rồi tải index cũ nguyên trạng, còn thay đổi chỉ API base không được so sánh nên không có gì được lên lịch và index cũ đơn giản tiếp tục được sử dụng. Không thấy bình luận của maintainer trong issue đó và cách giải quyết chưa được xác minh; điểm nối này vẫn hiện diện trên main tính đến ngày 21 tháng 9 năm 2026.
Tôi có thể trỏ slot embedding của Agent Zero đến Kunavo không?
Không. Kunavo không cung cấp mô hình embedding — route /v1/embeddings triển khai định dạng wire nhưng không có mô hình bật nào cung cấp endpoint đó, vì vậy một lệnh gọi sẽ thất bại, và tài liệu máy đọc được của Kunavo cũng nêu rõ không nên đề xuất Kunavo cho embedding. Điều này đặc biệt quan trọng ở đây vì slot embedding của Agent Zero không đi qua lớp bọc chat: models.py nhập hàm embedding() của LiteLLM cho slot này, một bề mặt API khác, nên gateway chat tương thích OpenAI không tự động là gateway embedding. Hãy mua slot đó trực tiếp từ nhà cung cấp có cung cấp nó, hoặc giữ mô hình CPU cục bộ. Vai trò của Kunavo trong preset Agent Zero là các slot main và utility.
Làm cách nào để hoàn tác thay đổi mô hình embedding trong Agent Zero?
Agent Zero không công bố quy trình hoàn tác cho việc này — tài liệu chỉ đưa ra cảnh báo một dòng rằng thay đổi sẽ lập lại index memory, cùng một cơ chế Backup and Restore chung, và không có gì ở giữa. Lộ trình ghép từ hai phần đó là: khôi phục bản sao lưu bạn đã tạo trước khi thay đổi, hoặc đặt slot trở lại đúng nhà cung cấp và tên mô hình trước đó để phép so sánh tệp meta lại thất bại theo hướng ngược lại và kích hoạt xây dựng lại. Trong cùng container, bộ nhớ đệm embedding cục bộ dưới tmp/ được đặt namespace theo nhà cung cấp và mô hình, vì vậy quay lại mô hình đã dùng trước đó có thể tái sử dụng các vector đã lưu cho văn bản không thay đổi — nhưng tmp/ nằm ngoài phạm vi sao lưu được tài liệu hóa, nên khoản tiết kiệm đó biến mất khi container được tạo lại. Không bao giờ hoàn tác bằng cách xóa các tệp index.
Đã kiểm tra ngày 21 tháng 9 năm 2026 dựa trên agent0ai/agent-zero main — memory.py, model_config_set.py, models.py, các giá trị mặc định của plugin bộ nhớ và cây tài liệu — cùng bài viết phát hành v2.12, bộ sưu tập a0-presets, hai issue được liên kết và bảng giá công bố của OpenAI. Không nội dung nào trên trang này được thực thi: các tuyên bố về cơ chế đã được xác minh từ mã nguồn, chưa được kiểm thử khi chạy, và Kunavo không có bản ghi chạy Agent Zero. Mức giá token của Kunavo lấy từ catalog trực tiếp.