שימוש במסד נתונים של Weaviate עם RAG Engine

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

אתם יכולים גם לעקוב אחרי ההוראות ב-notebook הזה: RAG Engine with Weaviate.

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

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

לתשומת ליבכם

לפני שמשתמשים במסד הנתונים של Weaviate, כדאי לבצע את הפעולות הבאות:

  1. אתם צריכים ליצור, להגדיר ולפרוס את המכונה והאוסף של מסד הנתונים ב-Weaviate. פועלים לפי ההוראות במאמר יצירת אוסף ב-Weaviate כדי להגדיר אוסף על סמך הסכימה.
  2. אתם צריכים לספק מפתח Weaviate API, שמאפשר למנוע RAG לקיים אינטראקציה עם מסד הנתונים של Weaviate. מנוע RAG תומך ב-AuthN וב-AuthZ שמבוססים על מפתח API, שמתחברים למסד הנתונים של Weaviate ותומכים בחיבור HTTPS.
  3. מנוע RAG לא מאחסן ומנהל את מפתח ה-API של Weaviate. במקום זאת, צריך לבצע את הפעולות הבאות:
    1. שומרים את המפתח ב- Google Cloud Secret Manager.
    2. נותנים לחשבון השירות של הפרויקט הרשאות גישה לסוד.
    3. נותנים למנוע RAG גישה לשם המשאב של הסוד.
    4. כשאתם מבצעים אינטראקציה עם מסד הנתונים של Weaviate, מנוע ה-RAG ניגש למשאב הסודי באמצעות חשבון השירות שלכם.
  4. הקורפוס של RAG Engine והאוסף של Weaviate ממופים ביחס של אחד לאחד. קבצי RAG מאוחסנים באוסף של מסד נתונים ב-Weaviate. כששולחים קריאה ל-API של CreateRagCorpus או ל-API של UpdateRagCorpus, מאגר הנתונים של RAG משויך לאוסף של מסד הנתונים.
  5. בנוסף לחיפושים סמנטיים שמבוססים על הטמעות צפופות, חיפוש היברידי נתמך גם ב-RAG Engine באמצעות מסד נתונים של Weaviate. אפשר גם לשנות את המשקל בין דמיון וקטורי דחוס ודליל בחיפוש היברידי.

הקצאת מסד הנתונים של Weaviate

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

  1. מגדירים ופורסים את המכונה של מסד הנתונים של Weaviate.
  2. מכינים את נקודת הקצה (endpoint) של HTTPS.
  3. יוצרים את האוסף ב-Weaviate.
  4. משתמשים במפתח ה-API כדי להקצות את Weaviate באמצעות AuthN ו-AuthZ.
  5. מקצים את חשבון השירות של RAG Engine.

הגדרה ופריסה של המכונה של מסד הנתונים של Weaviate

צריך לפעול לפי המדריך הרשמי למתחילים של Weaviate. עם זאת, אפשר להשתמש Google Cloud במדריך של Marketplace, אבל זה אופציונלי.

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

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

הכנת נקודת הקצה (endpoint) של HTTPS

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

יצירת אוסף Weaviate

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

כשיוצרים אוסף ב-Weaviate, צריך להשתמש בסכימה הבאה:

שם המאפיין סוג נתונים
fileId text
corpusId text
chunkId text
chunkDataType text
chunkData text
fileOriginalUri text

משתמשים במפתח ה-API כדי להקצות את Weaviate באמצעות AuthN ו-AuthZ

כדי להקצות את מפתח ה-API של Weaviate, צריך לבצע את השלבים הבאים:

  1. יוצרים את מפתח ה-API של Weaviate.
  2. מגדירים את Weaviate באמצעות מפתח ה-API של Weaviate.
  3. שומרים את מפתח ה-API של Weaviate ב-Secret Manager.

יצירת מפתח ה-API

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

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

אחסון מפתח ה-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 למכונות של מסד הנתונים של Weaviate, מנוע ה-RAG משתמש בכל חשבון שירות כדי לקרוא את מפתח ה-API שתואם למשאבי הסודות ב-Secret Manager מהפרויקטים.

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

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

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

לדוגמה, service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com.

כשמשלבים את מסד הנתונים של Weaviate, חשבון השירות משמש בתרחישים הבאים:

  • אתם יכולים להשתמש בחשבון השירות כדי ליצור את מפתח ה-API של Weaviate לצורך אימות. במקרים מסוימים, כדי ליצור את מפתח ה-API לא נדרשים פרטי משתמש, כלומר לא נדרש חשבון שירות כשיוצרים את מפתח ה-API.
  • כדי להגדיר את האימות (AuthN) וההרשאה (AuthZ), אתם יכולים לקשר את חשבון השירות למפתח ה-API במסד הנתונים של Weaviate, אבל לא חייבים להשתמש בחשבון שירות.
  • אתם יכולים לאחסן את מפתח ה-API ב-Secret Manager בפרויקט, ולתת לחשבון השירות הרשאות למשאבי הסודות האלה.
  • מנוע RAG משתמש בחשבונות שירות כדי לגשת למפתח ה-API מ-Secret Manager בפרויקטים שלכם.

הגדרה של סביבת מסוף Google Cloud

איך מגדירים את הסביבה

כדי להגדיר את הסביבה, בוחרים באחת מהכרטיסיות הבאות:

