שימוש ב-RagManagedDb עם RAG Engine ב-Gemini Enterprise Agent Platform

‫VPC-SC security controls ו-CMEK נתמכים על ידי Agent Platform RAG Engine. אין תמיכה במיקום נתונים ובאמצעי בקרה לאבטחת AXT.

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

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

בנוסף, בדף הזה מוסבר איך מטמיעים CMEK.

חשוב: RagManagedDb משמש כברירת מחדל ומשתמש ב-Spanner. הלקוחות יחויבו על השימוש במופע Spanner שמנוהל על ידי Google, שהוקצה בפרויקט של דייר ב-Google באמצעות מק"טים סטנדרטיים של Spanner.

ניהול אסטרטגיית השליפה

‫RagManagedDb מציע את אסטרטגיות השליפה הבאות כדי לתמוך בתרחישי השימוש שלכם ב-RAG:

אסטרטגיית אחזור	תיאור
k-Nearest Neighbors (KNN) (ברירת מחדל)	הפונקציה מוצאת את השכנים הקרובים ביותר על ידי השוואה של כל נקודות הנתונים במאגר המידע של RAG. אם לא מציינים אסטרטגיה במהלך היצירה של מאגר המידע RAG, נעשה שימוש באסטרטגיית השליפה KNN כברירת מחדל.	מאמת את הזיכרון המושלם (1.0) במהלך השליפה. מתאים במיוחד לאפליקציות שבהן חשוב לזכור את ההקשר. מתאים מאוד למאגרי מידע קטנים עד בינוניים של RAG, שמאחסנים פחות מ-10,000 קבצים של RAG. החיפוש מתבצע בכל נקודת נתונים, ולכן זמן האחזור גדל עם מספר קובצי ה-RAG במאגר.
שכנים קרובים משוערים (ANN)	משתמש בטכניקות קירוב כדי למצוא שכנים דומים מהר יותר מטכניקת KNN.	הפחתה משמעותית של זמן האחזור של שאילתות במאגרי מידע גדולים של RAG. הדיוק ירד מעט בגלל השימוש בטכניקות קירוב. האפשרות הזו יעילה מאוד כשמשתמשים במאגרי מידע גדולים של RAG, כלומר בערך יותר מ-10,000 קבצי RAG. המידה שבה אתם מוכנים להתפשר על דיוק התוצאות תלויה בתרחיש השימוש, אבל ברוב המקרים בקנה מידה גדול, כדאי להתפשר על דיוק התוצאות כדי לשפר את ביצועי השאילתות.

יצירת מאגר מידע של RAG באמצעות KNN RagManagedDb

בדוגמאות הקוד האלה מודגם איך ליצור קורפוס RAG באמצעות KNNRagManagedDb.

Python

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

vector_db = rag.RagManagedDb(retrieval_strategy=rag.KNN())
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

REST

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

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫LOCATION: האזור שבו הבקשה תעובד.
• ‫CORPUS_DISPLAY_NAME: השם המוצג של מאגר המידע של RAG.

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME

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 \
-d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "vector_db_config": {
        "ragManagedDb": {
          "knn": {}
        }
      }
    }'

תצוגה מקדימה

חלק מהתכונות של RAG הן מוצרים בגרסת טרום-GA, והשימוש בהן כפוף ל "תנאי השימוש במוצרים בגרסת טרום-GA" בתנאים הספציפיים לשירות של Google Cloud. השימוש בתכונות ובמוצרים בגרסת טרום-GA הוא "כפי שהם" (As is), ויכול להיות שהתמיכה בהם תהיה מוגבלת. בנוסף, יכול להיות ששינויים במוצרים ובתכונות בגרסת טרום-GA לא יהיו תואמים לגרסאות אחרות של טרום-GA. מידע נוסף זמין במאמר תיאורים של שלבי ההשקה. השימוש ב-Gemini API ב-Gemini Enterprise Agent Platform כפוף לתנאים ולהגבלות של גרסת הטרום-השקה של AI גנרטיבי (תנאי גרסת הטרום-השקה).

יצירת מאגר מידע של RAG באמצעות ANN RagManagedDb

כדי להציע את התכונה ANN, ‏ RagManagedDb משתמש במבנה מבוסס-עץ כדי לחלק את הנתונים ולאפשר חיפושים מהירים יותר. כדי להשיג את הזיכרון והחביון הטובים ביותר, צריך להגדיר את המבנה של העץ הזה באמצעות ניסויים, כך שיתאים לגודל הנתונים ולפיזור שלהם. ‫RagManagedDb מאפשרת להגדיר את tree_depth ואת leaf_count של העץ.

הערך tree_depth קובע את מספר השכבות או הרמות בעץ. חשוב להקפיד על ההנחיות הבאות:

