Skip to main content

Suit penilaian

CLI yb disertakan dengan dua arahan penilaian luar talian supaya anda boleh mengukur kualiti penghalaan dan kualiti pengesanan cangkuk pengawal sebelum dan selepas perubahan, pada set data berlabel yang tetap. Kedua-duanya berketentuan dan boleh dijalankan dalam CI.

yb evaluate routing --golden datasets/eval/golden_routing.jsonl [--save] [--against datasets/eval/routing_baseline.json] [--max-mismatch N]
yb evaluate guards --corpus datasets/eval/guards_labeled.jsonl [--min-precision 0.98] [--min-recall 0.90]
yb evaluate guards --revision datasets/eval/guards-revision.json [--min-precision 0.98] [--min-recall 0.90]

Sasaran make membalut arahan tersebut:

make evaluate-routing
make evaluate-guards

Sasaran make evaluate-guards terus menggunakan masukan legasi --corpus. Gunakan --revision secara terus apabila hasil perlu mengenal pasti dokumen semakan tempatan yang tepat yang dinilai.


Regresi penghalaan (yb evaluate routing)​

Penghalaan ialah talian paip pengelas + penghala peringkat. Perubahan pada pengelas, peraturan, penetapan harga, atau penghala boleh mengubah secara senyap model yang dituju oleh gesaan. Penilaian penghalaan menyemat tingkah laku itu.

Set data. datasets/eval/golden_routing.jsonl ialah set permintaan yang berlabel. Setiap baris ialah satu permintaan (gesaan/metadata) serta peringkat penghalaan yang sepatutnya dipetakan di bawah dasar penghalaan semasa. Set ini dijana supaya sepadan dengan tingkah laku pengeluaran rule_tier, jadi ia ialah garis dasar regresi, bukan "orakel ketepatan".

Apa yang dilakukannya.

  1. Menjalankan talian paip penghalaan semasa ke atas setiap baris.
  2. Membandingkan peringkat yang terhasil dengan label golden.
  3. Melaporkan kiraan dan kadar ketidakpadanan.
  4. Dengan --save, menulis petikan (datasets/eval/routing_baseline.json) bagi pemetaan semasa. Dengan --against <file>, membandingkan larian semasa dengan garis dasar yang disimpan dan melaporkan baris yang berubah.
  5. --max-mismatch N menyebabkan arahan gagal (keluar bukan sifar) apabila lebih daripada N baris tidak sepadan — sambungkan ini ke CI untuk menangkap regresi penghalaan.

Larian yang bersih ialah larian di mana talian paip semasa menghasilkan semula peringkat golden (atau, apabila digunakan dengan --against, menghasilkan semula garis dasar yang disimpan).


Pengesanan pengawal (yb evaluate guards)​

Cangkuk pengawal (lihat Tadbir urus ejen) ialah pengesan yang berketentuan. Penilaian pengawal mengukur ketepatan dan perolehan semula terhadap korpus yang berlabel.

Set data. datasets/eval/guards_labeled.jsonl ialah set sampel yang berlabel. Baris positif mengandungi datum sensitif yang sebenar dan disahkan digit semak/Luhn (INN, SNILS, PAN, secret, atau frasa suntikan) yang sepatutnya ditanda oleh pengesan. Baris negatif adalah bersih — termasuk umpan (nombor dan rentetan yang kelihatan sensitif tetapi gagal jumlah semak, cth. jujukan 10 digit yang bukan INN yang sah) yang tidak sepatutnya ditanda oleh pengesan. Korpus dijana oleh scripts/gen_guards_corpus.py, yang mengira jumlah semak yang sah supaya label positif adalah tulen.

Apa yang dilakukannya.

  1. Menjalankan pengesan ke atas setiap baris.
  2. Menilai terhadap label: positif benar, positif palsu, negatif palsu.
  3. Melaporkan ketepatan (dikesan-dan-betul / dikesan) dan perolehan semula (dikesan / sepatutnya-dikesan).
  4. Gagal (keluar bukan sifar) apabila ketepatan < --min-precision (lalai 0.98) atau perolehan semula < --min-recall (lalai 0.90).

Nilai lalai adalah ketat dengan sengaja: pengawal yang berjalan pada mod deny mesti mempunyai ketepatan yang sangat tinggi (untuk mengelakkan penyekatan trafik yang sah) dan perolehan semula yang tinggi (untuk mengelakkan kebocoran data sensitif).

Menyemat semakan set data pengawal tempatan​

--revision FILE ialah alternatif ikut serta bagi --corpus FILE. Ia membaca dokumen JSON tempatan dengan versi skema yang nyata, ID set data dan ID sampel. Setiap muatan sampel menggunakan medan text, type dan expect yang sama seperti penilai pengawal.

Gunakan binaan yb yang commit-nya merangkumi pilihan --revision; tiada versi minimum keluaran yang berasingan untuk dipasang. Semak binari dengan yb version. Jika binari yang lebih lama melaporkan bendera --revision yang tidak dikenali, bina semula atau naik taraf kepada binaan yang mengandungi pilihan ini, atau teruskan dengan masukan legasi --corpus.

Sebagai contoh, semakan sintetik yang kecil kelihatan seperti ini:

{
"schema_version": 1,
"dataset_id": "demo-guards",
"samples": [
{
"id": "sample-detect-1",
"payload": {
"text": "<SYNTHETIC_SECRET>",
"type": "secret",
"expect": "detect"
}
},
{
"id": "sample-clean-1",
"payload": {
"text": "ordinary synthetic text",
"type": "clean",
"expect": "clean"
}
}
]
}

