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

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

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

  1. מגדירים ופורסים את מופע מסד הנתונים של Weaviate.
  2. מכינים את נקודת הקצה של 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 לא יהיה אחראי להתנהגויות לא צפויות כתוצאה מהשינויים האלה.

הכנת נקודת הקצה של 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

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

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

יצירת מפתח API

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

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

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

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

כדי להגן על נתוני SPII, צריך:

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

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

כשיוצרים את המשאב הראשון בפרויקט, RAG Engine יוצר חשבון שירות ייעודי. אפשר למצוא את חשבון השירות בדף 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.
  • אתם יכולים לקשר את חשבון השירות שלכם למפתח ה-API במסד הנתונים של Weaviate כדי להגדיר את האימות (AuthN) וההרשאה (AuthZ). עם זאת, חשבון השירות לא נדרש.
  • אפשר לאחסן את מפתח ה-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 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 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. במסוף Google Cloud , מפעילים את Cloud Shell.

    הפעלת 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 for 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 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 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. במסוף Google Cloud , מפעילים את Cloud Shell.

    הפעלת 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 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 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. במסוף Google Cloud , מפעילים את Cloud Shell.

    הפעלת 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 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 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. במסוף Google Cloud , מפעילים את Cloud Shell.

    הפעלת Cloud Shell

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

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

    gcloud auth application-default login

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

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

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

    • Package cloud.google.com/go/vertexai (מומלץ)

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

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

    • Package 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 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 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. במסוף Google Cloud , מפעילים את Cloud Shell.

    הפעלת 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 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 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. במסוף Google Cloud , מפעילים את Cloud Shell.

    הפעלת 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: אחרי שקוראים ל-CreateRagCorpus API, נבחרת ההגדרה של מסד הנתונים הווקטורי. ההגדרה של מסד הנתונים הווקטורי מכילה את כל שדות ההגדרה. אם השדה 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 בקריאה ל-CreateRagCorpus API. אחרת, המערכת בוחרת באפשרות RAG Managed Database (מסד נתונים מנוהל של RAG), שהיא ברירת המחדל. אי אפשר לשנות את האפשרות הזו כשמתקשרים אל UpdateRagCorpus ה-API. כשמתקשרים אל UpdateRagCorpus והשדה vector_db מוגדר באופן חלקי, אפשר לעדכן את השדות שמסומנים כניתנים לשינוי (נקראים גם משתנים).

בטבלה הזו מפורטים השדות 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. מפעילים את CreateRagCorpus API כדי ליצור מאגר RAG עם הגדרת Weaviate ריקה, ומפעילים את UpdateRagCorpus API כדי לעדכן את מאגר ה-RAG עם המידע הבא:
    • נקודת הקצה (endpoint) של Weaviate HTTPS או HTTP.
    • השם של אוסף Weaviate.
    • שם המשאב של מפתח ה-API.

יצירת מאגר מידע נוסף של RAG

אם חשבון השירות של RAG Engine קיים, מבצעים את הפעולות הבאות:

  1. מקבלים את חשבון השירות של מנוע ה-RAG מההרשאות של הפרויקט.
  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. מבצעים קריאה ל-CreateRagCorpus API כדי ליצור מאגר RAG עם הגדרת Weaviate ריקה, ומבצעים קריאה ל-UpdateRagCorpus API כדי לעדכן את מאגר ה-RAG עם המידע הבא:
      • נקודת קצה (endpoint) של מסד נתונים ב-Weaviate בפרוטוקול HTTP
      • שם האוסף ב-Weaviate
      • מפתח API

דוגמאות

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

כדי להשתמש במחברת RAG API של Model Garden, אפשר לעיין במאמר בנושא שימוש ב-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. מזינים את השם של הסוד. שמות של סודות יכולים להכיל רק אותיות באנגלית (A-Z), מספרים (0-9), מקפים (-) וקווים תחתונים (_).

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

    1. כדי להעלות את הקובץ עם הסוד, לוחצים על עיון.
    2. כדאי לקרוא את המדיניות בנושא שכפול.
    3. אם רוצים לנהל ידנית את המיקומים של הסוד, מסמנים את התיבה Manually manage locations for this secret (ניהול ידני של המיקומים של הסוד הזה). צריך לבחור לפחות אזור אחד.
    4. בוחרים את אפשרות ההצפנה.
    5. אם רוצים להגדיר ידנית את תקופת הרוטציה, מסמנים את התיבה הגדרת תקופת הרוטציה.
    6. אם רוצים לציין נושאים לפרסום או להרשמה כדי לקבל התראות על אירועים, לוחצים על הוספת נושאים.
    7. כברירת מחדל, התוקף של הסוד לא פג אף פעם. אם רוצים להגדיר תאריך תפוגה, מסמנים את התיבה הגדרת תאריך תפוגה.
    8. כברירת מחדל, גרסאות של סודות מושמדות לפי בקשה. כדי לדחות את ההשמדה של גרסאות סודיות, מסמנים את התיבה הגדרת משך זמן לדחיית ההשמדה.
    9. אם רוצים להשתמש בתוויות כדי לארגן ולסווג את הסודות, לוחצים על + הוספת תווית.
    10. אם רוצים להשתמש בהערות כדי לצרף מטא-נתונים לא מזהים לסודות, לוחצים על + הוספת הערה.

  5. לוחצים על יצירת סוד.

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 (גישה לסודות ב-Secret Manager).

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

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

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

