9. Checklist cho bản `metrics.py` khi dựng lại

Repo này đã gỡ toàn bộ code (labs/) để thuần tài liệu học. Bảng dưới là bản rà soát bản labs/common/metrics.py từng tồn tại — đọc như checklist khi viết lại từ đầu. Muốn xem code cũ: git show ada36f4:labs/common/metrics.py.

Quan sát	Mức độ
Thiếu `average_precision` — metric duy nhất trong nhóm cổ điển còn thiếu; bắt được lỗi “doc liên quan bị rải rác” mà recall/precision bỏ qua (kịch bản A vs B, §2.4)	Nên thêm
`precision_at_k` không báo trần $\min(k,R)/k$ → điểm 0.32 trông như thất bại dù có thể là 78% mức tối đa khả thi	Nên thêm
Chỉ đo ở một $k$ → không tách được “lỗi retrieval” khỏi “lỗi ranking”; cần recall ở cả $k$ nhỏ và $k$ lớn	Nên thêm
Không có test ý nghĩa thống kê → mọi so sánh giữa lab hiện đang là so cảm giác	Quan trọng nhất
`reciprocal_rank` nhị phân hoá `rel > 0`	Đúng theo định nghĩa; chỉ cần biết giới hạn (§2.1)
`dcg(gains)` — tham số tên `gains` nhưng thực chất nhận relevance grades (hàm tự áp $2^g-1$ bên trong)	Đổi tên thành `rels` cho khỏi truyền sai
`recall_at_k` trả 0.0 khi $R = 0$	Nên loại truy vấn đó khỏi trung bình thay vì tính 0
Dùng macro-average, tách theo class	✅ Đúng
Gain hàm mũ $2^{\mathrm{rel}}-1$	✅ Đúng lựa chọn cho RAG
IDCG cắt ở $k$	✅ Đúng

Phần 2 — Metrics