Python

  1. נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. מפעילים את Cloud Shell במסוף Google Cloud .

    הפעלת Cloud Shell

    בחלק התחתון של מסוף Google Cloud יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

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

    gcloud auth application-default login

    אם אתם משתמשים ב-Cloud Shell, אתם לא צריכים לעשות את זה.

    אם מוחזרת שגיאת אימות ואתם משתמשים בספק זהויות חיצוני (IdP), ודאו ש נכנסתם ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  8. מתקינים או מעדכנים את Agent Platform SDK ל-Python באמצעות הפקודה הבאה:

    pip3 install --upgrade "google-cloud-aiplatform>=1.38"

Node.js

  1. נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. מפעילים את Cloud Shell במסוף Google Cloud .

    הפעלת Cloud Shell

    בחלק התחתון של מסוף Google Cloud יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

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

    gcloud auth application-default login

    אם אתם משתמשים ב-Cloud Shell, אתם לא צריכים לעשות את זה.

    אם מוחזרת שגיאת אימות ואתם משתמשים בספק זהויות חיצוני (IdP), ודאו ש נכנסתם ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  8. מתקינים או מעדכנים את Agent Platform SDK ל-Node.js באמצעות הפקודה הבאה:

    npm install @google-cloud/vertexai

Java

  1. נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. מפעילים את Cloud Shell במסוף Google Cloud .

    הפעלת Cloud Shell

    בחלק התחתון של מסוף Google Cloud יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

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

    gcloud auth application-default login

    אם אתם משתמשים ב-Cloud Shell, אתם לא צריכים לעשות את זה.

    אם מוחזרת שגיאת אימות ואתם משתמשים בספק זהויות חיצוני (IdP), ודאו ש נכנסתם ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  8. כדי להוסיף את google-cloud-vertexai כתלות, מוסיפים את הקוד שמתאים לסביבה:

    ‫Maven עם BOM

    מוסיפים את קוד ה-HTML הבא ל-pom.xml:

    <dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.32.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-vertexai</artifactId>
  </dependency>
</dependencies>

    ‫Maven בלי BOM

    מוסיפים את קוד ה-HTML הבא ל-pom.xml:

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-vertexai</artifactId>
  <version>0.4.0</version>
</dependency>

    ‫Gradle בלי BOM

    מוסיפים את הנתונים הבאים לקובץ build.gradle:

    implementation 'com.google.cloud:google-cloud-vertexai:0.4.0'

Go

  1. נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. מפעילים את Cloud Shell במסוף Google Cloud .

    הפעלת Cloud Shell

    בחלק התחתון של מסוף Google Cloud יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

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

    gcloud auth application-default login

    אם אתם משתמשים ב-Cloud Shell, אתם לא צריכים לעשות את זה.

    אם מוחזרת שגיאת אימות ואתם משתמשים בספק זהויות חיצוני (IdP), ודאו ש נכנסתם ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  8. כדי לבחור את החבילה שהכי מתאימה לפרויקט, כדאי לעיין בחבילות של Agent Platform API Go:

    • החבילה cloud.google.com/go/vertexai (מומלץ)

      ‫vertexai היא חבילה שנוצרה על ידי בני אדם ומספקת גישה ליכולות ולתכונות נפוצות.

      החבילה הזו מומלצת כנקודת התחלה לרוב המפתחים שמשתמשים ב-Agent Platform API. כדי לגשת ליכולות ולתכונות שעדיין לא נכללות בחבילה הזו, צריך להשתמש ב-aiplatform שנוצר אוטומטית.

    • החבילה cloud.google.com/go/aiplatform

      ‫aiplatform היא חבילה שנוצרה אוטומטית.

      החבילה הזו מיועדת לפרויקטים שדורשים גישה ליכולות ולתכונות של Agent Platform API, שעדיין לא קיימות בחבילה vertexai שנוצרה על ידי בני אדם.

  9. מתקינים את חבילת Go הרצויה בהתאם לצרכים של הפרויקט, על ידי הפעלת אחת מהפקודות הבאות:

    # Human authored package. Recommended for most developers.
go get cloud.google.com/go/vertexai
    
    
# Auto-generated package.
go get cloud.google.com/go/aiplatform

C#

  1. נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. מפעילים את Cloud Shell במסוף Google Cloud .

    הפעלת Cloud Shell

    בחלק התחתון של מסוף Google Cloud יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

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

    gcloud auth application-default login

    אם אתם משתמשים ב-Cloud Shell, אתם לא צריכים לעשות את זה.

    אם מוחזרת שגיאת אימות ואתם משתמשים בספק זהויות חיצוני (IdP), ודאו ש נכנסתם ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

REST

  1. נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. מפעילים את Cloud Shell במסוף Google Cloud .

    הפעלת Cloud Shell

    בחלק התחתון של מסוף Google Cloud יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

  7. מזינים את הפרטים הבאים כדי להגדיר משתני סביבה. מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud . 
    MODEL_ID="gemini-3.5-flash"
PROJECT_ID="PROJECT_ID"
  8. מקצים את נקודת הקצה: 
    gcloud beta services identity create --service=aiplatform.googleapis.com --project=${PROJECT_ID}
  9. אופציונלי: אם אתם משתמשים ב-Cloud Shell ומתבקשים לאשר את Cloud Shell, לוחצים על Authorize.

הכנת קורפוס RAG

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

שימוש בממשקי ה-API של CreateRagCorpus ו-UpdateRagCorpus

