使用 Vertex AI RAG 引擎擷取資料

本頁面說明如何使用支援的資料來源 (例如 Cloud Storage、Google 雲端硬碟、Slack、Jira 或 SharePoint) 擷取資料，以及如何將這些資料用於 Vertex AI RAG 引擎。Import RagFiles API 提供這些資料來源的資料連接器。

支援 RAG 的資料來源

支援的資料來源如下：

  • 上傳本機檔案：使用 upload_file 上傳單一檔案 (大小上限為 25 MB)，這是同步呼叫。
  • Cloud Storage：從 Cloud Storage 匯入檔案。

  • Google 雲端硬碟：從 Google 雲端硬碟匯入目錄。

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

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

    1. 前往專案的「IAM」頁面。Google Cloud
    2. 選取「包含 Google 提供的角色授權」。
    3. 搜尋 Vertex AI RAG 資料服務代理服務帳戶。
    4. 按一下雲端硬碟資料夾的「共用」，然後與服務帳戶共用。
    5. 將 Google 雲端硬碟資料夾或檔案的權限授予服務帳戶。ViewerGoogle 雲端硬碟資源 ID 位於網頁網址中。

  • Slack： 使用資料連接器從 Slack 匯入檔案。

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

詳情請參閱 RAG API 參考資料。

資料重複刪除

如果多次匯入相同檔案，且檔案內容沒有變更，系統會略過匯入作業，因為檔案已存在。因此，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 語料庫」一文中的操作說明建立語料庫。

  2. 如要從 Cloud Storage 或 Google 雲端硬碟匯入檔案，請使用範本。

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

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

從 Slack 匯入檔案

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

  1. 建立索引，也就是建立索引來建構及最佳化資料，以利搜尋。請按照「建立 RAG 語料庫」的指示操作。
  2. 從 Slack 頻道 ID 取得 CHANNEL_ID。
  3. 建立及設定應用程式，以便搭配 Vertex AI RAG 引擎使用。
    1. 在 Slack UI 的「Add features and functionality」(新增功能) 部分，按一下「Permissions」(權限)。
    2. 新增下列權限：
      • channels:history
      • groups:history
      • im:history
      • mpim:history
    3. 按一下「安裝至工作區」，將應用程式安裝至 Slack 工作區。
  4. 按一下「複製」即可取得 API 權杖，驗證身分並授權存取 API。
  5. 將 API 權杖新增至 Secret Manager。
  6. 如要查看儲存的密鑰，請將 Secret Manager 密鑰存取者角色授予專案的 Vertex AI RAG Engine 服務帳戶。

下列 curl 和 Python 程式碼範例示範如何從 Slack 資源匯入檔案。

curl

如要接收特定管道的訊息，請變更 CHANNEL_ID。

API_KEY_SECRET_VERSION=SLACK_API_KEY_SECRET_VERSION
CHANNEL_ID=SLACK_CHANNEL_ID
PROJECT_ID=us-central1

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ ENDPOINT }/v1beta1/projects/${ PROJECT_ID }/locations/${ PROJECT_ID }/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/my-project/locations/us-central1/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

從 Jira 匯入檔案

如要將 Jira 中的檔案匯入語料庫，請按照下列步驟操作：

  1. 建立索引，也就是建立索引來建構及最佳化資料，以利搜尋。請按照「建立 RAG 語料庫」的指示操作。
  2. 如要建立 API 權杖，請登入 Atlassian 網站。
  3. 在要求中，使用 {YOUR_ORG_ID}.atlassian.net 做為 SERVER_URI。
  4. 在要求中，將 Atlassian 電子郵件地址做為 EMAIL。
  5. 在要求中提供 projects 或 customQueries。如要進一步瞭解自訂查詢，請參閱「使用 Jira 查詢語言 (JQL) 進行進階搜尋」。

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

  6. 按一下「複製」即可取得 API 權杖，驗證身分並授權存取 API。
  7. 將 API 權杖新增至 Secret Manager。
  8. 將Secret Manager 密鑰存取者角色授予專案的 Vertex AI RAG Engine 服務帳戶。

curl

