Theo dõi các quyết định của tác nhân AI bằng BigQuery Graph

1. Giới thiệu

BigQuery Graph, BigQuery Conversational Analytics và BigQuery Agent Analytics SDK hiện đang ở giai đoạn Xem trước trên Google Cloud. Trình bổ trợ Phân tích tác nhân BigQuery hiện đã được phát hành rộng rãi (GA). Các ví dụ trong lớp học lập trình này sử dụng dữ liệu tổng hợp.

Khi các tác nhân AI tự trị đảm nhận nhiều trách nhiệm vận hành hơn (đánh giá đơn đăng ký vay, quản lý ngân sách tiếp thị, phê duyệt yêu cầu truy cập), các tổ chức phải có khả năng kiểm tra và giải thích các quyết định của mình. Việc tái tạo chính xác bối cảnh, các lựa chọn thay thế được cân nhắc và lý do cuối cùng cho quyết định của một tác nhân là điều cần thiết để tuân thủ, quản lý rủi ro và tin tưởng vào hoạt động.

Lớp học lập trình này sử dụng BigQuery Agent Analytics SDK để chuyển đổi nhật ký sự kiện thô của tác nhân thành Biểu đồ bối cảnh của tác nhân – một biểu đồ có thể truy vấn trong Biểu đồ BigQuery về các quyết định của tác nhân – theo lịch trình mà không cần cơ sở dữ liệu biểu đồ bên ngoài hoặc quy trình ETL.

Từ khóa

  • Dấu vết quyết định của tác nhân – bằng chứng ở cấp độ quyết định được lấy từ các lần chạy của chính tác nhân: các lựa chọn mà tác nhân cân nhắc, dữ liệu mà tác nhân đã xử lý và kết quả mà tác nhân đã cam kết.
  • Biểu đồ bối cảnh của tác nhân – biểu đồ có thể truy vấn, được nhập trong BigQuery Graph mà các dấu vết đó được hiện thực hoá. Đây là phiên bản có phạm vi tác nhân của khái niệm biểu đồ ngữ cảnh trong ngành (lớp ngữ cảnh quyết định bền vững, liên kết theo thời gian mà các tác nhân vừa tạo vừa sử dụng); trình đủ tiêu chuẩn "Tác nhân" sẽ giới hạn phạm vi trong các lần chạy tác nhân của riêng bạn thay vì lớp ngữ cảnh trên toàn doanh nghiệp.

Trong lớp học lập trình này, bqaa context-graph sẽ trích xuất dấu vết quyết định của tác nhân từ agent_events và hiện thực hoá chúng thành một Biểu đồ bối cảnh của tác nhân mà bạn có thể truy vấn bằng GQL – theo mẫu ngành, trong đó biểu đồ bối cảnh được tạo từ dấu vết quyết định.

Quy trình công việc của Biểu đồ ngữ cảnh tác nhân: các sự kiện của tác nhân ADK truyền qua Trình bổ trợ Phân tích tác nhân BigQuery vào bảng agent_events, biểu đồ ngữ cảnh bqaa trích xuất các dấu vết quyết định của tác nhân vào Biểu đồ ngữ cảnh tác nhân có cấu trúc và bạn truy vấn biểu đồ đó bằng GQL và Phân tích đàm thoại

Sản phẩm bạn sẽ tạo ra

  • Một Biểu đồ ngữ cảnh của tác nhân (với BigQuery Graph) mô hình hoá một quy trình quyết định chung của tác nhân: một yêu cầu được gửi đến, tác nhân cân nhắc các lựa chọn, một kết quả được đưa ra.
  • Một bảng agent_events được điền sẵn dữ liệu với một kho ngữ liệu sự kiện tổng hợp.
  • Một lần chạy bqaa context-graph đang hoạt động sẽ điền vào biểu đồ từ những sự kiện đó.
  • Một truy vấn GQL theo kiểu kiểm tra, theo dõi một quyết định duy nhất từ đầu đến cuối.

Kiến thức bạn sẽ học được

  • Cách Trình bổ trợ Phân tích tác nhân BigQuery ghi vào agent_events.
  • Cách biểu đồ bối cảnh được xác định chỉ bằng hai cấu phần phần mềm khai báo – một DDL bảng và một giản đồ CREATE PROPERTY GRAPH.
  • Cách chạy bqaa context-graph dựa trên Biểu đồ BigQuery.
  • Cách truy vấn biểu đồ bằng GQL.
  • Các chức năng cấp sản xuất mà SDK hỗ trợ cho việc triển khai doanh nghiệp.

