שימוש ב-Pinecone עם Vertex AI RAG Engine

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

אפשר גם לעקוב באמצעות מסמך ה-notebook הזה Vertex AI RAG Engine with Pinecone.

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

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

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

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

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

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

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

    • מאחסנים את המפתח ב-Secret Manager. Google Cloud
    • מעניקים לחשבון השירות של הפרויקט הרשאות גישה לסוד.
    • צריך לספק למנוע Vertex AI RAG גישה לשם המשאב של הסוד.
    • כשאתם מקיימים אינטראקציה עם מאגר המידע של RAG, מנוע RAG של Vertex AI ניגש למשאב הסודי באמצעות חשבון השירות שלכם.

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

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

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

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

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

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

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

    דגם גודל המאפיין
    ‫Gecko בדומיין של המפרסם 768
    ‫Gecko מותאם אישית של צד ראשון 768
    E5 איך משתמשים במודלים להטמעה של OSS

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

    • cosine
    • dotproduct
    • euclidean

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

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

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

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

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

כדי להגן על פרטים אישיים רגישים, צריך לבצע את הפעולות הבאות:

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

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

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

    2. מפעילים את האפשרות Include Google-provided role grants (הכללת תפקידים שניתנו על ידי Google).

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

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

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

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

  3. במהלך היצירה או העדכון של מאגר המידע של RAG, מעבירים את שם משאב הסוד למנוע RAG של Vertex AI ושומרים את שם משאב הסוד.

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

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

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

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

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

לדוגמה,

service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com

הכנת קורפוס RAG

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

כדי שהשיוך ייחשב להשלמה, צריך להגדיר שלושה שדות מרכזיים במאגר המידע של RAG:

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

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

  • ‫rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: זהו שם המשאב המלא של הסוד שמאוחסן ב-Secret Manager, שמכיל את מפתח ה-API של Pinecone. אפשר להגדיר את השם במהלך CreateRagCorpusהשיחה, או לציין את השם כשמתקשרים אל UpdateRagCorpusAPI. עד שלא תציינו את השדה הזה, לא תוכלו לייבא נתונים למאגר המידע של RAG.
    הפורמט של השדה הזה צריך להיות:
    projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

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

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

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

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

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonהוראות ההגדרה במאמר Vertex AI quickstart using client libraries. מידע נוסף מופיע במאמרי העזרה של Vertex AI Python API.

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


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# pinecone_index_name = "pinecone-index-name"
# pinecone_api_key_secret_manager_version = "projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/latest"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = rag.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=rag.VertexPredictionEndpoint(
        publisher_model="publishers/google/models/text-embedding-005"
    )
)

# Configure Vector DB
vector_db = rag.Pinecone(
    index_name=pinecone_index_name,
    api_key=pinecone_api_key_secret_manager_version,
)

corpus = rag.create_corpus(
    display_name=display_name,
    description=description,
    backend_config=rag.RagVectorDbConfig(
        rag_embedding_model_config=embedding_model_config,
        vector_db=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. משתמשים ב-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

‫UpdateRagCorpus API מאפשר לעדכן את ההגדרות של מסד הנתונים הווקטורי. אם שם האינדקס של 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}

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