04 Điều tra với con người

Điểm khởi đầu

Mô-đun 03 đã tạo một trace Chat có thẩm quyền cho câu hỏi How many active customers do we have? với mâu thuẫn có chủ đích:

Giữ lại trace ID/URL này cùng hai số đếm tham chiếu trong bảng ghi nhận. Không dùng trace chẩn đoán curl không chấm điểm từ Mô-đun 03.

Vì sao cần con người điều tra

Một lượt 👎 cho nhóm biết nên xem xét ở đâu, nhưng không cho biết điều gì đã thất bại. Có thể người dùng muốn hỏi ý khác, yêu cầu còn mơ hồ, SQL được tạo không hợp lệ, hoặc hai định nghĩa nghiệp vụ không giống nhau. Nếu đưa mọi tín hiệu tiêu cực thẳng vào bộ dữ liệu vàng, bạn sẽ biến phỏng đoán thành ground truth.

Trong mô-đun này, người đánh giá trước hết ghi lại những gì quan sát được, sau đó kiểm tra các giả thuyết, rồi mới ghi chẩn đoán và bản sửa. Chính quyết định đã được xem xét — không phải lượt 👎 — mới là ground truth được bàn giao sang Mô-đun 05.

Mục tiêu

Hoàn thành một annotation task trong queue production-investigation-<session> cho root chat_turn từ Mô-đun 03. Task đã hoàn tất phải chứa mô tả quan sát, loại lỗi, SQL sửa đúng, quyết định phê duyệt vào bộ dữ liệu vàng và thông tin nguồn gốc production.

Bước 1 — Tìm đúng sự cố có phản hồi

Trong Langfuse, mở Tracing và lọc theo điểm Boolean user-thumbs = false. Mở trace thỏa mãn đầy đủ các điều kiện sau:

• tên/root observation là chat_turn;
• câu hỏi How many active customers do we have?;
• config_id chiến thắng và trace ID đã ghi ở Mô-đun 03;
• metadata policyversion=policy-v1; và
• điểm sql-execution-success=true và user-thumbs=false.

Mã nguồn serving phát trường policy_version, nhưng adapter OpenTelemetry loại bỏ dấu gạch dưới, vì vậy khóa metadata trong Langfuse là policyversion.

Bước 2 — Tạo ba score config cho annotation

Đây là bước đánh giá của con người được thực hiện có chủ đích chỉ trên UI. Repository workshop không có lệnh tự động tạo hay hoàn tất annotation task này.

Trước khi tạo queue, mở Settings → Scores → Create và tạo các config sau:

Dùng đúng tên và dấu gạch nối như hiển thị. Quy trình an toàn nhất là tạo score config trước, vì tập ID score config gắn với queue được cố định tại thời điểm tạo queue. Nếu bỏ sót một config, hãy tạo queue mới với hậu tố mới. Bản thân score config có thể thay đổi: các chỉnh sửa được hỗ trợ về tên, schema hoặc category phải được thực hiện dưới dạng update score config đã kiểm thử; những chỉnh sửa đó không ghi lại các điểm số đã tồn tại.

Bước 3 — Tạo queue và nhắm đúng root

Mở Annotations → Queues → Create và:

1. Đặt tên production-investigation-<session>, thay <session> bằng một định danh ngắn, duy nhất cho workshop.
2. Gắn cả ba score config từ Bước 2.
3. Tạo queue.
4. Quay lại trace từ Mô-đun 03, chọn root observation chat_turn, mở menu thả xuống Annotate và chọn queue này.
5. Mở task mới và xác minh target là chat_turn, không phải llm_call.

Sau khi tạo, queue không thể thay đổi tập ID score config đã gắn. Chỉ tạo lại queue nếu tập config đó sai; với các thay đổi được hỗ trợ trên config đã gắn, hãy dùng thao tác update score config đã được kiểm thử.

Bước 4 — Ghi lại những gì quan sát được

Mô-đun 03 đã chủ động công khai tình huống được seed. Trong lần điều tra này, hãy tạm gác kiến thức đó và thực hành đúng quy trình mà người đánh giá dùng cho một sự cố chưa biết: kiểm tra câu hỏi, SQL được tạo, số đếm trả về, model/prompt và cả hai điểm số trước khi đặt tên nguyên nhân. Nhập một ghi chú chỉ dựa trên bằng chứng vào observed-issue, ví dụ:

The answer returned a count and its SQL executed. The observed count differs from the
second reference count recorded in Module 03. The generated query uses a 90-day
customer signup window, and the trace metadata reports policy-v1.

