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

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

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

כדי להשתמש בחיפוש מטא-נתונים, צריך קורפוס 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 באמצעות Common Expression Language (CEL) (לדוגמה, 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\""
         }
      }
    }
}'

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