تتبُّع قرارات وكيل الذكاء الاصطناعي باستخدام 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

من المفترض أن يظهر لك بانر واجهة سطر الأوامر.

مصادقة

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

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} تقريبًا.

بعد الحصول على هذه المجموعة الواقعية من النصوص، يوضّح دليل "التحليلات الحوارية أولاً" كيفية طرح السؤال باللغة الإنجليزية البسيطة ("which requests weighed a low-confidence option?" أي "ما هي الطلبات التي فضّلت خيارًا بمستوى ثقة منخفض؟") قبل الانتقال إلى 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 جلسات ناجحة من مجموعة النصوص عند التشغيل لأول مرة إذا أضفتها سابقًا في مجموعة البيانات نفسها).

لم تُصدر الجلسات العشر المعزولة 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، ثم اطرح سؤال التدقيق مباشرةً:

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

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

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

يمكنك الاطّلاع على مستندات "الإحصاءات الحوارية" لمعرفة خطوات الإعداد.

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 التي يحتاجها الإجراء. اتّبِع دليل التشغيل الخاص بنشر "مخطط سياق الوكيل" المُجدوَل لنقل هذا المخطط الذي تم نشره إلى عملية نشر مُجدوَلة باستخدام مسار --graph نفسه.

10. تَنظيم

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

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

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

11. تهانينا

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

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