בדיקת QueryData

במסמך הזה מוסבר איך לבדוק את QueryData ל-Spanner Graph באמצעות קריאה ל-method‏ QueryData של Conversational Analytics API, ואיך לעדכן את קובץ קבוצת ההקשר. אתם יכולים לבדוק את היכולת של QueryData ליצור שאילתות ב-Graph Query Language‏ (GQL) משאלות בשפה טבעית. אם שאילתת GQL שנוצרה לא מדויקת, אתם יכולים לעדכן את קובץ קבוצת ההקשר.

סקירה כללית על קבוצות הקשרים ב-Spanner Graph

לפני שמתחילים

איך מוצאים את המזהה של קבוצת ההקשרים הקיימת

כדי לבדוק את QueryData עם קבוצת ההקשרים, או כדי לחבר אפליקציית נתונים ל-QueryData, אתם צריכים את המזהה של קבוצת ההקשרים.

  1. נכנסים לדף Spanner במסוף Google Cloud .

    כניסה ל-Spanner

  2. בוחרים מכונה מהרשימה ואז בוחרים מסד נתונים.

  3. בתפריט הניווט, לוחצים על Spanner Studio.

  4. בחלונית Explorer, לוחצים על View actions ליד קבוצת ההקשר שבה משתמשים.

  5. לוחצים על עריכת קבוצת ההקשר.

  6. שימו לב למזהה של קבוצת ההקשרים בקטע מזהה קבוצת ההקשרים. הפורמט של מזהה קבוצת ההקשר דומה ל-projects/my-project/locations/us-central1/contextSets/fingraph-assistant.

בדיקת QueryData באמצעות HTTP POST

כדי לבדוק את QueryData ב-Spanner Graph, שולחים בקשת POST מסוג QueryData שכוללת את השדה graph_ids ואת מזהה קבוצת ההקשר:

  1. יוצרים קובץ בשם request.json עם התוכן הבא:

    {
      "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
      "context": {
        "datasource_references": {
          "spanner_reference": {
            "database_reference": {
              "engine": "GOOGLE_SQL",
              "project_id": "PROJECT_ID",
              "instance_id": "INSTANCE_ID",
              "database_id": "DATABASE_ID",
              "graph_ids": ["FinGraph"]
            },
            "agent_context_reference": {
              "context_set_id": "CONTEXT_SET_ID"
            }
          }
        }
      },
      "generation_options": {
        "generate_query_result": true,
        "generate_natural_language_answer": true,
        "generate_explanation": true
      }
    }

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫INSTANCE_ID: מזהה המכונה של Spanner.
    • ‫DATABASE_ID: מזהה מסד הנתונים ב-Spanner.
    • ‫CONTEXT_SET_ID: המזהה המלא של קבוצת ההקשרים שרשמתם לעצמכם בקטע איתור המזהה של קבוצת ההקשרים.
  2. שולחים את הבקשה:

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "x-goog-user-project: PROJECT_ID" \
      "https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/global:queryData" \
      -d @request.json
    
  3. בתשובה, בודקים את השדה generatedQuery (GRAPH FinGraph MATCH ...) כדי לוודא שהוא מדויק, ובודקים את השדה queryResult בשורות שהוחזרו.

כדי לבדוק שאלות אחרות, משנים את הערך של prompt ב-request.json ושולחים שוב את הבקשה. כדי לראות איך QueryData פועל בלי הקשר שנוצר, מסירים את האובייקט agent_context_reference.

כדי לבדוק אם QueryData משתמש בהקשר שהגדרתם, אתם יכולים לשאול שאלה שתלויה בו (למשל, "מי הבעלים של החשבון ליום גשום?") ולהשוות בין התשובות עם האובייקט agent_context_reference ובלעדיו. בלי להגדיר את ההקשר, יכול להיות ש-QueryData יסנן לפי 'rainy day' ולא יחזיר שורות. אחרי הגדרת ההקשר, הפונקציה מסננת לפי 'Rainy Day Fund' ומחזירה את הערך "דנה".

מורידים ומעדכנים את קבוצת ההקשר הקיימת

