00 Cài đặt

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 00 Cài đặt.

Trước buổi học — tạo một key dùng chung cho học viên (dùng công bằng)

Với một buổi công khai do giảng viên dẫn, đừng đưa cho một phòng đầy người lạ key OpenRouter cá nhân của bạn hay một key không giới hạn. OpenRouter có Management (provisioning) API để tạo các key chuyên dụng có mức trần credit cứng, theo cách lập trình được — nhờ đó chi tiêu của workshop được giới hạn và công bằng.

1. Tạo một Management key (một lần duy nhất). OpenRouter → Settings → Management API Keys (openrouter.ai/settings/management-keys) → Create New Key. Key này có thể tạo, xem và xóa các key khác cũng như chi tiêu trên tài khoản của bạn — hãy coi nó như một credential quản trị.

export OPENROUTER_PROVISIONING_KEY=sk-or-v1-<management-key>   # instructor only — never share

2. Tạo key dùng chung cho học viên với một mức trần cứng. Repo có kèm một script hỗ trợ (scripts/provision_workshop_keys.py) gọi POST https://openrouter.ai/api/v1/keys:

# one shared key the whole room uses, capped at $20 total (reset daily at 00:00 UTC):
python -m scripts.provision_workshop_keys --name "Agent Arena $(date +%F)" --limit 20 --daily

Phản hồi khi tạo in ra chuỗi key đúng một lần — hãy sao chép nó và đưa cho học viên làm OPENROUTER_API_KEY của họ. Sau đó chỉ còn lấy lại được hash của nó (để xem hoặc xóa). Bạn thích dùng curl thuần hơn? Vẫn cùng một lệnh gọi:

curl -s https://openrouter.ai/api/v1/keys \
  -H "Authorization: Bearer $OPENROUTER_PROVISIONING_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Agent Arena workshop","limit":20}'

python -m scripts.provision_workshop_keys --name "Agent Arena $(date +%F)" --limit 2 --count 30

3. Theo dõi và dọn dẹp. Xem mức chi giữa buổi và xóa các key khi xong:

python -m scripts.provision_workshop_keys --list
python -m scripts.provision_workshop_keys --delete <keyHash>

Về quy mô: danh sách model thuộc lớp flash-lite giá rẻ và lưới chỉ có 6 × 3 = 18 cấu hình, nên mức trần dùng chung $20 dư sức cho cả một phòng chạy Arena vài lần — mức trần là một lan can bảo vệ chống các vòng lặp mất kiểm soát, không phải một ngân sách chật.

Thời lượng

Tổng khoảng 25–30 phút khi tài khoản đã có sẵn; hãy chừa thêm thời gian nếu phải tạo tài khoản.

• 5 phút — tạo ba tài khoản (OpenRouter, Langfuse Cloud, ClickHouse Cloud) nếu học viên chưa làm việc này từ hôm trước.
• 5 phút — clone repo, tạo virtualenv, cài dependencies.
• 5 phút — điền .env.
• 5 phút — source .env && scripts/arena.sh up, xác nhận dashboard mở được tại http://localhost:5174.

Trước buổi học, hãy mở OpenRouter → Settings → Privacy → Data Policies → Zero Data Retention và tắt Non-frontier (xám/off), rồi thử Qwen với key của học viên. Qwen định tuyến tới endpoint không-ZDR của Alibaba, nên bật ZDR cho non-frontier sẽ tạo ra No endpoints available matching your guardrail restrictions and data policy dù Alibaba đã được cho phép và các guardrail theo key/workspace đã nới. Đây là một thiết lập ở cấp tài khoản và không thể nới qua Management API hay qua một tham số request. Chỉ dùng thiết lập này cho khối lượng công việc tổng hợp của workshop; hãy giữ trong đầu các yêu cầu xử lý dữ liệu của tổ chức bạn khi làm với dữ liệu thật.

Nội dung dẫn dắt

• Mở đầu bằng cách nêu tên cả ba tài khoản ngay từ đầu — OpenRouter, ClickHouse Cloud, Langfuse Cloud — và nói rõ rằng Langfuse là một trong số đó, ngay ở module đầu tiên, trước khi chọn dù chỉ một model. Đó chính là điểm cốt lõi: Langfuse không phải một thứ gắn thêm cho production ở Mô-đun 03, mà là công cụ chạy cuộc thi ngay ở mô-đun kế tiếp.
• Chỉ vào sơ đồ kiến trúc và nêu tên một đường code dùng chung: agents/ được dùng bởi cả eval/harness.py (benchmark) và serving/api.py (production) — nên không có gì được đo hôm nay bị lệch khỏi những gì lên production ở Mô-đun 03.
• Vừa chạy vừa thuyết minh scripts/arena.sh up thực sự làm gì: tạo database arena, tạo user chỉ đọc arena_ro, sinh dữ liệu thương mại điện tử tổng hợp trực tiếp vào ClickHouse, dựng các view v_*, và khởi động dashboard API + web UI.
• Đặt kỳ vọng rằng tab Leaderboard sẽ trống ở cuối module này — đó là đúng, không phải lỗi, và nó là cái kết mở dẫn sang Module 01.

Lỗi thường gặp

• Để OPENROUTER_API_KEY còn là placeholder sk-or-... — harness sẽ thất bại với lỗi 401 ngay lần đầu nó gọi một model ở Module 01, chứ không phải trong lúc cài đặt. Hãy yêu cầu học viên kiểm tra lại .env đã có key thật ngay lúc này, trước khi việc gỡ lỗi trở nên đắt về sau.
• Để trống ARENA_RO_PASSWORD — scripts/arena.sh up vẫn tạo user arena_ro, nhưng với mật khẩu rỗng, và client chỉ đọc của agent có thể từ chối nó tùy vào chính sách mật khẩu của service ClickHouse Cloud. Hãy cho học viên đặt một giá trị không rỗng bất kỳ.
• Service ClickHouse Cloud vẫn đang được cấp phát — một service vừa tạo có thể mất một hai phút mới nhận kết nối; scripts/arena.sh up sẽ thất bại ngay với lỗi kết nối nếu chạy quá sớm. Chỉ cần đợi rồi chạy lại.
• Chưa source .env trước khi chạy script — source .env && scripts/arena.sh up là một dòng vì có lý do; chạy scripts/arena.sh up một mình trong một shell mới sẽ thất bại vì thiếu các biến môi trường CLICKHOUSE_CLOUD_*.
• Port 5174 (hoặc 8000) đã bị chiếm — tiến trình còn sót từ lần chạy trước. scripts/arena.sh stop dọn các server cục bộ trước khi chạy lại up.

Các bước reset

• Seed lại từ đầu: source .env && scripts/arena.sh up — nó idempotent và không dùng Aurora, ClickPipes hay ClickStack; nó tạo lại database arena, user arena_ro, dữ liệu tổng hợp và các view v_*, rồi khởi động lại dashboard API và web UI. Kết quả benchmark vẫn nằm trong Langfuse.
• Nếu chỉ các server cục bộ bị treo (không phải ClickHouse), scripts/arena.sh stop rồi scripts/arena.sh serve nhanh hơn một lần up đầy đủ.
• Kiểm tra trạng thái bất cứ lúc nào bằng scripts/arena.sh status — nó báo dashboard API và web UI có đang chạy không, và in số dòng của từng view v_*.
• Nếu .env của một học viên vẫn còn giá trị placeholder, không có đường tắt nào — hãy lấy key/credential thật và chạy lại scripts/arena.sh up.