Cấu hình Model Catalog và OpenRouter
Trang này hướng dẫn chọn provider và model cho LLM/Embedding/Vision, tinh chỉnh OpenRouter và chạy Diagnose trước go-live. Đọc khi Planner báo lỗi model hoặc bạn cần đổi model an toàn.
Đối tượng: Arkon admin cấu hình LLM/Embedding/Vision; member cần hiểu vì sao Planner lỗi model.
Chọn Provider → Model → Switch & Save
Vào Settings: mỗi card (Embedding / LLM / Vision) là 2 dropdown Provider rồi Model, phía dưới là ô API key. Chọn provider (OpenRouter, OpenAI, Google…) → chọn model → Switch & Save kích hoạt.
Khi provider là openrouter, card hiện thêm Advanced OpenRouter settings:
| Nhóm | Bạn điền gì |
|---|---|
| Kết nối & định danh | Base URL, Site URL, App title, End-user tag (dùng ID/hash ổn định, không tên/email) |
| Model & dự phòng | Danh sách model dự phòng (OpenRouter tự chuyển khi model chính chết; chỉ LLM) |
| Sampling | temperature, top_p, top_k, max_tokens… (điều khiển model không nhận sẽ hiện mờ kèm lý do) |
| Reasoning | Bật/tắt, effort, ngân sách, ẩn trace (model bắt buộc reasoning thì không có nút tắt) |
| Định tuyến | only / ignore / sort / data_collection — cũng là cách duy nhất ghim context window |
| Structured output | auto / json_schema / json_object / prompt (auto hạ cấp đúng 1 lần khi bị từ chối) |
| Ngân sách | Ngưỡng cảnh báo số dư |
Section Budget & pipeline timeouts: MAP extraction timeout (120s) · Writer timeout (300s). Thứ tự hiệu lực: DB > biến môi trường > mặc định.
Tham số theo từng model (badge)
Mỗi model giữ bộ tham số riêng — đổi model không rò tham số model cũ:
| Badge | Nghĩa |
|---|---|
| Safe default | Chưa tinh chỉnh (reasoning OFF, max_tokens = min(trần model, 32768)) |
| Legacy fallback | Tham số capability cũ còn hiệu lực — bấm Save 1 lần để chuyển sang bộ riêng |
| Customized | Đã có bộ riêng — có nút Reset to safe defaults |
Hai nút cạnh Save (khoá tới khi model đã active): Preview request (chạy khô, hiện đúng body sẽ gửi + tham số bị loại) và Diagnose (6 kiểm tra bên dưới). Chạy Diagnose trước khi go-live.
Sáu kiểm tra của Diagnose — hỏng check nào sửa đúng chỗ đó:
- Key & quota — key sai, hết hạn hoặc chạm hạn mức free tier (50 req/ngày không credit, 1000 req/ngày khi đã
nạp từ 5 USD) → xoay key, kiểm tra
GET /api/v1/key. - Model còn sống — model ngừng được phục vụ (
no endpoints found) → đổi model, đừng cố cấu hình tiếp. - Structured outputs — model LLM cho Planner phải hỗ trợ; thiếu thì Planner 400 tuỳ endpoint được định tuyến.
- Tương thích tham số — xem panel "Dropped" ở Preview: sanitizer loại tham số model không khai, không bao giờ gửi mù.
- Routing filter — bộ lọc
only/ignore/data_collectioncòn endpoint nào không; bẫy hay gặp:data_collection=denyloại sạch endpoint:free→ 404 ngầm "No endpoints found matching your data policy". - Số chiều embedding — đo thật ở request đầu, lệch catalog thì dừng ngay; đổi embedding model là phải re-embed.
Một model ID có hàng chục endpoint cửa sổ khác nhau (ví dụ 384K→1M); catalog luôn khai số nhỏ nhất. Muốn cửa sổ lớn: ghim provider ở Routing → Only rồi chạy lại Diagnose.
Planner Board đọc env, không đọc DB Arkon
- Chọn OpenRouter bằng
AGENTBOARD_LLM_BASE_URL(không có biếnOPENROUTER_API_KEYriêng). - Key và model của Planner nằm ở env:
AGENTBOARD_LLM_MODE=live+AGENTBOARD_LLM_API_KEY(hoặcOPENAI_API_KEY) +AGENTBOARD_LLM_MODEL(bắt buộc ở modelive, không có default). - Model phải hỗ trợ structured outputs; production kiểm tra offline qua allowlist đóng gói trong server
(file
openrouter-structured-models.ts, sinh bởiarkon/scripts/sync_openrouter_catalog.py --emit-ts— không sửa tay); preflight production cảnh báoLLM_OPENROUTER_MODEL_UNVERIFIEDnếu model chưa verify. - Triệu chứng thường gặp:
no endpoints found= model ngừng phục vụ → Diagnose #2 → đổi model. - Ở mode
replay(mặc định) mọi ý tưởng thật đều lỗi[LLM VCR ERROR] Cassette cache miss— đó là throw có chủ ý, không phải bug model.
Nguồn error sau upload — Retry chỉ chạy lại commit
Nếu embed thất bại, nguồn chuyển error (trang Wiki đã ghi, chỉ thiếu vector).
Dán key embedding thật → Retry trên bảng Knowledge — idempotent, rẻ, bấm nhiều lần an toàn.
Gặp lỗi? Xem Sự cố & checklist go-live và Xử lý sự cố.
Đi tiếp: Vận hành hằng ngày · Sự cố & checklist go-live · Xử lý sự cố.