‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

שימוש בהעברת נתונים עם RAG Engine

בדף הזה מוסבר איך לבצע הטמעה של נתונים באמצעות מקור נתונים נתמך, כמו Cloud Storage,‏ Google Drive,‏ Slack,‏ Jira או SharePoint, ואיך להשתמש בנתונים האלה עם RAG Engine. השיטה ragFiles.import מספקת מחברים לנתונים ממקורות הנתונים האלה.

מקורות נתונים שנתמכים ב-RAG

מקורות הנתונים הנתמכים:

העלאת קובץ מקומי: העלאה של קובץ יחיד באמצעות upload_file (עד 25MB), שהיא קריאה סינכרונית.
‫Cloud Storage: ייבוא קבצים מ-Cloud Storage.
Google Drive: ייבוא של ספרייה מ-Google Drive.

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

כדי לאמת ולהעניק הרשאות, מבצעים את הפעולות הבאות:
1. עוברים אל דף IAM של פרויקטGoogle Cloud .
2. בוחרים באפשרות Include Google-provided role grant.
3. מחפשים את חשבון השירות Agent Platform RAG Data Service Agent.
4. לוחצים על שיתוף בתיקייה ב-Drive ומשתפים אותה עם חשבון השירות.
5. נותנים לחשבון השירות Viewer הרשאה לגשת לתיקייה או לקובץ ב-Google Drive. אפשר למצוא את מזהה המשאב של Google Drive בכתובת ה-URL באינטרנט.
‫Slack: ייבוא קבצים מ-Slack באמצעות מחבר נתונים.
‫Jira: ייבוא קבצים מ-Jira באמצעות מחבר נתונים.

ביטול כפילויות בנתונים

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

קובץ יידלג אם התנאים הבאים יתקיימו:

הקובץ יובא.
הקובץ לא השתנה.
ההגדרה של חלוקת הקובץ לחלקים לא השתנתה.

הסבר על כשלים בייבוא

כדי להבין את הכשלים בייבוא, בקטע הזה מוסבר על המטא-נתונים בתגובה לבקשת ייבוא ועל data sink, שהוא היעד של הנתונים שאתם מייבאים.

מטא-נתונים של התשובה

אפשר להשתמש ב-response.metadata (אובייקט תגובה ב-SDK) כדי לראות את תוצאות הייבוא, את זמן הבקשה ואת זמן התגובה.

יעד לייבוא תוצאות

ב-SDK, ‏ import_result_sink הוא פרמטר אופציונלי של פונקציה שאפשר להגדיר לו ערך מחרוזת תקין.

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

הערך של import_result_sink חייב להיות נתיב ב-Cloud Storage או טבלה ב-BigQuery.

אם import_result_sink הוא נתיב של Cloud Storage, הוא צריך להיות בפורמט gs://my-bucket/my/object.ndjson, והאובייקט לא יכול להיות קיים. אחרי שמשימת הייבוא מסתיימת, כל שורה באובייקט Cloud Storage מכילה אובייקט JSON, שכולל מזהה פעולה, חותמת זמן של יצירה, שם קובץ, סטטוס ומזהה קובץ.
אם import_result_sink היא טבלה ב-BigQuery, צריך להשתמש בפורמט bq://my-project.my-dataset.my-table. הטבלה לא חייבת להיות קיימת. אם הטבלה לא קיימת, היא נוצרת. אם הטבלה קיימת, הסכימה מאומתת. בפעם הראשונה שמספקים את יעד התוצאות של הייבוא מ-BigQuery, צריך לספק טבלה שלא קיימת. אחרת, אפשר לעשות שימוש חוזר בטבלה הקיימת.

ייבוא קבצים מ-Cloud Storage או מ-Google Drive

כדי לייבא קבצים מ-Cloud Storage או מ-Google Drive אל מאגר המידע, צריך לבצע את הפעולות הבאות:

יוצרים מאגר מידע של RAG. מידע נוסף זמין במאמר בנושא Method: ragCorpora.create.
כדי לייבא קבצים מ-Cloud Storage או מ-Google Drive, משתמשים בשיטה ragFiles.import.

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

אם קובץ עם אותו שם ועם אותה נתיב כולל עדכון תוכן, הקובץ עובר אינדוקס מחדש.

ייבוא קבצים מ-Slack

כדי לייבא קבצים מ-Slack למאגר המידע, מבצעים את הפעולות הבאות:

יוצרים קובץ חיפוש, שהוא אינדקס שמבנה ומייעל את הנתונים לחיפוש. מידע נוסף זמין במאמר בנושא Method: ragCorpora.create.
מקבלים את CHANNEL_ID ממזהה הערוץ ב-Slack.
יוצרים ומגדירים אפליקציה לשימוש עם RAG Engine.
1. בממשק המשתמש של Slack, בקטע Add features and functionality (הוספת תכונות ופונקציות), לוחצים על Permissions (הרשאות).
2. מוסיפים את ההרשאות הבאות:
  - channels:history
  - groups:history
  - im:history
  - mpim:history