Bạn cần có

  • Một dự án trên Google Cloud đã bật tính năng thanh toán.
  • Vai trò Chủ sở hữu hoặc Người chỉnh sửa trong dự án đó. Bạn sẽ tạo một tập dữ liệu BigQuery và cấp IAM.
  • Đã cài đặt và xác thực CLI gcloud hoặc có quyền truy cập vào Cloud Shell.
  • Python 3.10 trở lên.
  • Có kiến thức về BigQuery SQL. Bạn không cần có kiến thức về GQL.

Lớp học lập trình này dành cho nhà phát triển ở mọi cấp độ, kể cả những người mới làm quen với BigQuery Graph.

Các tài nguyên được tạo trong lớp học lập trình này có chi phí rất thấp và bước cuối cùng sẽ xoá mọi thứ để bạn không bị tính phí cho một tập dữ liệu không hoạt động.

Thời lượng ước tính: Bạn sẽ mất khoảng 35 phút để hoàn thành lớp học lập trình này.

2. Trước khi bắt đầu

Chọn một dự án và khu vực

Mở Cloud Shell hoặc một cửa sổ dòng lệnh cục bộ:

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

Biến DATASET duy nhất chứa cả bảng agent_events thô và các bảng đồ thị được hiện thực hoá. Việc sử dụng một tập dữ liệu giúp lớp học lập trình này trở nên đơn giản. Các hoạt động triển khai sản xuất thường chia các sự kiện và biểu đồ thành các tập dữ liệu riêng biệt để có thể cấp IAM một cách hẹp cho mỗi tập dữ liệu.

Bật các API bắt buộc

Chạy lệnh sau để bật các API mà lớp học lập trình này sử dụng:

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

Bạn cần có API aiplatform.googleapis.com vì đường dẫn trích xuất mặc định của SDK gọi hàm AI.GENERATE của BigQuery. Nếu sau này bạn chuyển sang phương thức trích xuất có tính xác định bằng --extraction-mode=compiled-only, thì bạn không cần dùng API này nữa.

Tạo tập dữ liệu BigQuery

Tạo tập dữ liệu sẽ chứa cả bảng agent_events thô và bảng biểu đồ cụ thể hoá:

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

Bạn sẽ thấy thông báo thành công:

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

Nếu tập dữ liệu đã tồn tại, lệnh sẽ báo lỗi không gây hại. Để nguyên vị trí.

3. Cài đặt SDK

Thiết lập môi trường ảo Python và cài đặt SDK từ PyPI:

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

Gói bigquery-agent-analytics sẽ kéo thư viện ứng dụng BigQuery, vì vậy, đây là gói duy nhất bạn cần cài đặt cho toàn bộ lớp học lập trình.

Xác minh quá trình cài đặt:

bqaa context-graph --help | head -8

Bạn sẽ thấy biểu ngữ CLI.

Xác thực

Nếu bạn đang sử dụng máy trạm, hãy thực hiện các bước sau đây:

gcloud auth login
gcloud auth application-default login

Người dùng Cloud Shell có thể bỏ qua bước này; thông tin đăng nhập đã được định cấu hình.

4. Lấy các cấu phần phần mềm của lớp học lập trình

Lớp học lập trình chỉ cần 2 cấu phần phần mềm sẵn sàng sử dụng: DDL bảng (các bảng đồ thị vật lý) và sơ đồ đồ thị thuộc tính (CREATE PROPERTY GRAPH). Bạn không tự tạo ra cả hai cấu phần phần mềm này; lớp học lập trình sử dụng chúng nguyên trạng và README trong thư mục cấu phần phần mềm giải thích cách điều chỉnh chúng cho miền quyết định của riêng bạn.

Giản đồ biểu đồ thuộc tính là nguồn thông tin xác thực duy nhất cho nội dung của biểu đồ. Bạn chỉ cần áp dụng một lần cho BigQuery; từ đó trở đi, chính biểu đồ được triển khai là hợp đồng. Khi bạn hiện thực hoá, bqaa context-graph sẽ đọc lại định nghĩa của biểu đồ từ INFORMATION_SCHEMA.PROPERTY_GRAPHS của BigQuery (cùng với giản đồ của các bảng mà biểu đồ tham chiếu) để xác định những thực thể và mối quan hệ cần trích xuất cũng như vị trí ghi các thực thể và mối quan hệ đó – do đó, không có tệp SQL nào được truyền đến trình hiện thực hoá.

