تتبُّع قرارات وكيل الذكاء الاصطناعي باستخدام BigQuery Graph

1. مقدمة

تتوفّر حاليًا ميزات BigQuery Graph وBigQuery Conversational Analytics وBigQuery Agent Analytics SDK في إصدار تجريبي على Google Cloud. المكوّن الإضافي BigQuery Agent Analytics متاح للجميع. تستخدِم الأمثلة في هذا الدرس التطبيقي بيانات اصطناعية.

مع تولي وكلاء الذكاء الاصطناعي المستقلين المزيد من المسؤوليات التشغيلية (مثل تقييم طلبات القروض وإدارة ميزانيات التسويق والموافقة على طلبات الوصول)، يجب أن تتمكّن المؤسسات من تدقيق قراراتهم وتفسيرها. تُعدّ إعادة إنشاء السياق الدقيق والبدائل التي تمّت دراستها والأساس المنطقي النهائي لقرار أحد العملاء أمرًا ضروريًا للامتثال وإدارة المخاطر والثقة التشغيلية.

يستخدم هذا الدرس التطبيقي حزمة تطوير البرامج (SDK) الخاصة بـ "إحصاءات وكيل BigQuery" لتحويل سجلّات أحداث الوكيل الأولية إلى مخطّط سياق الوكيل، وهو مخطط قابل للاستعلام في "مخطّط BigQuery" لقرارات الوكيل، وذلك وفقًا لجدول زمني محدّد، بدون أي قاعدة بيانات خارجية للمخطّطات أو مسار ETL.

العبارات الرئيسية

• تتبُّع قرار الوكيل: هو دليل على مستوى القرار يتم استخلاصه من عمليات تشغيل الوكيل، ويتضمّن الخيارات التي درسها والبيانات التي استخدمها والنتيجة التي توصّل إليها.
• مخطط سياق الوكيل: هو مخطط قابل للبحث فيه ومكتوب في BigQuery Graph يتم تحويل عمليات التتبُّع هذه إليه. وهي نسخة على مستوى الوكيل من مفهوم مخطط السياق الخاص بالنشاط التجاري (وهي طبقة دائمة مرتبطة بالوقت من سياق اتخاذ القرار الذي ينتجه الوكلاء ويستخدمونه)، ويحدّد المؤهّل "الوكيل" نطاقها ليشمل عمليات تشغيل وكلائك بدلاً من طبقة سياق على مستوى المؤسسة.

في هذا الدرس التطبيقي حول الترميز، تستخرج أداة bqaa context-graph آثار قرارات الوكيل من agent_events وتحوّلها إلى "رسم بياني لسياق الوكيل" يمكنك البحث فيه باستخدام GQL، وذلك باتّباع النمط الشائع في المجال حيث يتم إنشاء رسومات بيانية للسياق من آثار القرارات.

ما ستنشئه

• رسم بياني لسياق الوكيل (مع BigQuery Graph) يضع نموذجًا لسير عمل عام لاتّخاذ القرارات من قِبل الوكيل: يتم تلقّي طلب، ويقيّم الوكيل الخيارات، ويتم تنفيذ النتيجة.
• جدول agent_events مملوء بمجموعة من الأحداث الاصطناعية
• bqaa context-graph عملية تشغيل تعمل على ملء الرسم البياني من هذه الأحداث
• استعلام GQL بنمط التدقيق يتتبّع قرارًا واحدًا من البداية إلى النهاية.

أهداف الدورة التعليمية

• طريقة كتابة المكوّن الإضافي BigQuery Agent Analytics في agent_events
• كيف يتم تحديد الرسم البياني للسياق من خلال عنصرَين تعريفيَين فقط، وهما DDL للجدول ومخطط CREATE PROPERTY GRAPH.
• كيفية تنفيذ bqaa context-graph على رسم بياني في BigQuery
• كيفية طلب بحث في رسم بياني باستخدام GQL
• الإمكانات الجاهزة للاستخدام في بيئة الإنتاج التي تتيحها حزمة SDK لعمليات النشر في المؤسسات

المتطلبات