3. לוחצים על Install to Workspace (התקנה בסביבת העבודה) כדי להתקין את האפליקציה בסביבת העבודה של Slack.
לוחצים על העתקה כדי לקבל את טוקן ה-API, שמאמת את הזהות שלכם ומעניק לכם גישה ל-API.
מוסיפים את טוקן ה-API ל-Secret Manager.
כדי להציג את הסוד שמאוחסן, צריך להקצות לחשבון השירות של RAG Engine בפרויקט את התפקיד Secret Manager Secret Accessor.

בדוגמאות הקוד הבאות של curl ו-Python אפשר לראות איך לייבא קבצים מהמשאבים שלכם ב-Slack.

curl

אם רוצים לקבל הודעות מערוץ ספציפי, משנים את CHANNEL_ID.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT/v1beta1/projects/PROJECT_ID/locations/REGION/ragCorpora/RAG_CORPUS_ID/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "slack_source": {
      "channels": [
        {
          "apiKeyConfig": {
            "apiKeySecretVersion": "API_KEY_SECRET_VERSION"
          },
          "channels": [
            {
              "channel_id": "CHANNEL_ID"
            }
          ]
        }
      ]
    }
  }
}'

Python

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

START_TIME
END_TIME
CHANNEL1 או CHANNEL2

    # Slack example
    start_time = protobuf.timestamp_pb2.Timestamp()
    start_time.GetCurrentTime()
    end_time = protobuf.timestamp_pb2.Timestamp()
    end_time.GetCurrentTime()
    source = rag.SlackChannelsSource(
        channels = [
            SlackChannel("CHANNEL1", "api_key1"),
            SlackChannel("CHANNEL2", "api_key2", START_TIME, END_TIME)
        ],
    )

    response = rag.import_files(
        corpus_name=(
            "projects/PROJECT_ID/locations/"
            "REGION/ragCorpora/RAG_CORPUS_ID"
        ),
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

ייבוא קבצים מ-Jira

כדי לייבא קבצים מ-Jira אל המאגר, מבצעים את הפעולות הבאות:

יוצרים קובץ חיפוש, שהוא אינדקס שמבנה ומייעל את הנתונים לחיפוש. מידע נוסף זמין במאמר בנושא Method: ragCorpora.create.
כדי ליצור אסימון API, נכנסים לאתר Atlassian.
משתמשים ב-{YOUR_ORG_ID}.atlassian.net בתור SERVER_URI בבקשה.
משתמשים בכתובת האימייל שלכם ב-Atlassian כEMAIL בבקשה.
מצרפים לבקשה את projects או את customQueries. מידע נוסף על שאילתות מותאמות אישית זמין במאמר שימוש בחיפוש מתקדם עם שפת השאילתות של Jira‏ (JQL).

כשמייבאים את projects, הוא מורחב לשאילתות התואמות כדי לקבל את כל הפרויקט.projects לדוגמה, MyProject יורחב ל-project = MyProject.
לוחצים על העתקה כדי לקבל את טוקן ה-API, שמאמת את הזהות שלכם ומעניק לכם גישה ל-API.
מוסיפים את טוקן ה-API ל-Secret Manager.
מקצים את התפקיד Secret Manager Secret Accessor לחשבון השירות של מנוע ה-RAG בפרויקט.

curl

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT/v1beta1/projects/PROJECT_ID/locations/REGION/ragCorpora/RAG_CORPUS_ID/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "jiraSource": {
      "jiraQueries": [{
        "projects": ["JIRA_PROJECT"],
        "customQueries": ["CUSTOM_QUERY"],
        "email": "EMAIL",
        "serverUri": "SERVER_URI",
        "apiKeyConfig": {
          "apiKeySecretVersion": "API_KEY_SECRET_VERSION"
        }
      }]
    }
  }
}'

