סינון באמצעות חיפוש מטא-נתונים

בדף הזה נסביר איך להשתמש בתכונה של חיפוש מטא-נתונים מבוסס-סכימה ב-RAG Engine בפלטפורמת הסוכנים של Gemini Enterprise. אתם יכולים להגדיר סכימת מטא-נתונים עבור קורפוס, לצרף מטא-נתונים לקבצים בקורפוס ולהשתמש במטא-נתונים האלה כדי לסנן הקשרים במהלך אחזור.

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

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

כשיוצרים קורפוס או מעלים קובץ, ה-API מחזיר ערך מספרי של RAG_CORPUS_ID ושל RAG_FILE_ID (לדוגמה, 123456789). צריך לשמור את המזהים האלה כדי לנהל את משאבי המטא-נתונים.

מקורות מידע על מטא-נתונים

תכונת החיפוש במטא-נתונים משתמשת בהיררכיית המשאבים הבאה:

  • ‫RagCorpus: המשאב ברמה העליונה שמכיל את קובצי ה-RAG וההגדרות שלהם.

    • ‫RagDataSchema: משאב צאצא של RagCorpus. הוא מגדיר את המבנה של שדה מטא נתונים יחיד שמשמש במאגר. כל סכימה מציינת מפתח (לדוגמה, year) וסוג נתונים (INTEGER,‏ FLOAT,‏ STRING,‏ DATETIME,‏ BOOLEAN או LIST). צריך להגדיר RagDataSchema לכל מפתח מטא-נתונים שרוצים להשתמש בו לסינון.

    • ‫RagFile: משאב צאצא של RagCorpus שמייצג מסמך יחיד שהוזן.

      • ‫RagMetadata: משאב צאצא של RagFile. הוא מייצג צמד מטא-נתונים יחיד של מפתח/ערך שמצורף לקובץ הספציפי הזה (לדוגמה, year=2024). המפתח שמשמש במשאב RagMetadata חייב להתאים למפתח שמוגדר ב-RagDataSchema עבור הקורפוס הראשי. אפשר לצרף כמה משאבי RagMetadata לקובץ אחד.

ניהול סכימות של מטא נתונים

אחרי שיוצרים קורפוס RAG, מגדירים את מבנה המטא-נתונים באמצעות משאב RagDataSchema ברמת הקורפוס. אפשר גם לראות ולמחוק את הסכימות שהגדרתם.

הגדרת סכימות של מטא-נתונים

כשמגדירים סכימה, מציינים מפתח וסוג נתונים. הסוגים התקינים של מפתחות הם:

  • ‫INTEGER: ערכי המטא-נתונים מועברים כ-int_value.
  • ‫FLOAT: הערכים של המטא-נתונים שמועברים כ-float_value.
  • ‫STRING: הערכים של המטא-נתונים שמועברים כ-str_value.
  • ‫DATETIME: מועבר בערכי המטא-נתונים כ-datetime_value (מחרוזת בפורמט RFC 3339, לדוגמה, ‎"2024-01-01T00:00:00Z"‎).
  • ‫BOOLEAN: הערכים של המטא-נתונים שמועברים כ-bool_value.
  • ‫LIST: ערכי המטא-נתונים מועברים כ-list_value. בדוגמה הבאה של REST מוצג איך ליצור סכמות של מטא-נתונים בקבוצות, שמגדירות את השדות year ו-month עבור מאגר מסמכים.

REST

מחליפים את המשתנים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של מאגר המידע של RAG.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragDataSchemas:batchCreate \
-d '{
  "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
  "requests": [
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
      "rag_data_schema": {
        "key": "year",
        "schema_details": {"type": "INTEGER"}
      }
    },
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
      "rag_data_schema": {
        "key": "month",
        "schema_details": {"type": "STRING"}
      }
    }
  ]
}'

רשימת סכימות של מטא-נתונים

בדוגמה הבאה של REST אפשר לראות איך מציגים את סכימות המטא-נתונים שהוגדרו עבור קורפוס.

REST

מחליפים את המשתנים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של מאגר המידע של RAG.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragDataSchemas

מחיקה של סכימות מטא-נתונים

בדוגמה הבאה של REST אפשר לראות איך מוחקים סכמות של מטא-נתונים ממאגר מסמכים.

REST

מחליפים את המשתנים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של מאגר המידע של RAG.
  • ‫RAG_DATA_SCHEMA_KEY_1: שם המפתח של סכימת המטא-נתונים הראשונה שרוצים למחוק.
  • ‫RAG_DATA_SCHEMA_KEY_2: שם המפתח של סכימת המטא-נתונים השנייה שרוצים למחוק.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_DATA_SCHEMA_KEY_1=RAG_DATA_SCHEMA_KEY_1
