CI/CD cho LLM agent: golden set, giám sát online & bánh đà cải thiện

9.1Vì sao LLM agent cần CI/CD

Làm agent chạy tốt một lần đã khó; giữ nó chạy tốt theo thời gian là bài toán khác hẳn. Có ít nhất ba lực kéo chất lượng đi xuống mà không cần bạn sửa dòng code nào: nhu cầu người dùng thay đổi (họ hỏi những thứ mới), phân bố dữ liệu trôi (mùa vụ, chiến dịch marketing, thị trường mới), và nhà cung cấp model âm thầm cập nhật. Chương 9 mượn hai thực hành từ software engineering — Continuous Integration và Continuous Deployment — nhưng gán cho mỗi cái một vai rất cụ thể:

Ví dụ của sách cho hai vai này đều lấy từ trợ lý bất động sản (Example 3-1): CI xác nhận một lỗi về địa danh đã sửa tháng trước không quay lại sau khi sửa prompt; còn CD phát hiện một tính năng mới khiến LLM "chế" ra một tên khu phố không tồn tại — thứ không test nào lường trước.

Khác gì CI/CD cho ML truyền thống?

9.2Golden dataset: thiết kế lưới an toàn

Golden dataset là tập input chọn tay kèm output tham chiếu (reference) hoặc tiêu chí kiểm tra, được tạo qua review + gán nhãn (Ch.3) và đồng thuận nhóm về "thế nào là đúng" (Ch.4). Mỗi thay đổi — sửa prompt, đổi model, thêm tool — đều chạy toàn bộ golden input qua agent rồi chấm bằng evaluator tự động (Ch.5). Sách liên hệ cách làm này với kiểu "assertion-based unit test": lấy input thật từ production, đặt vài tiêu chí cho mỗi input, và kiểm agent vẫn thoả chúng. CI ở đây là reference-based: so output mới với reference đã được người xác nhận.

Golden set tốt gồm những gì?

Ví dụ check CI (trợ lý bất động sản của sách)

Bất kỳ check nào fail trên golden case tương ứng → build fail → chặn merge. Để ý: hai trong ba check là code, rẻ và tất định; chỉ tiêu chí chủ quan (tone) mới cần judge.

Một định dạng lưu trữ đơn giản (JSONL, mỗi dòng một case) — tự soạn cho sổ tay:

{"id":"gs-007","kind":"core","critical":false,"input":"Còn ghế chuyến 7h sáng mai Hà Nội - Hải Phòng không?",
 "checks":[{"type":"tool_called","name":"search_trips"},{"type":"json_schema","tool":"search_trips","schema":"schemas/search_trips.json"}],
 "source":"trace:8f2c1a","last_audit":"2026-09-01"}
{"id":"gs-022","kind":"past_failure","critical":true,"input":"Mình huỷ vé trước 20 tiếng thì được hoàn bao nhiêu?",
 "reference":"Hoàn 70% giá vé (huỷ trước 12–24h theo chính sách v3).",
 "checks":[{"type":"regex","must_match":"70\\s*%"},{"type":"judge","criterion":"policy_faithful","judge":"judge-policy@v4"}],
 "source":"incident:INC-117","last_audit":"2026-09-01"}
{"id":"gs-041","kind":"edge","critical":false,"input":"ve di vinh mung 3 tet con ko",
 "checks":[{"type":"code","fn":"checks.lunar_date_resolved"},{"type":"judge","criterion":"tone_friendly","judge":"judge-tone@v2"}],
 "source":"trace:c19e77","last_audit":"2026-08-15"}

Bảo trì: thêm, sửa, cho nghỉ hưu

9.3Cổng CI trong thực tế: runner, ngưỡng & tính không tất định

Sách chỉ ra nguyên tắc (chạy golden set mỗi thay đổi, fail thì chặn merge) và ghi chú rằng có codebase đánh dấu test LLM là flaky để chạy lại vài lần. Phần này là tư liệu tự soạn, đi sâu vào câu hỏi thực hành: đặt ngưỡng thế nào khi chính agent đã "ồn"?

Trực giác: hai loại sai của một cái cổng

Cổng CI là một bộ phân loại nhị phân trên thay đổi: "có regression" hay "không". Nó sai theo hai cách:

Mẫu thiết kế cổng hai tầng

1. Tầng 1 — critical, không thương lượng. Case PII, hành động có hậu quả tiền bạc, lỗi từng gây sự cố. Check bằng code nếu được; nếu cần judge thì chạy k=3 lấy đa số. Fail một case = đỏ.
2. Tầng 2 — tổng thể, có dung sai. Pass rate trên phần còn lại không được thấp hơn baseline (đo trên nhánh main, cùng golden set, cùng judge đã pin) quá Δ điểm %. Δ chọn theo độ ồn đo được, không đoán.
3. Báo cáo diff theo case chứ không chỉ con số: case nào lật từ xanh sang đỏ, kèm output cũ/mới — reviewer mất 2 phút là biết regression thật hay đổi format.
4. Baseline cập nhật khi merge vào main, lưu cùng hash của golden set + version model/judge để không so táo với cam.

Runner kiểu pytest — tự soạn, chạy được với một hàm agent() và các check giả lập của bạn:

# evals/test_golden.py — chạy: pytest evals/ -q
import json, os, pathlib, statistics
import pytest
from myagent import agent                   # hàm agent(input: str) -> dict {"text":..., "tool_calls":[...]}
from evals.checks import run_check         # run_check(check: dict, case: dict, out: dict) -> bool

GOLDEN = [json.loads(l) for l in pathlib.Path("evals/golden/golden.jsonl").read_text().splitlines() if l.strip()]
K = int(os.getenv("EVAL_REPEATS", "3"))     # số lần chạy mỗi case để lấy đa số
BASELINE = json.loads(pathlib.Path("evals/baseline.json").read_text())   # {"pass_rate": 0.9, "golden_hash": "..."}
MAX_DROP = float(os.getenv("EVAL_MAX_DROP", "0.03"))                      # dung sai tầng 2: 3 điểm %

def case_passes(case) -> bool:
    votes = []
    for _ in range(K):
        out = agent(case["input"])
        votes.append(all(run_check(c, case, out) for c in case["checks"]))
    return sum(votes) > K / 2               # đa số

CRITICAL = [c for c in GOLDEN if c.get("critical")]
REGULAR = [c for c in GOLDEN if not c.get("critical")]

@pytest.mark.parametrize("case", CRITICAL, ids=[c["id"] for c in CRITICAL])
def test_critical(case):
    assert case_passes(case), f"critical case {case['id']} failed (nguồn: {case.get('source')})"

def test_regular_pass_rate(record_property):
    results = {c["id"]: case_passes(c) for c in REGULAR}
    rate = statistics.mean(results.values())
    record_property("pass_rate", rate)
    failed = [cid for cid, ok in results.items() if not ok]
    pathlib.Path("eval-report.json").write_text(json.dumps({"pass_rate": rate, "failed": failed}, indent=2))
    assert rate >= BASELINE["pass_rate"] - MAX_DROP, (
        f"pass rate {rate:.1%} < baseline {BASELINE['pass_rate']:.1%} - {MAX_DROP:.0%}; fail: {failed}")

Nối vào GitHub Actions — chỉ chạy khi file ảnh hưởng hành vi agent đổi, pin model qua biến môi trường, đăng báo cáo lên PR (YAML tự soạn):

# .github/workflows/eval-gate.yml
name: eval-gate
on:
  pull_request:
    paths: ["prompts/**", "agent/**", "tools/**", "evals/**", "models.lock.yaml"]
jobs:
  golden:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    env:
      AGENT_MODEL: ${{ vars.AGENT_MODEL_PINNED }}     # vd "provider-model-2026-06-01", KHÔNG dùng alias
      JUDGE_MODEL: ${{ vars.JUDGE_MODEL_PINNED }}
      EVAL_REPEATS: "3"
      EVAL_MAX_DROP: "0.03"
      LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install -r requirements.txt
      - name: Leakage check (golden vs prompt)
        run: python evals/check_leakage.py --golden evals/golden/golden.jsonl --prompts prompts/
      - name: Verify pinned versions
        run: python evals/check_pins.py models.lock.yaml
      - name: Run golden set
        run: pytest evals/ -q --junitxml=eval-junit.xml
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with: { name: eval-report, path: "eval-report.json" }