• אם יש לכם בערך 10,000 קובצי RAG במאגר ה-RAG, צריך להגדיר את הערך ל-2.
• אם יש לכם יותר קובצי RAG, צריך להגדיר את הערך הזה ל-3.
• אם לא מציינים את tree_depth, מנוע ה-RAG מקצה לפרמטר הזה ערך ברירת מחדל של 2.

הערך leaf_count קובע את מספר צמתי העלים במבנה מבוסס העץ. כל צומת עלה מכיל קבוצות של וקטורים קרובים יחד עם המרכז שלהם. חשוב להקפיד על ההנחיות הבאות:

• הערך המומלץ הוא 10 * sqrt(num of RAG files in your RAG corpus).

• אם לא מציינים ערך, מנוע RAG מקצה לפרמטר הזה ערך ברירת מחדל של 500.

Python

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
TREE_DEPTH = YOUR_TREE_DEPTH # Optional: Acceptable values are 2 or 3. Default is 2.
LEAF_COUNT = YOUR_LEAF_COUNT # Optional: Default is 500.

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

ann_config = rag.ANN(tree_depth=TREE_DEPTH, leaf_count=LEAF_COUNT)
vector_db = rag.RagManagedDb(retrieval_strategy=ann_config)
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

REST

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

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫LOCATION: האזור שבו הבקשה תעובד.
• ‫CORPUS_DISPLAY_NAME: השם המוצג של מאגר המידע של RAG.
• ‫TREE_DEPTH: עומק העץ.
• ‫LEAF_COUNT: מספר העלים הירוקים.

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME
TREE_DEPTH=TREE_DEPTH
LEAF_COUNT=LEAF_COUNT

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 \
-d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "vector_db_config": {
        "ragManagedDb": {
          "ann": {
            "tree_depth": '"${TREE_DEPTH}"',
            "leaf_count": '"${LEAF_COUNT}"'
          }
        }
      }
    }'

תצוגה מקדימה

חלק מהתכונות של RAG הן מוצרים בגרסת טרום-GA, והשימוש בהן כפוף ל "תנאי השימוש במוצרים בגרסת טרום-GA" בתנאים הספציפיים לשירות של Google Cloud. השימוש בתכונות ובמוצרים בגרסת טרום-GA הוא "כפי שהם" (As is), ויכול להיות שהתמיכה בהם תהיה מוגבלת. בנוסף, יכול להיות ששינויים במוצרים ובתכונות בגרסת טרום-GA לא יהיו תואמים לגרסאות אחרות של טרום-GA. מידע נוסף זמין במאמר תיאורים של שלבי ההשקה. השימוש ב-Gemini API ב-Gemini Enterprise Agent Platform כפוף לתנאים ולהגבלות של גרסת הטרום-השקה של AI גנרטיבי (תנאי גרסת הטרום-השקה).

ייבוא הנתונים אל ANN RagManagedDb

אתם יכולים להשתמש ב-ImportRagFiles API או ב-UploadRagFile API כדי לייבא את הנתונים שלכם ל-ANN RagManagedDb. עם זאת, בניגוד לאסטרטגיית השליפה של KNN, בגישת ANN צריך לבנות מחדש את האינדקס הבסיסי מבוסס העץ לפחות פעם אחת, ואפשר גם אחרי ייבוא של כמויות משמעותיות של נתונים, כדי להשיג היזכרות אופטימלית. כדי שמנוע RAG יבנה מחדש את אינדקס ה-ANN, צריך להגדיר את rebuild_ann_index לערך true בבקשת ImportRagFiles API.

הדברים הבאים חשובים:

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

כדי להעלות קובץ מקומי למאגר המידע של RAG, אפשר לעיין במאמר בנושא העלאת קובץ RAG. כדי לייבא נתונים למאגר המידע של RAG ולהפעיל מחדש את בניית אינדקס ANN, אפשר לעיין בדוגמת הקוד הבאה שמראה איך לייבא מ-Cloud Storage. מידע נוסף על מקורות נתונים נתמכים זמין במאמר בנושא מקורות נתונים שנתמכים ב-RAG.

Python

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
CORPUS_ID = YOUR_CORPUS_ID
PATHS = ["gs://my_bucket/my_files_dir"]
REBUILD_ANN_INDEX = REBUILD_ANN_INDEX # Choose true or false.

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

corpus_name = f"projects/{PROJECT_ID}/locations/{LOCATION}/ragCorpora/{CORPUS_ID}"
# This is a non blocking call.
response = await rag.import_files_async(
    corpus_name=corpus_name,
    paths=PATHS,
    rebuild_ann_index=REBUILD_ANN_INDEX
)