• مشروع Google Cloud تم تفعيل الفوترة فيه
• دور المالك أو المحرِّر في هذا المشروع ستنشئ مجموعة بيانات في BigQuery وتمنح إذن الوصول إلى "إدارة الهوية وإمكانية الوصول".
• يجب أن تكون واجهة سطر الأوامر gcloud مثبَّتة ومصدَّقًا عليها، أو يجب أن يكون لديك إذن الوصول إلى Cloud Shell.
• الإصدار 3.10 أو الإصدارات الأحدث من Python
• الإلمام بلغة SQL في BigQuery لا يلزم معرفة لغة GQL.

هذا الدرس العملي مخصّص للمطوّرين من جميع المستويات، بما في ذلك المطوّرون الجدد في BigQuery Graph.

تتطلّب الموارد التي تم إنشاؤها في هذا الدرس التطبيقي حول الترميز القليل جدًا، وتؤدي الخطوة الأخيرة إلى إيقاف كل شيء حتى لا تتم فوترتك مقابل مجموعة بيانات غير مستخدَمة من قِبل أي برنامج حاليًا.

المدة المقدَّرة: يستغرق إكمال هذا الدرس العملي حوالي 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) بشكل محدود لكل مجموعة بيانات.

تفعيل واجهات برمجة التطبيقات المطلوبة

نفِّذ الأمر التالي لتفعيل واجهات برمجة التطبيقات التي يستخدمها هذا الدرس التطبيقي حول الترميز:

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

يجب توفّر واجهة برمجة التطبيقات aiplatform.googleapis.com لأنّ مسار الاستخراج التلقائي لحزمة تطوير البرامج (SDK) يستدعي الدالة AI.GENERATE في BigQuery. إذا انتقلت لاحقًا إلى الاستخراج الحتمي باستخدام --extraction-mode=compiled-only، لن تحتاج إلى واجهة برمجة التطبيقات هذه.

إنشاء مجموعة بيانات 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، لذا هذا هو التثبيت الوحيد الذي تحتاجه في كل درس تطبيقي حول الترميز.

التحقّق من عملية التثبيت:

bqaa context-graph --help | head -8

من المفترض أن يظهر لك بانر سطر الأوامر (CLI).

مصادقة

إذا كنت تستخدم محطة عمل:

gcloud auth login
gcloud auth application-default login

يمكن لمستخدمي Cloud Shell تخطّي هذه الخطوة، لأنّ بيانات الاعتماد تم إعدادها مسبقًا.

4. الحصول على نتائج الدرس التطبيقي حول الترميز

لا يحتاج الدرس التطبيقي حول الترميز إلا إلى عنصرَين جاهزَين للاستخدام: جدول DDL (جداول الرسم البياني الفعلي) ومخطط الرسم البياني للعناصر (CREATE PROPERTY GRAPH). ولست بحاجة إلى إنشاء أي منهما بنفسك، إذ يستخدمهما الدرس التطبيقي حول الترميز كما هما، ويوضّح ملف README في مجلد العناصر كيفية تعديلهما ليناسبا مجال اتخاذ القرار الخاص بك.

مخطط الرسم البياني للعلاقات هو المصدر الوحيد للمعلومات الصحيحة حول محتوى الرسم البياني. يمكنك تطبيقها على BigQuery مرة واحدة، وبعد ذلك يكون الرسم البياني الذي تم نشره هو العقد. عند إنشاء العرض المادي، تقرأ الدالة bqaa context-graph تعريف الرسم البياني من INFORMATION_SCHEMA.PROPERTY_GRAPHS في BigQuery (بالإضافة إلى مخططات الجداول التي تشير إليها) لتحديد الكيانات والعلاقات التي سيتم استخراجها ومكان كتابتها، وبالتالي لا يتم تمرير أي ملف SQL إلى أداة إنشاء العرض المادي.

هذا الدرس التطبيقي حول الترميز موجّه ذاتيًا، لذا لا يلزم إجراء عملية تنزيل لأي شيء. يكتب الأمر أدناه لغة تعريف البيانات الخاصة بمخطط السياق في دليل عمل. محتواه مطابق للعناصر التي تم شحنها في 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

