‫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, משתמשים ב-method‏ ragFiles.import.

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

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

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

דוגמאות הקוד הבאות ב-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. מידע נוסף על שאילתות בהתאמה אישית זמין במאמר Use advanced search with Jira Query Language (JQL)‎.

כשמייבאים את projects, הערך projects מורחב לשאילתות המתאימות כדי לקבל את כל הפרויקט. לדוגמה, MyProject מורחב ל-project = MyProject.
לוחצים על העתקה כדי לקבל את טוקן ה-API, שמאמת את הזהות שלכם ומעניק לכם גישה ל-API.
מוסיפים את אסימון ה-API ל-Secret Manager.
מקצים את התפקיד גישה לסודות ב-Secret Manager לחשבון השירות של מנוע ה-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, משתמשים ב-Application (client) ID בתור CLIENT_ID, וב-Directory (tenant) ID בתור TENANT_ID.
3. בקטע Manage, מעדכנים את הרשאות ה-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 לחשבון השירות של מנוע ה-RAG בפרויקט.
משתמשים ב-{YOUR_ORG_ID}.sharepoint.com בתור SHAREPOINT_SITE_NAME.
בבקשה צריך לציין שם או מזהה של אחסון באתר SharePoint.
אופציונלי: אפשר לציין נתיב של תיקייה או מזהה תיקייה ב-Drive. אם לא מציינים את נתיב התיקייה או את מזהה התיקייה, כל התיקיות והקבצים באחסון מיובאים.

מאתרים את מזהה האתר

פותחים את הדפדפן ועוברים לכתובת ה-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