05 Khép kín vòng lặp

Tài liệu dành cho giảng viên, đi cùng bài học 05 Khép kín vòng lặp.

Thời lượng

Tổng cộng khoảng 25 phút.

• 5 phút — tạo và promote ba bản ghi có nguồn gốc production.
• 5 phút — khởi chạy hai experiment đối chứng policy-v1 và policy-v2.
• 5 phút — so sánh correctness và hiệu chỉnh business-policy-adherence.
• 5 phút — bật observation rule có kiểm soát và replay bốn loại metric.
• 5 phút — kiểm tra bằng chứng, thảo luận rollback, chi phí và vòng feedback tiếp theo.

Hai experiment và evaluator bất đồng bộ có thể mất lâu hơn các khung thời gian này. Hãy khởi chạy sớm, dùng thời gian chờ cho phần giải thích khái niệm và diễn tập độ trễ của provider từ ngày hôm trước.

Chuẩn bị của giảng viên

Trước workshop, chạy các lệnh kiểm tra không thay đổi trạng thái sau tại thư mục gốc của lab và xác minh cấu hình đã chọn tồn tại:

cd ClickHouse_Demos/workshops/agent_arena
.venv/bin/python -m scripts.promote_to_golden --help
.venv/bin/python -m scripts.provision_online_evaluators --help
.venv/bin/python -m eval.harness --help
.venv/bin/python -m scripts.verify_online_scores --help

Sau đó xác nhận:

• Mô-đun 03 có root chat_turn có thẩm quyền với sql-execution-success=true và Boolean user-thumbs=false;
• Annotation task chỉ trên UI production-investigation-<session> của Mô-đun 04 đã hoàn tất, SQL sửa đã được thực thi, trace ID thật được giữ riêng và annotation task ID được ghi lại khi Langfuse hiển thị;
• reviewed.json sẽ được tạo từ review thật đó, không phải fixture tổng hợp được track;
• WINNER_MODEL, WINNER_PROMPT và WINNER_CONFIG_ID cùng mô tả cấu hình chiến thắng của lớp;
• kết nối Langfuse LLM agent-arena-openrouter gọi được model judge đã cấu hình và có thông tin xác thực hợp lệ;
• structured categorical output của judge nhận chính xác PASS, FAIL và NOT_APPLICABLE, kèm reasoning; và
• evaluator dispatcher hoạt động, lớp có thể nhận score bất đồng bộ.

Trong mỗi lần diễn tập, tạo một hậu tố duy nhất và giữ cặp baseline/candidate đi cùng nhau:

export LOOP_RUN_SUFFIX="$(date +%Y%m%d-%H%M%S)"
export BASELINE_RUN_ID="online-loop-baseline-${LOOP_RUN_SUFFIX}"
export CANDIDATE_RUN_ID="online-loop-candidate-${LOOP_RUN_SUFFIX}"

Không dùng lại run ID của session trước. Harness nối thêm phiên bản chính sách và config; base ID duy nhất giúp học viên không so sánh các run không liên quan hoặc bằng chứng bị ghi đè một phần.

Ranh giới annotation thủ công

Annotation của con người ở Mô-đun 04 có chủ đích không được tự động hóa. Script runtime không tạo queue, điền đánh giá của con người, nhập corrected output, phê duyệt item hay hoàn tất task. Fixture tổng hợp được track hữu ích để giảng viên diễn tập khi chưa có review thật, nhưng luôn mang source=synthetic-reviewed-fixture và không chứng minh vòng lặp annotation của con người đã hoàn tất.

Trong lộ trình người học, dùng reviewed.json thật đã được ignore. Câu đầu tiên là nguyên văn câu hỏi có feedback của người dùng; hai input còn lại là cách diễn đạt do người review tạo, bắt nguồn từ chính sự cố đã review:

How many active customers do we have?
What is our active customer count right now?
How many customers qualify as active under our business definition?

Cả ba giữ chung source trace thật và nguồn gốc annotation. Hãy nói rõ để học viên không nhầm một sự cố production thành ba trace feedback độc lập.

Độ tin cậy và nguồn gốc khi promotion

Trước khi lớp chạy promotion, kiểm tra reviewed.json nhưng không trình chiếu. File phải chứa SQL chỉ đọc đã sửa đúng, nguồn gốc production bắt buộc và ba ID duy nhất an toàn. Script promotion trước hết xác thực toàn bộ batch cục bộ, sau đó đọc metadata để kiểm tra trước khi thực thi ClickHouse hay upsert dataset. Script fail-closed nếu không đọc được metadata và từ chối ID xung đột có nguồn gốc production thật khác nhau.