Simpan sebagai guards-revision.json. Jana lekapan rahsia sintetik sebelum menilainya; jangan gunakan kelayakan yang sebenar:

python3 - <<'PY'
import json
from pathlib import Path

path = Path("guards-revision.json")
revision = json.loads(path.read_text())
revision["samples"][0]["payload"]["text"] = "synthetic marker " + "sk-" + "abcdefghijklmnop12345678"
path.write_text(json.dumps(revision, indent=2) + "\n")
PY
yb evaluate guards --revision guards-revision.json

Laporan merangkumi ID set data dan revision_id SHA-256 huruf kecil bagi bait tepat yang dibaca. Simpan file yang menghasilkan keputusan dan rekodkan ID ini bersama metrik apabila larian perlu dibandingkan. Menyunting file menukar ID semakannya. Satu panggilan menilai dan mengira hash petikan bait dalam memori yang sama; jika file diganti selepas petikan itu dibaca, keputusan yang aktif masih mengenal pasti bait yang dinilainya. Panggilan yang kemudian membaca file semasa dan mungkin melaporkan ID semakan yang berbeza.

Dokumen semakan dihadkan kepada 8 MiB dan 10,000 sampel. Versi skema mesti 1; ID set data dan ID sampel mesti tidak kosong, dan ID sampel mesti unik dalam dokumen. Setiap payload mesti objek dengan text yang tidak kosong dan expect ditetapkan kepada detect atau clean. Medan yang tidak dikenali, kunci JSON yang berulang, JSON yang salah bentuk, dokumen JSON kedua yang mengikuti, dan ID sampel pendua ditolak sebelum metrik dicetak. Jika pengesahan gagal, betulkan dokumen dan jalankan arahan sekali lagi. Membekalkan --corpus dan --revision serentak ialah ralat; pilih satu mod masukan bagi setiap panggilan.

Pilihan legasi --corpus dan keluarannya kekal tersedia. Masukan semakan adalah tempatan bagi aliran CLI ini: ia tidak memuat naik atau mengekalkan sampel, menambah katalog di sebelah pelayan, atau mengubah format manifes larian yang sedia ada. ID semakan mengenal pasti masukan tepat yang digunakan untuk penilaian ini; ia tidak memperakui kualiti set data atau mendakwa bahawa pengeluar larian yang lain telah menerima pakai penyematan semakan.


Dasar garis dasar​

Suit penilaian wujud untuk mengekalkan garis dasar dan untuk membandingkan dengannya:

  • Sebelum perubahan yang mempengaruhi penghalaan atau pengawal, jalankan kedua-dua penilaian dan catat nombornya (atau --save garis dasar penghalaan).
  • Selepas perubahan, jalankan sekali lagi dan bandingkan. Regresi penghalaan kelihatan sebagai kenaikan kadar ketidakpadanan; regresi pengawal kelihatan sebagai penurunan ketepatan atau perolehan semula di bawah ambang.
  • Dalam CI, jalankan make evaluate-routing -- --max-mismatch 0 dan make evaluate-guards sebagai pintu semak. (Bajet --max-mismatch yang tepat ialah pilihan dasar: 0 adalah yang paling ketat dan hanya membenarkan pengeluaran semula yang tepat.)

Penilaian sebagai pintu semak PR (yb-eval)​

Tindakan komposit yang boleh digunakan semula di .github/actions/yb-eval/action.yml menyambungkan suit ini ke permintaan tarik:

  • membina binari yb dalam pelari daripada repositori (tiada rangkaian — penilaian penghalaan dan pengawal adalah dalam proses dan berketentuan);
  • menjalankan yb evaluate routing --against <baseline> --max-mismatch 0 dan yb evaluate guards --min-precision … --min-recall …;
  • menulis ringkasan yang boleh dibaca mesin (lulus/gagal + pembilang) ke artifak yb-eval;
  • menyiarkan satu komen ringkasan PR (diganti semasa jalankan semula, tidak diduplikasi);
  • menggagalkan langkah (tanda merah) apabila mana-mana pintu semak berwarna merah, supaya regresi penghalaan atau pengawal menggagalkan CI.

Sambungkan ke aliran kerja pull_request dengan penapis laluan pada sumber penghalaan / penetapan harga / cangkuk pengawal dan set data penilaian, cth.:

on:
pull_request:
paths:
- 'pkg/classifier/**'
- 'pkg/router/**'
- 'pkg/guardhooks/**'
- 'pkg/pricing/**'
- 'datasets/eval/**'
- 'cmd/yb/**'
jobs:
eval-gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/yb-eval
with:
comment: true

Semua masukan mempunyai lalai repositori, jadi tindakan itu boleh digunakan terus; gantikan routing-max-mismatch, guards-min-precision, atau guards-min-recall untuk melonggarkan pintu semak mengikut dasar.

Ini ialah rangka regresi, bukan suit penanda aras: ia tidak mengejar nombor mutlak "terbaik dalam kelas", ia memastikan perubahan tidak menggerakkan tingkah laku yang tidak anda maksudkan untuk digerakkan.

Nombor yang dilaporkan di sini diukur terhadap set data yang dibekalkan. Nombor itu tidak dipetik daripada mana-mana kertas putih luaran atau penilaian pihak ketiga.