Python

    # Jira Example
    jira_query = rag.JiraQuery(
        email="EMAIL",
        jira_projects=["JIRA_PROJECT"],
        custom_queries=["CUSTOM_QUERY"],
        api_key="API_KEY_SECRET_VERSION",
        server_uri="SERVER_URI"
    )
    source = rag.JiraSource(
        queries=[jira_query],
    )

    response = rag.import_files(
        corpus_name=(
            "projects/PROJECT_ID/locations/"
            "REGION/ragCorpora/RAG_CORPUS_ID"
        ),
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

ייבוא קבצים מ-SharePoint

כדי לייבא קבצים מאתר SharePoint למאגר המידע:

יוצרים קובץ חיפוש, שהוא אינדקס שמבנה ומייעל את הנתונים לחיפוש. מידע נוסף זמין במאמר בנושא Method: ragCorpora.create.
יוצרים אפליקציית Azure כדי לגשת לאתר SharePoint.
1. כדי ליצור רישום, עוברים אל App Registrations.
  1. מזינים שם לאפליקציה.
  2. בוחרים באפשרות חשבונות רק בספרייה הארגונית הזו.
  3. מוודאים שמזהי ה-URI להפניה אוטומטית ריקים.
2. בקטע Overview (סקירה כללית), משתמשים במזהה האפליקציה (הלקוח) בתור CLIENT_ID, ובמזהה הספריה (הדייר) בתור TENANT_ID.
3. בקטע ניהול, מעדכנים את הרשאות ה-API באופן הבא:
  1. מוסיפים את ההרשאה Sites.Read.All של SharePoint.
  2. מוסיפים את ההרשאות Files.Read.All ו-Browser SiteLists.Read.All של Microsoft Graph.
  3. צריך לתת הסכמה של אדמין כדי שהשינויים בהרשאות ייכנסו לתוקף.
4. בקטע Manage (ניהול), מבצעים את הפעולות הבאות:
  1. מעדכנים את Certificates and Secrets עם סוד לקוח חדש.
  2. משתמשים ב-API_KEY_SECRET_VERSION כדי להוסיף את ערך הסוד ל-Secret Manager.
מקצים את התפקיד Secret Manager Secret Accessor לחשבון השירות של מנוע ה-RAG בפרויקט.
משתמשים ב-{YOUR_ORG_ID}.sharepoint.com בתור SHAREPOINT_SITE_NAME.
צריך לציין בבקשה שם או מזהה של כונן באתר SharePoint.
אופציונלי: אפשר לציין נתיב של תיקייה או מזהה של תיקייה בכונן. אם לא מציינים את נתיב התיקייה או את מזהה התיקייה, כל התיקיות והקבצים בכונן מיובאים.

איתור מזהה האתר

פותחים את הדפדפן ועוברים לכתובת ה-URL של אתר SharePoint שאליו רוצים להגיע.
מוסיפים את התו /_api/site/id/ בסוף כתובת ה-URL.

דוגמה: https://example-sp.sharepoint.com/sites/example-site/_api/site/id/

הדף מחזיר מטען ייעודי (payload) בפורמט XML. שימו לב למחרוזת אחרי Edm.Guid. זהו מזהה האתר שלכם.

איתור המזהה של Drive

בעזרת מזהה האתר שאספתם, שולחים בקשת GET מאומתת באמצעות Microsoft Graph Explorer או לקוח ה-API שלכם:

GET https://graph.microsoft.com/v1.0/sites/SITE_ID/drive

מקבלים את SHAREPOINT_DRIVE_ID. הערך מופיע בשדה id בתגובת ה-JSON.

איתור מזהה תיקייה ספציפי

כדי לראות רשימה של הפריטים שמוכלים בספריית הבסיס, משתמשים במזהה של Drive:

GET https://graph.microsoft.com/v1.0/drives/SHAREPOINT_DRIVE_ID/root/children

מחפשים את האובייקט שתואם לשם התיקייה שבחרתם בתגובת ה-JSON ומעתיקים את המחרוזת id המתאימה. זה ה-SHAREPOINT_FOLDER_ID שלך.

curl

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT/v1beta1/projects/PROJECT_ID/locations/REGION/ragCorpora/RAG_CORPUS_ID/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "sharePointSources": {
      "sharePointSource": [{
        "clientId": "CLIENT_ID",
        "apiKeyConfig": {
          "apiKeySecretVersion": "API_KEY_SECRET_VERSION"
        },
        "tenantId": "SHAREPOINT_TENANT_ID",
        "sharepointSiteName": "SHAREPOINT_SITE_NAME",
        "sharepointFolderId": "SHAREPOINT_FOLDER_ID",
        "driveId": "SHAREPOINT_DRIVE_ID"
      }]
    }
  }
}'

Python

    from vertexai.preview import rag
    from vertexai.preview.rag.utils import resources
    import vertexai

    vertexai.init(
        project="PROJECT_ID",
        location="REGION",
    )

    # SharePoint Example.
    source = resources.SharePointSources(
        share_point_sources=[
            resources.SharePointSource(
                client_id="CLIENT_ID",
                client_secret="API_KEY_SECRET_VERSION",
                tenant_id="SHAREPOINT_TENANT_ID",
                sharepoint_site_name="SHAREPOINT_SITE_NAME",
                sharepoint_folder_id="SHAREPOINT_FOLDER_ID",
                drive_id="SHAREPOINT_DRIVE_ID",
            )
        ]
    )

    response = rag.import_files(
        corpus_name=(
            "projects/PROJECT_ID/locations/"
            "REGION/ragCorpora/RAG_CORPUS_ID"
        ),
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

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

אפשרויות של מסדי נתונים וקטוריים ב-RAG Engine ב-Gemini Enterprise Agent Platform

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

מקורות נתונים שנתמכים ב-RAG

ביטול כפילויות בנתונים

הסבר על כשלים בייבוא

מטא-נתונים של התשובה

יעד לייבוא תוצאות

ייבוא קבצים מ-Cloud Storage או מ-Google Drive

ייבוא קבצים מ-Slack

curl

Python

ייבוא קבצים מ-Jira

curl

Python

ייבוא קבצים מ-SharePoint

איתור מזהה האתר

איתור המזהה של Drive

איתור מזהה תיקייה ספציפי

curl

Python

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

שימוש בהעברת נתונים עם RAG Engine