RAG_DATA_SCHEMA_KEY_2=RAG_DATA_SCHEMA_KEY_2
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragDataSchemas:batchDelete \
-d '{
  "names": [
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragDataSchemas/'"${RAG_DATA_SCHEMA_KEY_1}"'",
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragDataSchemas/'"${RAG_DATA_SCHEMA_KEY_2}"'"
  ]
}'

ניהול מטא-נתונים של קבצים

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

צירוף מטא-נתונים לקובץ

המטא-נתונים המצורפים צריכים להיות תואמים לסכימה שמוגדרת עבור הקורפוס. בדוגמה הבאה של REST אפשר לראות איך לצרף כמה ערכים של מטא-נתונים לקובץ.

REST

מחליפים את המשתנים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של מאגר המידע של RAG.
  • ‫RAG_FILE_ID: המזהה של קובץ ה-RAG.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata:batchCreate \
-d '{
  "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
  "requests": [
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
      "rag_metadata": {
        "user_specified_metadata": { "key": "year", "value": { "int_value": 2024 } }
      }
    },
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
      "rag_metadata": {
        "user_specified_metadata": { "key": "month", "value": { "str_value": "May" } }
      }
    }
  ]
}'

הצגת המטא-נתונים של קובץ

בדוגמה הבאה של REST אפשר לראות איך מציגים את המטא-נתונים שמצורפים לקובץ ספציפי.

REST

מחליפים את המשתנים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של מאגר המידע של RAG.
  • ‫RAG_FILE_ID: המזהה של קובץ ה-RAG.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata

עדכון מטא-נתונים

אפשר לעדכן את ערכי המטא-נתונים שמצורפים לקובץ. בדוגמה הבאה של REST מוצג איך לעדכן את ערך המטא-נתונים שמשויך למפתח year. ‫RAG_METADATA_KEY הוא המחרוזת שבה השתמשתם כשיצרתם את המטא-נתונים.

REST

מחליפים את המשתנים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של מאגר המידע של RAG.
  • ‫RAG_FILE_ID: המזהה של קובץ ה-RAG.
  • ‫RAG_METADATA_KEY: שם המפתח של המטא-נתונים שרוצים לעדכן.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
RAG_METADATA_KEY=RAG_METADATA_KEY
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata/${RAG_METADATA_KEY} \
-d '{
  "user_specified_metadata": { "key": "'"${RAG_METADATA_KEY}"'", "value": { "int_value": 2025 } }
}'

מחיקת מטא-נתונים מקובץ

בדוגמה הבאה של REST מוצג איך למחוק ערכים של מטא-נתונים מקובץ באמצעות בקשה לאצווה.

REST

מחליפים את המשתנים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של מאגר המידע של RAG.
  • ‫RAG_FILE_ID: המזהה של קובץ ה-RAG.
  • ‫RAG_METADATA_KEY_1: שם המפתח של ערך המטא-נתונים הראשון שרוצים למחוק.
  • ‫RAG_METADATA_KEY_2: שם המפתח של ערך המטא-נתונים השני שרוצים למחוק.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
RAG_METADATA_KEY_1=RAG_METADATA_KEY_1
RAG_METADATA_KEY_2=RAG_METADATA_KEY_2
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata:batchDelete \
-d '{
  "names": [
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'/ragMetadata/'"${RAG_METADATA_KEY_1}"'",
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'/ragMetadata/'"${RAG_METADATA_KEY_2}"'"
  ]
}'

סינון הקשרים באמצעות מטא-נתונים

כדי לשפר את הרלוונטיות של התוצאות, אפשר להשתמש במטא-נתונים של הקובץ כדי לצמצם את מרחב החיפוש במהלך אחזור ההקשר. מוסיפים ביטוי metadata_filter לבקשת RetrieveContexts באמצעות CEL (Common Expression Language) (לדוגמה, year == 2024 && month == "May"). רק קבצים עם מטא-נתונים שתואמים לביטוי המסנן נלקחים בחשבון לצורך אחזור.

בדוגמה הבאה של REST מוצג איך לאחזר הקשרים באמצעות מסנן מטא-נתונים.

REST

מחליפים את המשתנים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של מאגר המידע של RAG.
PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
QUERY="except share amounts"
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}:retrieveContexts -d '{
    "vertex_rag_store": {
       "rag_resources": [
         {
           "rag_corpus": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'"
         }
       ]
    },    
    "query": {
      "text": "'"${QUERY}"'", 
      "rag_retrieval_config": {
         "top_k": 10,
         "filter": {
            "vector_distance_threshold": 0.5,
            "metadata_filter": "year == 2024 && month == \"May\""
         }
      }
    }
}'

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