ติดตามการตัดสินใจของ AI Agent ด้วย BigQuery Graph

1. บทนำ

ปัจจุบัน BigQuery Graph, BigQuery Conversational Analytics และ BigQuery Agent Analytics SDK อยู่ในเวอร์ชันตัวอย่างบน Google Cloud ปลั๊กอิน BigQuery Agent Analytics พร้อมให้บริการแก่ผู้ใช้ทั่วไป (GA) แล้ว ตัวอย่างใน Codelab นี้ใช้ข้อมูลสังเคราะห์

เมื่อเอเจนต์ AI แบบอัตโนมัติรับผิดชอบด้านการปฏิบัติงานมากขึ้น (การประเมินใบสมัครขอสินเชื่อ การจัดการงบประมาณด้านการตลาด การอนุมัติคำขอเข้าถึง) องค์กรต้องสามารถตรวจสอบและอธิบายการตัดสินใจของเอเจนต์ได้ การสร้างบริบทที่แน่นอน ตัวเลือกที่พิจารณา และเหตุผลสุดท้ายของการตัดสินใจของตัวแทนขึ้นมาใหม่เป็นสิ่งจำเป็นสำหรับการปฏิบัติตามข้อกำหนด การจัดการความเสี่ยง และความน่าเชื่อถือในการปฏิบัติงาน

Codelab นี้ใช้ BigQuery Agent Analytics SDK เพื่อเปลี่ยนบันทึกเหตุการณ์ของเอเจนต์ดิบให้เป็นกราฟบริบทของเอเจนต์ ซึ่งเป็นกราฟที่ค้นหาได้ใน BigQuery Graph ของการตัดสินใจของเอเจนต์ตามกำหนดการ โดยไม่ต้องใช้ฐานข้อมูลกราฟภายนอกหรือไปป์ไลน์ ETL

คำสำคัญ

• การติดตามการตัดสินใจของเอเจนต์ - หลักฐานระดับการตัดสินใจที่ดึงมาจากการเรียกใช้ของเอเจนต์เอง ได้แก่ ตัวเลือกที่พิจารณา ข้อมูลที่เกี่ยวข้อง และผลลัพธ์ที่ได้
• กราฟบริบทของ Agent - กราฟที่พิมพ์และค้นหาได้ใน BigQuery Graph ซึ่งร่องรอยเหล่านั้นจะกลายเป็นกราฟ ซึ่งเป็นอินสแตนซ์ระดับ Agent ของแนวคิดกราฟบริบทของอุตสาหกรรม (เลเยอร์บริบทการตัดสินใจที่ยั่งยืนและเชื่อมโยงกับเวลาซึ่ง Agent ทั้งสร้างและใช้) โดยตัวระบุ"Agent" จะกำหนดขอบเขตให้กับการเรียกใช้ของ Agent ของคุณเองแทนที่จะเป็นเลเยอร์บริบททั่วทั้งองค์กร

ในโค้ดแล็บนี้ bqaa context-graph จะดึงข้อมูลการตัดสินใจของเอเจนต์จาก agent_events และสร้างเป็นกราฟบริบทของเอเจนต์ที่คุณสามารถค้นหาด้วย GQL ซึ่งเป็นไปตามรูปแบบอุตสาหกรรมที่สร้างกราฟบริบทจากข้อมูลการตัดสินใจ

สิ่งที่คุณจะสร้าง

• กราฟบริบทของเอเจนต์ (ที่มีกราฟ BigQuery) ที่จำลองขั้นตอนการตัดสินใจของเอเจนต์ทั่วไป: มีคำขอเข้ามา เอเจนต์จะพิจารณาตัวเลือกต่างๆ และจะบันทึกผลลัพธ์
• ตาราง agent_events ที่มีข้อมูลพร้อมคลังข้อความเหตุการณ์สังเคราะห์
• bqaa context-graphการวิ่งที่ใช้งานได้ซึ่งจะเติมกราฟจากเหตุการณ์เหล่านั้น
• การค้นหา GQL ในรูปแบบการตรวจสอบที่ติดตามการตัดสินใจเดียวตั้งแต่ต้นจนจบ

สิ่งที่คุณจะได้เรียนรู้

• วิธีที่ปลั๊กอิน BigQuery Agent Analytics เขียนไปยัง agent_events
• วิธีที่ออบเจ็กต์ประกาศ 2 รายการ ได้แก่ DDL ของตารางและสคีมา CREATE PROPERTY GRAPH กำหนดกราฟบริบท
• วิธีเรียกใช้ bqaa context-graph กับกราฟ BigQuery
• วิธีค้นหากราฟโดยใช้ GQL
• ความสามารถระดับเวอร์ชันที่ใช้งานจริงที่ SDK รองรับสำหรับการติดตั้งใช้งานในองค์กร

สิ่งที่คุณต้องมี

• โปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงิน
• บทบาทเจ้าของหรือผู้แก้ไขในโปรเจ็กต์นั้น คุณจะสร้างชุดข้อมูล BigQuery และให้สิทธิ์ IAM
• gcloud CLI ที่ติดตั้งและตรวจสอบสิทธิ์แล้ว หรือสิทธิ์เข้าถึง Cloud Shell
• Python 3.10 ขึ้นไป
• คุ้นเคยกับ BigQuery SQL ไม่จำเป็นต้องมีความรู้เกี่ยวกับ GQL

