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

Điểm khởi đầu

Bạn đã hoàn thành Mô-đun 02. Hãy ghi lại config_id chiến thắng từ lần chạy Agent Arena thực tế, rồi export giá trị đó tại thư mục gốc của lab (ClickHouse_Demos/workshops/agent_arena):

source .env
export WINNER_CONFIG_ID="${WINNER_CONFIG_ID:-qwen3.7-flash__P2_fewshot}"

Lần chạy đã được kiểm chứng của workshop chọn qwen3.7-flash__P2_fewshot; nếu kết quả trong lớp của bạn khác, hãy dùng chính cấu hình chiến thắng đó. Bạn sẽ sử dụng đúng mô hình và prompt đã đo lường, không phải một tác nhân đặc biệt được dựng riêng để thất bại.

Vì sao evaluator đạt vẫn có thể bỏ sót giá trị người dùng

Evaluator online chỉ đo khía cạnh mà nó được thiết kế để đo. Trong trường hợp này, sql-execution-success trả lời một câu hỏi vận hành quan trọng: tác nhân có tạo ra SQL mà ClickHouse thực thi được hay không? Evaluator này không biết SQL có tuân theo định nghĩa kinh doanh hiện tại về khách hàng đang hoạt động hay không.

Điều đó tạo ra một khoảng trống giám sát rất thực tế:

Đánh giá vận hành phát hiện SQL lỗi, timeout và lỗi thực thi. Đánh giá ngữ nghĩa hoặc đánh giá từ người dùng xem một câu trả lời thực thi được có hữu ích và đúng với ý nghĩa kinh doanh hay không. Hai loại đánh giá bổ sung cho nhau. Một lượt 👎 chỉ là tín hiệu ưu tiên điều tra, không phải ground truth; con người sẽ xem xét sự cố ở Mô-đun 04.

Mục tiêu

Tạo một trace chat_turn thật trong đó evaluator vận hành đạt nhưng người dùng đánh giá tiêu cực. Ghi lại trace và hai số đếm mâu thuẫn để chuyển sang bước điều tra của con người.

Bước 1 — Chứng minh có thể tái hiện sự cố đã seed

Chạy bước kiểm tra trước tại thư mục gốc của lab trước khi khởi động máy chủ demo:

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"

Lệnh này thực thi cả hai định nghĩa và gửi ba cách diễn đạt khác nhau tới cấu hình đã chọn. Kết quả phải in hai giá trị stale_count và current_count khác nhau, ba dòng classification_N=policy-v1, cùng thông báo:

Nếu một cách diễn đạt trả về ok/unknown, bước kiểm tra trước chỉ thử lại đúng cách diễn đạt và cấu hình đó một lần. Bước này không thử lại khi kết quả là policy-v2 hoặc khi nhà cung cấp/mô hình/tác nhân gặp lỗi; nếu lần thứ hai vẫn là ok/unknown thì quy trình vẫn bị chặn.

OK: seeded online-evaluation incident is reproducible

Nếu hai số đếm bằng nhau hoặc có bất kỳ phân loại nào khác policy-v1, hãy dừng lại: lần chạy dữ liệu/mô hình này không thể hiện được tình huống đối chứng.

Định nghĩa kinh doanh hiện tại được biểu diễn chính xác bằng SQL sau:

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

Định nghĩa cũ trong policy-v1 lại đếm khách hàng đăng ký trong 90 ngày gần nhất. Vì vậy, SQL do mô hình tạo ra trong mô-đun này vẫn hợp lệ theo hướng dẫn policy-v1 được cung cấp rõ ràng. Đây không phải bằng chứng cho thấy mô hình kém thông minh; nguyên nhân là ngữ cảnh chính sách được triển khai đã lỗi thời, còn evaluator thực thi SQL quá hẹp để nhận ra vấn đề.

Bước 2 — Provision evaluator vận hành

Quá trình provision có tính idempotent nên có thể chạy lại an toàn:

source .env
.venv/bin/python -m scripts.provision_online_evaluators --operational

Đầu ra phải nêu evaluator sql-execution-success và rule đang bật agent-arena-sql-execution-online.

Bước 3 — Khởi động bản phát hành dùng chính sách lỗi thời

Trong terminal thứ nhất, tại thư mục gốc của lab, khởi động máy chủ với chính sách cũ được chỉ định rõ ràng và giữ tiến trình tiếp tục chạy:

source .env
AGENT_ARENA_POLICY_VERSION=policy-v1 \
  .venv/bin/uvicorn serving.api:app --port 8100

Không được bỏ qua AGENT_ARENA_POLICY_VERSION. Nếu không, dịch vụ sẽ mặc định dùng policy-v2 hiện tại, vốn loại trừ chính xác các đơn hàng đã hủy và hoàn trả.

Bước 4 — Đặt câu hỏi và đánh giá trong Chat

Trong terminal khác, khởi động dashboard nếu chưa chạy:

scripts/arena.sh serve

Mở http://localhost:5174, chọn tab Chat và $WINNER_CONFIG_ID rồi hỏi:

How many active customers do we have?

Đọc SQL được tạo và kết quả. Câu trả lời phải tuân theo định nghĩa khách hàng đăng ký trong 90 ngày từ policy-v1. Nhấp 👎 cho câu trả lời này và chờ đến khi UI hiển thị feedback sent.

