01 Chọn model nền

Tài liệu đồng hành của người điều phối cho bài học của học viên 01 Chọn model nền.

Thời lượng

Khoảng 20 phút với tập con được khuyến nghị; 45–60 phút nếu bạn chạy toàn bộ lưới trực tiếp.

• 8 phút — thiết lập evaluator của Langfuse (LLM Connection, code evaluator correctness, và evaluator definition LLM-as-a-judge llm_judge, phát score agent-arena-llm-judge). Hãy làm việc này như một buổi trình diễn trực tiếp trên máy chiếu của bạn, không chỉ đưa một liên kết tới README — đây là bước lắt nhắt nhất trong buổi học.
• 8 phút — chạy một tập con hai model, một prompt (hãy nói chuyện trong lúc chờ; đó là lúc tốt để đưa ra cách khung "vì sao dùng chi phí trên mỗi câu trả lời đúng"). Một lưới đầy đủ thường mất 35–45 phút và nên chạy trước hoặc để lại cho phần tự học.
• 4 phút — mở Leaderboard, đọc người thắng, nêu tên config_id.

Nội dung dẫn dắt

• Hãy khung việc này là quyết định nền tảng của cả workshop: model nào là động cơ của agent, được quyết bằng bằng chứng thay vì một bảng xếp hạng công khai mà người khác chạy trên một khối lượng công việc khác.
• Nhấn mạnh việc chấm điểm diễn ra ở đâu: bên trong Langfuse, không phải bên trong harness. Harness điều phối lưới và ghi lại các Experiment Item hoàn chỉnh; leaderboard đọc chúng qua Langfuse Public API. Đây vẫn là project Langfuse đã được kết nối ở Module 00 — không có công cụ mới hay nơi lưu kết quả thứ hai nào được đưa vào ở đây.
• Làm rõ số lượng item: repo có 20 câu hỏi YAML, nhưng q019 và q020 là few-shot holdout, nên dataset experiment arena-golden sạch có 18 item.
• Nêu rõ tên chỉ số chính và vì sao nó không phải độ chính xác thuần: chi phí trên mỗi câu trả lời đúng — chất lượng trên mỗi đô la cho đúng bài toán này. Hãy chỉ ra rằng chi phí được tính từ giá OpenRouter thời gian thực, làm mới ở đầu mỗi lần chạy, không phải một con số cũ cứng hóa trong config.yaml.
• Trình bày trên màn hình từ vựng của lưới: sáu model chia thành proprietary và open-weight (claude-sonnet-5, gpt-5.6-luna, gemini-flash-lite / deepseek-v4-flash, qwen3.7-flash, glm-4.7-flash) × các prompt (P1_zeroshot … P3_dialect), và rằng một config_id là <model>__<prompt>.
• Bấm trực tiếp từ một dòng trên Leaderboard vào kết quả của một câu hỏi, rồi vào trace Langfuse phía sau nó — đây là thói quen đào sâu mà Module 02 sẽ đi kỹ.
• Kết lại ở người thắng và đọc to config_id của nó — mọi module từ đây trở đi đều quy chiếu về nó.

Lỗi thường gặp

• Chưa cấu hình các evaluator của Langfuse — harness chỉ chờ tới hết --eval-timeout (mặc định 180s), rồi thoát với mã khác 0 và nêu tên các score còn thiếu. Nó chờ score có tên chính xác agent-arena-llm-judge, do evaluator definition llm_judge phát ra. Hãy chạy python -m scripts.provision_langfuse_evaluators cho judge chạy trên OpenRouter, sửa target/bộ lọc của evaluator correctness, rồi chạy một lưới nhỏ hai model, một prompt với một --run-id mới; có chủ ý không có phương án dự phòng chấm điểm cục bộ nào vì Langfuse là nơi lưu đánh giá.
• OPENROUTER_API_KEY còn là placeholder — mọi lệnh gọi trong lưới thất bại với 401. Hãy xác nhận điều này ở Module 00, nhưng nếu nó lọt qua, đây là nơi nó trở nên lộ rõ: cả một lần chạy với không câu trả lời đúng nào trên mọi cấu hình.
• Một model slug đã lệch khỏi catalog của OpenRouter — các id model trong config.yaml (ví dụ anthropic/claude-sonnet-5) được ghim theo những gì còn sống trên OpenRouter lúc viết tài liệu; OpenRouter có ngừng hỗ trợ/đổi tên slug. Nếu một cấu hình lỗi ngay lập tức với kiểu thất bại "model not found", hãy kiểm tra https://openrouter.ai/api/v1/models để lấy slug hiện tại và so với config.yaml. Endpoint /api/models của dashboard phản ánh catalog thời gian thực, nên một điểm lệch ở đó là cách nhanh để phát hiện sự trôi dạt trước khi chạy harness.
• ClickHouse chưa được seed — nếu Module 00 chưa chạy xong sạch sẽ, các truy vấn của harness trên các view v_* sẽ trả về kết quả rỗng hoặc lỗi; mọi cấu hình đều trả về cùng một outcome. Hãy chạy lại scripts/arena.sh up.
• Lần chạy trông như bị treo — lưới là models × prompts (mặc định 6 × 3 = 18 cấu hình); nó có thể mất vài phút từ đầu đến cuối. Dùng --models/--prompts để thu nhỏ nó cho một buổi demo trực tiếp (xem phần Các bước reset).

Các bước reset

• Xác nhận ClickHouse đã được seed: scripts/arena.sh up (idempotent; chạy lại an toàn).
• Chạy lại một tập con giá rẻ thay vì toàn bộ lưới: python -m eval.harness --run-id demo2 --models qwen3.7-flash,gpt-5.6-luna --prompts P1_zeroshot,P3_dialect
• Luôn cho một lần chạy mới một --run-id mới (ví dụ demo2, demo3) để nó hiện ra như một nhóm dòng riêng trên Leaderboard và một Experiment riêng trong Langfuse, thay vì trộn vào lần chạy trước.
• Nếu các evaluator của Langfuse là điểm nghẽn, hãy kiểm tra cả hai đều nhắm Experiments và bộ lọc dataset arena-golden, rồi chạy lại tập con giá rẻ ở trên với một --run-id mới.
• Nếu chính dashboard trông như bị treo (không phải harness), scripts/arena.sh stop rồi scripts/arena.sh serve sẽ khởi động lại chỉ các server cục bộ mà không chạm vào dữ liệu đã seed.