File size: 7,026 Bytes
36bacba
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
# /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. **1 file = 1 sự thật.** Không DB, không state ẩn trong RAM, không biến toàn cục.
2. **Claim = atomic rename.** Nhận job là `mv pending/x.json claimed/x.json` ⇒ hai worker không thể nhận cùng job.
3. **Không bao giờ eval lại thứ đã có** — bank tra theo khoá nội dung.
4. **Chỉ 3 loại job**, mỗi loại có runner riêng, không trộn vai.
5. **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)

```json
{
  "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 add` **tự 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 compare` sẽ cảnh báo khi so hai entry khác `env_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)

```bash
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`.