โค้ดแล็บนี้มีไว้สำหรับนักพัฒนาซอฟต์แวร์ทุกระดับ รวมถึงผู้ที่เพิ่งเริ่มต้นใช้งาน BigQuery Graph

ทรัพยากรที่สร้างขึ้นในโค้ดแล็บนี้มีค่าใช้จ่ายน้อยมาก และขั้นตอนสุดท้ายจะลบทิ้งทุกอย่างเพื่อให้คุณไม่ต้องถูกเรียกเก็บเงินสำหรับชุดข้อมูลที่ไม่ได้ใช้งาน

ระยะเวลาโดยประมาณ: Codelab นี้ใช้เวลาประมาณ 35 นาที

2. ก่อนเริ่มต้น

เลือกโปรเจ็กต์และภูมิภาค

เปิด Cloud Shell หรือเทอร์มินัลในเครื่อง

export PROJECT_ID="your-project-id"
export REGION="us-central1"
export DATASET="agent_analytics_demo"
gcloud config set project "$PROJECT_ID"

DATASET ตัวแปรเดียวจะเก็บทั้งตาราง agent_events ดิบและตารางกราฟที่สร้างขึ้น การใช้ชุดข้อมูลเดียวจะช่วยให้โค้ดแล็บไม่ซับซ้อน การติดตั้งใช้งานจริงมักจะแยกเหตุการณ์และกราฟออกเป็นชุดข้อมูลที่แยกต่างหากเพื่อให้ IAM สามารถให้สิทธิ์แบบจำกัดต่อชุดข้อมูลได้

เปิดใช้ API ที่จำเป็น

เรียกใช้คำสั่งต่อไปนี้เพื่อเปิดใช้ API ที่ Codelab นี้ใช้

gcloud services enable \
    bigquery.googleapis.com \
    aiplatform.googleapis.com \
    --project="$PROJECT_ID"

ต้องใช้ aiplatform.googleapis.com API เนื่องจากเส้นทางการแยกเริ่มต้นของ SDK จะเรียกใช้ฟังก์ชัน AI.GENERATE ของ BigQuery หากต่อมาคุณเปลี่ยนไปใช้การแยกข้อมูลแบบดีเทอร์มินิสติกด้วย --extraction-mode=compiled-only ก็ไม่จำเป็นต้องใช้ API นี้อีกต่อไป

สร้างชุดข้อมูล BigQuery

สร้างชุดข้อมูลที่จะเก็บทั้งตาราง agent_events ดิบและตารางกราฟที่สร้างขึ้น

bq --location=US mk --dataset "$PROJECT_ID:$DATASET"

คุณควรเห็นข้อความว่าดำเนินการสำเร็จแล้ว

Dataset 'your-project-id:agent_analytics_demo' successfully created.

หากมีชุดข้อมูลอยู่แล้ว คำสั่งจะแสดงข้อผิดพลาดที่ไม่เป็นอันตราย ปล่อยไว้อย่างนั้น

3. ติดตั้ง SDK

ตั้งค่าสภาพแวดล้อมเสมือนของ Python และติดตั้ง SDK จาก PyPI โดยทำดังนี้

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install bigquery-agent-analytics

bigquery-agent-analytics แพ็กเกจจะดึงข้อมูลไลบรารีของไคลเอ็นต์ BigQuery มาให้ ดังนั้นคุณจึงต้องติดตั้งเพียงครั้งเดียวสำหรับทั้ง Codelab

ยืนยันการติดตั้ง

bqaa context-graph --help | head -8

คุณควรเห็นแบนเนอร์ CLI

ตรวจสอบสิทธิ์

หากคุณใช้เวิร์กสเตชัน ให้ทำดังนี้

gcloud auth login
gcloud auth application-default login

ผู้ใช้ Cloud Shell สามารถข้ามขั้นตอนนี้ได้เนื่องจากมีการกำหนดค่าข้อมูลเข้าสู่ระบบไว้แล้ว

4. รับอาร์ติแฟกต์ Codelab

Codelab ต้องการเพียง 2 อาร์ติแฟกต์ที่พร้อมใช้งาน ได้แก่ DDL ของตาราง (ตารางกราฟจริง) และสคีมากราฟพร็อพเพอร์ตี้ (CREATE PROPERTY GRAPH) คุณไม่ต้องสร้างอาร์ติแฟกต์ด้วยตนเอง Codelab จะใช้อาร์ติแฟกต์ตามที่มี และREADME ในโฟลเดอร์อาร์ติแฟกต์จะอธิบายวิธีปรับอาร์ติแฟกต์ให้เหมาะกับโดเมนการตัดสินใจของคุณเอง

สคีมาของกราฟพร็อพเพอร์ตี้คือแหล่งข้อมูลเดียวที่เชื่อถือได้มากที่สุดสำหรับสิ่งที่กราฟมี คุณจะใช้กับ BigQuery เพียงครั้งเดียว จากนั้นกราฟที่ติดตั้งใช้งานจะเป็นสัญญา เมื่อคุณสร้างข้อมูลจริง bqaa context-graph จะอ่านคำจำกัดความของกราฟจาก INFORMATION_SCHEMA.PROPERTY_GRAPHS ของ BigQuery (พร้อมกับสคีมาของตารางที่อ้างอิง) เพื่อพิจารณาว่าควรถอนข้อมูลเอนทิตีและความสัมพันธ์ใด และควรเขียนข้อมูลไว้ที่ใด ดังนั้นจึงไม่มีการส่งไฟล์ SQL ไปยังเครื่องมือสร้างข้อมูลจริง