Lớp học lập trình này độc lập, nên bạn không cần tải bất cứ thứ gì xuống. Lệnh bên dưới sẽ ghi DDL biểu đồ ngữ cảnh vào một thư mục đang hoạt động. Nội dung của tệp này giống hệt với các cấu phần phần mềm được vận chuyển trong examples/context_graph/codelab/.

Tạo thư mục đang hoạt động:

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

Viết DDL biểu đồ ngữ cảnh (context_graph_ddl.sql). Các điểm đánh dấu ${PROJECT_ID} / ${DATASET} sẽ được điền khi bạn áp dụng tệp ở bước tiếp theo.

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

Xác nhận rằng tệp đã được đặt đúng vị trí:

ls

Bạn sẽ thấy một tệp:

context_graph_ddl.sql

Luồng quyết định mà họ mô tả có 3 loại nút và 2 cạnh không đồng nhất:

Sơ đồ đồ thị cho lớp học lập trình: một nút DecisionRequest liên kết thông qua các cạnh evaluatesOption đến các nút DecisionOption mà nút đó đã cân nhắc, và thông qua cạnh resultedIn đến DecisionOutcome đã cam kết

DecisionRequest là câu hỏi mà tác nhân nhận được. DecisionOption là một lựa chọn thay thế mà trợ lý đã cân nhắc. DecisionOutcome ghi lại lựa chọn đã cam kết và lý do.

5. Áp dụng giản đồ biểu đồ thuộc tính

bqaa context-graph ghi vào các bảng BigQuery, vì vậy các bảng này phải tồn tại trước lần chạy đầu tiên. context_graph_ddl.sql tạo 5 bảng trước, sau đó tạo biểu đồ thuộc tính tham chiếu đến các bảng đó (BigQuery từ chối CREATE PROPERTY GRAPH trỏ đến các bảng chưa tồn tại), vì vậy, một lần áp dụng sẽ thiết lập mọi thứ:

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

Bạn sẽ thấy 5 kết quả CREATE TABLE và 1 kết quả CREATE PROPERTY GRAPH. DDL là phương thức bất biến; bạn có thể chạy lại phương thức này một cách an toàn.

Đó là công việc duy nhất liên quan đến giản đồ mà bạn thực hiện và cũng là lần duy nhất các tệp SQL này được dùng. BigQuery hiện ghi lại định nghĩa của biểu đồ và bqaa context-graph đọc lại định nghĩa đó từ INFORMATION_SCHEMA.PROPERTY_GRAPHS theo tên. Không có tệp riêng biệt nào để truyền đến trình hiện thực hoá và những gì bạn truy vấn bằng GQL và những gì được hiện thực hoá không bao giờ có thể tách rời: chúng là cùng một đồ thị được triển khai.

6. Tạo sự kiện tác nhân mẫu

Trong quá trình sản xuất, Trình bổ trợ Phân tích tác nhân BigQuery sẽ tự động ghi lại các sự kiện khi tác nhân ADK của bạn chạy. Đoạn mã này chỉ mang tính chất tham khảo – bạn không chạy đoạn mã này trong lớp học lập trình này:

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])

Trong lớp học lập trình này, bạn sẽ sử dụng một trình tạo sự kiện tổng hợp nhỏ để ghi cùng một hình dạng của các hàng trực tiếp vào agent_events. Kích hoạt:

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

Lệnh này in một báo cáo JSON. Đối với 5 phiên, bạn sẽ thấy "events_generated": 30, "events_inserted": 30 và "ok": true.