כששולחים קריאה לממשקי ה-API של CreateRagCorpus ו-UpdateRagCorpus, צריך לציין את השדות הבאים:

  • ‫rag_vector_db_config.weaviate: אחרי ששולחים קריאה ל-API של CreateRagCorpus, בוחרים את ההגדרות של מסד הנתונים הווקטורי. ההגדרה של מסד הנתונים הווקטורי מכילה את כל שדות התצורה. אם השדה rag_vector_db_config.weaviate לא מוגדר, rag_vector_db_config.rag_managed_db מוגדר כברירת מחדל.
  • ‫weaviate.http_endpoint: נקודת הקצה (endpoint) של Weaviate ב-HTTPS או ב-HTTP נוצרת במהלך ההקצאה של המכונה של מסד הנתונים של Weaviate.
  • ‫weaviate.collection_name: שם האוסף שנוצר במהלך הקצאת המכונה של Weaviate. השם חייב להתחיל באות גדולה.
  • ‫api_auth.api_key_config: ההגדרה מציינת שצריך להשתמש במפתח API כדי לאשר את הגישה למסד הנתונים של הווקטורים.
  • ‫api_key_config.api_key_secret_version: שם המשאב של הסוד שמאוחסן ב-Secret Manager, שמכיל את מפתח ה-API של Weaviate.

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

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

  1. מגדירים את השדה weaviate ב-rag_vector_db_config.

    • אי אפשר לשנות את מסד הנתונים של הווקטורים המשויך.
    • משאירים את השדות http_endpoint ו-collection_name ריקים. אפשר לעדכן את שני השדות האלה מאוחר יותר.

  2. אם מפתח ה-API לא מאוחסן ב-Secret Manager, אפשר להשאיר את השדה api_auth ריק. כששולחים קריאה ל-API של UpdateRagCorpus, אפשר לעדכן את השדה api_auth. ב-Weaviate צריך לבצע את הפעולות הבאות:

    1. מגדירים את api_key_config בשדה api_auth.

    2. מגדירים את api_key_secret_version של מפתח ה-API של Weaviate ב-Secret Manager. השדה api_key_secret_version הוא בפורמט הבא:

      projects/{project}/secrets/{secret}/versions/{version}

  3. אם אתם מציינים שדות שאפשר להגדיר רק פעם אחת, כמו http_endpoint או collection_name, אתם לא יכולים לשנות אותם אלא אם אתם מוחקים את מאגר הנתונים של RAG ויוצרים אותו מחדש. אפשר לעדכן שדות אחרים, כמו השדה של מפתח ה-API,‏ api_key_secret_version.

  4. כשמפעילים את UpdateRagCorpus, אפשר להגדיר את השדה vector_db. הערך של vector_db צריך להיות מוגדר כ-weaviate על ידי הקריאה ל-API של CreateRagCorpus. אחרת, המערכת בוחרת באפשרות RAG Managed Database, שהיא ברירת המחדל. אי אפשר לשנות את האפשרות הזו כששולחים קריאה ל-API של UpdateRagCorpus. כשמפעילים את UpdateRagCorpus והשדה vector_db מוגדר באופן חלקי, אפשר לעדכן את השדות שמסומנים כניתנים לשינוי (נקראים גם mutable).

בטבלה הזו מפורטים WeaviateConfig השדות הניתנים לשינוי והשדות שלא ניתנים לשינוי שבהם נעשה שימוש בקוד.

שם השדה ניתן לשינוי או לא ניתן לשינוי
http_endpoint אי אפשר לשנות את ההגדרה אחרי שקובעים אותה
collection_name אי אפשר לשנות את ההגדרה אחרי שקובעים אותה
api_key_authentication ניתן לשינוי

יצירת קורפוס ה-RAG הראשון

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

  1. יוצרים קורפוס RAG ב-RAG Engine עם הגדרת Weaviate ריקה, שמתחילה את הקצאת המשאבים של RAG Engine כדי ליצור חשבון שירות.
  2. בוחרים שם לחשבון השירות של RAG Engine בפורמט הבא:

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

    לדוגמה, service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com.

  3. באמצעות חשבון השירות, ניגשים לסוד שמאוחסן ב-Secret Manager של הפרויקט, שמכיל את מפתח ה-API של Weaviate.
  4. אחרי שההקצאה של Weaviate מסתיימת, צריך לקבל את הפרטים הבאים:
    • נקודת הקצה (endpoint) של Weaviate ב-HTTPS או ב-HTTP.
    • שם האוסף ב-Weaviate.
  5. מפעילים את ה-API של CreateRagCorpus כדי ליצור קורפוס RAG עם הגדרת Weaviate ריקה, ומפעילים את ה-API של UpdateRagCorpus כדי לעדכן את קורפוס ה-RAG עם הפרטים הבאים:
    • נקודת הקצה (endpoint) של Weaviate ב-HTTPS או ב-HTTP.
    • שם האוסף ב-Weaviate.
    • שם המשאב של מפתח ה-API.

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

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

  1. מאתרים את חשבון השירות של RAG Engine בהרשאות של הפרויקט.
  2. מפעילים את האפשרות "Include Google-provided role grants" (הצגת תפקידים שניתנו על ידי Google).
  3. בוחרים שם לחשבון השירות של RAG Engine בפורמט הבא:

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

  4. באמצעות חשבון השירות, ניגשים לסוד שמאוחסן ב-Secret Manager של הפרויקט, שמכיל את מפתח ה-API של Weaviate.
  5. במהלך ההקצאה של Weaviate, צריך לקבל את הפרטים הבאים:
    • נקודת הקצה (endpoint) של Weaviate ב-HTTPS או ב-HTTP.
    • שם האוסף ב-Weaviate.
  6. יוצרים קורפוס RAG ב-RAG Engine ומקשרים אותו לאוסף ב-Weaviate באחת מהדרכים הבאות:
    1. שולחים קריאה ל-API של CreateRagCorpus כדי ליצור קורפוס RAG עם הגדרת Weaviate מאוכלסת, שהיא האפשרות המועדפת.
    2. מבצעים קריאה ל-API של CreateRagCorpus כדי ליצור קורפוס RAG עם הגדרת Weaviate ריקה, ומבצעים קריאה ל-API של UpdateRagCorpus כדי לעדכן את קורפוס ה-RAG עם הפרטים הבאים:
      • נקודת קצה (endpoint) ב-HTTP של מסד נתונים ב-Weaviate
      • שם האוסף ב-Weaviate
      • מפתח API

