sys-analysis-design/.claude/skills/ba-3-specification/templates/srs-part2/ml-model.md

PART 2 — biến thể ml-model

Dùng khi PRODUCT = ml-model — sản phẩm là mô hình dự đoán: phân loại, hồi quy, xếp hạng, gợi ý, sinh nội dung. Cắm khối này vào chỗ PART 2 của ../srs.md.

Tiêu chí G3 riêng của biến thể này: định nghĩa nhãn rõ ràng và có người gán · tập đánh giá được chốt và cách ly · mọi metric có ngưỡng chấp nhận và ngưỡng đó truy về được chi phí nghiệp vụ · có hành vi fallback · có tiêu chí giám sát drift.

---

🔴 Đọc trước: yêu cầu ở đây mang tính xác suất

Given/When/Then không mô tả được phần dự đoán. Không tồn tại AC kiểu "Given ảnh này, When chạy mô hình, Then trả về đúng nhãn" — mô hình sẽ sai một tỷ lệ nào đó, và điều đó không phải bug.

Chia làm hai phần và đối xử khác nhau:

Phần	Đặc tả bằng	Ai nghiệm thu
Hệ thống bao quanh — API, hàng đợi, lưu kết quả, hiển thị, xử lý lỗi	AC Given/When/Then bình thường, 4 nhóm đầy đủ	QA
Chất lượng dự đoán	Metric + ngưỡng chấp nhận trên tập đánh giá đã chốt	PO + người sở hữu nghiệp vụ

Nhầm hai phần này là lỗi kinh điển: QA viết test case đòi mô hình đúng 100% trên vài mẫu tự chọn, rồi kết luận fail.

---

2.1 Bài toán

Loại	Phân loại nhị phân / đa lớp / Hồi quy / Xếp hạng / Gợi ý / Sinh nội dung
Đầu vào	(thực thể nào, có những thông tin gì)
Đầu ra	(nhãn? điểm số? danh sách xếp hạng? văn bản?)
Quyết định nghiệp vụ nào phụ thuộc đầu ra này
Ai/cái gì hành động dựa trên đầu ra	Người xem rồi quyết / Hệ thống tự động thực thi

🔴 Câu cuối quyết định mọi thứ phía sau. Mô hình chỉ gợi ý cho người xem thì sai số chịu được cao hơn nhiều so với mô hình tự động chặn giao dịch.

2.2 Định nghĩa nhãn / ground truth

Mục quan trọng nhất và bị bỏ nhiều nhất. Nhãn định nghĩa lỏng ⇒ mọi metric phía sau vô nghĩa.

Nhãn là gì	(định nghĩa nghiệp vụ chính xác, không phải "gian lận" chung chung)
Ai gán nhãn
Gán theo quy tắc nào	(kèm ví dụ ca khó)
Hai người gán có ra cùng kết quả không	(đo bằng gì, tỷ lệ đồng thuận bao nhiêu)
Nhãn có sẵn tự nhiên không	(vd: khách có click hay không — nhãn ngầm)
Độ trễ có nhãn	🔴 (vd: biết một khoản vay xấu phải chờ 6 tháng)

Ca biên	Gán nhãn thế nào

2.3 Dữ liệu

Tập	Khoảng thời gian	Số bản ghi	Tỷ lệ lớp dương	Cách chọn
Train
Validation
Test / giữ lại				🔴 Chốt trước, không ai được xem trong lúc phát triển

Rà rò rỉ dữ liệu (data leakage) — bốn chỗ hay rò:

#	Chỗ rò	Kiểm tra
1	Trường chỉ tồn tại sau khi biết kết quả	☐ Mọi trường đầu vào đều có tại thời điểm cần dự đoán
2	Chia tập ngẫu nhiên trong khi dữ liệu có thứ tự thời gian	☐ Chia theo thời gian nếu bài toán có yếu tố thời gian
3	Cùng một thực thể xuất hiện ở cả train và test	☐ Chia theo nhóm thực thể
4	Chuẩn hoá/thống kê tính trên toàn bộ dữ liệu trước khi chia	☐ Chỉ tính trên train

2.4 Metric và ngưỡng chấp nhận

Thay cho "acceptance criteria" của phần dự đoán.