Lặp lại một promotion thật hoàn toàn giống nhau là bình thường. Fixture tổng hợp bắt buộc dùng flag --synthetic-fixture; không thể truyền trực tiếp đường dẫn hay kết hợp với reviewed.json. Không chạy fixture sau promotion thật. Nếu có collision, giữ nguyên cả hai nguồn, điều tra dataset item hiện có và chỉ chọn ID mới đã review khi hai item thật sự đại diện cho hai trường hợp khác nhau.

Experiment rule và observation rule

Giữ hai bối cảnh này hiển thị trên trang chiếu hoặc bảng trắng:

Provisioner cài một evaluator tổng quát dựa trên catalog, không phải evaluator chỉ đếm khách hàng. Catalog policy-v2 bao gồm khách hàng đang hoạt động, doanh thu, chuyển đổi từ xem sang mua và biên lợi nhuận gộp; câu hỏi không liên quan phải nhận NOT_APPLICABLE.

Phase --business-policy-experiments phải báo online rule enabled=False. Kiểm tra rule trên Langfuse UI như lớp bảo vệ thứ hai. Lệnh enable sau đó chứng minh có ít nhất một score business-policy-adherence trong phạm vi dataset, nhưng không thay thế review calibration đầy đủ của giảng viên.

Cổng hiệu chuẩn

So sánh baseline và candidate trên cùng item ID, model và prompt. Repo có 20 câu hỏi YAML, nhưng q019 và q020 là few-shot holdout, nên project sạch bắt đầu với 18 Experiment item và đạt 21 sau ba lần promotion. Project dùng chung đã xác minh có 22 item chỉ vì còn giữ một approved item cũ không liên quan; paired run mới nhất tăng từ 16/22 lên 19/22. Hãy xem đó là bằng chứng có điều kiện, không phải số item learner bắt buộc phải có hay cam kết rằng provider ngẫu nhiên sẽ tái tạo chính xác mọi aggregate.

Không kích hoạt trừ khi tất cả các cổng đều vượt qua:

• cả ba case prod-active-* chuyển từ FAIL và sai dưới policy-v1 thành PASS và đúng dưới policy-v2;
• revenue candidate (q005) và conversion (q018) là PASS;
• phép đếm đơn giản (q001) là NOT_APPLICABLE;
• correctness của mọi item có sẵn được so sánh từng item và không có regression 1→0;
• correctness tổng hợp không regression; và
• mọi Experiment item có correctness, agent-arena-llm-judge và đúng score business-policy-adherence với structured output hợp lệ.

Một judge gắn PASS cho mọi phép đếm vẫn chưa được hiệu chỉnh, dù candidate trông tốt. Dùng case NOT_APPLICABLE để chứng minh bước xác định khả năng áp dụng chính sách là một phép phân loại thật sự.

Xử lý score bất đồng bộ và score bị thiếu

Cả đánh giá Experiment lẫn observation đều bất đồng bộ. Harness chờ các Experiment score bắt buộc; scripts.verify_online_scores polling score trực tiếp trong 180 giây theo mặc định. Không refresh liên tục, tạo lại rule hay enable sớm chỉ vì score đang chờ xử lý.

Nếu điểm không xuất hiện:

1. Xác nhận đúng tên dự kiến. Experiment dùng business-policy-adherence; serving observation dùng agent-arena-business-policy-online.
2. Xác nhận evaluator dispatcher/worker hoạt động.
3. Kiểm tra kết nối agent-arena-openrouter và khả năng truy cập model judge. Provider chậm, rate limit hoặc hạn chế routing có thể khiến đánh giá chờ hoặc lỗi dù agent response thành công.
4. Xác nhận Experiment rule nhắm dataset arena-golden, còn observation rule nhắm root observation chat_turn. Mapping phải hiển thị $.question và $.sql.
5. Kiểm tra structured output. Thiếu category, category ngoài ba giá trị cho phép hoặc thiếu reasoning đều là lỗi calibration.
6. Nếu provisioner báo tên rule mơ hồ, dừng lại và xử lý chính xác các rule trùng tên trong Langfuse trước khi thử lại; không đoán bản sao nào đã được update.

Giữ lại trace lỗi và bằng chứng đánh giá. Không biến sự cố provider thành một PASS giả tạo hoặc bỏ qua cổng score bị thiếu.

Hướng dẫn replay

Sau khi enable, khởi động lại serving với policy-v2 được chỉ định rõ và dùng đúng bốn câu hỏi:

How many active customers do we have?
What was revenue in the last 30 days?
What is our view-to-purchase conversion rate for the last 7 days?
How many products are there?