9.4Ba lỗi thường gặp với CI

Script kiểm tra leakage đơn giản bằng n-gram (tự soạn, ~30 dòng):

# evals/check_leakage.py
import argparse, json, pathlib, re, sys

def ngrams(text: str, n: int = 6) -> set[tuple[str, ...]]:
    toks = re.findall(r"\w+", text.lower())
    return {tuple(toks[i:i + n]) for i in range(len(toks) - n + 1)}

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--golden", required=True)
    ap.add_argument("--prompts", required=True)          # thư mục chứa prompt + few-shot + prompt của judge
    ap.add_argument("--n", type=int, default=6)
    ap.add_argument("--max-overlap", type=float, default=0.5)
    a = ap.parse_args()
    prompt_grams = set()
    for p in pathlib.Path(a.prompts).rglob("*"):
        if p.is_file() and p.suffix in {".txt", ".md", ".j2", ".yaml", ".json"}:
            prompt_grams |= ngrams(p.read_text(errors="ignore"), a.n)
    leaks = []
    for line in pathlib.Path(a.golden).read_text().splitlines():
        if not line.strip():
            continue
        case = json.loads(line)
        g = ngrams(case["input"], a.n)
        if g and len(g & prompt_grams) / len(g) >= a.max_overlap:
            leaks.append(case["id"])
    if leaks:
        print("LEAKAGE: golden cases xuất hiện trong prompt:", leaks)
        sys.exit(1)
    print("no leakage")

if __name__ == "__main__":
    main()

9.5Pin version & xem lại prompt khi model mạnh lên

Hai ý của sách gắn với nhau: (1) luôn pin đúng version có ngày của model, cho cả agent lẫn judge; (2) khi có version mới, đừng chỉ "thả vào chạy CI" mà hãy xem lại prompt. Prompt hay tích tụ các chỉ dẫn "vá" cho điểm yếu của model cũ (bắt buộc số câu, câu mở, câu kết…). Model mới có thể tự làm tốt → gỡ bớt giúp prompt rẻ hơn (ít token), nhanh hơn, đôi khi chính xác hơn vì model được dùng phán đoán của nó thay vì bám ràng buộc lỗi thời.

Manifest pin version và script kiểm tra tuổi version (tự soạn):

# models.lock.yaml — mọi model mà hệ thống gọi, kể cả judge
agent:
  primary:  { id: "provider-a/chat-large-2026-03-14", pinned_on: "2026-03-20", newer_available_since: "2026-07-02" }
  fallback: { id: "provider-b/chat-small-2026-05-01", pinned_on: "2026-05-10", newer_available_since: null }
judges:
  tone:     { id: "provider-a/chat-large-2026-03-14", validated_on: "2026-08-28", tpr: 0.93, tnr: 0.88 }
  policy:   { id: "provider-a/chat-large-2026-03-14", validated_on: "2026-08-28", tpr: 0.95, tnr: 0.86 }
policy:
  max_age_after_newer_days: 180     # quá hạn → CI cảnh báo, phải lên kế hoạch nâng cấp
  judge_revalidate_every_days: 28

# evals/check_pins.py
import re, sys, datetime as dt, yaml
ALIAS = re.compile(r"(latest|preview)$|^[^0-9]*$")   # id không có ngày = alias
cfg, today, bad = yaml.safe_load(open(sys.argv[1])), dt.date.today(), []
for group in ("agent", "judges"):
    for name, m in cfg[group].items():
        if ALIAS.search(m["id"]):
            bad.append(f"{group}.{name}: '{m['id']}' là alias, phải pin version có ngày")
        newer = m.get("newer_available_since")
        if newer and (today - dt.date.fromisoformat(newer)).days > cfg["policy"]["max_age_after_newer_days"]:
            print(f"WARN {group}.{name}: đã có bản mới hơn {newer}, quá hạn nâng cấp")
        v = m.get("validated_on")
        if v and (today - dt.date.fromisoformat(v)).days > cfg["policy"]["judge_revalidate_every_days"]:
            print(f"WARN judges.{name}: cần tái kiểm định (lần cuối {v})")
sys.exit("\n".join(bad) if bad else 0)

9.6CD bước 1: observability — log gì, đọc thế nào

