使用 RAG Engine 擷取資料

本頁面說明如何使用支援的資料來源 (例如 Cloud Storage、Google 雲端硬碟、Slack、Jira 或 SharePoint) 擷取資料,以及如何將這些資料與 RAG Engine 搭配使用。ragFiles.import 方法提供這些資料來源的資料連接器。

RAG 支援的資料來源

支援的資料來源如下:

  • 上傳本機檔案:使用 upload_file 上傳單一檔案 (最多 25 MB),這是同步呼叫。
  • Cloud Storage:從 Cloud Storage 匯入檔案。
  • Google 雲端硬碟:從 Google 雲端硬碟匯入目錄。

    必須授予服務帳戶正確的權限才能匯入檔案。否則,系統不會匯入任何檔案,也不會顯示錯誤訊息。如要進一步瞭解檔案大小限制,請參閱「支援的文件類型」。

    如要驗證及授予權限,請按照下列步驟操作:

    1. 前往Google Cloud 專案的「IAM」頁面。
    2. 選取「包含 Google 提供的角色授予項目」。
    3. 搜尋 Agent Platform RAG Data Service Agent 服務帳戶。
    4. 按一下雲端硬碟資料夾上的「共用」,與服務帳戶共用。
    5. 將 Viewer 權限授予 Google 雲端硬碟資料夾或檔案的服務帳戶。您可以在網址中找到 Google 雲端硬碟資源 ID。
  • Slack:使用資料連接器從 Slack 匯入檔案。

  • Jira:使用資料連接器從 Jira 匯入檔案。

資料簡化

如果多次匯入相同檔案,且檔案內容沒有任何變更,系統會略過該檔案,因為檔案已存在。因此,response.skipped_rag_files_count 是指匯入過程中略過的檔案數量。

如果符合下列條件,系統會略過檔案:

  • 檔案已匯入。
  • 檔案未變更。
  • 檔案的分塊設定未變更。

瞭解匯入失敗

為瞭解匯入失敗的原因,本節將說明匯入要求和資料接收器 (匯入資料的目的地) 回應中的中繼資料。

回應中繼資料

您可以使用 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 物件,其中有作業 ID、建立時間戳記、檔案名稱、狀態和檔案 ID。

  • 如果 import_result_sink 是 BigQuery 資料表,則應使用 bq://my-project.my-dataset.my-table 格式。資料表不一定要存在。如果資料表不存在,系統會建立資料表。如果資料表存在,系統會驗證結構定義。第一次提供 BigQuery 匯入結果接收器時,請提供不存在的資料表;否則,您可以重複使用現有資料表。

從 Cloud Storage 或 Google 雲端硬碟匯入檔案

如要將 Cloud Storage 或 Google 雲端硬碟中的檔案匯入語料庫,請按照下列步驟操作:

  1. 建立 RAG 語料庫。詳情請參閱「方法:ragCorpora.create」。

  2. 如要從 Cloud Storage 或 Google 雲端硬碟匯入檔案,請使用 ragFiles.import 方法。

    系統會自動檢查檔案的路徑、檔案名稱和 version_id。version_id 是使用檔案內容計算出的檔案雜湊,可防止檔案重新建立索引。

    如果檔案的檔案名稱和路徑相同,但內容有更新,系統會重新建立索引。

從 Slack 匯入檔案