# Wait for the import to complete.
await response.result()

REST

GCS_URI=GCS_URI
REBUILD_ANN_INDEX=<true/false>

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/${CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URI}"\"',
      },
    "rebuild_ann_index": '${REBUILD_ANN_INDEX}'
  }
}'

ניהול ההצפנה

מנוע RAG מספק אפשרויות חזקות לניהול ההצפנה של הנתונים באחסון. כברירת מחדל, כל נתוני המשתמשים ב-RagManagedDb מוצפנים באמצעות Google-owned and Google-managed encryption key, שהיא הגדרת ברירת המחדל. הגדרת ברירת המחדל הזו עוזרת לכם לוודא שהנתונים מאובטחים בלי שתצטרכו לבצע הגדרה ספציפית.

אם אתם צריכים יותר שליטה במפתחות שמשמשים להצפנה, RAG Engine תומך במפתחות הצפנה בניהול הלקוח (CMEK). בעזרת CMEK, אתם יכולים להשתמש במפתחות קריפטוגרפיים שמנוהלים ב-Cloud Key Management Service‏ (KMS) כדי להגן על נתוני מאגר ה-RAG.

למידע על מגבלות CMEK במאגרי מידע של RAG, ראו מגבלות CMEK ב-RAG Engine ב-Gemini Enterprise Agent Platform.

הגדרת מפתח KMS והענקת הרשאות

כדי ליצור מאגר מידע RAG שמוצפן באמצעות CMEK, צריך להגדיר מפתח קריפטוגרפי ב-Google Cloud KMS ולהעניק לחשבון השירות של RAG Engine את ההרשאות הנדרשות לשימוש במפתח הזה.

דרישות מוקדמות

כדי לבצע את שלבי ההגדרה הבאים, צריך לוודא שלחשבון המשתמש שלכם יש את ההרשאות המתאימות לניהול זהויות והרשאות גישה (IAM) ב Google Cloud פרויקט שבו אתם רוצים ליצור את מפתח ה-KMS ואת מאגר הנתונים של RAG. בדרך כלל נדרש תפקיד כמו Cloud KMS Admin (roles/cloudkms.admin).

הפעלת ה-API

כדי להפעיל את Cloud Key Management Service API:

1. עוברים אל המסוף Google Cloud .
2. בוחרים את הפרויקט שבו רוצים לנהל את המפתחות ויוצרים את מאגר המידע של RAG.
3. בסרגל החיפוש, מקלידים Key Management (ניהול מפתחות) ובוחרים בשירות Key Management.
4. אם ה-API לא מופעל, לוחצים על הפעלה. יכול להיות שתצטרכו להמתין כמה דקות עד שה-API יוקצה באופן מלא.

יצירה של אוסף מפתחות ומפתח KMS

כדי ליצור אוסף מפתחות:

1. בקטע Key Management (ניהול מפתחות), לוחצים על Create Key Ring (יצירת מחזיק מפתחות).

   כתבו:

   • שם אוסף המפתחות: מזינים שם ייחודי לאוסף המפתחות, כמו rag-engine-cmek-keys.
   • סוג המיקום: בוחרים באפשרות 'אזור'. אוסף המפתחות של Cloud Key Management Service צריך להיות באותו אזור כמו נקודת הקצה של RAG Engine שבה אתם משתמשים כשאתם מצפינים קורפוס RAG באמצעות CMEK.
   • מיקום: בוחרים את האזור הרצוי, למשל us-central1. האזור הזה צריך להיות זהה לאזור שבו ימוקמו משאבי RAG Engine.

2. לוחצים על יצירה.

כדי ליצור מפתח בתוך אוסף המפתחות:

1. אחרי שיוצרים את אוסף המפתחות, מוצגת הנחיה או שאפשר לנווט אל יצירת מפתח.

   כתבו:

   • שם המפתח: מזינים שם ייחודי למפתח, כמו my-rag-corpus-key.
   • רמת הגנה: בוחרים רמת הגנה (תוכנה או HSM). אם אתם צריכים מפתחות שמגובים בחומרה, בוחרים באפשרות HSM.
   • מטרה: בוחרים באפשרות הצפנה/פענוח סימטריים. הפרמטר הזה נדרש ל-CMEK.
   • מקור חומרי לימוד מרכזיים: בוחרים באפשרות יצירת חומרים מרכזיים.
   • תקופת הרוטציה: אופציונלי. מומלץ. קובעים לוח זמנים להחלפת מפתחות בהתאם למדיניות האבטחה של הארגון, למשל כל 90 יום.

2. לוחצים על יצירה.

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

1. אחרי שיוצרים את המפתח, עוברים לדף הפרטים שלו.