CI lo những gì đã biết; CD theo dõi production — nơi người dùng hỏi những thứ không có trong golden set. Mọi thứ bắt đầu từ log. Với mỗi request (hoặc một mẫu đại diện), sách liệt kê cần ghi: input + metadata (user/session id, cờ tính năng), mọi LLM call trung gian (prompt, response, suy luận trung gian), mọi tool call (tên, tham số, kết quả, lỗi), tài liệu được retrieve, output cuối, feedback người dùng (thumb, chỉnh sửa, câu hỏi tiếp) và kết quả evaluator nếu có.

Công cụ sách nhắc: LangSmith, Arize Phoenix, W&B Weave, hoặc tích hợp OpenTelemetry. Khuyến nghị: xem một mẫu trace production mỗi ngày — vừa luyện cảm giác chất lượng, vừa thấy pattern mới sớm.

Một trace tối thiểu nhưng đủ để tái dựng tương tác (JSON tự soạn):

{
  "trace_id": "tr_9c41", "session_id": "ss_22a0", "ts": "2026-09-21T08:14:03Z",
  "input": {"text": "đổi vé 7h mai sang chuyến 9h được không", "channel": "zalo", "flags": {"promo_banner": true}},
  "versions": {"prompt": "v12", "agent_model": "provider-a/chat-large-2026-03-14", "router_policy": "r-2026-09-10"},
  "spans": [
    {"type": "llm", "name": "plan", "latency_ms": 820, "tokens_in": 1840, "tokens_out": 96},
    {"type": "tool", "name": "search_trips", "args": {"route": "HN-HP", "date": "2026-09-22", "after": "09:00"},
     "latency_ms": 140, "status": "ok", "result_count": 3},
    {"type": "tool", "name": "change_ticket", "args": {"ticket_id": "T-5521", "new_trip": "HP0900"},
     "status": "error", "error": "fee_confirmation_required"},
    {"type": "llm", "name": "respond", "latency_ms": 1210, "tokens_out": 142}
  ],
  "output": "Chuyến 9h còn 4 ghế. Đổi vé mất phí 20.000đ, bạn xác nhận nhé?",
  "guardrails": [{"name": "pii", "tripped": false}, {"name": "price_format", "tripped": false}],
  "feedback": {"thumb": null, "followup_within_60s": true},
  "evals": {"sampled": true, "policy_faithful": "pass", "tone": "pass"}
}

9.7CD bước 2: evaluator trên production, hiệu chỉnh & alert

Có log rồi, ta chạy evaluator tự động (Ch.5) trên mẫu trace. Cấu hình điển hình theo sách: 5–7 evaluator, trộn code-based và LLM-as-judge, mỗi cái theo một failure mode đã biết. Judge chậm và đắt nên thường chấm 1–5% traffic, bất đồng bộ sau khi request xong. Với mỗi failure mode, tính success rate đã hiệu chỉnh theo TPR/TNR đã đo của judge cùng khoảng tin cậy 95% bằng bootstrap, đưa lên dashboard và alert khi dải tin cậy vượt ngưỡng.

Tính rate hiệu chỉnh + bootstrap (tự soạn, numpy):

import numpy as np
rng = np.random.default_rng(0)

def corrected(p_obs, tpr, tnr):
    """Hiệu chỉnh tỷ lệ pass thô theo độ chính xác đã biết của judge (kẹp vào [0,1])."""
    return float(np.clip((p_obs + tnr - 1) / (tpr + tnr - 1), 0, 1))

def bootstrap_ci(judge_prod, human_lab, judge_lab, B=2000, alpha=0.05):
    """judge_prod: 0/1 judge chấm trên trace production (không có nhãn người).
       human_lab, judge_lab: 0/1 trên tập kiểm định có nhãn người (dùng để ước TPR/TNR)."""
    judge_prod, human_lab, judge_lab = map(np.asarray, (judge_prod, human_lab, judge_lab))
    stats = []
    for _ in range(B):
        jp = rng.choice(judge_prod, size=len(judge_prod))          # resample production
        idx = rng.integers(0, len(human_lab), len(human_lab))       # resample tập kiểm định
        h, j = human_lab[idx], judge_lab[idx]
        tpr = (j[h == 1] == 1).mean() if (h == 1).any() else np.nan
        tnr = (j[h == 0] == 0).mean() if (h == 0).any() else np.nan
        if np.isnan(tpr) or np.isnan(tnr) or tpr + tnr - 1 <= 0.05:
            continue                                                 # judge gần như ngẫu nhiên: bỏ mẫu
        stats.append(corrected(jp.mean(), tpr, tnr))
    lo, hi = np.quantile(stats, [alpha / 2, 1 - alpha / 2])
    return float(np.median(stats)), float(lo), float(hi)