דוגמאות

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

כדי להשתמש ב-notebook של Model Garden RAG API, קראו את המאמר שימוש ב-Weaviate עם Llama 3.

הגדרת מסד הנתונים של Weaviate

דוגמת הקוד הזו ממחישה איך להגדיר את הנתונים של Weaviate ואת Secret Manager.

REST

# TODO(developer): Update the variables.
# The HTTPS/HTTP Weaviate endpoint you created during provisioning.
HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

# Your Weaviate API Key.
WEAVIATE_API_KEY="example-api-key"

# Select your Weaviate collection name, which roughly corresponds to a Agent Platform Knowledge Engine Corpus.
# For example, "MyCollectionName"
# Note that the first letter needs to be capitalized.
# Otherwise, Weavaite will capitalize it for you.
WEAVIATE_COLLECTION_NAME="MyCollectionName"

# Create a collection in Weaviate which includes the required schema fields shown below.
echo '{
  "class": "'${WEAVIATE_COLLECTION_NAME}'",
  "properties": [
    { "name": "fileId", "dataType": [ "string" ] },
    { "name": "corpusId", "dataType": [ "string" ] },
    { "name": "chunkId", "dataType": [ "string" ] },
    { "name": "chunkDataType", "dataType": [ "string" ] },
    { "name": "chunkData", "dataType": [ "string" ] },
    { "name": "fileOriginalUri", "dataType": [ "string" ] }
  ]
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer "${WEAVIATE_API_KEY} \
    -d @- \
    ${HTTP_ENDPOINT_NAME}/v1/schema

הגדרת Secret Manager

כדי להגדיר את Secret Manager, צריך להפעיל אותו ולהגדיר הרשאות.

יצירת סוד

כדי להפעיל את Secret Manager:

המסוף

  1. נכנסים לדף Secret Manager.

    כניסה ל-Secret Manager

  2. לוחצים על ‎+ Create Secret.

  3. מזינים את ה-Name של הסוד. שמות של סודות יכולים להכיל רק אותיות באנגלית (A-Z), מספרים (0-9), מקפים (-) וקווים תחתונים (_).

  4. השדות הבאים הם אופציונליים:

    1. כדי להעלות את הקובץ עם הסוד, לוחצים על Browse.
    2. המדיניות בנושא שכפול
    3. אם רוצים לנהל באופן ידני את המיקומים של הסוד, מסמנים את האפשרות Manually manage locations for this secret. צריך לבחור לפחות אזור אחד.
    4. בוחרים את אפשרות ההצפנה.
    5. אם רוצים להגדיר ידנית את תקופת הרוטציה, מסמנים את האפשרות Set rotation period.
    6. אם רוצים לציין נושאים לפרסום או להרשמה כדי לקבל התראות על אירועים, לוחצים על הוספת נושאים.
    7. כברירת מחדל, לסוד אין תאריך תפוגה. אם רוצים להגדיר תאריך תפוגה, מסמנים את האפשרות הגדרת תאריך תפוגה.
    8. כברירת מחדל, גרסאות של סודות מושמדות לפי בקשה. כדי לעכב את ההשמדה של גרסאות סודיות, מסמנים את האפשרות Set duration for delayed destruction.
    9. אם רוצים להשתמש בתוויות כדי לארגן ולסווג את הסודות, לוחצים על ‎+ Add label.
    10. אם רוצים להשתמש בהערות כדי לצרף לסודות מטא-נתונים לא מזהים, לוחצים על + Add annotation.

  5. לוחצים על Create secret.

REST

# Create a secret in SecretManager.
curl "https://secretmanager.googleapis.com/v1/projects/${PROJECT_ID}/secrets?secretId=${SECRET_NAME}" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"replication\": {\"automatic\": {}}}"

Python

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

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

# Import the Secret Manager client library.
from google.cloud import secretmanager


