使用 Vertex AI RAG 引擎擷取資料

本頁面說明如何使用支援的資料來源 (例如 Cloud Storage、Google 雲端硬碟、Slack、Jira 或 SharePoint) 執行資料擷取作業,以及如何在 Vertex AI RAG Engine 中使用這些資料。Import RagFiles API 會提供這些資料來源的資料連接器。

RAG 支援的資料來源

系統支援下列資料來源:

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

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

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

    1. 前往Google Cloud 專案的「IAM」頁面
    2. 選取「包含 Google 提供的角色授予項目」
    3. 搜尋 Vertex AI RAG 資料服務代理 服務帳戶。
    4. 按一下雲端硬碟資料夾中的「共用」,然後與服務帳戶共用。
    5. Viewer 權限授予 Google 雲端硬碟資料夾或檔案的服務帳戶。您可以在網頁版網址中找到 Google 雲端硬碟資源 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_idversion_id 是使用檔案內容計算而得的檔案雜湊,可防止檔案重新索引。

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

從 Slack 匯入檔案

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

  1. 建立字體庫,這是用於建構及最佳化資料以利搜尋的索引。請按照「建立 RAG 語料庫」中的操作說明進行。
  2. 從 Slack 頻道 ID 取得 CHANNEL_ID
  3. 建立並設定要搭配 Vertex AI RAG Engine 使用的應用程式。
    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,請將 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
  • CHANNEL1CHANNEL2
    # 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. 請在要求中提供 projectscustomQueries。如要進一步瞭解自訂查詢,請參閱「使用 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. 選擇「僅限這個機構目錄中的帳戶」
      3. 確認重新導向 URI 為空白。
    2. 在「總覽」部分,請使用應用程式 (用戶端) ID 做為 CLIENT_ID,並使用「目錄 (租用戶) ID」做為 TENANT_ID
    3. 在「管理」部分中,按照下列步驟更新 API 權限:
      1. 新增 SharePoint Sites.Read.All 權限。
      2. 新增 Microsoft Graph Files.Read.AllBrowser 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,
    )

後續步驟