def should_alert(ci_hi, threshold=0.90):
    return ci_hi < threshold      # chỉ báo khi CẢ dải tin cậy nằm dưới ngưỡng (ít báo nhầm)

Đọc dashboard: alert khi khoảng tin cậy chạm ngưỡng

9.8Guardrails: kiểm tra ngay trên đường trả lời

Phần lớn evaluator chạy sau sự việc. Guardrail thì khác: nó chạy trong lúc thực thi, trước khi output tới người dùng. Vì nằm trên critical path nên phải nhanh và có tỷ lệ báo nhầm rất thấp — điều này gần như loại LLM judge (vài giây mỗi lần gọi, người dùng sẽ cảm nhận). Thứ hợp: check tất định vài mili-giây như regex, JSON schema, blocklist/allowlist, kiểm độ dài/format, parser nhẹ (parse SQL, parse AST Python). Về bản chất, guardrail chỉ là một hàm được gọi trên mọi output: kiểm nhanh, log khi nó kích hoạt, và có phản ứng định sẵn.

Thứ tự ưu tiên: không thương lượng trước, sở thích sau

Wrapper guardrail có chính sách cấu hình được (tự soạn — khác ví dụ trong sách, dùng schema + PII kiểu Việt Nam):

import json, re, time
from dataclasses import dataclass
from typing import Callable, Optional

PHONE_VN = re.compile(r"(?<!\d)(?:\+?84|0)(?:3|5|7|8|9)\d{8}(?!\d)")    # SĐT di động VN
CCCD     = re.compile(r"(?<!\d)\d{12}(?!\d)")                          # căn cước 12 số

@dataclass
class Verdict:
    ok: bool
    rule: Optional[str] = None
    severity: str = "none"            # "block" (không thương lượng) | "retry" | "log"

def check(output: str, allowed_phones: set[str]) -> Verdict:
    for m in PHONE_VN.findall(output):
        if m not in allowed_phones:                       # số hotline công ty thì cho phép
            return Verdict(False, "pii_phone", "block")
    if CCCD.search(output):
        return Verdict(False, "pii_cccd", "block")
    try:
        data = json.loads(output)
    except ValueError:
        return Verdict(False, "not_json", "retry")
    if not {"answer", "citations"} <= data.keys():
        return Verdict(False, "schema_missing_keys", "retry")
    if len(data["answer"].split()) > 250:
        return Verdict(False, "too_long", "log")            # sở thích: chỉ log
    return Verdict(True)

def guarded(call: Callable[[str], str], fallback: Callable[[str], str], log: Callable[..., None],
            req: str, allowed_phones: set[str], max_retry: int = 1) -> str:
    for attempt in range(max_retry + 1):
        t0 = time.perf_counter()
        out = call(req)
        v = check(out, allowed_phones)
        log(rule=v.rule, attempt=attempt, check_ms=(time.perf_counter() - t0) * 1000, ok=v.ok)
        if v.ok or v.severity == "log":
            return out
        if v.severity == "block":
            return json.dumps({"answer": "Xin lỗi, câu trả lời chứa thông tin nhạy cảm nên đã bị chặn. "
                               "Mình chuyển bạn tới nhân viên hỗ trợ.", "citations": []}, ensure_ascii=False)
    return fallback(req)                                    # retry hết lượt → đường dự phòng

9.9Judge drift: khi chính "giám khảo" trôi

TPR/TNR bạn đo lúc kiểm định judge (Ch.5) không đứng yên. Sách nêu hai nguồn trôi, và nhấn mạnh rằng nếu không chủ động kiểm tra thì độ chính xác của judge sẽ xuống cấp mà không ai nhận ra:

