Lỗi mô hình LiteLLM của Agent Zero: xác thực, ID mô hình và điểm cuối

Lỗi model LiteLLM của Agent Zero thường là vấn đề prefix hoặc vai trò hơn là vấn đề key, vì Agent Zero không bao giờ gửi đúng model name bạn đã nhập. Trên nhánh main của agent0ai/agent-zero, models.py xây dựng f"{provider}/{model}" trước mỗi lệnh gọi LiteLLM — dòng 385 cho chat, dòng 800 cho embedding — và phần provider lấy từ conf/model_providers.yaml, không phải nhãn trong menu dropdown.

Hai thông tin về phiên bản quyết định cách hiểu phần còn lại. Bản phát hành mới nhất là v2.12, công bố ngày 9 tháng 9 năm 2026, còn đường dẫn cũ frdel/agent-zero hiện trỏ đến agent0ai/agent-zero, nên các lệnh clone và liên kết issue cũ sẽ gặp chuyển hướng. Và requirements.txt ghim litellm==1.88.1, kèm chú thích # CVE-2026-42271 fix: patched floor is 1.83.7. PyPI ghi nhận bản này ngày 9 tháng 6 năm 2026, trong khi 1.102.0 hiện tại là từ ngày 20 tháng 9 năm 2026. Hãy kiểm tra triệu chứng theo 1.88.1, không phải tài liệu LiteLLM hiện tại. Tất cả được kiểm tra ngày 21 tháng 9 năm 2026.

Đọc status code trước khi chạm vào key

Khi exception mang status code dạng số nguyên, _is_transient_litellm_error chỉ dựa vào giá trị đó: true với 408, 429, 500, 502, 503 và 504, true với mọi 5xx khác, false với mọi status khác. Chỉ khi không có status code nó mới chuyển sang đối chiếu lớp exception — bao gồm timeout và lỗi kết nối — nên "không có status" là trường hợp duy nhất retry có thể xảy ra mà không có 4xx/5xx để chỉ ra. Mọi lớp trong bảng dưới đây đều mang status, và chúng được đọc bên trong wheel litellm 1.88.1.

Một exception và một điểm mù. Dòng models.py 638 ném lỗi thay vì thử lại khi got_any_chunk là true, nên lỗi tạm thời xuất hiện giữa stream không được thử lại — "nó lỗi ngay lập tức" là gợi ý, không phải bằng chứng. Và configure_litellm() chạy khi import, thiết lập LITELLM_LOG=ERROR và litellm.suppress_debug_info = True. Trong 1.88.1, gợi ý danh sách provider trong get_llm_provider_logic.py được bảo vệ bởi if litellm.suppress_debug_info is False — chính là dòng mà LiteLLM sẽ in ra để hướng bạn đến danh sách provider, nhưng Agent Zero đã tắt nó.

Id bạn nhập không phải id được gửi đi

Mỗi provider có hai identifier, và header provider config nói rõ điều đó: provider ID điều khiển "the settings UI dropdowns" và biến môi trường API-key, còn litellm_provider là "The corresponding provider name in LiteLLM". Chính giá trị thứ hai được thêm vào phía trước. Với endpoint tương thích OpenAI của bên thứ ba, provider id là other ("Other OpenAI compatible"), có litellm_provider là openai, và _adjust_call_args cũng ánh xạ lại other thành openai. Giá trị trên wire là openai/<your-model>, theo biểu mẫu LiteLLM lập tài liệu. Vì vậy hãy nhập id thuần: đọc hai vị trí code đó, nếu tự thêm prefix thì sẽ tạo ra openai/openai/gpt-4o — suy luận từ code, không phải lỗi đã quan sát.