Yêu cầu mọi trace đều thành công về vận hành. Khách hàng đang hoạt động, doanh thu và tỷ lệ chuyển đổi phải có agent-arena-business-policy-online=PASS; phép đếm sản phẩm phải là NOT_APPLICABLE.

Câu hỏi tỷ lệ chuyển đổi có biên ngẫu nhiên đã được kiểm chứng. Cho phép retry tối đa một lần với cùng cấu hình, giữ cả trace ID lẫn kết quả và dừng nếu cả hai lần không đạt. Thất bại lặp lại là bằng chứng production mới cần điều tra, không phải lý do retry cho đến khi có kết quả xanh.

Sampling, chi phí và độ tin cậy

Rule workshop dùng sampling 1 để mọi trace đủ điều kiện đều tạo bằng chứng rõ ràng. Ở quy mô production, đánh giá LLM cho mọi request làm tăng chi phí provider, tiêu tốn rate limit và có thể tạo score sau khi người dùng đã nhận response. Chọn tỷ lệ sampling dựa trên traffic, rủi ro sự cố, chi phí/độ trễ evaluator và độ bao phủ bắt buộc. Giữ các kiểm tra vận hành có tính xác định ở phạm vi rộng; dành semantic judge tốn kém cho traffic và metric xứng đáng.

Evaluator giám sát chứ không nằm trên đường request có quyền chặn. Judge chậm không được âm thầm chặn serving response. Hãy chuyển score bị thiếu, category drift và mâu thuẫn tín hiệu thành cảnh báo vận hành hoặc backlog review theo mục tiêu dịch vụ của hệ thống.

Rollback và đặt lại

Nếu observation judge tạo false pass, false fail, output sai định dạng hoặc chi phí/độ trễ không chấp nhận được sau khi enable:

1. Mở Langfuse Evaluations, tìm đúng observation rule agent-arena-business-policy-online và chuyển sang disabled.
2. Xác nhận observation chat_turn mới không còn nhận score từ online rule đó.
3. Tiếp tục chạy policy-v2, sql-execution-success và 👍/👎 trừ khi bằng chứng riêng của chúng cho thấy cần dừng; tắt một judge lỗi không nên đưa chính sách cũ đã biết trở lại.
4. Thêm trace bị ảnh hưởng vào queue con người có hậu tố, cải thiện catalog/prompt của evaluator và dữ liệu vàng, rồi lặp lại calibration bằng experiment đối chứng trước khi enable lại.

Để dừng dịch vụ cục bộ mà không xóa bằng chứng từ xa:

scripts/arena.sh stop

scripts/arena.sh down còn xóa database ClickHouse của workshop và user chỉ đọc, nhưng không xóa Langfuse dataset, Experiment run, annotation queue hay score. Không dùng lệnh này như thao tác rollback evaluator.

Nội dung dẫn dắt: vòng lặp vẫn tiếp tục

• Evaluator ban đầu đạt vì hợp đồng của nó chỉ kiểm tra “SQL có thực thi hay không”. Lượt 👎 của người dùng làm lộ lỗi giá trị nằm ngoài hợp đồng đó.
• Review của con người biến một tín hiệu chưa chắc chắn thành chẩn đoán và bản sửa đã kiểm thử.
• Nguồn gốc production giúp sự cố vẫn kiểm toán được khi vào bộ dữ liệu vàng; các cách diễn đạt bổ sung tăng độ bao phủ câu chữ mà không giả tạo thêm trace người dùng.
• Experiment đối chứng tách thay đổi chính sách khỏi thay đổi model/prompt và kiểm thử judge tổng quát trước production.
• PASS online không làm phản hồi người dùng lỗi thời. Trong tương lai, agent-arena-business-policy-online=PASS cộng với user-thumbs=false chính xác là đúng là loại mâu thuẫn cần khởi động lại cuộc điều tra.

Cổng hoàn tất

Không kết thúc mô-đun cho đến khi lớp trình bày được cả sáu bằng chứng:

1. trace production có tín hiệu vận hành đạt và tín hiệu người dùng tiêu cực;
2. annotation của con người đã hoàn tất cùng SQL sửa đã xác minh;
3. ba item vàng có nguồn gốc production thật;
4. bằng chứng baseline/candidate trên cùng dataset, không có regression correctness hiện có;
5. bằng chứng Experiment đã hiệu chỉnh cho FAIL, PASS và NOT_APPLICABLE; và
6. score online đã bật cho khách hàng đang hoạt động, doanh thu, tỷ lệ chuyển đổi và phép đếm đơn giản, trong khi 👍/👎 vẫn tiếp tục sẵn sàng cho vòng lặp tiếp theo.