本頁面說明如何使用支援的資料來源 (例如 Cloud Storage、Google 雲端硬碟、Slack、Jira 或 SharePoint) 執行資料擷取作業,以及如何在 Vertex AI RAG Engine 中使用這些資料。Import RagFiles API 會提供這些資料來源的資料連接器。
RAG 支援的資料來源
系統支援下列資料來源:
- 上傳本機檔案:使用
upload_file
上傳單一檔案 (大小上限為 25 MB),這是同步呼叫。 - Cloud Storage:從 Cloud Storage 匯入檔案。
Google 雲端硬碟:從 Google 雲端硬碟匯入目錄。
必須授予服務帳戶正確的權限才能匯入檔案。否則,系統不會匯入任何檔案,也不會顯示錯誤訊息。如要進一步瞭解檔案大小限制,請參閱「支援的文件類型」。
如要驗證並授予權限,請按照下列步驟操作:
- 前往Google Cloud 專案的「IAM」頁面。
- 選取「包含 Google 提供的角色授予項目」。
- 搜尋 Vertex AI RAG 資料服務代理 服務帳戶。
- 按一下雲端硬碟資料夾中的「共用」,然後與服務帳戶共用。
- 將
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 雲端硬碟中的檔案匯入語料庫,請按照下列步驟操作:
按照「建立 RAG 語料庫」一文中的操作說明建立語料庫。
如要從 Cloud Storage 或 Google 雲端硬碟匯入檔案,請使用範本。
系統會自動檢查檔案路徑、檔案名稱和
version_id
。version_id
是使用檔案內容計算而得的檔案雜湊,可防止檔案重新索引。如果檔案名稱和路徑相同,且內容有更新,系統會重新建立索引。
從 Slack 匯入檔案
如要將 Slack 中的檔案匯入語料庫,請按照下列步驟操作:
- 建立字體庫,這是用於建構及最佳化資料以利搜尋的索引。請按照「建立 RAG 語料庫」中的操作說明進行。
- 從 Slack 頻道 ID 取得
CHANNEL_ID
。 - 建立並設定要搭配 Vertex AI RAG Engine 使用的應用程式。
- 在 Slack UI 的「Add features and functionality」部分中,按一下「Permissions」。
- 新增下列權限:
channels:history
groups:history
im:history
mpim:history
- 按一下「安裝至工作區」,將應用程式安裝到 Slack 工作區。
- 按一下「複製」即可取得 API 權杖,這項資訊可驗證您的身分,並授予您存取 API 的權限。
- 將 API 權杖新增至 Secret Manager。
- 如要查看已儲存的 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
- 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 匯入至語料庫,請按照下列步驟操作:
- 建立字體庫,這是用於建構及最佳化資料以利搜尋的索引。請按照「建立 RAG 語料庫」中的操作說明進行。
- 如要建立 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 密鑰存取者角色授予專案的 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 網站中的檔案匯入語料庫,請按照下列步驟操作:
- 建立字體庫,這是用於建構及最佳化資料以利搜尋的索引。請按照「建立 RAG 語料庫」中的操作說明進行操作。
- 建立 Azure 應用程式,以便存取 SharePoint 網站。
- 如要建立註冊,請前往「應用程式註冊」。
- 提供應用程式名稱。
- 選擇「僅限這個機構目錄中的帳戶」。
- 確認重新導向 URI 為空白。
- 在「總覽」部分,請使用應用程式 (用戶端) ID 做為 CLIENT_ID,並使用「目錄 (租用戶) ID」做為 TENANT_ID。
- 在「管理」部分中,按照下列步驟更新 API 權限:
- 新增 SharePoint
Sites.Read.All
權限。 - 新增 Microsoft Graph
Files.Read.All
和Browser SiteLists.Read.All
權限。 - 授予管理員同意權,讓這些權限變更生效。
- 新增 SharePoint
- 在「管理」部分執行下列操作:
- 使用新的用戶端密碼更新憑證和密鑰。
- 使用 API_KEY_SECRET_VERSION 將密鑰值新增至 Secret Manager。
- 如要建立註冊,請前往「應用程式註冊」。
- 將 Secret Manager 密鑰存取者角色授予專案的 Vertex AI RAG Engine 服務帳戶。
- 使用 {YOUR_ORG_ID}.sharepoint.com 做為 SHAREPOINT_SITE_NAME。
- 請務必在要求中指定 SharePoint 網站中的雲端硬碟名稱或雲端硬碟 ID。
- 選用:您可以指定磁碟機上的資料夾路徑或資料夾 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,
)