בדף הזה מוסבר איך מנוע RAG ב-Gemini Enterprise Agent Platform משתמש ב-RagManagedDb, מסד נתונים וקטורי שמתאים לארגונים ומשמש לאחסון ולניהול של ייצוגים וקטוריים של המסמכים שלכם. לאחר מכן, מסד הנתונים הווקטורי משמש לאחזור מסמכים רלוונטיים על סמך הדמיון הסמנטי של המסמך לשאילתה נתונה.
בנוסף, בדף הזה מוסבר איך להטמיע CMEK.
ניהול אסטרטגיית השליפה
ב-RagManagedDb יש את אסטרטגיות השליפה הבאות, שתומכות בתרחישים לדוגמה של RAG:
| אסטרטגיית אחזור | תיאור | |
|---|---|---|
| k-Nearest Neighbors (KNN) (ברירת מחדל) | מאתר את השכנים הקרובים ביותר על ידי השוואה בין כל הנקודות על הגרף בקורפוס ה-RAG. אם לא תציינו אסטרטגיה במהלך היצירה של קורפוס ה-RAG, אסטרטגיית האחזור שתיבחר כברירת מחדל היא KNN. |
|
| שכנים קרובים משוערים (ANN) | משתמשת בטכניקות של קירוב כדי למצוא שכנים דומים מהר יותר מאשר בטכניקת KNN. |
|
יצירת קורפוס RAG עם KNN RagManagedDb
בדוגמת הקוד הזו מוסבר איך ליצור קורפוס RAG באמצעות KNN RagManagedDb.
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 עם ANN RagManagedDb
כדי להציע את התכונה ANN, RagManagedDb משתמש במבנה מבוסס-עץ כדי לחלק את הנתונים ולאפשר חיפושים מהירים יותר. כדי להשיג את ה-recall והזמן האחזור הטובים ביותר, צריך להגדיר את מבנה העץ הזה באמצעות ניסויים כך שיתאים לגודל הנתונים ולהתפלגות שלהם. בעזרת 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}"'
}
}
}
}'
ייבוא הנתונים אל ANN RagManagedDb
אתם יכולים להשתמש ב-API של ImportRagFiles או ב-API של UploadRagFile כדי לייבא את הנתונים ל-ANN RagManagedDb. עם זאת, בניגוד לאסטרטגיית השליפה של KNN, בגישת ANN צריך לבנות מחדש את האינדקס הבסיסי שמבוסס על עץ לפחות פעם אחת, ואם רוצים, גם אחרי שמייבאים כמויות משמעותיות של נתונים כדי לשפר את ה-recall. כדי שמנוע RAG יבנה מחדש את אינדקס ה-ANN, צריך להגדיר את rebuild_ann_index כ-true בבקשת ה-API של ImportRagFiles.
חשוב לשים לב לנקודות הבאות:
- לפני ששולחים שאילתה לקורפוס RAG, צריך לבנות מחדש את אינדקס ה-ANN לפחות פעם אחת.
- אפשר לבנות מחדש רק אינדקס אחד בו-זמנית בפרויקט בכל מיקום.
כדי להעלות קובץ מקומי לקורפוס 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 Engine יש אפשרויות מתקדמות לניהול ההצפנה של הנתונים במנוחה. כברירת מחדל, כל נתוני המשתמשים ב-RagManagedDb מוצפנים באמצעות Google-owned and Google-managed encryption key. הגדרת ברירת המחדל הזו עוזרת לוודא שהנתונים מאובטחים בלי צורך בהגדרה ספציפית.
אם אתם צריכים יותר שליטה במפתחות שמשמשים להצפנה, מנוע RAG תומך במפתחות הצפנה בניהול הלקוח (CMEK). באמצעות CMEK, אתם יכולים להשתמש במפתחות הקריפטוגרפיים שלכם, שמנוהלים ב-Cloud Key Management Service (Cloud KMS), כדי להגן על הנתונים בקורפוס ה-RAG.
מידע נוסף על המגבלות של CMEK בקורפוסים של RAG מופיע במאמר המגבלות של CMEK ב-RAG Engine ב-Gemini Enterprise Agent Platform.
הגדרת מפתח Cloud KMS והענקת הרשאות
כדי ליצור קורפוס RAG שמוצפן באמצעות CMEK, צריך להגדיר מפתח קריפטוגרפי ב-Cloud KMS ולתת לחשבון השירות של מנוע RAG את ההרשאות שנדרשות כדי להשתמש במפתח הזה.
דרישות מוקדמות
כדי לבצע את שלבי ההגדרה הבאים, ודאו שלחשבון המשתמש שלכם יש את ההרשאות המתאימות לניהול זהויות והרשאות גישה (IAM) בפרויקט Google Cloud שבו אתם מתכוונים ליצור את מפתח Cloud KMS ואת קורפוס ה-RAG. בדרך כלל נדרש תפקיד כמו אדמין ב-Cloud KMS (roles/cloudkms.admin).
הפעלת ה-API
כדי להפעיל את Cloud Key Management Service API:
- עוברים למסוף Google Cloud .
- בוחרים את הפרויקט שבו רוצים לנהל את המפתחות וליצור את קורפוס ה-RAG.
- בסרגל החיפוש, מקלידים "Key Management" ובוחרים בשירות "Key Management".
- אם ה-API לא מופעל, לוחצים על Enable. יכול להיות שתצטרכו להמתין כמה דקות עד שה-API יוקצה באופן מלא.
יצירת אוסף מפתחות ומפתח ב-Cloud KMS
כדי ליצור אוסף מפתחות:
בקטע Key Management, לוחצים על יצירת אוסף מפתחות.
כתבו:
- Key ring name: נותנים שם ייחודי לאוסף המפתחות, למשל rag-engine-cmek-keys.
- Location type: בוחרים באפשרות Region. אוסף המפתחות של Cloud KMS צריך להיות באותו אזור שבו נמצאת נקודת הקצה של RAG Engine, שבה אתם משתמשים כשאתם מצפינים קורפוס RAG באמצעות CMEK.
- מיקום: בוחרים את האזור הרצוי, למשל
us-central1. האזור הזה צריך להתאים לאזור שבו נמצאים המשאבים של מנוע ה-RAG.
לוחצים על יצירה.
כדי ליצור מפתח בתוך אוסף המפתחות:
אחרי שיוצרים את אוסף המפתחות, תופיע בקשה ליצור מפתח. אפשר גם לעבור אל Create Key.
כתבו:
- שם המפתח: נותנים שם ייחודי למפתח, למשל
my-rag-corpus-key. - רמת הגנה: בוחרים רמת הגנה (תוכנה או HSM). אם אתם צריכים מפתחות מבוססי-חומרה, בחרו באפשרות HSM.
- Purpose: בוחרים באפשרות Symmetric encrypt/decrypt. ההרשאה הזו נדרשת ל-CMEK.
- מקור חומר המפתח: בוחרים באפשרות מפתח שנוצר.
- תקופת רוטציה: אופציונלי. מומלץ. להגדיר לוח זמנים לרוטציית מפתחות בהתאם למדיניות האבטחה של הארגון, למשל כל 90 יום.
- שם המפתח: נותנים שם ייחודי למפתח, למשל
לוחצים על יצירה.
כדי להעתיק את שם המשאב של המפתח, מבצעים את הפעולות הבאות:
אחרי שיוצרים את המפתח, עוברים לדף הפרטים שלו.
מאתרים את שם המשאב. הפורמט הוא
projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME/cryptoKeyVersions/1.מעתיקים את שם המשאב ומסירים את החלק
/cryptoKeyVersions/VERSION_NUMBER. הפורמט הנכון של שם המשאב הואprojects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME.
מתן הרשאות לסוכן השירות של RAG Engine
כדי שמנוע ה-RAG יוכל להצפין ולפענח נתונים באמצעות המפתח שלכם ב-Cloud KMS, סוכן השירות שלו צריך הרשאות מתאימות למפתח הספציפי הזה.
כדי לזהות את סוכן השירות של RAG Engine:
במסוף Google Cloud , נכנסים לדף IAM & Admin > IAM של הפרויקט.
בדף "ניהול זהויות והרשאות גישה", מסמנים את התיבה Include Google-provided role grants.
בסרגל הסינון או החיפוש של רשימת חשבונות המשתמשים, מחפשים את סוכן השירות של RAG Engine. הוא תואם לתבנית
service-YOUR_PROJECT_NUMBER@gcp-sa-vertex-rag.iam.gserviceaccount.com.מחליפים את YOUR_PROJECT_NUMBER במספר הפרויקט ב- Google Cloud .
אם סוכן השירות של RAG Engine עדיין לא קיים, מבצעים את הפעולות הבאות כדי ליצור אותו:
מריצים את הפקודה הבאה ב-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"מוודאים שנוצר סוכן השירות של RAG Engine.
כדי לתת הרשאות למפתח Cloud KMS:
חוזרים לשירות Cloud KMS במסוף Google Cloud .
בוחרים את אוסף המפתחות שמכיל את המפתח שיצרתם.
בוחרים את המפתח הספציפי שיצרתם.
בדף הפרטים של המפתח, עוברים לכרטיסייה Permissions.
לוחצים על Add Principal.
בשדה New principals, מקלידים את כתובת האימייל של סוכן השירות של מנוע ה-RAG.
בתפריט הנפתח Select a role, בוחרים את התפקיד Cloud KMS CryptoKey Encrypter/Decrypter (
roles/cloudkms.cryptoKeyEncrypterDecrypter). התפקיד הזה נותן לסוכן השירות את ההרשאות שנדרשות כדי להשתמש במפתח לפעולות הצפנה ופענוח.לוחצים על 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.
בכל פעם שמשתמשים במפתח Cloud KMS חדש וייחודי כדי ליצור משאב כמו קורפוס RAG בפרויקט ובאזור, מפתח Cloud KMS צורך יחידה אחת מהמכסה הזו. יחידת המכסה הזו לא משתחררת גם אם המשאבים שמשתמשים במפתח הספציפי הזה נמחקים.
אם אתם צריכים יותר מפתחות ייחודיים מהמגבלה הנוכחית, אתם צריכים לבקש הגדלה של המכסה של aiplatform.googleapis.com/in_use_customer_managed_encryption_keys באזור שנבחר.
במאמר הצגה ועריכה של המכסות במסוף Google Cloud מוסבר איך מבקשים להגדיל את המכסה.
המאמרים הבאים
- מידע נוסף על RagManagedDb זמין במאמר מצבי פריסה.
- כדי לייבא קבצים ותיקיות מ-Google Drive או מ-Cloud Storage, עיינו בדוגמה לייבוא קובצי RAG.
- כדי להציג רשימה של קובצי RAG, עיינו בדוגמה להצגת רשימה של קובצי RAG.