من المفترض أن يظهر لك ملف واحد:

context_graph_ddl.sql

يتضمّن مسار اتّخاذ القرار الذي يصفونه ثلاثة أنواع من العُقد وحافتين مختلفتين:

DecisionRequest هو السؤال الذي تلقّاه الوكيل. DecisionOption هو أحد الخيارات البديلة التي أخذها الموظف في الاعتبار. تسجّل DecisionOutcome الخيار الذي تم الالتزام به والسبب.

5- تطبيق مخطط الرسم البياني للعناصر

تكتب bqaa context-graph في جداول BigQuery، لذا يجب أن تكون هذه الجداول متوفّرة قبل التشغيل الأول. ينشئ context_graph_ddl.sql الجداول الخمسة أولاً ثم الرسم البياني للسمات الذي يشير إليها (ترفض BigQuery عبارة CREATE PROPERTY GRAPH التي تشير إلى جداول غير موجودة بعد)، لذا يؤدي تطبيق واحد إلى إعداد كل شيء:

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

من المفترض أن تظهر لك خمس نتائج CREATE TABLE ونتيجة واحدة CREATE PROPERTY GRAPH. إنّ لغة تعريف البيانات (DDL) هي لغة متكررة، ويمكنك إعادة تشغيلها بأمان.

هذا هو العمل الوحيد الذي عليك إجراؤه على المخطط، وهو المرة الوحيدة التي يتم فيها استخدام ملفات SQL هذه. تسجّل BigQuery الآن تعريف الرسم البياني، وتعيد bqaa context-graph قراءته من INFORMATION_SCHEMA.PROPERTY_GRAPHS بالاسم. لا يوجد ملف منفصل لتمريره إلى أداة التحويل، ولا يمكن أن يختلف ما تستعلمه باستخدام GQL عمّا يتم تحويله: فهما الرسم البياني نفسه الذي تم نشره.

6. إنشاء أحداث وكيل نموذجية

في مرحلة الإنتاج، يسجّل المكوّن الإضافي BigQuery Agent Analytics الأحداث تلقائيًا أثناء تشغيل وكيل ADK. هذا المقتطف مخصّص للمراجعة فقط، ولن يتم تنفيذه في هذا الدرس العملي:

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

في هذا الدرس التطبيقي، ستستخدم أداة صغيرة لإنشاء أحداث اصطناعية تكتب شكل الصفوف نفسه مباشرةً إلى 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 حدثًا على مدار بضع دقائق. (يجب إعداد السيناريو الواقعي أدناه، وستسجّل تقارير طلب البحث نفسها حوالي 100 جلسة على مدار ثلاثة أيام تقريبًا).

تأكَّد من وصول الأحداث:

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 واحدًا للإغلاق، أي خمسة أحداث أدوات بالإضافة إلى أداة إنهاء واحدة لكل جلسة). تمثّل الصفوف 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؛ وإلا يكون ناجحًا). يصنّف التمرير الأول كل جلسة، ثم يجمع التمرير الثاني حسب النتيجة:

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 ساعة سوى الجزء الأخير من سجلّ متراكم لعدة أيام، لذا وسِّع --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 إلى أنّ النظام عثر على خمس جلسات مكتملة، واستخرج مسار اتخاذ القرار من كل جلسة باستخدام AI.GENERATE، وكتب الصفوف المقابلة في جداول الرسومات البيانية.bqaa context-graph تؤدي عملية الاستخراج المحدَّدة (--extraction-mode=compiled-only، التي سيتم تناولها أدناه) إلى عرض شكل التقرير نفسه، أي الحقول نفسها وok: true نفسها، ولكنها تتخطى طلبات AI.GENERATE.

تحديد المشاكل وحلّها: استخراج فارغ