ID	Metric	Đo trên	Ngưỡng chấp nhận	Baseline hiện tại	Truy về chi phí nghiệp vụ nào
M-01	Precision @ ngưỡng 0.7	Test	≥ 0,85	Quy tắc tay: 0,62	Mỗi FP tốn … công xử lý tay
M-02	Recall	Test	≥ 0,70	0,45	Mỗi FN tốn … thiệt hại
M-03	Metric theo phân khúc (xem §2.6)	Test	Không phân khúc nào < 0,60

🔴 Mỗi ngưỡng phải truy về được chi phí nghiệp vụ. "Precision ≥ 0,85" chọn từ đâu? Nếu không trả lời được thì đó là con số ai đó thấy đẹp — và nó sẽ bị tranh cãi lại đúng lúc mô hình đạt 0,84.

Baseline bắt buộc: so với cách làm hiện tại (quy tắc tay, con người, hoặc đoán theo lớp phổ biến nhất). Mô hình đạt 0,85 mà quy tắc tay đã đạt 0,84 thì không đáng triển khai.

2.5 Ngưỡng quyết định và đánh đổi

Đầu ra thô	Điểm số 0–1
Ngưỡng cắt	(giá trị, và ai được đổi nó)
Đổi ngưỡng có cần triển khai lại không	🔴 Nên là không — để nghiệp vụ tự điều chỉnh

Ngưỡng	Precision	Recall	Số ca/ngày phải xử lý tay	Ghi chú
0,5
0,7				← đề xuất
0,9

Bảng này là bảng PO đọc để chọn, không phải BA chọn thay.

2.6 Công bằng và phân khúc

Phân khúc	Vì sao cần kiểm riêng	Metric	Ngưỡng	Kết quả
Khách hàng mới (< 30 ngày)	Ít dữ liệu lịch sử
Theo vùng/chi nhánh	Phân bố khác nhau

Metric tổng thể đẹp mà một phân khúc quan trọng rất tệ là tình huống phổ biến, và người dùng sẽ phát hiện ra trước bạn.

2.7 Hành vi khi không chắc chắn & fallback

Đây là phần có viết được bằng AC bình thường.

Tình huống	Hệ thống làm gì	AC
Điểm số nằm trong vùng xám (0,4–0,6)	Chuyển người xử lý tay / gán nhãn "không xác định"	AC-nn
Thiếu trường đầu vào bắt buộc	🔴 Đoán đại hay từ chối dự đoán?	AC-nn
Mô hình không phản hồi / timeout	Trả kết quả mặc định nào?	AC-nn
Đầu vào ngoài phân phối đã học		AC-nn

🔴 "Từ chối dự đoán" phải là một đầu ra hợp lệ. Bắt mô hình luôn trả lời là bắt nó đoán bừa ở đúng những ca nó không biết.

2.8 Giám sát và huấn luyện lại

Theo dõi gì	Ngưỡng cảnh báo	Ai được báo	Hành động
Phân phối đầu vào lệch so với train
Tỷ lệ dự đoán lớp dương
Metric trên nhãn thật (khi có)
Tỷ lệ rơi vào vùng xám

Tiêu chí huấn luyện lại	(theo lịch? theo ngưỡng drift? theo lượng nhãn mới?)
Ai duyệt mô hình mới trước khi thay
So sánh mô hình mới với cũ bằng gì	(cùng tập test đã chốt ở §2.3)
Rollback về mô hình cũ thế nào

2.9 Giải thích được và khiếu nại

Người bị ảnh hưởng có quyền biết lý do không	(có yêu cầu pháp lý không)
Hiển thị lý do ở mức nào	Không / Yếu tố chính / Đầy đủ
Người dùng phản đối kết quả thì quy trình nào
Lưu vết: đầu vào, phiên bản mô hình, đầu ra, giữ bao lâu	🔴 Bắt buộc nếu RIGOR = strict

2.10 Nghiệm thu — thay cho UAT thông thường

Giai đoạn	Làm gì	Tiêu chí đi tiếp
1. Offline	Đánh giá trên tập test đã chốt	Đạt mọi ngưỡng §2.4
2. Shadow	Chạy song song, không tác động nghiệp vụ, so với quyết định của người	Sai lệch trong ngưỡng, tối thiểu … ngày
3. Thí điểm	Bật cho một phân khúc nhỏ	Metric online giữ ngưỡng, không có sự cố
4. Mở rộng

🔴 Bỏ bước shadow là rủi ro lớn nhất của loại sản phẩm này. Metric offline đẹp mà dữ liệu thật khác phân phối là chuyện xảy ra thường xuyên, và chỉ shadow mới phát hiện được trước khi có thiệt hại.