EMAIL=JIRA_EMAIL
API_KEY_SECRET_VERSION=JIRA_API_KEY_SECRET_VERSION
SERVER_URI=JIRA_SERVER_URI
CUSTOM_QUERY=JIRA_CUSTOM_QUERY
PROJECT_ID=JIRA_PROJECT
REGION= "us-central1"

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": ["'"${ PROJECT_ID }"'"],
        "customQueries": ["'"${ CUSTOM_QUERY }"'"],
        "email": "'"${ EMAIL }"'",
        "serverUri": "'"${ SERVER_URI }"'",
        "apiKeyConfig": {
          "apiKeySecretVersion": "'"${ API_KEY_SECRET_VERSION }"'"
        }
      }]
    }
  }
}'

Python

    # Jira Example
    jira_query = rag.JiraQuery(
        email="xxx@yyy.com",
        jira_projects=["project1", "project2"],
        custom_queries=["query1", "query2"],
        api_key="api_key",
        server_uri="server.atlassian.net"
    )
    source = rag.JiraSource(
        queries=[jira_query],
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/REGION/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

從 SharePoint 匯入檔案

如要將 SharePoint 網站中的檔案匯入語料庫，請按照下列步驟操作：

  1. 建立索引，也就是建立索引來建構及最佳化資料，以利搜尋。請按照「建立 RAG 語料庫」的指示操作。
  2. 建立 Azure 應用程式，存取 SharePoint 網站。
    1. 如要建立註冊，請前往「應用程式註冊」。
      1. 提供應用程式名稱。
      2. 選擇「Accounts in this organizational directory only」選項。
      3. 確認重新導向 URI 為空。
    2. 在「總覽」部分，使用「應用程式 (用戶端) ID」做為 CLIENT_ID，並使用「目錄 (租戶) ID」做為 TENANT_ID。
    3. 在「管理」部分中，執行下列操作來更新 API 權限：
      1. 新增 SharePoint Sites.Read.All 權限。
      2. 新增 Microsoft Graph Files.Read.All 和 Browser SiteLists.Read.All 權限。
      3. 授予管理員同意，讓這些權限變更生效。
    4. 在「管理」部分執行下列操作：
      1. 使用新的用戶端密碼更新「憑證和密鑰」。
      2. 使用 API_KEY_SECRET_VERSION 將密鑰值新增至 Secret Manager。
  3. 將Secret Manager 密鑰存取者角色授予專案的 Vertex AI RAG Engine 服務帳戶。
  4. 使用 {YOUR_ORG_ID}.sharepoint.com 做為 SHAREPOINT_SITE_NAME。
  5. 要求中必須指定 SharePoint 網站中的雲端硬碟名稱或雲端硬碟 ID。
  6. 選用：可以指定雲端硬碟上的資料夾路徑或資料夾 ID。如未指定資料夾路徑或資料夾 ID，系統會匯入雲端硬碟中的所有資料夾和檔案。

curl

CLIENT_ID=SHAREPOINT_CLIENT_ID
API_KEY_SECRET_VERSION=SHAREPOINT_API_KEY_SECRET_VERSION
TENANT_ID=SHAREPOINT_TENANT_ID
SITE_NAME=SHAREPOINT_SITE_NAME
FOLDER_PATH=SHAREPOINT_FOLDER_PATH
DRIVE_NAME=SHAREPOINT_DRIVE_NAME

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": "'"${ TENANT_ID }"'",
        "sharepointSiteName": "'"${ SITE_NAME }"'",
        "sharepointFolderPath": "'"${ FOLDER_PATH }"'",
        "driveName": "'"${ DRIVE_NAME }"'"
      }]
    }
  }
}'

Python

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

    CLIENT_ID="SHAREPOINT_CLIENT_ID"
    API_KEY_SECRET_VERSION="SHAREPOINT_API_KEY_SECRET_VERSION"
    TENANT_ID="SHAREPOINT_TENANT_ID"
    SITE_NAME="SHAREPOINT_SITE_NAME"
    FOLDER_PATH="SHAREPOINT_FOLDER_PATH"
    DRIVE_NAME="SHAREPOINT_DRIVE_NAME"

    # SharePoint Example.
    source = resources.SharePointSources(
        share_point_sources=[
            resources.SharePointSource(
                client_id=CLIENT_ID,
                client_secret=API_KEY_SECRET_VERSION,
                tenant_id=TENANT_ID,
                sharepoint_site_name=SITE_NAME,
                folder_path=FOLDER_PATH,
                drive_id=DRIVE_ID,
            )
        ]
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/REGION/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

後續步驟