שימוש ב-Pinecone עם מנוע RAG

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

כדי לראות דוגמה לשימוש ב-RAG Engine ב-Gemini Enterprise Agent Platform עם Pinecone, מריצים את ה-notebook‏ "RAG Engine with Pinecone" באחת מהסביבות הבאות:

פתיחה ב-Colab | פתיחה ב-Colab Enterprise | פתיחה ב-Agent Platform Workbench | הצגה ב-GitHub

בדף הזה מוסבר איך לחבר את קורפוס ה-RAG למסד הנתונים של Pinecone.

אפשר גם לעקוב אחרי ה-notebook הזה: RAG Engine with Pinecone.

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

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

האם כדאי להשתמש ב-Pinecone עם RAG Engine

כדי להחליט אם מסד הנתונים של Pinecone הוא הבחירה הכי טובה לאפליקציית ה-RAG שלכם, כדאי לבדוק את הדברים הבאים:

• אתם צריכים ליצור, להגדיר ולנהל את ההתאמה לעומס (scaling) של המכונה של מסד הנתונים ב-Pinecone.

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

• אתם צריכים לספק מפתח Pinecone API, שמאפשר למנוע RAG לקיים אינטראקציה עם מסד הנתונים של Pinecone. ‫RAG Engine לא מאחסן ומנהל את מפתח ה-API של Pinecone. במקום זאת, צריך לבצע את הפעולות הבאות:

  • שומרים את המפתח ב- Google Cloud Secret Manager.
  • נותנים לחשבון השירות של הפרויקט הרשאות גישה לסוד.
  • נותנים ל-RAG Engine גישה לשם המשאב של הסוד.

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

  • לקורפוס RAG ולאינדקס Pinecone יש מיפוי של אחד לאחד. השיוך הזה מתבצע כחלק מה-method‏ ragCorpora.create או מה-method‏ ragCorpora.patch.

יצירת אינדקס ב-Pinecone

כדי ליצור אינדקס ב-Pinecone, צריך לפעול לפי השלבים הבאים:

1. במדריך למתחילים של Pinecone מוסבר איך להגדיר את האינדקס כך שיתאים לקורפוס RAG.

2. כדאי לוודא שהמיקום של האינדקס של Pinecone זהה למיקום שבו אתם משתמשים במנוע RAG או קרוב אליו, מהסיבות הבאות:

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

3. כשיוצרים אינדקס ב-Pinecone, מציינים את מאפיין ההטמעה שבו רוצים להשתמש ב-RAG Engine. בטבלה הזו מפורטים הגדלים של המאפיינים או המיקום של הגדלים של המאפיינים:

   דגם	גודל המאפיין
   Gecko מאינטראקציה ישירה (First-Party)	768
   ‫Gecko – מודל צד ראשון שעבר כוונון עדין	768
   E5	איך משתמשים במודלים של הטמעות בקוד פתוח

4. בוחרים באחד ממדדי המרחק הנתמכים הבאים:

   • cosine
   • dotproduct
   • euclidean

5. אופציונלי: כשיוצרים אינדקס מבוסס-פוד, צריך לציין את file_id בשדה pod.metadata_config.indexed. מידע נוסף מופיע במאמר הוספה סלקטיבית של מטא-נתונים לאינדקס.

יצירת מפתח API של Pinecone

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

אחסון מפתח ה-API ב-Secret Manager

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

כדי להגן על SPII, אתם צריכים:

1. אחסנו את מפתח ה-API ב-Secret Manager.

2. נותנים לחשבון השירות של RAG Engine הרשאות לסודות, ומנהלים את בקרת הגישה ברמת המשאב של הסוד.

   1. עוברים אל ההרשאות של הפרויקט.

   2. מפעילים את האפשרות Include Google-provided role grants.

   3. מאתרים את חשבון השירות, שמופיע בפורמט הבא:

      service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

   4. עורכים את חשבונות המשתמשים של חשבון השירות.

   5. מוסיפים לחשבון השירות את התפקיד Secret Manager Secret Accessor.

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

כששולחים בקשות API לאינדקסים של Pinecone, מנוע ה-RAG משתמש בכל חשבון שירות כדי לקרוא את מפתח ה-API שתואם למשאבים הסודיים ב-Secret Manager מהפרויקטים.

הקצאת חשבון שירות ל-RAG Engine

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

חשבון השירות מופיע בפורמט הקבוע הבא:

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

לדוגמה,

[e-mail]

הכנת קורפוס RAG

כדי להשתמש באינדקס של Pinecone עם RAG Engine, צריך לשייך את האינדקס לקורפוס RAG בשלב היצירה שלו. אחרי שהשיוך נוצר, הקישור הזה קבוע לכל משך החיים של קורפוס ה-RAG. אפשר לבצע את השיוך באמצעות ה-API של CreateRagCorpus או של UpdateRagCorpus.

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

• ‫rag_vector_db_config.pinecone: השדה הזה עוזר לכם להגדיר את הבחירה של מסד נתונים וקטורי שאתם רוצים לשייך לקורפוס ה-RAG, וצריך להגדיר אותו במהלך הקריאה ל-API של CreateRagCorpus. אם לא מגדירים את המאפיין, מסד הנתונים הווקטורי שמוגדר כברירת מחדל, RagManagedDb, מוקצה לקורפוס ה-RAG.

