Download docs/DESIGN.md from codemaivanngu/job-manager: direct link, hf CLI and curl.
- Browser
- Download file 7.03 kB
-
https://huggingface.co/codemaivanngu/job-manager/resolve/main/docs/DESIGN.md
- Command line
-
hf download hf://codemaivanngu/job-manager/docs/DESIGN.md
-
curl -L -o DESIGN.md https://huggingface.co/codemaivanngu/job-manager/resolve/main/docs/DESIGN.md
/eval-core/ — thiết kế hệ thống eval quản lý theo file
Mục tiêu: thay chuỗi lệnh paste tay bằng một CLI nhỏ + các file JSON để (a) không còn thao tác mơ hồ, (b) không bao giờ eval trùng, (c) mỗi lần kẹt chỉ cần một lệnh in ra một nguyên nhân.
Vị trí: /workspace/storage-shared/nlp/tungks/eval-core/ (trên share, cạnh các clone/case).
1. Nguyên tắc
- 1 file = 1 sự thật. Không DB, không state ẩn trong RAM, không biến toàn cục.
- Claim = atomic rename. Nhận job là
mv pending/x.json claimed/x.json⇒ hai worker không thể nhận cùng job. - Không bao giờ eval lại thứ đã có — bank tra theo khoá nội dung.
- Chỉ 3 loại job, mỗi loại có runner riêng, không trộn vai.
- Mọi lần kẹt đều trả lời được bằng
ec why <job>— in job, chỗ chờ, file/log liên quan.
2. Cây thư mục
eval-core/
bin/ec # CLI duy nhất: bash + python3 (không venv riêng)
bin/runners/
gen.sh # vòng lặp pool cho job type=gen
score-cpu.sh # vòng lặp pool cho type=score-cpu
score-judge.sh # bản nháp cho type=score-judge
schemas/
job.schema.json
bank-entry.schema.json
queue/
pending/ # ec add -> file job nằm đây
claimed/ # worker mv sang đây khi nhận (atomic)
done/ # xong
failed/ # lỗi, kèm last-error.txt
bank/
entries/<key>.json # 1 kết quả đã có
index.jsonl # append-only, để tra cứu nhanh
locks/
gpu-0.lock … gpu-7.lock # flock cho engine gen (1 engine / card)
job-<id>.lock # flock cho 1 job
run/
<job-id>/stdout.log stderr.log result.json
env/
fp-<hash>.json # fingerprint môi trường chấm (python, numpy, sympy, contract_sha)
3. Job spec (1 file, ~12 dòng, đọc là hiểu)
{
"id": "gen__FIX-fixed5-s44__step120__gsm8k__seed42",
"type": "gen", // gen | score-cpu | score-judge
"case": "/workspace/.../fixedspan5-diag-549b1ae-20261001",
"run": "FIX-fixed5-s44",
"step": 120,
"benchmark": "gsm8k", // gsm8k | math500 | mbpp | live-code-bench-v6 | ...
"seed": 42,
"gen_seed": 0,
"needs": { "gpu": 1, "vram_gb": 140 },
"engine": { "plan": "<case>/eval/<run>-step<step>/plan.json",
"cmd": "eval_queue.py worker --plan … --gpu N --phase generate" },
"bank_key": "sha256:model…|gsm8k|seed42|contract:ab12|env:7f3c",
"prio": 50,
"created": "2026-10-02T04:20:00+00:00",
"by": "ec add"
}
4. Vòng đời một job
ec add -> queue/pending/<id>.json
worker: flock job-<id>.lock (non-blocking) -> mv pending -> claimed
chạy runner -> run/<id>/{stdout,stderr}.log
ghi run/<id>/result.json + bank entry -> mv claimed -> done
lỗi -> failed/<id>.json + last-error.txt (KHÔNG tự retry)
ec gc --older-than 2h -> claimed quá hạn (worker chết) trả về pending
Không có bước nào dựa vào "nhớ trạng thái": nếu chết, file nằm ở claimed/ và ec gc đưa về.
5. Ba loại job
| type | Chạy ở đâu | Khoá cần | Ghi ra | Ghi chú |
|---|---|---|---|---|
gen |
GPU pool (engine — đúng như cũ) | locks/gpu-N.lock + job-<id>.lock |
cells/…/responses.jsonl, bank entry |
tốn VRAM, 1 engine/card |
score-cpu |
CPU pool (16 worker) | chỉ job-<id>.lock |
cells/…/metrics.json + env_fp |
không cần GPU, rẻ, song song cao |
score-judge (nháp) |
CPU hoặc API LLM | job-<id>.lock (+judge-<model>.lock nếu gọi API) |
judge.jsonl (rubric, từng sample, lý do) |
cần rubric + giá; chưa implement |
Ba loại này tách đúng ba nguyên nhân thất bại hôm nay: hết VRAM (gen), chờ lock (score), drift môi trường (env_fp gắn vào bank).
6. Bank — ngân hàng kết quả & chống trùng
- Khoá:
sha256(model_sha | benchmark | seed | contract_sha | env_fp).model_sha= hash file checkpoint;contract_sha= hash script chấm;env_fp= hash môi trường (env/fp-*.json). ec addtự bỏ job nếu bank đã có khoá ⇒ không bao giờ sinh/chấm lại thứ đã có.- Mỗi entry ghi rõ ai chấm (contract + env_fp) ⇒ chuyện "numpy 2.1.0 → 2.2.6" trở thành dữ liệu đọc được
thay vì lỗi chặn:
ec comparesẽ cảnh báo khi so hai entry khácenv_fp. ec bank import <case>/eval⇒ nạp toàn bộ cell đã có (451 file hôm nay) vào bank, kèm env_fp suy từ plan cũ.
7. Tương thích queue master cũ
ec không thay scripts/evaluation/eval_queue.py ✗ — nó là lớp trên, gọi đúng các lệnh cũ:
worker --plan … --gpu N --phase generate và score-spool --plan ….
Vì vậy mọi plan.json/cells/ hiện có dùng nguyên, không migrate dữ liệu, không đổi contract.
8. CLI (7 lệnh — học trong 5 phút)
ec add --case <dir> --run FIX-fixed5-s44 --steps 40..312 --bench all --seeds 42,43,44
ec run --type gen --gpu 0,1,3 # pool, tự claim, tự nhả lock
ec run --type score-cpu --workers 16
ec status # bảng: theo run × step: pending/claimed/done/failed
ec why <job-id> # MỘT nguyên nhân + file/log liên quan
ec gc --older-than 2h # trả job treo về pending
ec bank ls|import|verify|compare # ngân hàng kết quả
ec why là thứ hôm nay thiếu nhất: mỗi lần kẹt, một dòng lý do (vd thiếu receipt train/FIX-fixed5-s44.last-exit.json),
kèm đường dẫn file cần sửa — thay cho việc đọc 40 dòng traceback.
9. Lộ trình (mỗi bước tự chạy và tự kiểm được)
| Bước | Nội dung | Rủi ro | Xong khi |
|---|---|---|---|
| B1 | Khung thư mục + ec add/status/why + ec bank import cho 451 cell hiện có |
thấp (chủ yếu đọc) | ec status in đúng bảng của case hiện tại, bank có ≥451 entry |
| B2 | Runner gen + score-cpu (bọc eval_queue.py cũ), khoá + pool như §5 |
trung bình (chạm GPU) | một job gen + một job score chạy trọn vòng, để lại bank entry |
| B3 | score-judge (nháp): schema rubric, runner, ec compare |
thấp (chưa dùng thật) | chạy được 1 job judge trên 20 sample |
10. Việc đầu tiên tôi đề nghị làm ngay
B1 + import bank: nó không đụng GPU, không đụng job đang chạy, mà ngay lập tức cho bạn
ec status / ec why để nhìn hệ thống bằng một bảng thay vì paste lệnh. Sau đó B2 thay dần các
queue paste tay (queue_tail_gpu0.sh, run_pending_and_eval.sh) bằng ec run.