1. Pin version judge ở cả CI và production (id có ngày, không alias).
2. Tái kiểm định định kỳ (vài tuần/lần): lấy trace mới, gán nhãn người, tính lại TPR/TNR; tụt dưới ngưỡng → sửa prompt/few-shot của judge, kiểm định lại rồi mới deploy.
3. Đổi LLM của judge → chạy lại toàn bộ quy trình kiểm định.

Script tái kiểm định định kỳ (tự soạn):

# evals/revalidate_judge.py — chạy mỗi 4 tuần (cron) trên trace mới đã được người gán nhãn
import json, sys
from sklearn.metrics import confusion_matrix

MIN_TPR, MIN_TNR = 0.85, 0.80

def revalidate(labels_path: str, judge_fn, judge_id: str):
    rows = [json.loads(l) for l in open(labels_path) if l.strip()]   # {"trace": ..., "human": 0/1}
    human = [r["human"] for r in rows]
    judge = [judge_fn(r["trace"]) for r in rows]                      # judge_fn dùng đúng judge_id đã pin
    tn, fp, fn, tp = confusion_matrix(human, judge, labels=[0, 1]).ravel()
    tpr, tnr = tp / (tp + fn), tn / (tn + fp)
    report = {"judge": judge_id, "n": len(rows), "tpr": round(tpr, 3), "tnr": round(tnr, 3),
              "ok": tpr >= MIN_TPR and tnr >= MIN_TNR}
    print(json.dumps(report, ensure_ascii=False))
    if not report["ok"]:
        sys.exit("Judge dưới ngưỡng: sửa prompt/few-shot, kiểm định lại trước khi dùng tiếp")
    return report   # ghi tpr/tnr mới vào models.lock.yaml để dashboard hiệu chỉnh đúng

9.10Mở rộng: triển khai an toàn — shadow, canary, rollback

Sách tập trung vào CI (trước deploy) và monitoring (sau deploy). Giữa hai thứ đó, thực hành DevOps phổ biến là triển khai từng bậc — phần này là mở rộng của sổ tay, dùng đúng các công cụ của chương (evaluator, guardrail, trace) nhưng áp vào một nhóm traffic nhỏ trước khi mở rộng.

9.11Bánh đà cải thiện liên tục

CI và CD không phải hai công đoạn rời: chúng nối thành vòng lặp. Deploy kèm monitoring → phát hiện vấn đề ở production → chẩn đoán bằng error analysis → cải thiện agent và cập nhật evaluator → xác nhận bản sửa qua CI → deploy lại. Mỗi vòng làm hệ thống vững hơn và bộ eval đầy đủ hơn.

Một vòng quay theo sách (trợ lý bất động sản)

9.12Pitfalls thường gặp

• Golden set đóng băng trong khi traffic tiến hoá → CI mất giá trị dần. Ví dụ: golden set soạn trước khi có kênh Zalo; nửa năm sau 40% traffic đến từ Zalo với câu cực ngắn, không dấu — CI không có case nào như vậy. Mỗi vòng bánh đà phải thêm ví dụ từ lỗi thật.
• Metric xung đột (ngắn gọn ↔ đủ thông tin chính xác): xếp thứ ưu tiên trước khi xung đột xảy ra; an toàn luôn đứng đầu. Ví dụ: ShopMate ngày 0 — "ngắn gọn" cắt mất điều kiện chính sách.
• Metric AI tách rời metric sản phẩm: satisfaction giảm có thể do AI hoặc do UX — điều tra cả hai; nếu do AI (vd dài dòng khiến người dùng bỏ đi), định nghĩa failure mode + evaluator mới.
• Chỉ nhìn monitoring tự động: judge bỏ sót lỗi tinh vi. Đọc cả trace ngẫu nhiên, không chỉ trace bị flag. Engagement giảm mà metric evaluator phẳng → có lỗi chưa ai thấy.
• Dùng alias model cho agent hoặc judge → hai thứ cùng trôi, regression gần như không thể chẩn đoán.
• Leakage: ví dụ golden lọt vào few-shot (của agent hoặc judge) → CI xanh giả.
• (Mở rộng) Re-run CI tới khi xanh: biến CI thành trò may rủi; cố định k và luật đa số trong runner.
• (Mở rộng) Alert trên trung bình ngày với mẫu nhỏ: kêu liên tục rồi bị tắt tiếng; dùng dải tin cậy và cửa sổ phù hợp mức nghiêm trọng.
• (Mở rộng) Bật guardrail thẳng ở chế độ chặn: không đo báo nhầm trên trace hợp lệ và không chạy log-only trước.