如要將 Slack 中的檔案匯入語料庫,請按照下列步驟操作:

  1. 建立語料庫,也就是將資料結構化並最佳化,以便搜尋的索引。詳情請參閱「方法:ragCorpora.create」。
  2. 從 Slack 頻道 ID 取得 CHANNEL_ID。
  3. 建立及設定要與 RAG Engine 搭配使用的應用程式。
    1. 在 Slack UI 的「Add features and functionality」(新增功能) 專區中,按一下「Permissions」(權限)。
    2. 新增下列權限:
      • channels:history
      • groups:history
      • im:history
      • mpim:history
    3. 按一下「Install to Workspace」,將應用程式安裝到 Slack 工作區。
  4. 按一下「Copy」(複製) 即可取得 API 權杖,用於驗證身分及授予 API 存取權。
  5. 將 API 權杖新增至 Secret Manager。
  6. 如要查看儲存的密鑰,請將 Secret Manager 密鑰存取者角色授予專案的 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 中的檔案匯入語料庫,請按照下列步驟操作:

  1. 建立語料庫,也就是為資料建立結構並最佳化,以便搜尋的索引。詳情請參閱「方法:ragCorpora.create」。

  2. 如要建立 API 權杖,請登入 Atlassian 網站。

  3. 在要求中,將 SERVER_URI 替換為 {YOUR_ORG_ID}.atlassian.net。

  4. 在要求中,使用 Atlassian 電子郵件做為 EMAIL。

  5. 請在要求中提供 projects 或 customQueries。如要進一步瞭解自訂查詢,請參閱「使用 Jira 查詢語言 (JQL) 進行進階搜尋」。

    匯入 projects 時,projects 會展開為對應的查詢,以取得整個專案。例如,MyProject 會展開為 project = MyProject。

  6. 按一下「Copy」(複製) 即可取得 API 權杖,用於驗證身分及授予 API 存取權。

  7. 將 API 權杖新增至 Secret Manager。

  8. 將 Secret Manager 密鑰存取者角色授予專案的 RAG Engine 服務帳戶。

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 網站中的檔案匯入語料庫,請按照下列步驟操作:

  1. 建立語料庫,也就是將資料結構化並最佳化,以便搜尋的索引。詳情請參閱「方法:ragCorpora.create」。

  2. 建立 Azure 應用程式,以便存取 SharePoint 網站。

    1. 如要建立註冊,請前往「App Registrations」(應用程式註冊)。

      1. 輸入應用程式名稱。

      2. 選擇「Accounts in this organizational directory only」選項。

      3. 確認重新導向 URI 為空白。

    2. 在「Overview」(總覽) 區段中,使用「Application (client) ID」(應用程式 (用戶端) ID) 做為 CLIENT_ID,並使用「Directory (tenant) ID」(目錄 (用戶群) ID) 做為 TENANT_ID。

    3. 在「Manage」(管理) 部分,按照下列步驟更新 API 權限:

      1. 新增 SharePoint Sites.Read.All 權限。

      2. 新增 Microsoft Graph Files.Read.All 和 Browser SiteLists.Read.All 權限。

      3. 請授予管理員同意聲明,讓這些權限變更生效。

    4. 在「Manage」(管理) 部分,執行下列操作:

      1. 使用新的用戶端密鑰更新「Certificates and Secrets」。

      2. 使用 API_KEY_SECRET_VERSION 將密鑰值新增至 Secret Manager。

  3. 將 Secret Manager 密鑰存取者角色授予專案的 RAG Engine 服務帳戶。

  4. 使用 {YOUR_ORG_ID}.sharepoint.com 做為 SHAREPOINT_SITE_NAME。

  5. 您必須在要求中指定 SharePoint 網站的雲端硬碟名稱或雲端硬碟 ID。

  6. 選用:可指定雲端硬碟上的資料夾路徑或資料夾 ID。如未指定資料夾路徑或資料夾 ID,系統會匯入雲端硬碟中的所有資料夾和檔案。

找出網站 ID

  1. 開啟瀏覽器,前往目標 SharePoint 網站網址。
  2. 在該網址結尾附加 /_api/site/id/。

    範例: https://example-sp.sharepoint.com/sites/example-site/_api/site/id/

    頁面會傳回 XML 酬載。請記下 Edm.Guid 後方的字串。這就是網站 ID。

找出雲端硬碟 ID

使用收集到的網站 ID,透過 Microsoft Graph Explorer 或 API 用戶端,發出經過驗證的 GET 要求:

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

取得 SHAREPOINT_DRIVE_ID。這個值會列在 JSON 回應的 id 欄位中。

找出特定資料夾 ID

使用雲端硬碟 ID 列出根目錄的子目錄:

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,
    )

後續步驟