03 Phát hành và phát hiện

Ghi chú giảng viên để phát hành chính sách lỗi thời đã seed và minh họa một điểm mù đánh giá online thực tế.

Tài liệu dành cho giảng viên, đi cùng bài học 03 Phát hành và phát hiện.

Thời lượng

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

3 phút — giải thích đánh giá vận hành khác với giá trị người dùng như thế nào.
4 phút — trình bày bước kiểm tra trước và phát hành cấu hình đã chọn với policy-v1.
4 phút — đặt câu hỏi nghiệp vụ trong Chat và thu thập 👎 cho câu trả lời.
4 phút — tìm trace Chat, xác minh cả hai điểm số và tái hiện bằng curl.

Kiểm tra trước từ ngày hôm trước

Chạy các lệnh này với đúng cấu hình bạn dự kiến lớp sẽ chọn. Cấu hình dự phòng đã được kiểm chứng là qwen3.7-flash__P2_fewshot:

cd ClickHouse_Demos/workshops/agent_arena
source .env
export WINNER_CONFIG_ID="${WINNER_CONFIG_ID:-qwen3.7-flash__P2_fewshot}"
.venv/bin/python -m schema.gen_schema_context
.venv/bin/python -m scripts.check_online_eval_scenario \
  --config-id "$WINNER_CONFIG_ID"
.venv/bin/python -m scripts.provision_online_evaluators --operational

Bước kiểm tra trước chỉ thực hiện một lần thử lại có giới hạn khi kết quả đầu tiên của một cách diễn đạt là ok/unknown, và chỉ thử lại đúng cách diễn đạt cùng cấu hình đó. Mọi lỗi khác đều là kết quả cuối cùng; không cách diễn đạt nào được thử lại quá một lần.

Không dựa vào trí nhớ. Hãy xác nhận đầy đủ các điều kiện sau trong chính môi trường sẽ dùng cho workshop:

stale_count và current_count đều xuất hiện và có giá trị khác nhau;
cả ba phân loại đều là policy-v1;
dòng cuối cùng cho biết sự cố có thể tái diễn được;
evaluator sql-execution-success tồn tại; và
rule agent-arena-sql-execution-online đang bật.

Với Qwen, phải tắt OpenRouter Settings → Privacy → Data Policies → Zero Data Retention → Non-frontier để route Alibaba đủ điều kiện. Chỉ thay đổi thiết lập này sau khi xem xét yêu cầu xử lý dữ liệu của sự kiện. Học viên cần runtime key có hạn mức, tuyệt đối không dùng provisioning key của giảng viên.

Nội dung dẫn dắt

Bắt đầu bằng cấu hình chiến thắng thực tế từ Mô-đun 02 và viết WINNER_CONFIG_ID ở vị trí mọi người đều nhìn thấy. Lõi tác nhân và cấu hình đã chọn không thay đổi; chỉ ngữ cảnh chính sách nghiệp vụ được cố ý triển khai chậm một phiên bản.
Nêu rõ giới hạn của evaluator trước khi trình bày kết quả: sql-execution-success chứng minh ClickHouse chấp nhận SQL, nhưng không chứng minh SQL tuân theo định nghĩa hiện tại của một metric được quản trị.
Đặt câu hỏi trong Chat, cho xem SQL được tạo, kết quả và policy_version=policy-v1, rồi nhấp 👎 và chờ feedback sent. Root trace Chat này là sự cố có thẩm quyền duy nhất.

Trình bày định nghĩa hiện tại cạnh kết quả đó:

SELECT uniqExact(customer_id) FROM v_orders
WHERE order_ts >= now() - INTERVAL 30 DAY
AND status NOT IN ('cancelled', 'returned')

Nói rõ SQL dựa trên ngày đăng ký là hợp lệ theo policy-v1 lỗi thời đã được cung cấp cho mô hình. Đây là lỗi phát hành/quy trình và là điểm mù của evaluator, không phải bằng chứng cho thấy mô hình bỏ qua hướng dẫn rõ ràng.
Trong Langfuse, lọc theo user-thumbs = false, mở chat_turn Chat mới nhất phù hợp, rồi đặt sql-execution-success=true cạnh user-thumbs=false. Tín hiệu này ưu tiên một cuộc điều tra; tự nó không đưa ra chẩn đoán hay trở thành ground truth.
Sau đó chạy bước tái hiện bắt buộc bằng curl như một chẩn đoán không chấm điểm. Đặt tên ID là CURL_TRACE_ID, chỉ xác minh sql-execution-success=true, không POST feedback và không dùng trace này để bàn giao sang Mô-đun 04.
Ghi lại root trace ID/URL cùng cả hai số đếm cho Mô-đun 04. Chỉ lưu các định danh thật trong project Langfuse và bảng ghi nhận của workshop.

Bằng chứng trace dự kiến

Mở observation gốc chat_turn, không chỉ observation con llm_call. Kết quả dự kiến:

Trường	Giá trị dự kiến
tên trace/observation	`chat_turn`
tag	`config_id` đã chọn, model, prompt, `policy-v1`, `serving`
metadata `policyversion`	`policy-v1`
output	SQL được tạo, cột/hàng, `outcome_hint`
điểm vận hành	`sql-execution-success=true`
điểm phản hồi	Boolean `user-thumbs=false`

Mã nguồn serving đặt tên trường này là policy_version; adapter OpenTelemetry chuẩn hóa khóa metadata thành ký tự chữ và số, vì vậy Langfuse hiển thị khóa đã phát là policyversion.

Evaluator vận hành chạy bất đồng bộ. Hãy dùng công cụ xác minh thay vì xem một điểm số chưa xuất hiện là thất bại:

.venv/bin/python -m scripts.verify_online_scores "$CHAT_TRACE_ID" \
  sql-execution-success=true user-thumbs=false

Các lỗi thường gặp

Provider bị ZDR chặn — Qwen lỗi trước khi tạo SQL nếu yêu cầu Zero Data Retention cho non-frontier của OpenRouter đang bật và route Alibaba đủ điều kiện bị loại. Hãy tắt hạn chế ZDR này cho workshop hoặc dùng phương án dự phòng đã công bố sau khi xem xét yêu cầu quyền riêng tư.
Evaluator dispatcher không chạy — trace xuất hiện nhưng sql-execution-success không bao giờ có. Xác nhận dịch vụ/dispatcher thực thi evaluator của Langfuse hoạt động và rule agent-arena-sql-execution-online đang bật; chỉ provision rule sẽ không tạo điểm nếu worker đánh giá không sẵn sàng.
Thiếu dependency OpenTelemetry — không có trace dù /ask trả response. Cài lại dependencies đã pin bằng .venv/bin/python -m pip install -r requirements.txt; runtime dùng luồng OpenTelemetry của Langfuse v4 và cần các gói OTel tương thích.
Tiến trình server cũ — response báo policy-v2 dù lệnh shell đặt policy-v1. Một tiến trình cũ vẫn chiếm cổng 8100; dừng hoàn toàn tiến trình đó trước khi bắt đầu bản phát hành đã seed.
Sai cổng — UI Chat mặc định gọi http://localhost:8100. Nếu serving dùng cổng khác, đặt VITE_SERVING_BASE về cùng địa chỉ hoặc gửi curl tới đúng cổng thực tế.
Feedback trùng lặp — feedback dùng score ID xác định user-thumbs-<trace_id>. Chỉ gửi một đánh giá cho mỗi trace. Dùng lại cùng trace cho các đánh giá mâu thuẫn có thể gây lỗi dịch vụ feedback hoặc làm demo không rõ ràng; hãy tạo session/trace mới.
Điểm số vẫn chờ xử lý — đánh giá chạy bất đồng bộ. Cho scripts.verify_online_scores tiếp tục polling trước khi thay đổi cấu hình.
Hai số đếm tham chiếu bằng nhau — dữ liệu hiện tại không còn tình huống đối chứng đã seed. Không tạo giả một thất bại; hãy seed lại hoặc chẩn đoán dữ liệu trước workshop.

Các bước đặt lại

Dừng mọi server đang chạy, rồi khởi động một tiến trình policy-v1 sạch:

scripts/arena.sh stop
scripts/arena.sh serve
source .env
.venv/bin/python -m schema.gen_schema_context
AGENT_ARENA_POLICY_VERSION=policy-v1 \
  .venv/bin/uvicorn serving.api:app --port 8100

scripts/arena.sh serve khởi động lại dashboard và web UI ở chế độ nền trước khi serving API chiếm terminal. Refresh trang Chat để tạo session mới. Nếu dùng API trực tiếp, hãy truyền session ID mới hoặc bỏ qua để /ask tự tạo. Chạy lại bước kiểm tra trước và provisioner trong terminal thứ hai; cả hai thao tác đều có thể lặp lại an toàn.

Chính sách dự phòng

Chỉ dùng cấu hình dự phòng đã kiểm chứng của giảng viên qwen3.7-flash__P2_fewshot khi cấu hình chiến thắng của lớp không còn tuân theo chính sách lỗi thời được nêu rõ trong ba câu hỏi kiểm tra trước. Hãy công khai việc thay thế: phương án dự phòng giữ cho sự cố giảng dạy có tính xác định, còn cấu hình đứng đầu leaderboard vẫn là kết quả đo thực tế. Không âm thầm đổi model và không dùng phương án dự phòng để che giấu lỗi số đếm bằng nhau, thông tin xác thực, provider routing hay hạ tầng evaluator.

Bàn giao sang Mô-đun 04

Trước khi tiếp tục, xác nhận bảng ghi nhận có root trace ID/URL Chat có thẩm quyền, số đếm cũ, số đếm hiện tại, sql-execution-success=true và Boolean user-thumbs=false. Mô-đun 04 bắt đầu từ chính mâu thuẫn này và bổ sung phán đoán của con người; không bắt đầu bằng một chẩn đoán viết sẵn tách rời trace production.

Trên trang này