def create_secret(
    project_id: str, secret_id: str, ttl: Optional[str] = None
) -> secretmanager.Secret:
    """
    Create a new secret with the given name. A secret is a logical wrapper
    around a collection of secret versions. Secret versions hold the actual
    secret material.

     Args:
        project_id (str): The project ID where the secret is to be created.
        secret_id (str): The ID to assign to the new secret. This ID must be unique within the project.
        ttl (Optional[str]): An optional string that specifies the secret's time-to-live in seconds with
                             format (e.g., "900s" for 15 minutes). If specified, the secret
                             versions will be automatically deleted upon reaching the end of the TTL period.

    Returns:
        secretmanager.Secret: An object representing the newly created secret, containing details like the
                              secret's name, replication settings, and optionally its TTL.

    Example:
        # Create a secret with automatic replication and no TTL
        new_secret = create_secret("my-project", "my-new-secret")

        # Create a secret with a TTL of 30 days
        new_secret_with_ttl = create_secret("my-project", "my-timed-secret", "7776000s")
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent project.
    parent = f"projects/{project_id}"

    # Create the secret.
    response = client.create_secret(
        request={
            "parent": parent,
            "secret_id": secret_id,
            "secret": {"replication": {"automatic": {}}, "ttl": ttl},
        }
    )

    # Print the new secret name.
    print(f"Created secret: {response.name}")

הגדרת ההרשאות

אתם צריכים לתת לחשבון השירות הרשאות ל-Secret Manager.

המסוף

  1. בקטע IAM & Admin במסוף Google Cloud , מוצאים את חשבון השירות ולוחצים על סמל העיפרון כדי לערוך אותו.

  2. בשדה Role, בוחרים באפשרות Secret Manager Secret Accessor.

Python

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

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

def iam_grant_access(
    project_id: str, secret_id: str, member: str
) -> iam_policy_pb2.SetIamPolicyRequest:
    """
    Grant the given member access to a secret.
    """

    # Import the Secret Manager client library.
    from google.cloud import secretmanager

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the secret.
    name = client.secret_path(project_id, secret_id)

    # Get the current IAM policy.
    policy = client.get_iam_policy(request={"resource": name})

    # Add the given member with access permissions.
    policy.bindings.add(role="roles/secretmanager.secretAccessor", members=[member])

    # Update the IAM Policy.
    new_policy = client.set_iam_policy(request={"resource": name, "policy": policy})

    # Print data about the secret.
    print(f"Updated IAM policy on {secret_id}")

הוספת גרסת סוד

REST

# TODO(developer): Update the variables.
# Select a resource name for your Secret, which contains your API Key.
SECRET_NAME="MyWeaviateApiKeySecret"

# Your Weaviate API Key.
WEAVIATE_API_KEY="example-api-key"
# Encode your WEAVIATE_API_KEY using base 64.
SECRET_DATA=$(echo ${WEAVIATE_API_KEY} | base64)

# Create a new version of your secret which uses SECRET_DATA as payload
curl "https://secretmanager.googleapis.com/v1/projects/${PROJECT_ID}/secrets/${SECRET_NAME}:addVersion" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"payload\": {\"data\": \"${SECRET_DATA}\"}}"

Python

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

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

from google.cloud import secretmanager
import google_crc32c  # type: ignore


def add_secret_version(
    project_id: str, secret_id: str, payload: str
) -> secretmanager.SecretVersion:
    """
    Add a new secret version to the given secret with the provided payload.
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent secret.
    parent = client.secret_path(project_id, secret_id)

    # Convert the string payload into a bytes. This step can be omitted if you
    # pass in bytes instead of a str for the payload argument.
    payload_bytes = payload.encode("UTF-8")

    # Calculate payload checksum. Passing a checksum in add-version request
    # is optional.
    crc32c = google_crc32c.Checksum()
    crc32c.update(payload_bytes)

    # Add the secret version.
    response = client.add_secret_version(
        request={
            "parent": parent,
            "payload": {
                "data": payload_bytes,
                "data_crc32c": int(crc32c.hexdigest(), 16),
            },
        }
    )

    # Print the new secret version name.
    print(f"Added secret version: {response.name}")

שימוש ב-Weaviate עם Llama 3

ב-notebook של Model Garden RAG API מוסבר איך להשתמש ב-Agent Platform SDK ל-Python עם קורפוס של Weaviate ומודל Llama 3. כדי להשתמש ב-notebook, צריך:

  1. מגדירים את מסד הנתונים של Weaviate.

  2. מגדירים את Secret Manager.

  3. משתמשים ב-Model Garden RAG API notebook.

דוגמאות נוספות

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

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

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Agent Platform Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  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" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  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}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

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"
# weaviate_http_endpoint = "weaviate-http-endpoint"
# weaviate_collection_name = "weaviate-collection-name"
# weaviate_api_key_secret_manager_version = "projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/latest"
# 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.RagVectorDbConfigWeaviate(
    http_endpoint=weaviate_http_endpoint,
    collection_name=weaviate_collection_name,
)