Khi phân giải thất bại, 1.88.1 có hai chuỗi khác nhau, cả hai đều là 400. get_llm_provider_logic.py ném BadRequestError với "LLM Provider NOT provided … You passed model=…" — không suy ra được gì có thể sử dụng từ chuỗi. LiteLLMUnknownProvider tại exceptions.py dòng 902 mang "Unmapped LLM provider for this endpoint. You passed model=…, custom_llm_provider=…" — một provider đã được suy ra, nhưng không có route cho nó trên endpoint đó. Lỗi thứ hai là lỗi có thể gặp khi provider hoạt động cho một vai trò nhưng không hoạt động cho vai trò khác.

Một xung đột khiến người dùng điền nhầm trường. FAQ của Agent Zero nói openai/gpt-5.3 đúng với OpenRouter nhưng sai với provider OpenAI nguyên bản, "which goes without prefix", còn bảng đặt tên trong hướng dẫn cài đặt liệt kê OpenAI là "Model name only". Các phần đó mô tả ô nhập văn bản; code thêm prefix lên trên giá trị đó. Cả hai đều đúng khi xác định rõ lớp. Bảng này cũng có lỗi tài liệu — hàng OpenAI dùng model id của Anthropic làm ví dụ — nên đừng sao chép ô đó.

Tìm xem vai trò nào trong ba vai trò đã thất bại

Agent Zero cấu hình độc lập ba vai trò — chat, utility và embedding — mỗi vai trò có provider, model name và API base riêng. Các section cài đặt là chat_model, utility_model và embedding_model, còn các key phẳng legacy là chat_model_*, util_model_* và embed_model_*; tìm settings.json theo quy ước sai sẽ không thấy gì. Có một lựa chọn thứ tư, tùy chọn, cũng đáng biết: browser plugin đi kèm có model_preset riêng, được cung cấp ở trạng thái rỗng và lập tài liệu là "Empty uses the effective Main Model" — vì vậy nếu bạn không thiết lập nó, lỗi browser tool là lỗi của vai trò chat dưới một tên khác. Và một phản hồi chat thành công chỉ chứng minh một vai trò hoạt động, không phải cả ba.

Vai trò embedding khác biệt theo hai cách làm thay đổi việc phân loại sự cố. LiteLLMEmbeddingWrapper.embed gọi embedding() của LiteLLM mà không có try/except và không có vòng lặp thử lại, nên luôn phát sinh lỗi ngay ở lần thử đầu tiên bất kể loại lỗi. Ngoài ra, mặc định được phân phối là provider huggingface với tên sentence-transformers/all-MiniLM-L6-v2; models.py định tuyến mọi tên huggingface bắt đầu bằng sentence-transformers/ đến một wrapper chạy trong tiến trình mà mã mô tả là tránh các lệnh gọi API HuggingFace, vì vậy lỗi tại đó không nhất thiết liên quan đến bất kỳ lệnh gọi mạng nào.

Kunavo không cung cấp model embedding, vì vậy các vai trò mà một key Kunavo có thể đảm nhiệm trong Agent Zero là vai trò chat và tiện ích.

OpenRouter là sự phân tách vai trò đã được xác nhận, đồng thời là nhánh duy nhất ở đây có bản sửa từ maintainer thay vì suy luận. Issue #1597, "Các model embedding của OpenRouter bị lỗi do LiteLLM thiếu tuyến provider", được mở ngày 2 tháng 5 năm 2026 và đóng ngày 27 tháng 8 năm 2026, vài giờ trước khi v2.11 được phát hành cùng ngày. Có hai điều cần tách riêng vì rất dễ bị đánh đồng. Cấu hình có định tuyến provider theo vai trò — chat giữ litellm_provider: openrouter gốc, còn embedding dùng litellm_provider: openai cùng api_base tường minh, theo TODO của maintainer rằng OpenRouter "chưa được LiteLLM hỗ trợ" — nhưng sự phân tách đó giống hệt trên tag v2.10 và trên main, nên không phải nguyên nhân đóng issue. Thay đổi thực sự giải quyết vấn đề chỉ là một dòng trong models.py: trên v2.10, wrapper embedding tạo f"{provider}/{model}" if provider != "openai" else model, làm mất tiền tố trên mọi embedding được định tuyến qua openai, còn từ v2.11, nó luôn thêm tiền tố; đó là lý do ghi chú đóng issue của maintainer nói rằng các ID chứa dấu gạch chéo hiện được gửi nguyên vẹn đến endpoint. Ở nhánh đó, cách sửa là nâng cấp, không phải thay đổi cài đặt.