Cách diễn đạt này chưa quy lỗi cho model, SQL engine, người dùng hay chính sách. Sự tách biệt đó ngăn một chẩn đoán có sẵn len vào quá trình review trước khi kiểm tra bằng chứng.

Bước 5 — Kiểm tra đầy đủ bằng chứng trong trace

Vẫn trên root chat_turn, xác minh:

• metadata policyversion=policy-v1;
• SQL được tạo sử dụng v_customers và cửa sổ signup_date 90 ngày;
• output có cấu trúc chứa số đếm đã quan sát trong trace ở Mô-đun 03;
• điểm vận hành là Boolean sql-execution-success=true; và
• tín hiệu người dùng là Boolean user-thumbs=false.

SQL được tạo phù hợp với hướng dẫn policy-v1 mà bản phát hành nhận được. Điểm thực thi thành công cũng đúng trong phạm vi hẹp có chủ đích. Ở thời điểm này, chưa có dữ kiện nào xác nhận chính sách đã triển khai có khớp định nghĩa quản trị hiện tại hay không.

Bước 6 — Kiểm tra hai định nghĩa chính sách cạnh nhau

Tại ClickHouse_Demos/workshops/agent_arena, thực thi cả hai định nghĩa chỉ đọc trong cùng một môi trường:

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

queries = {
    "policy-v1": """SELECT count() FROM v_customers
WHERE signup_date >= today() - INTERVAL 90 DAY""",
    "policy-v2": """SELECT uniqExact(customer_id) FROM v_orders
WHERE order_ts >= now() - INTERVAL 30 DAY
AND status NOT IN ('cancelled', 'returned')""",
}
client = ROClickHouseClient(load_config().clickhouse)
for version, sql in queries.items():
    result = client.query(sql)
    print(f"{version}: {result.rows[0][0]}")
PY

Hai số đếm phải khớp với giá trị trong bảng ghi nhận và khác nhau. Giờ bạn đã có đủ bằng chứng để chẩn đoán một định nghĩa nghiệp vụ lỗi thời đã được triển khai: trace công bố policy-v1, SQL tuân theo chính sách đó, còn truy vấn hiện tại đã được xác minh triển khai policy-v2.

Bước 7 — Annotation, sửa, phê duyệt và hoàn tất

Quay lại annotation task và ghi:

Chuyển Corrected output sang plain-text mode, rồi nhập chính xác SQL thô sau:

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

Langfuse chỉ ghi lại bản sửa này, không thực thi SQL. Trước khi phê duyệt, ClickHouse client chỉ đọc ở Bước 6 phải thực thi thành công chính xác đoạn SQL đó. Nếu chỉnh sửa nội dung, hãy chạy lại bằng cùng client. Sau đó chọn Complete hoặc Complete + Next. Không chấp nhận một bản sửa sai định dạng, không thực thi được hoặc chưa xác minh làm ground truth vàng.

Bước 8 — Ghi lại nguồn gốc cho Mô-đun 05

Chép các giá trị sau vào bảng ghi nhận. Giữ các ID trong phạm vi project workshop:

source_trace_id, failure_category và source_policy_version là bắt buộc để bản ghi vàng có nguồn gốc production. Runtime cho phép thiếu annotation_id, nhưng hãy ghi lại khi UI hiển thị để quyết định vẫn có thể được kiểm toán.

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

• Bạn đã điều tra trace Chat từ Mô-đun 03 có user-thumbs=false.
• Target của annotation là root chat_turn, không phải llm_call con.
• Queue có tên production-investigation-<session> và chứa đủ ba score config đúng kiểu.
• observed-issue ghi lại hành vi trước khi chẩn đoán.
• Bạn đã chạy SQL cũ và hiện tại cạnh nhau và xác nhận số lượng khác nhau.
• Task đã hoàn tất ghi stale-business-policy, SQL sửa chính xác và approved-for-golden=true.
• Bảng ghi nhận giữ được nguồn gốc production cho Mô-đun 05 mà không công khai trace ID thật hay project URL.
• Bạn có thể giải thích vì sao lượt 👎 giúp ưu tiên review của con người nhưng tự nó không trở thành ground truth.

Tiếp tục đến Mô-đun 05 — Khép kín vòng lặp để đưa bản sửa đã review vào dữ liệu vàng, so sánh các phiên bản chính sách và ngăn cùng một lớp lỗi tái diễn online.