2. מאתרים את שם המשאב. הפורמט הוא projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME/cryptoKeyVersions/1.

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

3. מעתיקים את שם המשאב ומסירים את החלק /cryptoKeyVersions/VERSION_NUMBER. שם המשאב בפורמט הנכון הוא projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME.

מתן הרשאות לסוכן השירות של מנוע RAG

כדי שמנוע RAG יוכל להצפין ולפענח נתונים באמצעות מפתח KMS, לסוכן השירות שלו צריכות להיות הרשאות מתאימות למפתח הספציפי הזה.

כדי לזהות את סוכן השירות של RAG Engine:

1. במסוף Google Cloud , עוברים לדף IAM & Admin > IAM של הפרויקט.

2. בדף 'ניהול זהויות והרשאות גישה', מסמנים את התיבה Include Google-provided role grants (הצגת תפקידים שהוענקו על ידי Google).

3. בסרגל הסינון או החיפוש של רשימת הגורמים המורשים, מחפשים את סוכן השירות של RAG Engine. הוא פועל לפי התבנית [e-mail].

   מחליפים את YOUR_PROJECT_NUMBER במספר הפרויקט ב- Google Cloud .

אם סוכן השירות של מנוע RAG עדיין לא נוצר, צריך לבצע את הפעולות הבאות כדי ליצור אותו:

1. הפעלת Resource Manager API

2. מריצים את הפקודה הבאה ב-Cloud Shell או בשורת הפקודה:

   gcloud beta services identity create --service=aiplatform.googleapis.com \
       --projects=PROJECT_ID
   

   אפשרות אחרת היא לשלוח את הקריאה ל-API ל-REST:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json; charset=utf-8" -d "" "https://serviceusage.googleapis.com/v1beta1/projects/PROJECT_ID/services/aiplatform.googleapis.com:generateServiceIdentity"
   

3. מוודאים שסוכן השירות של RAG Engine נוצר.

כדי להעניק הרשאות למפתח KMS:

1. חוזרים לשירות ניהול המפתחות במסוף Google Cloud .

2. בוחרים את אוסף המפתחות שמכיל את המפתח שיצרתם.

3. בוחרים את המפתח הספציפי שיצרתם.

4. בדף הפרטים של המפתח, עוברים לכרטיסייה הרשאות.

5. לוחצים על Add Principal.

6. בשדה New principals, מקלידים את כתובת האימייל של סוכן השירות של RAG Engine.

7. בתפריט הנפתח Select a role, בוחרים בתפקיד Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter). התפקיד הזה מעניק לסוכן השירות את ההרשאות הנדרשות לשימוש במפתח לפעולות הצפנה ופענוח.

8. לוחצים על Save.

יצירת מאגר מידע של RAG עם הצפנה בניהול הלקוח

בדוגמת הקוד הזו מוצג איך ליצור מאגר מידע של RAG שמוצפן באמצעות מפתח הצפנה בניהול הלקוח (CMEK).

מחליפים את המשתנים בדוגמאות הקוד הבאות:

Python

import vertexai
from google.cloud import aiplatform
from vertexai import rag
from google.cloud.aiplatform_v1.types.encryption_spec import EncryptionSpec

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME

vertexai.init(project=PROJECT_ID)

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, encryption_spec=EncryptionSpec(kms_key_name=KMS_KEY_NAME))

REST

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora \
-d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "encryption_spec" : {
        "kms_key_name" : '\""${KMS_KEY_NAME}"\"'
      }
    }'

מכסות

כשמשתמשים ב-CMEK עם שירותי Gemini Enterprise Agent Platform, כמו RAG Engine ב-Gemini Enterprise Agent Platform, יש מכסה על מספר מפתחות Cloud KMS הייחודיים שאפשר להשתמש בהם לכל פרויקט בכל אזור. המכסה הזו מתועדת במדד aiplatform.googleapis.com/in_use_customer_managed_encryption_keys.

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

אם אתם צריכים יותר מפתחות ייחודיים מהמכסה הנוכחית, אתם צריכים לבקש הגדלה של המכסה של aiplatform.googleapis.com/in_use_customer_managed_encryption_keys לאזור שבחרתם.

במאמר איך רואים ועורכים את המכסות במסוף Google Cloud מוסבר איך לבקש הגדלה של המכסה.

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

• מידע נוסף על RagManagedDb זמין במאמר בנושא מצבי פריסה.
• כדי לייבא קבצים ותיקיות מ-Google Drive או מ-Cloud Storage, אפשר לעיין בדוגמה לייבוא קובצי RAG.
• כדי לראות רשימה של קובצי RAG, אפשר לעיין בדוגמה לרשימת קובצי RAG.