04 Investigasi bersama manusia

Titik awal

Modul 03 menghasilkan satu trace Chat otoritatif untuk How many active customers do we have? dengan ketidaksesuaian yang memang disengaja:

Simpan ID/URL trace tersebut beserta dua angka referensi dari worksheet Anda. Jangan gunakan diagnostik curl yang belum diberi rating dari Modul 03.

Mengapa investigasi manusia diperlukan

Thumbs-down memberi tahu tim ke mana harus mencari; itu tidak memberi tahu tim apa yang sebenarnya gagal. Bisa jadi pengguna memaksudkan sesuatu yang berbeda, permintaannya ambigu, SQL yang dihasilkan tidak valid, atau dua definisi bisnis saling berbeda. Mempromosikan setiap sinyal negatif langsung menjadi golden dataset akan mengubah tebakan menjadi kebenaran dasar.

Dalam modul ini, reviewer pertama-tama mencatat apa yang bisa diamati, kemudian menguji kemungkinan penjelasan, dan baru setelah itu mencatat diagnosis serta koreksi. Keputusan hasil tinjauan itu—bukan thumbs-down-nya—yang menjadi kebenaran dasar yang diserahkan ke Modul 05.

Tujuan

Selesaikan satu annotation task production-investigation-<session> untuk chat_turn akar dari Modul 03. Task yang telah diselesaikan harus memuat sebuah observasi, kategori kegagalan, SQL koreksi yang tepat, persetujuan untuk golden dataset, dan provenance produksi.

Langkah 1 — Temukan insiden feedback yang tepat

Di Langfuse, buka Tracing dan filter untuk score Boolean user-thumbs = false. Buka trace yang cocok dengan semua kriteria berikut:

• name/root observation chat_turn;
• pertanyaan How many active customers do we have?;
• config_id pemenang dan trace ID yang tercatat pada Modul 03;
• metadata policyversion=policy-v1; dan
• score sql-execution-success=true dan user-thumbs=false.

Sumber serving memancarkan policy_version, tetapi adapter OpenTelemetry menghapus underscore-nya, sehingga key metadata di Langfuse menjadi policyversion.

Langkah 2 — Buat tiga score config untuk review

Setup ini memang sengaja dibuat sebagai langkah human-review yang hanya berlangsung di UI. Repository workshop tidak menyediakan command yang membuat atau menyelesaikan annotation task ini untuk Anda.

Sebelum membuat queue, buka Settings → Scores → Create dan buat config berikut:

Gunakan nama dan tanda hubung persis seperti yang tertulis. Membuat config lebih dulu adalah cara kerja paling aman, karena kumpulan score-config ID yang terpasang pada sebuah queue ditetapkan secara permanen saat queue itu dibuat. Jika ada config yang terlewat dari kumpulan attachment tersebut, buat queue baru dengan suffix baru. Score config itu sendiri bersifat mutable: perubahan name, schema, atau category yang didukung harus dilakukan sebagai score-config update yang tercatat (audited), dan perubahan tersebut tidak menulis ulang score yang sudah ada.

Langkah 3 — Buat queue dan targetkan root logisnya

Buka Annotations → Queues → Create lalu:

1. Beri nama production-investigation-<session>, ganti <session> dengan pengenal workshop yang singkat dan unik.
2. Lampirkan ketiga score config dari Langkah 2.
3. Buat queue-nya.
4. Kembali ke trace Modul 03, pilih observation chat_turn akarnya, buka dropdown Annotate, lalu pilih queue ini.
5. Buka task barunya dan pastikan targetnya adalah chat_turn, bukan llm_call.

Queue tidak bisa mengubah kumpulan score-config ID yang terpasang setelah dibuat. Buat ulang hanya jika kumpulan attachment tersebut salah; gunakan score-config update yang tercatat untuk perubahan yang didukung pada config yang sudah terpasang.

Langkah 4 — Tuliskan apa yang bisa Anda amati

Modul 03 memang sengaja membuka setup yang telah diseed. Untuk investigasi ini, kesampingkan pengetahuan workshop sebelumnya dan praktikkan alur kerja yang akan dipakai reviewer pada insiden yang belum diketahui: periksa pertanyaan, SQL yang dihasilkan, count yang dikembalikan, model/prompt, serta kedua score-nya sebelum menyebutkan penyebabnya. Masukkan catatan yang hanya berisi bukti pada observed-issue, contohnya:

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.