# 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_embedding_model_config=embedding_model_config,
        rag_vector_db_config=types.RagVectorDbConfig(
            weaviate=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=...
# ...

שימוש בקובץ 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. מידע נוסף מופיע ב מאמרי העזרה של Python API. 


import agentplatform

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

# Initialize Agent Platform client once per session
client = agentplatform.Client(project=PROJECT_ID, location="us-east4")

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-central1/ragCorpora/1234567890/ragFiles/09876543',
#  display_name='file_display_name')

ייבוא קבצים של RAG

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

REST

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

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

  • 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 Engine קורא למודל ההטמעה במהלך תהליך יצירת האינדקס 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 Engine במהלך 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. מידע נוסף מופיע ב מאמרי העזרה של Python API. 


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-central1/ragCorpora/{rag_corpus_id}"

# Supports Google Cloud Storage and Google Drive Links
# paths = ["https://drive.google.com/file/d/123", "gs://my_bucket/my_files_dir/*"]

# Initialize Agent Platform client once per session
client = agentplatform.Client(project=PROJECT_ID, location="us-central1")

response = client.rag.import_files(
    name=corpus_name,
    import_config=types.ImportRagFilesConfig(
        gcs_source=genai_types.GcsSource(uris=[paths[1]]),
        google_drive_source=types.GoogleDriveSource(
            resource_ids=[
                types.GoogleDriveSourceResourceId(
                    resource_id=paths[0],
                    resource_type=types.ResourceType.RESOURCE_TYPE_FILE
                )
            ]
        ), # optional
        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. מידע נוסף מופיע ב מאמרי העזרה של Python API. 


import agentplatform

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

# Initialize Agent Platform client once per session
client = agentplatform.Client(project=PROJECT_ID, location="us-central1")

rag_file = client.rag.get_file(name=file_name)
print(rag_file)
# Example response:
# RagFile(name='projects/1234567890/locations/us-central1/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. מידע נוסף מופיע ב מאמרי העזרה של Python API. 


import agentplatform

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

# Initialize Agent Platform client once per session
client = agentplatform.Client(project=PROJECT_ID, location="us-central1")

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-central1/ragCorpora/111111111111/ragFiles/222222222222
# g_cloud_file.txt
# projects/1234567890/locations/us-central1/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. מידע נוסף מופיע ב מאמרי העזרה של Python API. 


import agentplatform

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

# Initialize Agent Platform client once per session
client = agentplatform.Client(project=PROJECT_ID, location="us-central1")

client.rag.delete_file(name=file_name)
print(f"File {file_name} deleted.")
# Example response:
# Successfully deleted the RagFile.
# File projects/1234567890/locations/us-central1/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. מידע נוסף מופיע ב מאמרי העזרה של Python API. 


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-central1/ragCorpora/[rag_corpus_id]"

# Initialize Agent Platform client once per session
client = agentplatform.Client(project=PROJECT_ID, location="us-east4")

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. מידע נוסף מופיע ב מאמרי העזרה של Python API. 


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-central1/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(enterprise=True, project=PROJECT_ID, location="us-central1")

response = genai_client.models.generate_content(
    model="gemini-2.5-pro",
    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, שמשלב חיפושים סמנטיים וחיפושים לפי מילות מפתח כדי לשפר את הרלוונטיות של תוצאות החיפוש. במהלך אחזור תוצאות החיפוש, שילוב של ציוני דמיון מחיפוש סמנטי (ווקטור צפוף) והתאמה למילות מפתח (ווקטור דליל) יוצר את התוצאות הסופיות המדורגות.

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

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

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. מידע נוסף מופיע ב מאמרי העזרה של Python API. 


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-central1/ragCorpora/[rag_corpus_id]"

# Initialize Agent Platform client once per session
client = agentplatform.Client(project=PROJECT_ID, location="us-east4")

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 ליצירה מעוגנת

זוהי דוגמה לשימוש בחיפוש היברידי ובמנוע RAG ליצירת תוכן מבוסס.

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. מידע נוסף מופיע ב מאמרי העזרה של Python API. 


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-central1/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(enterprise=True, project=PROJECT_ID, location="us-central1")

response = genai_client.models.generate_content(
    model="gemini-2.5-pro",
    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....
#   ...

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