Codelab นี้มีทุกอย่างครบถ้วน คุณจึงไม่ต้องดาวน์โหลดอะไร คำสั่งด้านล่างจะเขียน DDL ของกราฟบริบทลงในไดเรกทอรีการทำงาน เนื้อหาของไฟล์จะเหมือนกับอาร์ติแฟกต์ที่จัดส่งใน examples/context_graph/codelab/

สร้างไดเรกทอรีการทำงาน

mkdir -p ~/context-graph-codelab
cd ~/context-graph-codelab

เขียน DDL กราฟบริบท (context_graph_ddl.sql) ระบบจะกรอกเครื่องหมาย ${PROJECT_ID} / ${DATASET} เมื่อคุณใช้ไฟล์ในขั้นตอนถัดไป

cat > context_graph_ddl.sql <<'SQL'

-- Node and edge table DDL for the context-graph codelab.
--
-- `bqaa context-graph` writes into these tables on every run.
-- `session_id` and `extracted_at` are SDK metadata columns that
-- `bqaa context-graph` fills automatically; they are required on
-- every table behind the graph.
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.decision_request` (
  request_id STRING, request_text STRING, requested_at TIMESTAMP,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.decision_option` (
  option_id STRING, option_label STRING, confidence FLOAT64,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.decision_outcome` (
  outcome_id STRING, status STRING, rationale STRING, decided_at TIMESTAMP,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.evaluates_option` (
  request_id STRING, option_id STRING,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.resulted_in` (
  request_id STRING, outcome_id STRING,
  session_id STRING, extracted_at TIMESTAMP
);

-- Graph DDL for the context-graph codelab.
--
-- Models a generic agent decision flow:
--   DecisionRequest -> evaluatesOption -> DecisionOption
--   DecisionRequest -> resultedIn       -> DecisionOutcome
CREATE OR REPLACE PROPERTY GRAPH `${PROJECT_ID}.${DATASET}.agent_decisions_graph`
  NODE TABLES (
    `${PROJECT_ID}.${DATASET}.decision_request` AS decision_request
      KEY (request_id)
      LABEL DecisionRequest PROPERTIES (request_id, request_text, requested_at),
    `${PROJECT_ID}.${DATASET}.decision_option` AS decision_option
      KEY (option_id)
      LABEL DecisionOption PROPERTIES (option_id, option_label, confidence),
    `${PROJECT_ID}.${DATASET}.decision_outcome` AS decision_outcome
      KEY (outcome_id)
      LABEL DecisionOutcome PROPERTIES (outcome_id, status, rationale, decided_at)
  )
  EDGE TABLES (
    `${PROJECT_ID}.${DATASET}.evaluates_option` AS evaluates_option
      KEY (request_id, option_id)
      SOURCE KEY (request_id) REFERENCES decision_request (request_id)
      DESTINATION KEY (option_id) REFERENCES decision_option (option_id)
      LABEL evaluatesOption,
    `${PROJECT_ID}.${DATASET}.resulted_in` AS resulted_in
      KEY (request_id, outcome_id)
      SOURCE KEY (request_id) REFERENCES decision_request (request_id)
      DESTINATION KEY (outcome_id) REFERENCES decision_outcome (outcome_id)
      LABEL resultedIn
  );
SQL

ยืนยันว่าไฟล์อยู่ในตำแหน่งที่ถูกต้อง

ls

คุณควรเห็นไฟล์ 1 ไฟล์ดังนี้

context_graph_ddl.sql

โฟลว์การตัดสินใจที่อธิบายมีโหนด 3 ประเภทและขอบ 2 รายการที่แตกต่างกัน

DecisionRequest คือคำถามที่เอเจนต์ได้รับ DecisionOption เป็นอีกทางเลือกหนึ่งที่ตัวแทนพิจารณา DecisionOutcome จะบันทึกตัวเลือกที่เลือกไว้และเหตุผล

5. ใช้สคีมา Property Graph

bqaa context-graph เขียนลงในตาราง BigQuery ดังนั้นตารางจึงต้องมีอยู่ก่อนการเรียกใช้ครั้งแรก context_graph_ddl.sql จะสร้างตารางทั้ง 5 ก่อน แล้วจึงสร้างกราฟพร็อพเพอร์ตี้ที่อ้างอิงตารางเหล่านั้น (BigQuery จะปฏิเสธ CREATE PROPERTY GRAPH ที่ชี้ไปยังตารางที่ยังไม่มีอยู่) ดังนั้น single apply จะตั้งค่าทุกอย่าง

envsubst < context_graph_ddl.sql | bq query --use_legacy_sql=false

คุณควรเห็นผลลัพธ์ CREATE TABLE 5 รายการและผลลัพธ์ CREATE PROPERTY GRAPH 1 รายการ DDL เป็นแบบ Idempotent คุณจึงเรียกใช้ซ้ำได้อย่างปลอดภัย

นั่นคือการทำงานกับสคีมาเพียงอย่างเดียวที่คุณต้องทำ และเป็นครั้งเดียวที่จะมีการใช้ไฟล์ SQL เหล่านี้ ตอนนี้ BigQuery จะบันทึกคำจำกัดความของกราฟ และ bqaa context-graph จะอ่านคำจำกัดความนั้นจาก INFORMATION_SCHEMA.PROPERTY_GRAPHS ตามชื่อ ไม่มีไฟล์แยกต่างหากที่จะส่งไปยัง Materializer และสิ่งที่คุณค้นหาด้วย GQL กับสิ่งที่ได้รับการสร้างขึ้นจะไม่มีวันแยกจากกันได้ เนื่องจากเป็นกราฟที่ติดตั้งใช้งานเดียวกัน

6. สร้างเหตุการณ์ตัวอย่างของ Agent

ในสภาพแวดล้อมการใช้งานจริง ปลั๊กอิน BigQuery Agent Analytics จะบันทึกเหตุการณ์โดยอัตโนมัติเมื่อ ADK Agent ทำงาน ข้อมูลโค้ดนี้มีไว้เพื่อใช้อ้างอิงเท่านั้น คุณไม่ต้องดำเนินการใน Codelab นี้

from google.adk.plugins import BigQueryAgentAnalyticsPlugin

plugin = BigQueryAgentAnalyticsPlugin(
    project_id="your-project-id",
    dataset_id="agent_analytics_demo",
)
runner = Runner(agent=root_agent, plugins=[plugin])

สำหรับ Codelab นี้ คุณจะใช้เครื่องมือสร้างเหตุการณ์สังเคราะห์ขนาดเล็กที่เขียนแถวที่มีรูปร่างเดียวกันลงใน agent_events โดยตรง ดำเนินการ

bqaa seed-events \
    --project-id "$PROJECT_ID" \
    --dataset-id "$DATASET" \
    --sessions 5

คำสั่งจะพิมพ์รายงาน JSON สำหรับ 5 เซสชัน คุณควรเห็น "events_generated": 30, "events_inserted": 30 และ "ok": true

ดูตัวอย่างคลังข้อมูลโดยย่อ เช่น จำนวนเซสชัน จำนวนเหตุการณ์ และช่วงเวลาที่ครอบคลุมได้ในแถวเดียว

bq query --use_legacy_sql=false \
    "SELECT COUNT(DISTINCT session_id) AS sessions, COUNT(*) AS events, MIN(timestamp) AS earliest_event, MAX(timestamp) AS latest_event FROM \`$PROJECT_ID.$DATASET.agent_events\`"

สําหรับการเรียกใช้ 5 เซสชันเริ่มต้น รายงานนี้จะแสดง 5 เซสชันและ 30 เหตุการณ์ที่เกิดขึ้นในช่วง 2-3 นาที (สร้างสถานการณ์สมมติที่สมจริงด้านล่างและรายงานการค้นหาเดียวกันจะแสดงเซสชันประมาณ 100 รายการในช่วง 3 วันโดยประมาณ)

ตรวจสอบว่าเหตุการณ์มาถึงแล้ว

bq query --use_legacy_sql=false \
    "SELECT event_type, COUNT(*) AS n FROM \`$PROJECT_ID.$DATASET.agent_events\` GROUP BY event_type ORDER BY n DESC"

คุณควรเห็น 25 TOOL_COMPLETED แถวและ 5 AGENT_COMPLETED แถว (แต่ละเซสชันจะปล่อย submit_request หนึ่งรายการ evaluate_option สามรายการ commit_outcome หนึ่งรายการ และ AGENT_COMPLETED ปิดหนึ่งรายการ ซึ่งเป็นเหตุการณ์เครื่องมือ 5 รายการและตัวสิ้นสุดเอเจนต์ 1 รายการต่อเซสชัน) AGENT_COMPLETED แถวคือตัวสิ้นสุดเซสชันที่ bqaa context-graph คีย์สําหรับการตรวจหาเหตุการณ์สิ้นสุด

ไม่บังคับ: ข้อมูลขนาดสมจริง

คลังข้อมูล 5 เซสชันด้านบนมีขนาดเล็กมากโดยตั้งใจเพื่อให้การเรียกใช้ครั้งแรกรวดเร็วและประหยัด เมื่อต้องการข้อมูลที่คล้ายกับข้อมูลการใช้งานจริง ซึ่งมีเอเจนต์และผู้ใช้หลายรายกระจายอยู่หลายวัน โดยมีเซสชันที่ล้มเหลว เซสชันที่ไม่มีผู้ปกครอง และเซสชันที่ถูกตัดทอน ให้ใช้decision-realisticสถานการณ์ ค่าเริ่มต้นคือ 100 เซสชันในช่วง 72 ชั่วโมง โดยเส้นทางการเรียกใช้ครั้งแรกด้านบนจะไม่มีการเปลี่ยนแปลง

bqaa seed-events \
    --project-id "$PROJECT_ID" \
    --dataset-id "$DATASET" \
    --scenario decision-realistic \
    --sessions 100 \
    --seed 42

session_outcome_counts ของรายงาน JSON แสดงส่วนผสม ซึ่งโดยประมาณคือ {"success": 70, "failed": 10, "orphaned": 10, "truncated": 10}

เมื่อมีคลังข้อความที่สมจริงนี้แล้ว คู่มือการวิเคราะห์เชิงสนทนาแบบเน้นการวิเคราะห์เป็นอันดับแรกจะแสดงวิธีถามคำถามเป็นภาษาอังกฤษธรรมดา ("คำขอใดที่ใช้ตัวเลือกที่มีความน่าเชื่อถือต่ำ") ก่อนที่จะเปลี่ยนไปใช้ GQL

ยืนยันการกระจายผลลัพธ์โดยจัดประเภทแต่ละเซสชันจากแถว (ไม่สมบูรณ์ = ไม่มี AGENT_COMPLETED; ล้มเหลว = AGENT_COMPLETED ที่มี status = 'error'; ถูกตัดทอน = แถวที่มี is_truncated = true; ไม่เช่นนั้นถือว่าสำเร็จ) การส่งผ่านครั้งแรกจะจัดประเภทแต่ละเซสชัน จากนั้นการส่งผ่านครั้งที่ 2 จะรวบรวมข้อมูลตามผลลัพธ์

bq query --use_legacy_sql=false \
    "WITH per_session AS (SELECT session_id, CASE WHEN COUNTIF(event_type = 'AGENT_COMPLETED') = 0 THEN 'orphaned' WHEN COUNTIF(event_type = 'AGENT_COMPLETED' AND status = 'error') > 0 THEN 'failed' WHEN COUNTIF(is_truncated) > 0 THEN 'truncated' ELSE 'success' END AS outcome FROM \`$PROJECT_ID.$DATASET.agent_events\` GROUP BY session_id) SELECT outcome, COUNT(*) AS sessions FROM per_session GROUP BY outcome ORDER BY outcome"

คุณควรเห็นการดำเนินการที่สำเร็จประมาณ 70 รายการ การดำเนินการที่ไม่สำเร็จ 10 รายการ การดำเนินการที่ไม่มีรายการหลัก 10 รายการ และการดำเนินการที่ถูกตัดทอน 10 รายการ (รวมถึงเซสชันที่สำเร็จ 5 รายการจากคลังข้อความที่รวบรวมจากการเรียกใช้ครั้งแรก หากคุณเริ่มต้นด้วยคลังข้อความดังกล่าวในชุดข้อมูลเดียวกันก่อนหน้านี้)

เซสชันที่ไม่มีเซสชันหลัก 10 รายการไม่เคยปล่อย AGENT_COMPLETED ดังนั้น bqaa context-graph ที่ทำงานโดยค่าเริ่มต้นจึงข้ามเซสชันเหล่านั้น (จะแสดงเฉพาะเซสชันที่ปิดเหตุการณ์สิ้นสุด) หากต้องการแสดงข้อผิดพลาดเป็น session_orphaned แทนที่จะลองใหม่ไปเรื่อยๆ โดยไม่มีการแจ้งเตือน ให้เพิ่ม --max-session-age-hours เมื่อดำเนินการ ดู --max-session-age-hours ในนำไปใช้จริง

สถานการณ์นี้จะกระจายเซสชันในช่วง 72 ชั่วโมงโดยมีวัตถุประสงค์ คำแนะนำแบบทีละขั้นตอนในการสร้างกราฟบริบทด้านล่างใช้ --lookback-hours 24 และเขียนขึ้นสำหรับคลังข้อมูลการเรียกใช้ครั้งแรกขนาดเล็ก 5 เซสชัน ดังนั้นจำนวนที่แน่นอนจึงถือว่าคุณไม่ได้ทำตามขั้นตอนที่ไม่บังคับนี้ หากคุณทำเช่นนั้นได้ นั่นคือบทเรียนที่ต้องการสื่อให้ทราบว่าหน้าต่างการสร้างข้อมูลแมตทีเรียลไลซ์ 24 ชั่วโมงจะเลือกเฉพาะข้อมูลล่าสุดของ Backlog หลายวัน ให้ขยาย --lookback-hours เพื่อบันทึกเซสชันที่เก่ากว่า

7. สร้างกราฟบริบท

bqaa context-graph จะอ่าน agent_events ดิบ จากนั้นอนุมานสิ่งที่ต้องดึงข้อมูลจากกราฟที่ติดตั้งใช้งานโดยตรง ซึ่งจะอ่านคำจำกัดความ CREATE PROPERTY GRAPH ที่คุณใช้ในใช้สคีมากราฟพร็อพเพอร์ตี้จาก INFORMATION_SCHEMA.PROPERTY_GRAPHS ของ BigQuery, รวมเข้ากับสคีมาของตารางที่อ้างอิง, คำนวณเอนทิตี ความสัมพันธ์ และประเภทคอลัมน์ แล้วป้อนข้อมูลลงในตารางกราฟ คุณชี้ไปที่กราฟที่ติดตั้งใช้งานตามชื่อด้วย --graph agent_decisions_graph โดยไม่ต้องส่งไฟล์ SQL

วิ่ง

bqaa context-graph ในพื้นที่:

bqaa context-graph \
    --project-id "$PROJECT_ID" \
    --dataset-id "$DATASET" \
    --graph agent_decisions_graph \
    --lookback-hours 24 \
    --format json

การเรียกใช้ครั้งแรกจะอ่านทุกเหตุการณ์ในกรอบเวลามองย้อนกลับและเขียนตารางกราฟ จึงอาจใช้เวลาสักครู่จึงจะเสร็จ

คุณควรเห็นรายงาน JSON ที่มีโครงสร้างดังนี้

{
  "run_id": "...",
  "sessions_discovered": 5,
  "sessions_materialized": 5,
  "sessions_failed": 0,
  "rows_materialized": {
    "DecisionRequest": 5,
    "DecisionOption": 15,
    "DecisionOutcome": 5
  },
  "ok": true
}

ok: true แสดงว่า bqaa context-graph พบเซสชันที่เสร็จสมบูรณ์ 5 รายการ ดึงโฟลว์การตัดสินใจจากแต่ละเซสชันผ่าน AI.GENERATE และเขียนแถวที่เกี่ยวข้องลงในตารางกราฟ การแยกข้อมูลแบบดีเทอร์มินิสติก (--extraction-mode=compiled-only อธิบายไว้ด้านล่าง) จะแสดงรูปร่างรายงานเดียวกัน ซึ่งมีฟิลด์เดียวกันและ ok: true เดียวกัน เพียงแต่จะข้ามการเรียก AI.GENERATE

การแก้ปัญหา: การแยกข้อมูลว่างเปล่า

หากเห็น ok: false ที่มี error_code = "empty_extraction" สาเหตุที่พบบ่อยที่สุดคือ aiplatform.googleapis.com API ยังไม่ได้เผยแพร่ หรือบัญชีของคุณไม่มี roles/aiplatform.user โปรดรอสักครู่แล้วลองอีกครั้ง หรือมอบบทบาทโดยทำดังนี้

USER_EMAIL=$(gcloud auth list --filter=status:ACTIVE --format="value(account)")
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
    --member="user:$USER_EMAIL" --role="roles/aiplatform.user"

จากนั้นเรียกใช้คำสั่ง bqaa context-graph ด้านบนอีกครั้ง

ตรวจสอบว่ากราฟมีแถว ดังนี้

bq query --use_legacy_sql=false \
    "SELECT COUNT(*) AS n FROM \`$PROJECT_ID.$DATASET.decision_request\`"

คุณควรจะเห็น 5 แถว ใน 5 เซสชันนั้นมีโหนดกราฟ 25 รายการทั้งหมด ซึ่งประกอบด้วย 5 DecisionRequest, 15 DecisionOption และ 5 DecisionOutcome โดยมีขอบ 15 evaluatesOption และขอบ 5 resultedIn (เว็บการตัดสินใจ 1 รายการต่อเซสชัน)

2 วิธีในการดึงข้อมูลการตัดสินใจจากเหตุการณ์

bqaa context-graph มีเส้นทางการแยกข้อมูล 2 เส้นทาง เลือกตัวเลือกที่ตรงกับภาระงานของคุณ

• การแยกค่าเริ่มต้น เส้นทางที่ง่ายที่สุด ใช้ AI.GENERATE ของ BigQuery เพื่ออ่านเนื้อหาเหตุการณ์และอนุมานเอนทิตีและความสัมพันธ์ ใช้ได้กับรูปร่างเหตุการณ์ใดก็ได้โดยไม่ต้องใช้โค้ดเพิ่มเติม ซึ่งเป็นสิ่งที่ Codelab ใช้
• การแยกข้อมูลแบบดีเทอร์มินิสติก (--extraction-mode=compiled-only) เส้นทางที่มีต้นทุนต่ำกว่าและตรวจสอบได้ง่าย ใช้เครื่องมือแยกข้อมูลอ้างอิง Python ขนาดเล็กที่คุณเขียนเพียงครั้งเดียวสำหรับโดเมน ไม่มีการเรียกใช้ Vertex AI, ไม่มีค่าใช้จ่ายต่อโทเค็น และเอาต์พุตที่ทำซ้ำได้อย่างสมบูรณ์ การติดตั้งใช้งานจริงจะเลือกตัวเลือกนี้เมื่อความสามารถในการคาดการณ์ต้นทุนหรือความสามารถในการทำซ้ำที่เข้มงวดมีความสำคัญ

คู่มือการติดตั้งใช้งานกราฟบริบทเป็นข้อมูลอ้างอิงสำหรับทั้ง 2 เส้นทาง ซึ่งรวมถึงรายละเอียด IAM และวิธีเขียนโปรแกรมแยกข้อมูลอ้างอิง

8. ค้นหาการติดตามการตัดสิน

เมื่อสร้างกราฟแล้ว คุณจะตอบคำถามการตรวจสอบได้โดยตรง ลองดูคำถามที่เฉพาะเจาะจง เช่น "สำหรับคำขอแต่ละรายการ เอเจนต์พิจารณาตัวเลือกใดบ้าง และแก้ไขปัญหาอย่างไร" ใน GQL ซึ่งเป็นการข้ามผ่านครั้งเดียวในคำขอ ตัวเลือก และผลลัพธ์

เขียนคำค้นหาลงในไฟล์ (traversal.sql) ระบบจะกรอกเครื่องหมาย ${DATASET} เมื่อคุณเรียกใช้ในขั้นตอนถัดไป

cat > traversal.sql <<'SQL'
SELECT *
FROM GRAPH_TABLE (
  ${DATASET}.agent_decisions_graph
  MATCH
    (req:DecisionRequest) -[eo:evaluatesOption]-> (opt:DecisionOption),
    (req)                 -[ri:resultedIn]->      (out:DecisionOutcome)
  COLUMNS (
    req.request_id   AS request,
    req.request_text AS question,
    opt.option_label AS considered,
    opt.confidence   AS score,
    out.status       AS outcome,
    out.rationale    AS rationale
  )
);
SQL

ดำเนินการ

envsubst < traversal.sql | bq query --use_legacy_sql=false --max_rows=20

คุณควรเห็น 15 แถว ซึ่งมี 3 ตัวเลือกต่อคำขอ และมีคำขอ 5 รายการ แต่ละแถวจะแสดงคำขอ ตัวเลือกที่ตัวแทนพิจารณา คะแนนความเชื่อมั่น ผลลัพธ์สุดท้าย และเหตุผล

หากต้องการดูภาพรวมทั้งหมดของการตัดสินใจครั้งเดียว ให้กรองตาม request_id เพื่อรับชุดแถวที่ทีมตรวจสอบต้องการ ได้แก่ คำถามที่เข้ามา ตัวเลือกที่พิจารณา (พร้อมคะแนน) และเหตุผลที่บันทึกไว้

แสดงภาพกราฟใน BigQuery Studio

BigQuery Studio ยังแสดงกราฟเป็นภาพได้ด้วย เปิด BigQuery Studio ในคอนโซล BigQuery เรียกใช้การค้นหาเส้นทางด้านล่าง จากนั้นเปลี่ยนบานหน้าต่างผลลัพธ์ไปที่แท็บกราฟเพื่อดูเว็บการตัดสินใจ โดยคลังข้อมูลขนาดสมจริงนี้จะแสดงแผนภาพของคำขอ ตัวเลือก และผลลัพธ์ให้คุณเห็น

GRAPH agent_analytics_demo.agent_decisions_graph
MATCH p = (a)-[e]->(b)
RETURN TO_JSON(p) AS path_json

คอนโซล BigQuery จะไม่ขยายตัวแปร Shell ดังนั้นให้วางชื่อชุดข้อมูลตามตัวอักษร คําค้นหานี้ใช้ agent_analytics_demo (ค่า DATASET จากส่วนก่อนเริ่มต้น) โปรดเปลี่ยนหากคุณใช้ชุดข้อมูลอื่น

ถามคำถามเดียวกันเป็นภาษาอังกฤษง่ายๆ

ผู้อ่านการตรวจสอบบางคนไม่ได้เขียน GQL ด้วย BigQuery Conversational Analytics (เวอร์ชันตัวอย่าง) ทีมการปฏิบัติตามข้อกำหนดของคุณสามารถถามคำถามประเภทเดียวกันในภาษาธรรมชาติและรับการ์ดคำตอบที่มีโครงสร้างได้โดยไม่ต้องใช้ไวยากรณ์การค้นหาหรือเรียนรู้การรวม

ลงทะเบียน agent_decisions_graph (พร้อมกับ agent_events และตารางการตัดสินใจ) เป็นแหล่งข้อมูล Conversational Analytics แล้วถามคำถามการตรวจสอบโดยตรง

คำถามในการตรวจสอบ (ภาษาอังกฤษธรรมดา): "คำขอใดที่ไม่เคยมีผลลัพธ์ที่แน่นอน"

Conversational Analytics จะให้เหตุผลเกี่ยวกับกราฟ เขียน SQL ให้คุณ และตอบกลับเป็นภาษาอังกฤษธรรมดาพร้อมตารางสนับสนุน ซึ่งในที่นี้คือทุกคำขอที่บันทึกไว้จะบรรลุผลลัพธ์ที่มุ่งมั่น

คำตอบด้านบนแสดงถึงคลังข้อความขนาดสมจริงจากขั้นตอนข้อมูลขนาดสมจริงที่ไม่บังคับ (คำขอที่สร้างขึ้น 90 รายการ ซึ่งทั้งหมดได้รับการยืนยัน) ตัวเลขที่แน่นอนจะขึ้นอยู่กับคลังข้อความที่คุณเริ่มต้น และการเรียกใช้ 5 เซสชันเริ่มต้นจะแสดง 5 รายการ

ดูการตั้งค่าได้ในเอกสารประกอบการวิเคราะห์เชิงสนทนา

9. นำไปใช้ในเวอร์ชันที่ใช้งานจริง

การเรียกใช้ในเครื่องด้านบนใช้ลักษณะการทำงานเริ่มต้น ซึ่งครอบคลุมพื้นฐานสำหรับการติดตั้งใช้งานจริงอยู่แล้ว นั่นคือ การเรียกใช้ทุกครั้งจะทิ้งบันทึกการตรวจสอบไว้ (Cloud Logging ที่มีโครงสร้างบวกแถวต่อการเรียกใช้ในตารางสถานะในชุดข้อมูลของคุณ) ระบบจะลองใหม่โดยอัตโนมัติหากเกิดข้อผิดพลาดชั่วคราว และความคืบหน้าจะเกิดขึ้นเฉพาะในเซสชันที่สำเร็จอย่างสมบูรณ์ จึงไม่มีการนับซ้ำ

การควบคุมการผลิต ซึ่งได้แก่ การแยกข้อมูลที่แน่นอน (--extraction-mode=compiled-only), การตรวจหาเซสชันที่ค้าง (--max-session-age-hours), การเล่นซ้ำแบบครั้งเดียวของหน้าต่างที่ผ่านมา (--backfill --from / --to ซึ่งติดตามแยกจากการรีเฟรชปกติเพื่อไม่ให้รบกวนตารางการถ่ายทอดสด) และการกำหนดขอบเขตแบบกลุ่มต่อการดำเนินการ (--max-sessions) เป็นค่าสถานะการเลือกใช้ที่คุณจะใช้เมื่อต้องการ คู่มือการติดตั้งใช้งานกราฟบริบทจะบันทึกแต่ละรายการพร้อมเมทริกซ์ IAM แบบเต็มและกำหนดการที่แนะนำ

จาก "เรียกใช้ครั้งเดียว" เป็น "เรียกใช้ทุกๆ 6 ชั่วโมง": SDK จะจัดส่งสคริปต์การทำให้ใช้งานได้และโมดูล Terraform ที่ห่อหุ้ม bqaa context-graph เป็นงาน Cloud Run ที่ทริกเกอร์โดย Cloud Scheduler โดยมีบัญชีบริการที่มีสิทธิ์น้อยที่สุดและสิทธิ์ IAM ที่งานต้องการ ทำตามสมุดรันบุ๊กการทำให้กราฟบริบทของตัวแทนที่กำหนดเวลาไว้ใช้งานเพื่อนำกราฟที่ทำให้ใช้งานได้นี้ไปใช้ในการทำให้ใช้งานได้ตามกำหนดเวลาด้วยโฟลว์ --graph เดียวกัน

10. ล้างข้อมูล

ลบสิ่งที่คุณสร้างเพื่อไม่ให้ระบบเรียกเก็บเงินสำหรับชุดข้อมูลที่ไม่ได้ใช้งาน

bq rm -r -f --dataset "$PROJECT_ID:$DATASET"

คำสั่งเดียวดังกล่าวจะนำชุดข้อมูล เหตุการณ์ของเอเจนต์ ตารางกราฟ และตารางสถานะออกพร้อมกัน

11. ขอแสดงความยินดี

ยินดีด้วย คุณได้เปลี่ยนบันทึกเหตุการณ์ของเอเจนต์ดิบเป็นกราฟบริบทของเอเจนต์ที่ค้นหาได้ และติดตามการตัดสินใจครั้งเดียวแบบครบวงจรโดยไม่ต้องใช้ฐานข้อมูลกราฟภายนอกหรือไปป์ไลน์ ETL

รูปแบบเดียวกันนี้ใช้ได้ทุกที่ที่ตัวแทนทำการตัดสินใจที่สำคัญ ได้แก่ การรับประกันเครดิต การอนุมัติล่วงหน้า การย้ายงบประมาณการตลาด การจัดซื้อจัดจ้าง การบริการลูกค้า และไอทีภายใน หากต้องการสร้างกราฟบริบทของ Agent ของคุณเอง ให้คัดลอกอาร์ติแฟกต์ของ Codelab เป็นจุดเริ่มต้น ปรับไฟล์ประกาศ 2 ไฟล์ (DDL ของตาราง + สคีมา CREATE PROPERTY GRAPH) ให้เข้ากับโดเมนของคุณ แล้วนำไปใช้กับ BigQuery - bqaa context-graph --graph จะอ่านกราฟที่ติดตั้งใช้งานกลับจาก INFORMATION_SCHEMA และอนุมานส่วนที่เหลือ

สิ่งที่คุณได้เรียนรู้

• วิธีสร้างชุดข้อมูล BigQuery และใช้สคีมา Property Graph ที่อธิบายโดเมนการตัดสินใจของเอเจนต์
• วิธีสร้าง agent_events ด้วยคลังเหตุการณ์สังเคราะห์
• วิธีเรียกใช้ bqaa context-graph เพื่อดึงข้อมูลการตัดสินใจของเอเจนต์ลงในกราฟบริบทของเอเจนต์จากเหตุการณ์เหล่านั้น โดยอ่านคําจํากัดความของกราฟจาก INFORMATION_SCHEMA
• วิธีค้นหากราฟผลลัพธ์ใน GQL และอ่านคำตอบในรูปแบบการตรวจสอบ

เอกสารอ้างอิง

• ที่เก็บ Analytics SDK ของเอเจนต์ BigQuery
• คู่มือการดัดแปลงและอาร์ติแฟกต์ของ Codelab
• คู่มือการติดตั้งใช้งานกราฟบริบท: API ที่จำเป็น, เมทริกซ์ IAM, กำหนดการที่แนะนำ, การค้นหาการแจ้งเตือนของ Cloud Monitoring และโมดูล Terraform
• เอกสารประกอบของ BigQuery Graph (ตัวอย่าง)
• เอกสารประกอบของ BigQuery Conversational Analytics (ตัวอย่าง)