Bahasa ini belum mengklaim bahwa model, SQL engine, pengguna, atau policy yang bersalah. Pemisahan itu mencegah diagnosis yang sudah diseed diselundupkan ke dalam review sebelum buktinya diperiksa.

Langkah 5 — Periksa bukti trace secara lengkap

Masih di chat_turn akar, verifikasi:

• metadata policyversion=policy-v1;
• SQL yang dihasilkan menggunakan v_customers dan window signup_date 90 hari;
• hasil terstruktur memuat trace count yang teramati dari Modul 03;
• score operasional adalah Boolean sql-execution-success=true; dan
• sinyal pengguna adalah Boolean user-thumbs=false.

SQL yang dihasilkan konsisten dengan instruksi policy-v1 yang disediakan oleh release. Score keberhasilan eksekusi juga benar sesuai lingkup sempitnya yang memang disengaja. Pada titik ini, kedua fakta tersebut belum menentukan apakah policy yang di-deploy itu cocok dengan definisi terkini yang digoverning.

Langkah 6 — Uji kedua definisi policy secara berdampingan

Dari ClickHouse_Demos/workshops/agent_arena, jalankan kedua definisi read-only ini di lingkungan yang sama:

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

Kedua angka ini harus cocok dengan nilai worksheet dan berbeda satu sama lain. Anda sekarang punya bukti yang cukup untuk mendiagnosis definisi bisnis yang sudah kedaluwarsa (stale) pada deployment: trace ini mengklaim policy-v1, SQL-nya mengikuti policy tersebut, sementara query terkini yang telah diverifikasi menerapkan policy-v2.

Langkah 7 — Beri anotasi, koreksi, setujui, dan selesaikan

Kembali ke annotation task dan catat:

Alihkan Corrected Output ke plain-text mode, lalu masukkan SQL mentah yang persis seperti ini:

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

Langfuse mencatat koreksi ini; ia tidak menjalankan SQL-nya. Klien ClickHouse read-only pada Langkah 6 harus sudah menjalankan teks yang sama persis dan berhasil, sebelum disetujui. Jika Anda mengubah koreksinya, jalankan ulang teks itu melalui klien yang sama. Setelah itu, pilih Complete (atau Complete + next). Koreksi yang salah format, tidak bisa dijalankan, atau belum terverifikasi tidak boleh disetujui sebagai golden ground truth.

Langkah 8 — Catat provenance untuk Modul 05

Salin nilai-nilai ini ke worksheet Anda. Jaga kerahasiaan ID tetap khusus untuk proyek workshop ini:

source_trace_id, failure_category, dan source_policy_version wajib ada untuk golden record yang berasal dari produksi. annotation_id bersifat opsional di runtime, tetapi catat jika UI menampilkannya agar keputusan ini tetap bisa diaudit.

Cara memverifikasi bahwa Anda sudah selesai

• Anda menginvestigasi satu trace Chat dari Modul 03 dengan user-thumbs=false.
• Target anotasi adalah chat_turn akar, bukan llm_call turunannya.
• Queue diberi nama production-investigation-<session> dan memuat ketiga score config dengan tipe yang benar.
• observed-issue mencatat perilaku sebelum diagnosis.
• Anda menjalankan SQL yang stale dan yang terkini secara berdampingan, dan memastikan hasil count-nya berbeda.
• Task yang telah diselesaikan mencatat stale-business-policy, SQL koreksi yang tepat, dan approved-for-golden=true.
• Worksheet Anda menyimpan provenance produksi untuk Modul 05 tanpa mempublikasikan trace ID atau URL proyek yang bersifat live.
• Anda bisa menjelaskan mengapa thumbs-down memprioritaskan human review namun tidak dengan sendirinya menjadi kebenaran dasar.

Lanjutkan ke Modul 05 — Tutup siklusnya untuk mempromosikan koreksi hasil tinjauan, membandingkan versi policy, dan mencegah kelas kegagalan yang sama terjadi lagi secara online.