• ‫rag_vector_db_config.pinecone.index_name: השם שמשמש ליצירת האינדקס של Pinecone שמשמש את קורפוס ה-RAG. אפשר להגדיר את השם במהלך הקריאה ל-CreateRagCorpus, או לציין את השם כשקוראים ל-API של UpdateRagCorpus.

• ‫rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: שם המשאב המלא של הסוד שמאוחסן ב-Secret Manager, שמכיל את מפתח ה-API של Pinecone. אפשר להגדיר את השם במהלך הקריאה ל-CreateRagCorpus, או לציין את השם כשקוראים ל-API של UpdateRagCorpus. עד שתציינו את השדה הזה, לא תוכלו לייבא נתונים לקורפוס ה-RAG.

  השדה הזה צריך להיות בפורמט הבא:

  projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

יצירת קורפוס RAG

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

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

במאמר יצירת קורפוס RAG בלי שם אינדקס או מפתח API מוסבר איך יוצרים קורפוס RAG בלי לספק את פרטי חשבון השירות.

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Python שמפורטות במאמר התחלה מהירה של Agent Platform באמצעות ספריות לקוח.

כדי לבצע אימות ב-Agent Platform, צריך להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.

import agentplatform
from agentplatform import types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# pinecone_index_name = "pinecone-index-name"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

# Configure embedding model (Optional)
embedding_model_config = types.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=types.RagEmbeddingModelConfigVertexPredictionEndpoint(
        endpoint="publishers/google/models/text-embedding-005"
    )
)

# Configure Vector DB
vector_db = types.RagVectorDbConfig(
    pinecone=types.RagVectorDbConfigPinecone(
        index_name=pinecone_index_name,
    ),
    api_auth=types.ApiAuth(
        api_key_config=types.ApiAuthApiKeyConfig(
            api_key_secret_version=pinecone_api_key_secret_manager_version
        )
    ),
    rag_embedding_model_config=embedding_model_config,
)

corpus = client.rag.create_corpus(
    rag_corpus=types.RagCorpus(
        display_name=display_name,
        description=description,
        rag_vector_db_config=vector_db,
    )
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

REST

   # Set your project ID under which you want to create the corpus
   PROJECT_ID = "YOUR_PROJECT_ID"

   # Choose a display name for your corpus
   CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

   # Set your Pinecone index name
   PINECONE_INDEX_NAME=YOUR_INDEX_NAME

   # Set the full resource name of your secret. Follows the format
   # projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
   SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

   # Call CreateRagCorpus API with all the Vector DB information.
   # You can also add the embedding model choice or set other RAG corpus parameters on
   # this call per your choice.
   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
         "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
         "rag_vector_db_config" : {
            "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
            "api_auth": {"api_key_config":
                  {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
            }
         }
      }'

   # To poll the status of your RAG corpus creation, get the operation_id returned in
   # response of your CreateRagCorpus call.
   OPERATION_ID="YOUR_OPERATION_ID"

   # Poll Operation status until done = true in the response.
   # The response to this call will contain the ID for your created RAG corpus
   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

יצירת קורפוס RAG בלי שם אינדקס או מפתח API

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

חשוב להביא בחשבון את הדברים הבאים:

• אם לא תציינו את שם האינדקס ואת שם הסוד של מפתח ה-API, לא תוכלו לייבא קבצים לקורפוס ה-RAG.

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

דוגמת הקוד הבאה ממחישה איך ליצור קורפוס RAG עם Pinecone בלי לספק שם אינדקס של Pinecone או שם API Secret. אפשר להשתמש ב-API של UpdateRagCorpus כדי לציין את המידע החסר בשלב מאוחר יותר.

Python

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone()

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST

# Set your project ID under which you want to create the corpus
PROJECT_ID = "YOUR_PROJECT_ID"

# Choose a display name for your corpus
CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

# Call CreateRagCorpus API with all the Vector DB information.
# You can also add the embedding model choice or set other RAG corpus parameters on
# this call per your choice.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "rag_vector_db_config" : {
         "pinecone": {}
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

עדכון של קורפוס ה-RAG

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

שדה	יכולת שינוי	חובה או אופציונלי
rag_vector_db_config.vector_db	אי אפשר לשנות את הבחירה אחרי שמבצעים אותה.	חובה
rag_vector_db_config.pinecone.index_name	אי אפשר לשנות את השדה אחרי שמגדירים אותו בקורפוס RAG.	חובה
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version	ניתן לשינוי. אחרי שמגדירים את מפתח ה-API, אי אפשר להסיר אותו.	אופציונלי

Python

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone(index_name=)

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST

# Set your project ID for the corpus that you want to create.
PROJECT_ID = "YOUR_PROJECT_ID"

# Set your Pinecone index name
PINECONE_INDEX_NAME=YOUR_INDEX_NAME

# Set the full resource name of your secret. Follows the format
# projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

# Call UpdateRagCorpus API with the Vector DB information.
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "rag_vector_db_config" : {
         "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
         "api_auth": {"api_key_config":
               {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
         }
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

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

• איך משתמשים בחיפוש וקטורי ב-Gemini Enterprise Agent Platform עם RAG Engine