إذا ظهرت لك الرسالة ok: false مع error_code = "empty_extraction"، يكون السبب الأكثر شيوعًا هو أنّ واجهة برمجة التطبيقات aiplatform.googleapis.com لم يتم نشرها بعد، أو أنّ حسابك لا يتضمّن 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\`"

من المفترض أن تظهر لك خمسة صفوف. في الجلسات الخمس، يكون هناك 25 عقدة رسم بياني إجمالاً، أي 5 عقد DecisionRequest و15 عقدة DecisionOption و5 عقد DecisionOutcome، مرتبطة بـ 15 حافة evaluatesOption و5 حواف resultedIn (شبكة قرار واحدة لكل جلسة).

طريقتان لاستخراج القرارات من الأحداث

توفّر bqaa context-graph مسارَين للاستخراج. اختَر الخيار الذي يتطابق مع حجم العمل لديك:

• الاستخراج التلقائي: المسار الأسهل يستخدم AI.GENERATE من BigQuery لقراءة محتوى الحدث واستنتاج الكيانات والعلاقات. تعمل هذه الميزة مع أي شكل حدث بدون الحاجة إلى رموز إضافية. هذا ما يستخدمه الدرس التطبيقي.
• الاستخراج الحتمي (--extraction-mode=compiled-only): المسار الأقل تكلفةً والأكثر ملاءمةً للتدقيق يستخدم أداة استخراج مراجع صغيرة بلغة Python تكتبها مرة واحدة لنطاقك. لا يتم إجراء أي طلبات إلى Vertex AI، ولا يتم تحصيل أي رسوم مقابل الرموز المميزة، ويكون الناتج قابلاً لإعادة الإنتاج بالكامل. تختار عمليات نشر الإنتاج هذا الخيار عندما تكون القدرة على توقّع التكلفة أو إمكانية إعادة الإنتاج بدقة أمرًا مهمًا.

دليل نشر الرسم البياني السياقي هو المرجع لكلا المسارين، بما في ذلك تفاصيل إدارة الهوية وإمكانية الوصول (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

من المفترض أن تظهر خمسة عشر صفًا: ثلاثة خيارات لكل طلب، وخمسة طلبات. يعرض كل صف الطلب والخيار الذي نظر فيه الموظف ونتيجة الثقة والنتيجة النهائية والأساس المنطقي.

للحصول على صورة كاملة عن قرار واحد، يمكنك الفلترة حسب 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 (إصدار تجريبي)، يمكن لفريق الامتثال طرح النوع نفسه من الأسئلة باللغة الطبيعية والحصول على بطاقة إجابة منظَّمة، بدون الحاجة إلى بنية طلب بحث أو عمليات ربط.

سجِّل agent_decisions_graph (مع agent_events وجداول القرارات) كمصدر بيانات في Conversational Analytics، ثم اطرح سؤال التدقيق مباشرةً:

سؤال التدقيق (باللغة الإنجليزية البسيطة): "ما هي الطلبات التي لم تصل إلى نتيجة نهائية؟"

تستند "الإحصاءات الحوارية" إلى الرسم البياني، وتكتب رمز SQL نيابةً عنك، وتردّ باللغة الإنجليزية البسيطة مع جدول داعم، كما هو موضح أدناه، حيث وصل كل طلب مسجّل إلى نتيجة نهائية:

تعكس الردود أعلاه مجموعة النصوص الواقعية من خطوة البيانات الواقعية الاختيارية (90 طلبًا تم تنفيذه، وتمت الموافقة على جميعها). وتعتمد الأرقام الدقيقة على مجموعة النصوص التي أضفتها، ويعرض التشغيل التلقائي لخمس جلسات خمسة ردود.

يمكنك الاطّلاع على مستندات Conversational Analytics لمعرفة كيفية الإعداد.

9. طرحه في الإصدار العلني

يستخدم التشغيل المحلي أعلاه السلوك التلقائي الذي يغطي الأساسيات اللازمة لعمليات النشر الفعلية: يترك كل تشغيل سجل تدقيق (Cloud Logging منظَّم بالإضافة إلى صف لكل عملية تشغيل في جدول حالة في مجموعة البيانات)، ويتم تلقائيًا إعادة محاولة حالات الفشل المؤقتة، ولا يتم إحراز أي تقدّم إلا في الجلسات التي نجحت بالكامل، وبالتالي لا يتم احتساب أي شيء مرتين.

عناصر التحكّم في الإنتاج، مثل الاستخراج الحتمي (--extraction-mode=compiled-only) ورصد الجلسات المتوقفة (--max-session-age-hours) وإعادة تشغيل نافذة سابقة لمرة واحدة (--backfill --from / --to، يتم تتبّعها بشكل منفصل عن عملية إعادة التحميل العادية حتى لا تؤثر في جدول البث المباشر) وتحديد حدود الدُفعات لكل عملية تشغيل (--max-sessions)، هي علامات يمكنك تفعيلها عند الحاجة إليها. يوثّق دليل نشر الرسم البياني للسياق كلًّا منها باستخدام مصفوفة "إدارة الهوية وإمكانية الوصول" الكاملة والجداول الزمنية المقترَحة.

من "تشغيل هذا الإجراء مرة واحدة" إلى "تشغيل هذا الإجراء كل ست ساعات": توفّر حزمة تطوير البرامج (SDK) نصًا برمجيًا للتوزيع ووحدة Terraform تتضمّن bqaa context-graph كـ Cloud Run Job يتم تشغيله بواسطة Cloud Scheduler، مع حسابات خدمة بأقل امتيازات وأذونات IAM التي يحتاجها Job. اتّبِع دليل التشغيل الخاص بنشر "رسم بياني لسياق الوكيل" مُجدوَل لنقل هذا الرسم البياني المنشور إلى عملية نشر مُجدوَلة باستخدام مسار --graph نفسه.

10. تَنظيم

إيقاف ما أنشأته حتى لا يتم تحصيل رسوم منك مقابل مجموعة بيانات غير نشطة:

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

يزيل هذا الأمر الفردي مجموعة البيانات وأحداث الوكيل وجداول الرسومات وجدول الحالة معًا.

11. تهانينا

تهانينا! لقد حوّلت سجلّات أحداث الوكيل الأولية إلى "رسم بياني لسياق الوكيل" قابل للاستعلام، وتتبّعت قرارًا واحدًا من البداية إلى النهاية، بدون قاعدة بيانات رسوم بيانية خارجية أو مسار استخراج البيانات وتحويلها وتحميلها.

وينطبق النمط نفسه في أي مكان يتخذ فيه الموظف قرارات مهمة، مثل تقييم الجدارة الائتمانية، والموافقة المسبقة، وتحويل ميزانية التسويق، والمشتريات، وخدمة العملاء، وتكنولوجيا المعلومات الداخلية. لإنشاء "رسم بياني لسياق الوكيل" خاص بك، انسخ عناصر codelab كنقطة بداية، وعدِّل الملفَين التوضيحيَين (DDL للجدول + مخطط CREATE PROPERTY GRAPH) ليناسبا نطاقك، وطبِّقهما على BigQuery. سيقرأ bqaa context-graph --graph الرسم البياني الذي تم نشره من INFORMATION_SCHEMA ويستنتج الباقي.

ما تعلّمته

• كيفية إنشاء مجموعة بيانات BigQuery وتطبيق مخطط رسم بياني للعلاقات يصف نطاق قرار وكيل
• كيفية ملء agent_events بمجموعة من الأحداث الاصطناعية
• كيفية تنفيذ bqaa context-graph لاستخراج آثار قرار الوكيل إلى "رسم بياني لسياق الوكيل" من تلك الأحداث، وقراءة تعريف الرسم البياني مرة أخرى من INFORMATION_SCHEMA
• كيفية طلب البحث في الرسم البياني الناتج باستخدام GQL وقراءة الإجابة بأسلوب التدقيق

المستندات المرجعية

• مستودع حزمة تطوير البرامج (SDK) الخاصة بـ BigQuery Agent Analytics
• نتائج الدرس التطبيقي حول الترميز ودليل التكيّف
• دليل نشر "الرسم البياني للسياق": واجهات برمجة التطبيقات المطلوبة، ومصفوفة إدارة الهوية وإمكانية الوصول، والجداول الزمنية المقترَحة، وطلبات البحث عن تنبيهات Cloud Monitoring، ووحدة Terraform.
• مستندات BigQuery Graph (معاينة)
• مستندات BigQuery Conversational Analytics (معاينة)