Tra cứu key và lý do "đổi key" thường không giải quyết được vấn đề

get_api_key(service) đọc ba tên biến môi trường theo thứ tự cố định và dùng chuỗi ký tự "None" làm giá trị dự phòng.

# Provider id `other` ("Other OpenAI compatible"). models.py reads these
# three names in this order and stops at the first non-empty value.
API_KEY_OTHER=sk-...
# OTHER_API_KEY=sk-...
# OTHER_API_TOKEN=sk-...

# A comma in the value is not a syntax error: models.py splits on it
# and rotates the resulting keys round-robin.

Placeholder đó bị lọc — vị trí gọi kiểm tra api_key not in ("None", "NA") trước khi gắn nó — nên khi không phân giải được key thì hoàn toàn không gửi đối số api_key, và LiteLLM thay vào đó áp dụng cơ chế tra cứu môi trường riêng. Lỗi 401 có thể đến từ một thông tin xác thực mà bạn chưa từng chọn. Một lần tra cứu thứ hai dùng giá trị service khác: _merge_provider_defaults đọc key dưới mã provider gốc, sau đó _get_litellm_chat chuyển sang get_api_key(provider_name), lúc này tên đó là provider của LiteLLM — openai, dành cho other. Vì vậy, nếu API_KEY_OTHER chưa được đặt nhưng cùng .env có OpenAI key, OpenAI key sẽ được gửi đến endpoint của bạn. Hãy đọc hai hàm đó trên main; chúng không được ghi thành tài liệu và chưa được kiểm thử khi chạy tại đây.

Hướng dẫn cài đặt đặt key tại Các dịch vụ bên ngoài → Các key API tương thích OpenAI khác, sau đó chọn Tương thích OpenAI làm provider. Hai triệu chứng được ghi nhận gần đó không phải lỗi model ID: khi bấm gửi mà không có gì xảy ra, FAQ quy nguyên nhân cho việc chưa đặt key trong Settings; và ChatGPT Plus không bao gồm API credit — dù plugin OAuth đi kèm cung cấp một kết nối codex_oauth đăng nhập bằng tài khoản OpenAI, vì vậy nói rằng "không subscription nào có thể điều khiển Agent Zero" là sai.

Endpoint và hai quy tắc có vẻ mâu thuẫn

Provider other được phân phối mà không có api_base mặc định, và ModelConfig.build_kwargs chỉ chuyển trường đó khi trường không rỗng — vì vậy URL API trống sẽ không gửi base URL nào, và áp dụng mặc định openai có sẵn của LiteLLM. Không kiểm tra tại đây host mà cấu hình này phân giải đến trong 1.88.1; hãy coi lỗi 401 với URL trống là lý do cần điền trường này, không phải là chẩn đoán. Trang endpoint tương thích của LiteLLM sau đó đưa ra hai ghi chú có vẻ ngược hướng: "KHÔNG thêm bất cứ thứ gì vào base URL, ví dụ /v1/embedding" và "Nếu thấy Not Found Error khi kiểm thử, hãy đảm bảo api_base của bạn có hậu tố /v1." Hai ghi chú này quy về một quy tắc — kết thúc bằng /v1, không thêm gì phía sau.