אם התשובות לבדיקה מראות שצריך לשפר את שאילתת ה-GQL שנוצרה לשאלה בשפה טבעית, הורידו את קובץ קבוצת ההקשר הקיים. לאחר מכן, אתם יכולים לבדוק ולעדכן את תבניות השאילתות ב-GQL, את ההיבטים או את החיפושים לפי ערכים, ולהעלות את קובץ קבוצת ההקשרים המעודכן לקבוצת ההקשרים.

כדי להוריד ולעדכן קבוצת הקשר, מבצעים את השלבים הבאים:

  1. בחלונית Explorer, לוחצים על View actions לצד קבוצת ההקשרים.
  2. לוחצים על הורדת קובץ ההקשר.
  3. כדי לעדכן את קבוצת ההקשר עם עוד צמדים של שאילתות בשפה טבעית ושאילתות GQL, פועלים לפי השלבים שמפורטים בקטע יצירת קבוצות הקשר באמצעות סוכן עם מנוע הקשר.
  4. בחלונית Explorer, לוחצים על View actions ליד קבוצת ההקשר שבה משתמשים.
  5. לוחצים על עריכת קבוצת ההקשר.
  6. בקטע העלאת קובץ של קבוצת הקשרים, לוחצים על עיון ובוחרים את הקובץ המעודכן של קבוצת ההקשרים.
  7. לוחצים על שמירה כדי לעדכן את קבוצת ההקשרים.
  8. בודקים שוב את QueryData כדי לאמת את שאילתת ה-GQL שנוצרה.

אחרי שאתם מרוצים מהדיוק של התשובות, אתם יכולים להשתמש בנקודת הקצה QueryData כדי לחבר את האפליקציה לקבוצת ההקשר.

קישור של QueryData לאפליקציה

כדי לספק הקשר שנוצר על ידי משתמשים ולאפשר יצירת שאילתות GQL ל-Spanner Graph, צריך להגדיר את מזהה קבוצת ההקשרים ואת היעד graph_ids בהפעלת ה-method‏ QueryData. מידע נוסף על השימוש ב-QueryData עם מקורות נתונים של מסדי נתונים זמין במאמר הגדרת הקשר של סוכן לאינטראקציה עם נתונים למקורות נתונים של מסדי נתונים. לדוגמה שמחברת אפליקציית סוכן ל-QueryData באמצעות כלי HTTP בהתאמה אישית ששולח קריאה ל-QueryData API בארכיטקטורת REST, ראו שילוב של QueryData באפליקציה.

דוגמה לבקשה מ-QueryData עם הקשר שנוצר על ידי המשתמש

בדוגמה הבאה מוצגת בקשת QueryData שמשתמשת במקור הנתונים של מסד הנתונים spanner_reference עבור תרשים המאפיינים FinGraph. צריך לספק את graph_ids בתוך spanner_reference.database_reference כדי ש-QueryData יטרגט את תרשים המאפיינים וייצור שאילתות GQL. השדה agent_context_reference.context_set_id מקשר להקשר שנוצר מראש ומאוחסן במסד הנתונים:

{
  "parent": "projects/my-project/locations/global",
  "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
  "context": {
    "datasource_references": {
      "spanner_reference": {
        "database_reference": {
          "engine": "GOOGLE_SQL",
          "project_id": "my-project",
          "instance_id": "my-instance",
          "database_id": "fin-graph-db",
          "graph_ids": [
            "FinGraph"
          ]
        },
        "agent_context_reference": {
          "context_set_id": "projects/my-project/locations/us-central1/contextSets/fingraph-assistant"
        }
      }
    }
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

גוף הבקשה מכיל את השדות הבאים:

  • ‫parent: אופציונלי. הפרויקט והמיקום של הבקשה, בפורמט projects/PROJECT_ID/locations/LOCATION. משתמשים באותו פרויקט ובאותו מיקום כמו בכתובת ה-URL של הבקשה.
  • ‫prompt: השאלה בשפה טבעית ממשתמש הקצה.
  • ‫context: מכיל מידע על מקורות הנתונים.
    • ‫datasource_references: מציין את מקור הנתונים. השדה הזה הוא אובייקט, לא רשימה.
      • ‫spanner_reference: נדרש כששולחים שאילתה למסד נתונים של Spanner.
        • ‫database_reference: מציין מידע שקשור למסד הנתונים של Spanner ולתרשימי המאפיינים.
          • ‫engine: הניב של מסד הנתונים. צריך להגדיר את הערך GOOGLE_SQL למסדי נתונים של Spanner Graph.
          • ‫project_id: מזהה הפרויקט של מכונת Spanner.
          • ‫instance_id: מזהה המכונה של מכונת Spanner.
          • ‫database_id: המזהה של מסד הנתונים ב-Spanner.
          • ‫graph_ids: נדרש ל-Spanner Graph. רשימה של שמות תרשימי מאפיינים במסד הנתונים לשליחת שאילתות (לדוגמה, ["FinGraph"]). כשמציינים את graph_ids, הפונקציה QueryData יוצרת שאילתות GQL לגבי תרשימי המאפיינים שצוינו. אם משמיטים את graph_ids, QueryData יוצר רק שאילתות SQL יחסיות בטבלאות הבסיסיות.
        • agent_context_reference: קישורים להקשר שנוצר במסד הנתונים.
          • ‫context_set_id: המזהה המלא של קבוצת ההקשרים ששמורה במסד הנתונים, למשל projects/my-project/locations/us-central1/contextSets/fingraph-assistant.
  • ‫generation_options: מגדיר את סוג הפלט שייווצר.
    • ‫generate_query_result: צריך להגדיר את הערך true כדי להריץ את שאילתת ה-GQL שנוצרה ולהחזיר את תוצאות השאילתה.
    • ‫generate_natural_language_answer: אופציונלי. אם הערך הוא true, נוצרת תשובה בשפה טבעית שמסכמת את תוצאות השאילתה.
    • ‫generate_explanation: אופציונלי. אם הערך הוא true, נוצר הסבר על שאילתת ה-GQL.
    • ‫generate_disambiguation_question: אופציונלי. אם הערך הוא true, המערכת יוצרת שאלות להפגת עמימות אם ההנחיה בשפה טבעית לא ברורה.

תשובה לדוגמה של QueryData

בדוגמה הבאה מוצגת תגובה מוצלחת מקריאה ל-QueryData בתרשים המאפיינים FinGraph. ה-API בארכיטקטורת REST מחזיר שמות של שדות ב-camelCase, כמו generatedQuery ו-queryResult. מכיוון שיצירת GQL היא לא דטרמיניסטית, השאילתה, שמות העמודות וטקסט התשובה שנוצרים יכולים להיות שונים בין קריאות.

{
  "generatedQuery": "GRAPH `FinGraph` MATCH (p:`Person` {`name`: 'Dana'})-[:`Owns`]->(src:`Account`)-[t:`Transfers`]->(dst:`Account`) MATCH (p_recipient:`Person`)-[:`Owns`]->(dst) RETURN DISTINCT p_recipient.`name` AS recipient_name, dst.`id` AS recipient_account_id, t.`amount` AS transfer_amount",
  "intentExplanation": "To find everyone Dana transferred money to, we identify the person named Dana and locate the accounts they own. We trace the transfer relationships from Dana's accounts to any destination accounts, identifying the specific amounts sent and the IDs of those receiving accounts. Finally, we find the individuals who own those receiving accounts to present their names along with the account details and transfer amounts.",
  "queryResult": {
    "columns": [
      {
        "name": "recipient_name",
        "type": "STRING"
      },
      {
        "name": "recipient_account_id",
        "type": "INT64"
      },
      {
        "name": "transfer_amount",
        "type": "FLOAT64"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "Alex"
          },
          {
            "value": "7"
          },
          {
            "value": "500"
          }
        ]
      },
      {
        "values": [
          {
            "value": "Lee"
          },
          {
            "value": "16"
          },
          {
            "value": "200"
          }
        ]
      }
    ],
    "totalRowCount": "2"
  },
  "naturalLanguageAnswer": "Based on the transaction records, Dana transferred money to the following recipients:\n\n*   **Alex**: Account ID **7**, with a transfer amount of **500**\n*   **Lee**: Account ID **16**, with a transfer amount of **200**"
}

המאמרים הבאים