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

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

כדי לראות דוגמה לשימוש ב-RAG Engine עם Pinecone, מריצים את קובץ ה-notebook‏ RAG Engine with Pinecone באחת מהסביבות הבאות:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   • cosine
   • dotproduct
   • euclidean

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

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

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

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

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

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

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

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

   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 Engine ושומרים את שם משאב הסוד.

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

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

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

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

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

לדוגמה,

[e-mail]

הכנת קורפוס RAG

כדי להשתמש באינדקס Pinecone עם 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 או לציין את השם כשמתקשרים ל-API של UpdateRagCorpus. עד שתציינו את השדה הזה, לא תוכלו לייבא נתונים למאגר המידע של RAG.

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

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

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

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

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

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

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
client = agentplatform.Client(project=PROJECT_ID, location="us-central1")

# 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,
    ),
    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. משתמשים ב-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}

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

• שימוש בחיפוש וקטורי ב-Gemini Enterprise Agent Platform עם מנוע RAG