9.13Áp dụng cho dự án model-routing

Router của bạn quyết định mỗi request LLM đi tới model nào để cân bằng chất lượng, chi phí và latency. Về mặt CI/CD, router có hai điểm đặc biệt so với một agent thường: (1) nó phụ thuộc vào nhiều model đích cùng lúc, nên mọi thay đổi ngầm ở bất kỳ provider nào cũng làm lệch "bảng năng lực" mà router dựa vào; (2) lỗi của router thường không lộ ra ở output — route nhầm lên model đắt vẫn cho câu trả lời tốt, chỉ là tốn tiền; route nhầm xuống model rẻ có khi vẫn "tạm được". Vì thế cần đo cả quyết định lẫn kết quả. Phần này nối với bản blueprint bạn đã viết (playground/jcode-evaluation-study/04-blueprint-for-model-routing-eval.md): Eval A (độ đúng quyết định route), Eval B (kết quả/cost–quality), Eval C (cấu hình + sức khoẻ provider), và các nguyên tắc negative control, coverage lock, pinned manifest.

1 · Golden set cho router = nhãn quyết định, không chỉ nhãn output

Mỗi case lưu tập tier chấp nhận được (không chỉ một đáp án), vì thường có nhiều lựa chọn đúng. Từ đó định nghĩa bốn chỉ số khác nhau về hậu quả:

Coverage lock: mỗi nhóm request (FAQ, code, trích xuất, suy luận nhiều bước, ngôn ngữ, độ dài) có số case tối thiểu; CI fail nếu PR xoá case làm một nhóm tụt dưới mức khoá — tránh "sửa" golden set cho vừa router.

Cổng CI cho router (tự soạn):

# evals/router_gate.py — chạy trong CI khi router/** hoặc models.lock.yaml đổi
import json, sys, collections
from router import route                     # route(request: dict) -> "S" | "M" | "L"

TIER = {"S": 0, "M": 1, "L": 2}
PRICE = {"S": 0.0004, "M": 0.0020, "L": 0.0120}   # $/request trung bình, lấy từ bảng giá đã pin
GATES = {"max_under": 0.02, "max_over": 0.10, "max_cost_increase": 0.10}
COVERAGE_LOCK = {"faq": 25, "code": 25, "extract": 20, "multistep": 25, "long_ctx": 15, "neg_control": 20}

cases = [json.loads(l) for l in open("evals/router_golden.jsonl") if l.strip()]
base = json.load(open("evals/router_baseline.json"))          # {"cost": 0.0021, ...}
cov = collections.Counter(c["group"] for c in cases)
errors = [f"coverage {g}: {cov[g]} < {m}" for g, m in COVERAGE_LOCK.items() if cov[g] < m]

under = over = neg_fail = 0
cost = 0.0
for c in cases:
    t = route(c["request"])
    lo, hi = TIER[c["min_tier"]], TIER[c["max_tier"]]       # tập chấp nhận = [min_tier, max_tier]
    under += TIER[t] < lo
    over += TIER[t] > hi
    neg_fail += c["group"] == "neg_control" and TIER[t] > hi
    cost += PRICE[t]
n = len(cases); cost /= n
report = {"n": n, "under": under / n, "over": over / n, "neg_fail": neg_fail, "cost": cost,
          "cost_delta": cost / base["cost"] - 1}
print(json.dumps(report, indent=2))
if report["under"] > GATES["max_under"]: errors.append("under-routing vượt ngưỡng")
if neg_fail: errors.append(f"{neg_fail} negative control bị đẩy lên tier cao")
if report["over"] > GATES["max_over"]: errors.append("over-routing vượt ngưỡng")
if report["cost_delta"] > GATES["max_cost_increase"]: errors.append("chi phí dự kiến tăng quá hạn mức")
sys.exit("\n".join(errors) if errors else 0)

2 · Pin mọi thứ — và coi cập nhật model đích là một PR