Xem nhanh tổng quan về tập hợp văn bản (số phiên, số sự kiện và khoảng thời gian mà các phiên và sự kiện đó diễn ra) trong một hàng:

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\`"

Đối với lần chạy 5 phiên mặc định, báo cáo này cho thấy 5 phiên và 30 sự kiện kéo dài trong vài phút. (Gieo hạt cho tình huống thực tế bên dưới và cùng một truy vấn báo cáo khoảng 100 phiên trong khoảng 3 ngày.)

Xác minh các sự kiện đã được ghi nhận:

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"

Bạn sẽ thấy 25 hàng TOOL_COMPLETED và 5 hàng AGENT_COMPLETED (mỗi phiên phát ra một submit_request, ba evaluate_option, một commit_outcome và một AGENT_COMPLETED đóng — năm sự kiện công cụ cộng với một sự kiện kết thúc tác nhân cho mỗi phiên). Các hàng AGENT_COMPLETED là các dấu hiệu kết thúc phiên mà các khoá bqaa context-graph bật để phát hiện sự kiện kết thúc.

Không bắt buộc: dữ liệu ở quy mô thực tế

Corpus gồm 5 phiên ở trên có kích thước rất nhỏ để lần chạy đầu tiên diễn ra nhanh chóng và tiết kiệm. Khi bạn muốn dữ liệu có hình dạng sản xuất – nhiều tác nhân và người dùng trải rộng trong vài ngày, với các phiên không thành công, bị bỏ rơi và bị cắt bớt – hãy sử dụng kịch bản decision-realistic. Theo mặc định, giá trị này là 100 phiên trong khung thời gian 72 giờ; đường dẫn chạy lần đầu tiên ở trên không thay đổi.

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

session_outcome_counts của báo cáo JSON cho thấy sự kết hợp này – khoảng {"success": 70, "failed": 10, "orphaned": 10, "truncated": 10}.

Xác nhận phân phối kết quả bằng cách phân loại từng phiên từ các hàng của phiên đó (bị bỏ rơi = không có AGENT_COMPLETED; thất bại = AGENT_COMPLETED có status = 'error'; bị cắt ngắn = mọi hàng có is_truncated = true; nếu không thì thành công). Lượt đầu tiên phân loại từng phiên, sau đó lượt thứ hai tổng hợp theo kết quả:

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"

Bạn sẽ thấy khoảng 70 thành công, 10 thất bại, 10 bị bỏ rơi và 10 bị cắt bớt (cộng với 5 phiên thành công từ tập hợp dữ liệu chạy lần đầu nếu bạn đã gieo hạt giống trước đó trong cùng một tập dữ liệu).

10 phiên bị bỏ rơi này chưa bao giờ phát ra AGENT_COMPLETED, vì vậy, lần chạy bqaa context-graph mặc định sẽ bỏ qua các phiên này (chỉ hiện thực hoá các phiên đã đóng sự kiện kết thúc). Để hiển thị các lỗi này dưới dạng session_orphaned thay vì âm thầm thử lại mãi mãi, hãy thêm --max-session-age-hours khi bạn kích hoạt – hãy xem --max-session-age-hours trong phần Đưa vào sản xuất.

7. Hiện thực hoá biểu đồ ngữ cảnh

bqaa context-graph đọc agent_events thô, sau đó đưa ra thông tin cần trích xuất trực tiếp từ biểu đồ đã triển khai: nó đọc định nghĩa CREATE PROPERTY GRAPH mà bạn đã áp dụng trong phần Áp dụng giản đồ biểu đồ thuộc tính từ INFORMATION_SCHEMA.PROPERTY_GRAPHS của BigQuery, kết hợp định nghĩa đó với giản đồ của các bảng mà nó tham chiếu, xác định các thực thể, mối quan hệ và loại cột, đồng thời điền sẵn các bảng biểu đồ. Bạn trỏ đến biểu đồ đã triển khai theo tên bằng --graph agent_decisions_graph – không có tệp SQL nào để truyền.

Chạy

bqaa context-graph tại địa phương:

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

Bạn sẽ thấy một báo cáo JSON có cấu trúc:

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

ok: true cho biết bqaa context-graph đã tìm thấy 5 phiên hoàn tất, trích xuất quy trình đưa ra quyết định từ mỗi phiên thông qua AI.GENERATE và ghi các hàng tương ứng vào bảng biểu đồ. Hoạt động trích xuất có tính xác định (--extraction-mode=compiled-only, được đề cập bên dưới) trả về hình dạng báo cáo giống nhau – các trường giống nhau, ok: true giống nhau – chỉ bỏ qua các lệnh gọi AI.GENERATE.

Khắc phục sự cố: trích xuất trống

Nếu bạn thấy ok: false có error_code = "empty_extraction", thì nguyên nhân phổ biến nhất là API aiplatform.googleapis.com chưa được truyền hoặc tài khoản của bạn thiếu roles/aiplatform.user. Chờ một phút rồi thử lại hoặc cấp vai trò:

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"

Sau đó, hãy chạy lại lệnh bqaa context-graph ở trên.

Xác minh xem biểu đồ có các hàng hay không:

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

Bạn sẽ thấy 5 hàng. Trong 5 phiên, tổng cộng có 25 nút đồ thị – 5 DecisionRequest, 15 DecisionOption và 5 DecisionOutcome – được kết nối bằng 15 cạnh evaluatesOption và 5 cạnh resultedIn (mỗi phiên có một mạng lưới quyết định).

Hai cách để trích xuất quyết định từ các sự kiện

bqaa context-graph cung cấp hai đường dẫn trích xuất. Chọn một trong những lựa chọn phù hợp với khối lượng công việc của bạn:

  • Trích xuất mặc định. Đường đi dễ nhất. Sử dụng AI.GENERATE của BigQuery để đọc nội dung sự kiện và suy luận các thực thể cũng như mối quan hệ. Hoạt động với mọi hình dạng sự kiện mà không cần thêm mã. Đây là những gì lớp học lập trình sử dụng.
  • Trích xuất có tính xác định (--extraction-mode=compiled-only). Phương pháp có chi phí thấp hơn và thân thiện với việc kiểm tra. Sử dụng một trình trích xuất tham chiếu Python nhỏ mà bạn chỉ cần viết một lần cho miền của mình. Không có lệnh gọi Vertex AI, không tính phí theo mã thông báo, đầu ra hoàn toàn có thể tái tạo. Triển khai sản xuất: chọn lựa chọn này khi bạn cần dự đoán chi phí hoặc khả năng tái tạo chính xác.

Hướng dẫn triển khai biểu đồ ngữ cảnh là tài liệu tham khảo cho cả hai đường dẫn, bao gồm cả thông tin chi tiết về IAM và cách tạo trình trích xuất tham chiếu.

8. Truy vấn dấu vết quyết định

Sau khi biểu đồ được điền sẵn, bạn có thể trả lời trực tiếp câu hỏi kiểm tra. Hãy lấy một ví dụ cụ thể: "Đối với mỗi yêu cầu, tác nhân đã cân nhắc những lựa chọn nào và giải quyết như thế nào?" Trong GQL, đó là một lần duyệt qua yêu cầu, các lựa chọn và kết quả của yêu cầu.

Ghi truy vấn vào một tệp (traversal.sql). Dấu đánh dấu ${DATASET} sẽ được điền khi bạn chạy truy vấn ở bước tiếp theo:

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

Kích hoạt:

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

Bạn sẽ thấy 15 hàng: 3 lựa chọn cho mỗi yêu cầu, 5 yêu cầu. Mỗi hàng cho biết yêu cầu, lựa chọn mà trợ lý đã cân nhắc, điểm số mức độ tin cậy, kết quả cuối cùng và lý do.

Để có được bức tranh đầy đủ về một quyết định duy nhất, hãy lọc theo request_id để có được bộ hàng mà nhóm kiểm tra cần: câu hỏi đã nhận được, các lựa chọn đã được cân nhắc (kèm theo điểm số) và lý do đã được đưa ra.

Trực quan hoá biểu đồ trong BigQuery Studio

BigQuery Studio cũng có thể hiển thị biểu đồ một cách trực quan. Mở BigQuery Studio trong bảng điều khiển BigQuery, chạy truy vấn đường dẫn bên dưới, sau đó chuyển ngăn kết quả sang thẻ Graph (Đồ thị) để xem web quyết định. Với tập hợp dữ liệu ở quy mô thực tế, bạn sẽ có một bản đồ trực quan về các yêu cầu, lựa chọn và kết quả:

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

Đồ thị ngữ cảnh được cụ thể hoá hiển thị trong chế độ xem Đồ thị của BigQuery Studio từ một truy vấn đường dẫn GQL

Đặt cùng một câu hỏi bằng tiếng Anh đơn giản

Không phải trình đọc nhật ký kiểm tra nào cũng viết GQL. Với tính năng Conversational Analytics của BigQuery (Bản dùng thử), nhóm tuân thủ của bạn có thể đặt cùng loại câu hỏi bằng ngôn ngữ tự nhiên và nhận được thẻ câu trả lời có cấu trúc mà không cần cú pháp truy vấn hay học cách kết hợp.

Đăng ký agent_decisions_graph (cùng với agent_events và bảng quyết định) làm nguồn dữ liệu Conversational Analytics, sau đó đặt câu hỏi kiểm tra trực tiếp:

Câu hỏi kiểm tra (tiếng Anh đơn giản): "Which requests never reached a committed outcome?" (Những yêu cầu nào chưa bao giờ đạt được kết quả đã cam kết?)

Tính năng Phân tích dựa trên cuộc trò chuyện suy luận trên biểu đồ, viết SQL cho bạn và trả lời bằng tiếng Anh đơn giản kèm theo một bảng hỗ trợ. Trong trường hợp này, mọi yêu cầu được ghi lại đều đạt được kết quả đã cam kết:

Conversational Analytics trả lời câu hỏi &quot;Những yêu cầu nào chưa bao giờ đạt được kết quả đã cam kết?&quot; trên biểu đồ ngữ cảnh: mọi yêu cầu được ghi lại đều đạt được kết quả đã cam kết (các phiên bị bỏ rơi không được hiện thực hoá dưới dạng các nút biểu đồ)

Câu trả lời ở trên phản ánh tập hợp quy mô thực tế từ bước dữ liệu quy mô thực tế không bắt buộc (90 yêu cầu cụ thể, tất cả đều được cam kết); số liệu chính xác của bạn phụ thuộc vào tập hợp mà bạn đã gieo và lần chạy 5 phiên mặc định sẽ cho thấy 5.

Hãy xem tài liệu về Conversational Analytics để biết cách thiết lập.

9. Phát hành công khai

Lần chạy cục bộ ở trên sử dụng hành vi mặc định, vốn đã bao gồm những điều cơ bản cho các hoạt động triển khai thực tế: mỗi lần chạy đều để lại nhật ký kiểm tra (Cloud Logging có cấu trúc cộng với một hàng cho mỗi lần chạy trong bảng trạng thái trong tập dữ liệu của bạn), các lỗi tạm thời sẽ tự động thử lại và tiến trình chỉ tiến hành trên các phiên hoàn toàn thành công, vì vậy không có trường hợp tính hai lần.

Các chế độ kiểm soát sản xuất (trích xuất xác định (--extraction-mode=compiled-only), phát hiện phiên bị kẹt (--max-session-age-hours), phát lại một lần của một cửa sổ trước đó (--backfill --from / --to, được theo dõi riêng với hoạt động làm mới thông thường để không làm gián đoạn lịch phát sóng trực tiếp) và phân chia theo lô cho mỗi lần chạy (--max-sessions)) là các cờ chọn sử dụng mà bạn có thể sử dụng khi cần. Hướng dẫn triển khai biểu đồ ngữ cảnh ghi lại từng biểu đồ bằng ma trận IAM đầy đủ và lịch trình được đề xuất.

10. Dọn dẹp

Xoá những gì bạn đã tạo để không bị tính phí cho một tập dữ liệu không hoạt động:

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

Lệnh duy nhất đó sẽ xoá tập dữ liệu, các sự kiện của tác nhân, các bảng đồ thị và bảng trạng thái cùng một lúc.

11. Xin chúc mừng

Xin chúc mừng! Bạn đã chuyển nhật ký sự kiện của tác nhân thô thành một Biểu đồ bối cảnh của tác nhân có thể truy vấn và theo dõi một quyết định duy nhất từ đầu đến cuối mà không cần cơ sở dữ liệu biểu đồ bên ngoài hoặc quy trình ETL.

Mô hình tương tự cũng áp dụng ở bất kỳ nơi nào mà một tác nhân đưa ra quyết định quan trọng: bảo lãnh tín dụng, uỷ quyền trước, thay đổi ngân sách tiếp thị, mua sắm, dịch vụ khách hàng và công nghệ thông tin nội bộ. Để tạo Biểu đồ bối cảnh của tác nhân, hãy sao chép các cấu phần phần mềm của lớp học lập trình làm điểm bắt đầu, điều chỉnh 2 tệp khai báo (DDL bảng + giản đồ CREATE PROPERTY GRAPH) cho miền của bạn và áp dụng chúng vào BigQuery – bqaa context-graph --graph sẽ đọc biểu đồ đã triển khai từ INFORMATION_SCHEMA và suy ra phần còn lại.

Kiến thức bạn học được

  • Cách tạo một tập dữ liệu BigQuery và áp dụng giản đồ biểu đồ thuộc tính mô tả miền quyết định của tác nhân.
  • Cách điền sẵn agent_events bằng một tập hợp sự kiện giả tạo.
  • Cách chạy bqaa context-graph để trích xuất dấu vết quyết định của tác nhân vào Biểu đồ ngữ cảnh của tác nhân từ những sự kiện đó, đọc lại định nghĩa biểu đồ từ INFORMATION_SCHEMA.
  • Cách truy vấn biểu đồ kết quả trong GQL và đọc câu trả lời theo kiểu kiểm tra.

Tài liệu tham khảo