Trace gốc của lượt Chat này là sự cố có thẩm quyền duy nhất mà bạn sẽ chấm điểm và chuyển sang Mô-đun 04.

Bước 5 — Tìm và xác minh trace Chat

Trong Langfuse, mở Tracing và lọc theo user-thumbs = false. Mở root chat_turn mới nhất có câu hỏi How many active customers do we have?, config khớp với $WINNER_CONFIG_ID và metadata hiển thị policyversion=policy-v1. Sao chép trace ID và trace URL, rồi đặt ID trong terminal:

export CHAT_TRACE_ID="<paste the Chat trace ID>"
.venv/bin/python -m scripts.verify_online_scores "$CHAT_TRACE_ID" \
  sql-execution-success=true user-thumbs=false

Xác minh user-thumbs là giá trị Boolean false, không phải điểm số dạng số hay văn bản. Mã nguồn serving gọi trường metadata này là policy_version; adapter OpenTelemetry chuẩn hóa tên thành khóa policyversion được phát sang Langfuse.

Bước 6 — Tái hiện bằng curl không chấm điểm

Lệnh gọi API trực tiếp là bước tái hiện và chẩn đoán bắt buộc ở cấp command line. Lệnh này tạo một trace riêng, nhưng đó không phải sự cố phản hồi và không được chấm điểm:

source .env
export WINNER_CONFIG_ID="${WINNER_CONFIG_ID:-qwen3.7-flash__P2_fewshot}"
ASK_BODY=$(.venv/bin/python -c \
  'import json,sys; print(json.dumps({"question": sys.argv[1], "config_id": sys.argv[2]}))' \
  "How many active customers do we have?" "$WINNER_CONFIG_ID")
CURL_RESPONSE=$(curl -fsS http://localhost:8100/ask \
  -H 'content-type: application/json' -d "$ASK_BODY")
printf '%s\n' "$CURL_RESPONSE" | .venv/bin/python -m json.tool
CURL_TRACE_ID=$(printf '%s\n' "$CURL_RESPONSE" | .venv/bin/python -c \
  'import json,sys; data=json.load(sys.stdin); assert data.get("policy_version") == "policy-v1"; assert data.get("outcome") == "ok"; trace_id=data.get("trace_id"); assert isinstance(trace_id, str) and trace_id; print(trace_id)')

Response phải có outcome: "ok", trace_id không rỗng và policy_version: "policy-v1".

Chờ evaluator bất đồng bộ hoàn tất và chỉ xác minh điểm vận hành của trace này:

.venv/bin/python -m scripts.verify_online_scores "$CURL_TRACE_ID" \
  sql-execution-success=true

Không gọi /feedback cho CURL_TRACE_ID và không ghi ID này vào bảng điều tra. Đây chỉ là chẩn đoán API có thể tái hiện; CHAT_TRACE_ID vẫn là trace được bàn giao.

Bước 7 — So sánh với chính sách hiện tại

Thực thi SQL của chính sách hiện tại bằng cùng ClickHouse client chỉ đọc mà tác nhân sử dụng, rồi so sánh kết quả đơn với kết quả theo chính sách cũ trong CURL_RESPONSE:

.venv/bin/python - <<'PY'
from arena.config import load_config
from agents.chclient import ROClickHouseClient

sql = """SELECT uniqExact(customer_id) FROM v_orders
WHERE order_ts >= now() - INTERVAL 30 DAY
AND status NOT IN ('cancelled', 'returned')"""
result = ROClickHouseClient(load_config().clickhouse).query(sql)
print(result.rows[0][0])
PY

Đây chính xác là truy vấn bạn vừa thực hiện:

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

Hai số đếm khác nhau chính là lỗi mà người dùng nhìn thấy. SQL đã chạy thành công nhưng trả lời theo sai định nghĩa kinh doanh. Ghi số đếm này cùng bằng chứng từ trace Chat có thẩm quyền.

Bảng ghi nhận cho bước điều tra

Giữ lại các thông tin bàn giao sau cho Mô-đun 04:

Cách xác minh bạn đã hoàn tất

• Bước kiểm tra trước cho thấy số đếm cũ và hiện tại khác nhau, đồng thời cả ba câu hỏi đã seed đều được phân loại là policy-v1.
• Dịch vụ chạy với AGENT_ARENA_POLICY_VERSION=policy-v1 và /ask đã trả về outcome: "ok".
• Trace Chat có thẩm quyền có sql-execution-success=true và user-thumbs=false trong Langfuse.
• Chẩn đoán curl bắt buộc trả về outcome: "ok", tạo một CURL_TRACE_ID riêng và không được chấm điểm hay bàn giao.
• Bạn đã ghi lại trace ID/URL Chat có thẩm quyền cùng cả hai số đếm mà không chia sẻ thông tin xác thực.
• Bạn có thể giải thích lý do tại sao việc thực thi SQL thành công không chứng minh được tính chính xác về mặt ngữ nghĩa.

Tiếp tục với Mô-đun 04 — Điều tra với con người để biến tín hiệu này thành một chẩn đoán đã được con người xem xét.