• Manifest pin (models.lock.yaml) chứa id có ngày của mọi model đích + judge + bảng giá tại thời điểm đo. Mỗi trace ghi router_policy + id model thực sự được gọi.
• Provider ra version mới cho tier M: PR đổi manifest → chạy lại Eval B cho các nhóm request thường đi tier M và các nhóm "biên" giữa S/M, M/L. Nếu tier M mới mạnh lên, ngưỡng router có thể nên dịch (đẩy bớt từ L xuống M) — đó là "xem lại prompt khi model mạnh lên" phiên bản router.
• Behavioral drift dưới cùng version (sách cảnh báo có xảy ra): chạy hằng đêm một bộ "canary prompts" nhỏ cho từng model đích; nếu điểm của một tier lệch mà không ai đổi gì → nghi provider, không nghi router.
• Giá cũng là version: provider đổi giá làm lệch cổng chi phí dù hành vi không đổi — lưu bảng giá cùng manifest, đổi giá = PR.

3 · Monitoring online cho router

4 · Guardrail của router = Retry/Fallback theo tier

• Trước khi route (inter-step, tất định): request vượt context window của tier → không được chọn tier đó; request chứa PII + tier dùng provider không đạt yêu cầu dữ liệu → loại.
• Sau khi model trả lời: output fail schema/parse → escalate lên tier kế (đây chính là Fallback của sách, nhưng đi lên thay vì xuống). Giới hạn 1 lần escalate để chặn chi phí nổ.
• Mỗi lần escalate là một nhãn miễn phí: "tier S không đủ cho request này". Gom định kỳ, error analysis, và đưa các mẫu tiêu biểu vào golden set với min_tier = M — bánh đà của router.
• Budget guardrail: nếu chi phí giờ hiện tại vượt X lần kế hoạch, tạm khoá tier L cho các nhóm không critical — quyết định trước, không lúc sự cố.

5 · Shadow routing trước mọi thay đổi policy

1. Chạy policy ứng viên song song trên 100% traffic, chỉ ghi quyết định (rẻ: không gọi model).
2. Đo bất đồng: % request hai policy chọn khác nhau, theo nhóm và theo hướng (ứng viên chọn thấp hơn hay cao hơn).
3. Phân xử offline một mẫu bất đồng: chạy cả hai model, chấm bằng judge đã kiểm định (hoặc người) → ước lượng chất lượng và chi phí của policy mới chỉ trên vùng khác biệt — hiệu quả hơn nhiều so với canary mù.
4. Chỉ khi ước lượng trên vùng bất đồng đạt cổng mới canary; case bất đồng đã phân xử được thêm vào golden set.

9.14Checklist triển khai

1. Golden set 20–50 case (cốt lõi + lỗi cũ + edge case + phủ nhánh), metadata nguồn/critical/audit, lưu tách khỏi prompt.
2. Cổng CI hai tầng mỗi PR: critical không thương lượng; tổng thể có dung sai so với baseline; k lần chạy cố định; judge pin version.
3. Leakage check tự động (golden vs prompt agent + prompt judge).
4. Pin version mọi model; chính sách tuổi version; nâng cấp = PR qua CI + error analysis lại.
5. Log trace đầy đủ (spans, versions, feedback); đọc mẫu trace ngẫu nhiên hằng ngày.
6. 5–7 evaluator online trên 1–5% traffic (phân tầng khi cần); rate hiệu chỉnh + dải 95%; alert theo dải.
7. Guardrail tất định, đo báo nhầm < 1% trên trace hợp lệ, log-only trước; Reject/Retry/Fallback định sẵn; theo dõi tỷ lệ trip như một time series.
8. Tái kiểm định judge vài tuần/lần và mỗi khi judge hoặc tiêu chí đổi.
9. (Mở rộng) Shadow/canary với cổng và luật rollback định trước.
10. Quay bánh đà: mỗi lỗi mới từ production → golden case + evaluator → sửa → CI → deploy.

Tự kiểm tra

Tóm tắt diễn giải bằng tiếng Việt cho mục đích học tập cá nhân, không phải bản dịch. Ví dụ, code, bài tập, case study và lab là tư liệu tự soạn; số liệu trong đó là minh hoạ. Nguồn: Evals for AI Engineers — Shreya Shankar & Hamel Husain, O'Reilly (Early Release).