Trong Docker, hướng dẫn cài đặt nêu rõ rằng localhost và 127.0.0.1 trong base URL API chỉ container: hãy dùng http://host.docker.internal:<port>, hoặc một địa chỉ gateway như http://172.17.0.1:<port> trên Linux bridge mặc định, và chuyển server đang bind vào loopback của host sang địa chỉ Docker có thể truy cập, chẳng hạn 0.0.0.0. Sau đó xác nhận cấu hình bạn đang đọc chính là cấu hình đã chạy: các preset A0_SET_ chỉ là giá trị mặc định ban đầu — "Một khi giá trị được lưu trong settings.json, nó sẽ được ưu tiên hơn các biến môi trường này" — và cần khởi động lại. Riêng issue #1769 (mở ngày 15 tháng 7 năm 2026, vẫn đang mở) báo cáo LiteLLM gọi exit(-9) khi provider đã đăng ký của model khác với provider đang phục vụ model đó: đây là phân tích của một người báo cáo, chưa được xác nhận và chưa được tái hiện tại đây.

Cái giá của cách sửa sai

Cách nhanh nhất để làm im lỗi ở vai trò tiện ích là trỏ nó vào model chính. Cách này hoạt động, nhưng tính phí theo mức của model chính cho lưu lượng mà hướng dẫn cài đặt mô tả là dùng để tóm tắt và trích xuất bộ nhớ. Các con số này là phép tính token minh họa, không phải chi phí tác vụ đo được và không phải mức trần hóa đơn: giả sử một ngày làm việc với model chính gồm 1200k token đầu vào và 60k token đầu ra, lưu lượng tiện ích gồm 320k và 24k, cùng mức giá catalog Kunavo hiện hành theo mỗi triệu token.

Bản thân vai trò chính dùng model có giá $3,150 cho ngày đó; gộp vai trò tiện ích vào Claude Sonnet 4.6 sẽ thêm $0,924 trong khi Claude Haiku 4.5 có giá $0,308. Tuy nhiên, hãy lưu ý ngưỡng năng lực: hướng dẫn cài đặt cảnh báo rằng model tiện ích phải "đủ mạnh để trích xuất và hợp nhất bộ nhớ một cách đáng tin cậy" và các model rất nhỏ, khoảng 4B, thường không trích xuất ngữ cảnh đáng tin cậy. Hướng dẫn mô tả đây là thất bại ở cấp tác vụ chứ không phải lỗi, nên đây là trường hợp chẩn đoán "model bị lỗi" là sai.

Bản thân Agent Zero không mất phí cấp phép — LICENSE trên main là nội dung MIT, bản quyền "Agent Zero, s.r.o" — vì vậy chi phí nằm ở token model của các vai trò bạn cấu hình. Số tiền trong catalog Kunavo là mức sàn thanh toán, không phải mức trần: khi upstream báo chi phí, hóa đơn là giá trị lớn hơn giữa chi phí trong 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. Xem chi tiết thanh toán.

Nên đặt tuyến nào sau các vai trò

Để lập ngân sách theo từng vai trò, xem Chi phí API của Agent Zero; đối với vị trí thứ ba, xem thay đổi model embedding; đối với quy ước base URL và tiền tố nói chung, xem API tương thích OpenAI. Để kết nối key Kunavo vào other: bắt đầu từ tài liệu tham chiếu lỗi, sau đó tạo tài khoản. Agent Zero chưa được kiểm thử khi chạy với endpoint của Kunavo, vì vậy hãy giữ một tuyến đang hoạt động trong lúc thử nghiệm.

Câu hỏi thường gặp

Hành vi của Agent Zero được đọc từ mã nguồn trên nhánh main của agent0ai/agent-zero — models.py và conf/model_providers.yaml — cùng tài liệu, bản phát hành và issue của dự án, vào ngày 21 tháng 9 năm 2026; các lớp exception và chuỗi lỗi của LiteLLM được đọc bên trong wheel litellm 1.88.1 từ PyPI, là phiên bản Agent Zero ghim. Không nội dung nào ở đây được kiểm thử khi chạy: không thực hiện cài đặt và không tái hiện lỗi từ đầu đến cuối. Mức giá token Kunavo lấy từ catalog trực tiếp, và mọi con số đô la đều là phép tính token minh họa.