corpus = client.rag.create_corpus(
    rag_corpus=types.RagCorpus(
        display_name=display_name,
        description=description,
        rag_vector_db_config=types.RagVectorDbConfig(
            weaviate=vector_db,
            api_auth=types.ApiAuth(
                api_key_config=types.ApiAuthApiKeyConfig(
                    api_key_secret_version=weaviate_api_key_secret_manager_version
                )
            ),
            rag_embedding_model_config=embedding_model_config,
        ),
    )
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

שימוש בקובץ RAG

RAG API מטפל בהעלאה, בייבוא, בהצגה ובמחיקה של קבצים.

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • PROJECT_ID: .
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של המשאב RagCorpus.
  • ‫INPUT_FILE: הנתיב של קובץ מקומי.
  • ‫FILE_DISPLAY_NAME: השם המוצג של RagFile.
  • ‫RAG_FILE_DESCRIPTION: התיאור של RagFile.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/media:upload

גוף בקשת JSON: 

{
 "rag_file": {
  "display_name": "FILE_DISPLAY_NAME",
  "description": "RAG_FILE_DESCRIPTION"
 }
}

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

curl

שומרים את גוף הבקשה בקובץ בשם INPUT_FILE ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @INPUT_FILE \
     "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/media:upload"

PowerShell

שומרים את גוף הבקשה בקובץ בשם INPUT_FILE ומריצים את הפקודה הבאה: 

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile INPUT_FILE `
    -Uri "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/media:upload" | Select-Object -Expand Content
תגובה מוצלחת מחזירה את המשאב RagFile. הרכיב האחרון בשדה RagFile.name הוא rag_file_id שנוצר על ידי השרת.

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 


import agentplatform

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}"
# path = "path/to/local/file.txt"
# display_name = "file_display_name"

# 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")

rag_file = client.rag.upload_file(
    corpus_name=corpus_name,
    path=path,
    display_name=display_name,
)
print(rag_file)
# RagFile(name='projects/[PROJECT_ID]/locations/us-east5/ragCorpora/1234567890/ragFiles/09876543',
#  display_name='file_display_name')

ייבוא קובצי RAG

אפשר לייבא קבצים ותיקיות מ-Drive או מ-Cloud Storage.

REST

כדי לראות כשלים חלקיים, זמן בקשה וזמן תגובה באובייקט response של ה-SDK, משתמשים ב-response.metadata.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • PROJECT_ID: .
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של המשאב RagCorpus.
  • ‫GCS_URIS: רשימה של מיקומים ב-Cloud Storage. לדוגמה: gs://my-bucket1, gs://my-bucket2.
  • ‫DRIVE_RESOURCE_ID: המזהה של המשאב ב-Drive. דוגמאות:
    • https://drive.google.com/file/d/ABCDE
    • https://drive.google.com/corp/drive/u/0/folders/ABCDEFG
  • ‫DRIVE_RESOURCE_TYPE: סוג המשאב ב-Drive. אפשרויות:
    • RESOURCE_TYPE_FILE – קובץ
    • RESOURCE_TYPE_FOLDER – תיקייה
  • ‫CHUNK_SIZE: אופציונלי: מספר הטוקנים שצריכים להיות בכל קטע.
  • ‫CHUNK_OVERLAP: אופציונלי: מספר הטוקנים שחופפים בין החלקים.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import

גוף בקשת JSON: 

{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": GCS_URIS
    },
    "google_drive_source": {
      "resource_ids": {
        "resource_id": DRIVE_RESOURCE_ID,
        "resource_type": DRIVE_RESOURCE_TYPE
      },
    }
  }
}

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

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import" | Select-Object -Expand Content
תגובה מוצלחת מחזירה את המשאב ImportRagFilesOperationMetadata.

הדוגמה הבאה ממחישה איך לייבא קובץ מ-Cloud Storage. משתמשים בשדה הבקרה max_embedding_requests_per_min כדי להגביל את הקצב שבו מנוע ה-RAG קורא למודל ההטמעה במהלך תהליך ההוספה לאינדקס של ImportRagFiles. ערך ברירת המחדל של השדה הוא 1000 קריאות לדקה.

// Cloud Storage bucket/file location.
// Such as "gs://rag-e2e-test/"
GCS_URIS=YOUR_GCS_LOCATION

// Enter the QPM rate to limit RAG's access to your embedding model
// Example: 1000
EMBEDDING_MODEL_QPM_RATE=MAX_EMBEDDING_REQUESTS_PER_MIN_LIMIT

// ImportRagFiles
// Import a single Cloud Storage file or all files in a Cloud Storage bucket.
// Input: ENDPOINT, PROJECT_ID, RAG_CORPUS_ID, GCS_URIS
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ENDPOINT}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URIS}"\"'
    },
    "rag_file_chunking_config": {
      "chunk_size": 512
    },
    "max_embedding_requests_per_min": '"${EMBEDDING_MODEL_QPM_RATE}"'
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID=OPERATION_ID
poll_op_wait ${OPERATION_ID}

בדוגמה הבאה אפשר לראות איך לייבא קובץ מ-Drive. משתמשים בשדה הבקרה max_embedding_requests_per_min כדי להגביל את הקצב שבו מנוע ה-RAG קורא למודל ההטמעה במהלך תהליך ההוספה לאינדקס של ImportRagFiles. ערך ברירת המחדל של השדה הוא 1000 קריאות לדקה.

// Google Drive folder location.
FOLDER_RESOURCE_ID=YOUR_GOOGLE_DRIVE_FOLDER_RESOURCE_ID

// Enter the QPM rate to limit RAG's access to your embedding model
// Example: 1000
EMBEDDING_MODEL_QPM_RATE=MAX_EMBEDDING_REQUESTS_PER_MIN_LIMIT

// ImportRagFiles
// Import all files in a Google Drive folder.
// Input: ENDPOINT, PROJECT_ID, RAG_CORPUS_ID, FOLDER_RESOURCE_ID
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ENDPOINT}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "google_drive_source": {
      "resource_ids": {
        "resource_id": '\""${FOLDER_RESOURCE_ID}"\"',
        "resource_type": "RESOURCE_TYPE_FOLDER"
      }
    },
    "max_embedding_requests_per_min": '"${EMBEDDING_MODEL_QPM_RATE}"'
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID=OPERATION_ID
poll_op_wait ${OPERATION_ID}

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 


import agentplatform
from agentplatform import types

from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}"
# paths = ["gs://my_bucket/my_files_dir/*"]

# 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")

response = client.rag.import_files(
    name=corpus_name,
    import_config=types.ImportRagFilesConfig(
        gcs_source=genai_types.GcsSource(uris=paths),
        rag_file_transformation_config=types.RagFileTransformationConfig(
            rag_file_chunking_config=types.RagFileChunkingConfig(
                chunk_size=512,
                chunk_overlap=100,
            )
        ),  # optional
        max_embedding_requests_per_min=900,  # optional
    ),
)

print(f"Imported {response.imported_rag_files_count} files.")
# Example response:
# Imported 2 files.

איך מקבלים קובץ RAG

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • PROJECT_ID: .
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של המשאב RagCorpus.
  • ‫RAG_FILE_ID: המזהה של המשאב RagFile.

ה-method של ה-HTTP וכתובת ה-URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

כדי לשלוח את הבקשה אתם צריכים לבחור אחת מהאפשרויות הבאות:

curl

מריצים את הפקודה הבאה: 

curl -X GET \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

מריצים את הפקודה הבאה: 

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content
תגובה מוצלחת מחזירה את המשאב RagFile.

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 


import agentplatform

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# file_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}"

# 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")

rag_file = client.rag.get_file(name=file_name)
print(rag_file)
# Example response:
# RagFile(name='projects/1234567890/locations/us-east5/ragCorpora/11111111111/ragFiles/22222222222',
# display_name='file_display_name', description='file description')

הצגת רשימה של קובצי RAG

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • PROJECT_ID: .
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של המשאב RagCorpus.
  • ‫PAGE_SIZE: גודל הדף הסטנדרטי של הרשימה. אפשר לשנות את מספר הפריטים מסוג RagFiles שיוחזרו בכל דף על ידי עדכון הפרמטר page_size.
  • PAGE_TOKEN: אסימון הדף הרגיל של הרשימה. בדרך כלל מתקבל באמצעות ListRagFilesResponse.next_page_token של הקריאה הקודמת של VertexRagDataService.ListRagFiles.

ה-method של ה-HTTP וכתובת ה-URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN

כדי לשלוח את הבקשה אתם צריכים לבחור אחת מהאפשרויות הבאות:

curl

מריצים את הפקודה הבאה: 

curl -X GET \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

PowerShell

מריצים את הפקודה הבאה: 

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" | Select-Object -Expand Content
אמור להתקבל קוד סטטוס של הצלחה (2xx) ורשימה של RagFiles ב-RAG_CORPUS_ID שצוין.

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 


import agentplatform

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}"

# 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")

files_response = client.rag.list_files(name=corpus_name)
for file in files_response.rag_files:
    print(file.display_name)
    print(file.name)
# Example response:
# g-drive_file.txt
# projects/1234567890/locations/us-east5/ragCorpora/111111111111/ragFiles/222222222222
# g_cloud_file.txt
# projects/1234567890/locations/us-east5/ragCorpora/111111111111/ragFiles/333333333333

מחיקת קובץ RAG

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • PROJECT_ID: .
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫RAG_CORPUS_ID: המזהה של המשאב RagCorpus.
  • ‫RAG_FILE_ID: המזהה של המשאב RagFile. פורמט: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}/ragFiles/{rag_file_id}.

ה-method של ה-HTTP וכתובת ה-URL: 

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

כדי לשלוח את הבקשה אתם צריכים לבחור אחת מהאפשרויות הבאות:

curl

מריצים את הפקודה הבאה: 

curl -X DELETE \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

מריצים את הפקודה הבאה: 

$headers = @{  }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content
תגובה מוצלחת מחזירה את המשאב DeleteOperationMetadata.

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 


import agentplatform

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# file_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}"

# 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")

client.rag.delete_file(name=file_name)
print(f"File {file_name} deleted.")
# Example response:
# Successfully deleted the RagFile.
# File projects/1234567890/locations/us-east5/ragCorpora/1111111111/ragFiles/2222222222 deleted.

אחזור הקשר

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

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • PROJECT_ID: .
  • ‫RAG_CORPUS_RESOURCE: השם של המשאב ב-RagCorpus. פורמט: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.
  • ‫VECTOR_DISTANCE_THRESHOLD: המערכת מחזירה רק הקשרים עם מרחק וקטורי קטן מהסף.
  • ‫TEXT: טקסט השאילתה כדי לקבל הקשרים רלוונטיים.
  • ‫SIMILARITY_TOP_K: מספר ההקשרים המובילים לאחזור.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts

גוף בקשת JSON: 

{
 "vertex_rag_store": {
    "rag_resources": {
      "rag_corpus": "RAG_CORPUS_RESOURCE",
    },
    "vector_distance_threshold": 0.8
  },
  "query": {
   "text": "TEXT",
   "similarity_top_k": SIMILARITY_TOP_K
  }
 }

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

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts" | Select-Object -Expand Content
אמור להתקבל קוד סטטוס של הצלחה (‎2xx) ורשימה של RagFiles קשורים.

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 


import agentplatform

from agentplatform import types
from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-east5/ragCorpora/[rag_corpus_id]"

# 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")

response = client.rag.retrieve_contexts(
    vertex_rag_store=genai_types.VertexRagStore(
        rag_resources=[
            genai_types.VertexRagStoreRagResource(
                rag_corpus=corpus_name,
                # Optional: supply IDs from `rag.list_files()`.
                # rag_file_ids=["rag-file-1", "rag-file-2", ...],
            )
        ],
    ),
    query=types.RagQuery(
        text="Hello World!",
        rag_retrieval_config=genai_types.RagRetrievalConfig(
            top_k=10,
            filter=genai_types.RagRetrievalConfigFilter(
                vector_distance_threshold=0.5
            ),
        ),
    )
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

יוצר תוכן

החיזוי שולט בשיטת ה-LLM שיוצרת תוכן.

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • PROJECT_ID: .
  • ‫LOCATION: האזור שבו הבקשה תעובד.
  • ‫MODEL_ID: מודל LLM ליצירת תוכן. לדוגמה: gemini-3.5-flash
  • ‫GENERATION_METHOD: שיטת LLM ליצירת תוכן. אפשרויות: generateContent, streamGenerateContent
  • ‫INPUT_PROMPT: הטקסט שנשלח למודל ה-LLM ליצירת תוכן. נסו להשתמש בהנחיה שרלוונטית לקובצי ה-RAG שהעליתם.
  • ‫RAG_CORPUS_RESOURCE: השם של המשאב ב-RagCorpus. פורמט: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.
  • ‫SIMILARITY_TOP_K: אופציונלי: מספר ההקשרים המובילים שרוצים לאחזר.
  • ‫VECTOR_DISTANCE_THRESHOLD: אופציונלי: מוחזרים הקשרים עם מרחק וקטורי קטן מהסף.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD

גוף בקשת JSON: 

{
 "contents": {
  "role": "user",
  "parts": {
    "text": "INPUT_PROMPT"
  }
 },
 "tools": {
  "retrieval": {
   "disable_attribution": false,
   "vertex_rag_store": {
    "rag_resources": {
      "rag_corpus": "RAG_CORPUS_RESOURCE",
    },
    "similarity_top_k": SIMILARITY_TOP_K,
    "vector_distance_threshold": VECTOR_DISTANCE_THRESHOLD
   }
  }
 }
}

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

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD" | Select-Object -Expand Content
תגובה מוצלחת מחזירה את התוכן שנוצר עם ציטוטים.

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 


from google import genai
from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}"

rag_retrieval_tool = genai_types.Tool(
    retrieval=genai_types.Retrieval(
        vertex_rag_store=genai_types.VertexRagStore(
            rag_resources=[
                genai_types.VertexRagStoreRagResource(
                    rag_corpus=corpus_name
                )
            ],
            rag_retrieval_config=genai_types.RagRetrievalConfig(
                top_k=10,
                filter=genai_types.RagRetrievalConfigFilter(
                    vector_distance_threshold=0.5
                ),
            ),
        ),
    )
)

# Create a GenAI SDK client to make a generate_content request
genai_client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")

response = genai_client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Why is the sky blue?",
    config=genai_types.GenerateContentConfig(
        tools=[rag_retrieval_tool]
    ),
)
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

חיפוש היברידי נתמך במסד הנתונים של Weaviate, שמשלב חיפושים סמנטיים וחיפושים לפי מילות מפתח כדי לשפר את הרלוונטיות של תוצאות החיפוש. במהלך אחזור תוצאות החיפוש, שילוב של ציוני דמיון מסמנטיקה (וקטור צפוף) והתאמה למילות מפתח (וקטור דליל) מפיק את התוצאות הסופיות המדורגות.

חיפוש היברידי באמצעות ה-API לאחזור של RAG Engine

בדוגמה הבאה מוסבר איך להפעיל חיפוש היברידי באמצעות ה-API לאחזור של RAG Engine.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Agent Platform Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  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" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  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}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 


import agentplatform

from agentplatform import types
from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-east5/ragCorpora/[rag_corpus_id]"

# 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")

response = client.rag.retrieve_contexts(
    vertex_rag_store=genai_types.VertexRagStore(
        rag_resources=[
            genai_types.VertexRagStoreRagResource(
                rag_corpus=corpus_name,
                # Optional: supply IDs from `rag.list_files()`.
                # rag_file_ids=["rag-file-1", "rag-file-2", ...],
            )
        ],
    ),
    query=types.RagQuery(
        text="Hello World!",
        rag_retrieval_config=genai_types.RagRetrievalConfig(
            top_k=10,
            filter=genai_types.RagRetrievalConfigFilter(
                vector_distance_threshold=0.5
            ),
        ),
    )
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

שימוש בחיפוש היברידי וב-RAG Engine ליצירת תשובות מעוגנות

זו דוגמה לשימוש בחיפוש היברידי וב-RAG Engine ליצירת תשובות מבוססות-קרקע.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Agent Platform Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  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" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  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}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 


from google import genai
from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}"

rag_retrieval_tool = genai_types.Tool(
    retrieval=genai_types.Retrieval(
        vertex_rag_store=genai_types.VertexRagStore(
            rag_resources=[
                genai_types.VertexRagStoreRagResource(
                    rag_corpus=corpus_name
                )
            ],
            rag_retrieval_config=genai_types.RagRetrievalConfig(
                top_k=10,
                filter=genai_types.RagRetrievalConfigFilter(
                    vector_distance_threshold=0.5
                ),
            ),
        ),
    )
)

# Create a GenAI SDK client to make a generate_content request
genai_client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")

response = genai_client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Why is the sky blue?",
    config=genai_types.GenerateContentConfig(
        tools=[rag_retrieval_tool]
    ),
)
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

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