本指南提供 RAG 引擎的 API 參考資料。涵蓋下列主題： Vertex AI RAG 引擎是 Vertex AI 平台的一項元件，可協助您進行檢索增強生成 (RAG)。RAG 引擎可讓大型語言模型 (LLM) 存取並整合外部知識來源的資料，例如文件和資料庫。使用 RAG 後，LLM 就能生成更準確且實用的回覆。 如要瞭解 RAG 語料庫，請參閱「語料庫管理」。 建立 RAG 語料庫 下表列出用於建立 RAG 語料庫的參數。 要求主體
選用，不可變動。 用於指定語料庫類型的設定。 必要。 RAG 語料庫的顯示名稱。 選填。 RAG 語料庫的說明。 選用，不可變動。 用於加密與 RAG 語料庫相關靜態資料的 CMEK 金鑰名稱。這個鍵名僅適用於向量資料庫的 格式： 選用，不可變動。 向量資料庫的設定。 選填。 Vertex AI Search 的設定。 格式：
參數清單
語料庫管理參數
參數
說明
corpus_type_config
RagCorpus.CorpusTypeConfig
display_name
string
description
string
encryption_spec
stringRagManaged 選項。您可以在建立語料庫時設定這個欄位，但之後無法更新或刪除。projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}
vector_db_config
RagVectorDbConfig
vertex_ai_search_config.serving_config
stringprojects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}
或
projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/servingConfigs/{serving_config}
CorpusTypeConfig
| 參數 | 說明 |
|---|---|
|
|
|
如果設定這個類型，RAG 語料庫就是 詳情請參閱「將 Vertex AI RAG 引擎做為記憶體儲存空間」。 |
|
用於剖析及儲存 Gemini Live API 工作階段背景資訊的 LLM 剖析器。您可以建構記憶體以建立索引。 |
RagVectorDbConfig
建立 RAG 語料庫時，可以選擇多種向量資料庫。下表提供比較資訊，協助您為用途選取最佳選項。
| 向量資料庫選項 | 說明 | 用途 |
|---|---|---|
rag_managed_db |
Google 提供的全代管向量資料庫。 | 適合想要整合式解決方案，但不想管理自家資料庫基礎架構的使用者。 |
weaviate |
連線至自行管理的 Weaviate 執行個體。 | 適用於已使用或偏好使用 Weaviate 向量資料庫的使用者。 |
pinecone |
連線至自行管理的 Pinecone 執行個體。 | 適合已使用或偏好使用 Pinecone 向量資料庫的使用者。 |
vertex_feature_store |
使用現有的 Vertex AI 特徵儲存庫執行個體。 | 將 RAG 與 Vertex AI 特徵儲存庫中現有的機器學習特徵和資料整合。 |
vertex_vector_search |
使用現有的 Vector Search 索引。 | 充分運用向量搜尋的進階擴充性和效能，適用於大規模應用程式。 |
如果選擇 rag_managed_db 選項，也必須選取擷取策略。下表比較了可用的策略。
| 擷取策略 | 說明 | 優點 | 缺點 |
|---|---|---|---|
KNN (k 近鄰) |
透過對所有資料點執行詳盡搜尋，找出確切最鄰近的項目。 | 提供最準確且相關的結果。 | 速度可能較慢，且計算成本較高，尤其是在處理大型資料集時。 |
ANN (近似最近鄰) |
找出最接近的鄰點，以部分準確度換取大幅提升的速度。 | 查詢效能大幅提升，延遲時間也縮短。 | 結果為概略值，可能不是最相關的結果。 |
| 參數 | 說明 |
|---|---|
|
如未指定向量資料庫，則預設為 |
|
這是預設的擷取策略。 比較 RAG 語料庫中的所有資料點，找出最鄰近的項目。 如果您在建立 RAG 語料庫時未指定策略，系統會使用 KNN。 |
|
tree_depth 決定樹狀結構中的層數或層級數。
leaf_count 決定樹狀結構中的葉節點數量。
rebuild_ann_index
|
|
指定 Weaviate 執行個體。 |
|
Weaviate 執行個體的 HTTP 端點。 設定後即無法變更值。您可以在 |
|
RAG 語料庫對應的 Weaviate 集合。 設定後即無法變更值。您可以在 |
|
指定 Pinecone 執行個體。 |
|
用於建立 Pinecone 索引的名稱，該索引會與 RAG 語料庫搭配使用。 設定後即無法變更值。您可以在 |
|
指定 Vertex AI 特徵儲存庫執行個體。 |
|
RAG 語料庫對應的 Vertex AI 特徵儲存庫 格式： 設定後即無法變更值。您可以在 |
|
指定 Vector Search 執行個體。 |
|
與 RAG 語料庫搭配使用的 Vector Search 索引資源名稱。 格式： 設定後即無法變更值。您可以在 |
|
與 RAG 語料庫搭配使用的 Vector Search 索引端點資源名稱。 格式： 設定後即無法變更值。您可以在 |
|
這是儲存在 Secret Manager 中的密鑰完整資源名稱，內含 Weaviate 或 Pinecone 向量資料庫的 API 金鑰。 格式： 您可以在 |
|
選用，不可變動。 用於 RAG 語料庫的嵌入模型。設定後即無法變更此值。如果留空，RAG 引擎會使用 text-embedding-005 做為嵌入模型。 |
更新 RAG 語料庫
下表列出用於更新 RAG 語料庫的參數。
要求主體
| 參數 | 說明 |
|---|---|
|
選填。 RAG 語料庫的顯示名稱。 |
|
選填。 RAG 語料庫的說明。 |
|
Weaviate 執行個體的 HTTP 端點。 如果您使用 |
|
RAG 語料庫對應的 Weaviate 集合。 如果您使用 |
|
用於建立 Pinecone 索引的名稱，該索引會與 RAG 語料庫搭配使用。 如果您使用 |
|
RAG 語料庫對應的 Vertex AI 特徵儲存庫 格式： 如果您使用 |
|
與 RAG 語料庫搭配使用的 Vector Search 索引資源名稱。 格式： 如果您使用 |
|
與 RAG 語料庫搭配使用的 Vector Search 索引端點資源名稱。 格式： 如果您使用 |
|
儲存在 Secret Manager 中的密鑰完整資源名稱，內含 Weaviate 或 Pinecone 向量資料庫的 API 金鑰。 格式： |
列出 RAG 語料庫
下表列出用於列出 RAG 語料庫的參數。
| 參數 | 說明 |
|---|---|
|
選填。 標準清單頁面大小。 |
|
選填。 您可透過先前的 |
取得 RAG 語料庫
下表列出用於取得 RAG 語料庫的參數。
| 參數 | 說明 |
|---|---|
|
必要。
|
刪除 RAG 語料庫
下表列出用於刪除 RAG 語料庫的參數。
| 參數 | 說明 |
|---|---|
|
必要。
|
檔案管理參數
如要瞭解 RAG 檔案，請參閱「檔案管理」。
上傳 RAG 檔案
下表列出上傳 RAG 檔案時使用的參數。
要求主體
| 參數 | 說明 |
|---|---|
|
必要。
|
|
必要。 要上傳的檔案。 |
|
必要。 要上傳至 |
RagFile |
說明 |
|---|---|
|
必要。 RAG 檔案的顯示名稱。 |
|
選填。 RAG 檔案的說明。 |
UploadRagFileConfig |
說明 |
|---|---|
|
每個區塊的權杖數量。 |
|
區塊之間要重疊的權杖數量。 |
匯入 RAG 檔案
下表列出匯入 RAG 檔案時使用的參數。
| 參數 | 說明 |
|---|---|
|
必要。
格式： |
|
Cloud Storage 位置。支援匯入個別檔案和整個 Cloud Storage 目錄。 |
|
包含上傳檔案的 Cloud Storage URI。 |
|
Google 雲端硬碟位置。支援匯入個別檔案和 Google 雲端硬碟資料夾。 |
|
上傳檔案的 Slack 頻道。 |
|
上傳檔案的 Jira 查詢。 |
|
上傳檔案的 SharePoint 來源。 |
|
每個區塊的權杖數量。 |
|
區塊之間要重疊的權杖數量。 |
|
選填。 指定 如未設定這個欄位，RAG 會使用預設剖析器。 |
|
選填。 這項工作每分鐘可對嵌入模型發出的查詢數上限 (QPM)。這個值專屬於這項工作，不會與其他匯入工作共用。如要設定適當的值，請參閱專案的「配額」頁面。如未指定值，系統會使用預設值 1,000 QPM。 |
GoogleDriveSource |
說明 |
|---|---|
|
必要。 Google 雲端硬碟資源的 ID。 |
|
必要。 Google 雲端硬碟資源的類型。 |
SlackSource |
說明 |
|---|---|
|
重複。 Slack 頻道資訊，包括要匯入的 ID 和時間範圍。 |
|
必要。 Slack 頻道 ID。 |
|
選填。 要匯入訊息的起始時間戳記。 |
|
選填。 要匯入的訊息結束時間戳記。 |
|
必要。 儲存在 Secret Manager 中的密鑰完整資源名稱，內含可存取指定 Slack 管道 ID 的 Slack 管道存取權杖。 格式： |
JiraSource |
說明 |
|---|---|
|
重複。 要完整匯入的 Jira 專案清單。 |
|
重複。 要匯入的自訂 Jira 查詢清單。如要進一步瞭解 Jira 查詢語言 (JQL)，請參閱 |
|
必要。 Jira 電子郵件地址。 |
|
必要。 Jira 伺服器 URI。 |
|
必要。 儲存在 Secret Manager 中的密鑰完整資源名稱，內含 Jira API 金鑰。 格式： |
SharePointSources |
說明 |
|---|---|
|
在 要從中下載檔案的 SharePoint 資料夾路徑。 |
|
在 要從中下載檔案的 SharePoint 資料夾 ID。 |
|
在 要從中下載檔案的雲端硬碟名稱。 |
|
在 要從中下載檔案的雲端硬碟 ID。 |
|
在 Microsoft Azure 入口網站中註冊的應用程式的應用程式 (用戶端) ID。
|
|
必要。 儲存在 Secret Manager 中的密鑰完整資源名稱， 內含在 Azure 中註冊的應用程式密鑰。 格式： |
|
Azure Active Directory 執行個體的專屬 ID。 |
|
要從中下載檔案的 SharePoint 網站名稱。可以是網站名稱或網站 ID。 |
| 剖析器選項 | 說明 | 用途 |
|---|---|---|
layout_parser |
使用 Document AI 剖析檔案，保留文件的結構和版面配置。 | 最適合結構化或半結構化文件，例如含有表格、欄位和複雜版面的 PDF。 |
llm_parser |
使用大型語言模型 (LLM) 剖析檔案，著重於瞭解內容的語意。 | 適合用於非結構化文字文件，這類文件著重擷取意義和脈絡，而非保留原始視覺版面配置。 |
RagFileParsingConfig |
說明 |
|---|---|
|
用於 |
|
Document AI 處理器或處理器版本的完整資源名稱。 格式：
|
|
作業每分鐘可向 Document AI 處理器提出的要求數上限。 請參閱 https://cloud.google.com/document-ai/quotas 和專案的「配額」頁面，在此設定適當的值。如未指定，系統會使用預設值 120 QPM。 |
|
用於 |
|
LLM 模型的資源名稱。 格式：
|
|
工作每分鐘可向 LLM 模型提出的要求數上限。 如要為專案設定適當的值，請參閱模型配額部分和專案的「配額」頁面，以便在此設定適當的值。如未指定，系統會使用預設值 5000 QPM。 |
取得 RAG 檔案
下表列出用於取得 RAG 檔案的參數。
| 參數 | 說明 |
|---|---|
|
必要。
|
刪除 RAG 檔案
下表列出用於刪除 RAG 檔案的參數。
| 參數 | 說明 |
|---|---|
|
必要。
|
擷取和預測參數
本節列出擷取和預測參數。
擷取參數
下表列出 retrieveContexts 方法的參數。
| 參數 | 說明 |
|---|---|
|
必要。 要擷取 格式： |
|
Vertex RagStore 的資料來源。 |
|
必要。 單一 RAG 擷取查詢。 |
VertexRagStore
VertexRagStore |
說明 |
|---|---|
|
名單： RAG 來源。您可以指定單一語料庫，或從一個語料庫指定多個 |
|
選填。
格式： |
|
名單：
格式： |
RagQuery |
說明 |
|---|---|
|
以文字格式查詢，取得相關背景資訊。 |
|
選填。 查詢的擷取設定。 |
RagRetrievalConfig |
說明 |
|---|---|
|
選填。 要擷取的內容數量。 |
|
選填。 控制稠密和稀疏向量搜尋結果之間的權重。值必須介於 0.0 至 1.0 之間。值為 0.0 表示只進行稀疏向量搜尋，值為 1.0 則表示只進行稠密向量搜尋。預設值為 0.5。 混合搜尋僅適用於 Weaviate。 |
|
只傳回向量距離小於這個閾值的上下文。 |
|
只傳回向量相似度大於這個閾值的上下文。 |
|
選填。 排序服務的型號名稱。 範例： |
|
選填。 用於排名的模型名稱。 範例： |
預測參數
下表列出預測參數。
GenerateContentRequest |
說明 |
|---|---|
|
設定為使用 Vertex AI RAG 商店支援的資料來源。 |
詳情請參閱 VertexRagStore。
專案管理參數
這個表格會列出專案層級的參數。
使用 RagManagedDb 時，您可以選取最符合效能和費用需求的層級。下表比較了可用的層級。
| 級別 | 說明 | 用途 |
|---|---|---|
scaled |
正式環境規模的層級，可自動調度資源，處理高負載和變動的查詢負載。 | 建議用於需要高可用性和效能的正式版應用程式。 |
basic |
經濟實惠的低運算量級別，適合較小規模的需求。 | 適合用於開發、測試，或流量偏低且可預測的應用程式。 |
unprovisioned |
取消佈建代管資料庫及其基礎資源。 | 用於停用代管式資料庫，並停止產生相關費用。 |
RagEngineConfig
| 參數 | 說明 |
|---|---|
RagManagedDbConfig.scaled |
這個層級提供正式環境規模的效能，以及自動調度功能。 |
RagManagedDbConfig.basic |
這個層級的運算資源需求低，且符合成本效益。 |
RagManagedDbConfig.unprovisioned |
這個層級會取消佈建 RagManagedDb 和基礎 Spanner 執行個體。 |
語料庫管理範例
本節提供範例，說明如何使用 API 管理 RAG 語料庫。
建立 RAG 語料庫範例
以下範例說明如何建立 RAG 語料庫。
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的專案 ID。
- LOCATION：處理要求的區域。
- CORPUS_DISPLAY_NAME：
RagCorpus的顯示名稱。 - CORPUS_DESCRIPTION：
RagCorpus的說明。
HTTP 方法和網址：
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora
JSON 要求主體：
{
"display_name" : "CORPUS_DISPLAY_NAME",
"description": "CORPUS_DESCRIPTION",
}
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora"
PowerShell
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora" | Select-Object -Expand Content
更新 RAG 語料庫範例
您可以更新 RAG 語料庫的顯示名稱、說明和部分向量資料庫設定。不過，您無法變更下列不可變更的參數：
- 向量資料庫類型。舉例來說，您無法將向量資料庫從 Weaviate 變更為 Vertex AI 特徵儲存庫。
- 如果您使用受管理資料庫選項，則無法更新向量資料庫設定。
以下範例說明如何更新 RAG 語料庫。
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的專案 ID。
- LOCATION：處理要求的區域。
- CORPUS_ID：RAG 語料庫的語料庫 ID。
- CORPUS_DISPLAY_NAME：
RagCorpus的顯示名稱。 - CORPUS_DESCRIPTION：
RagCorpus的說明。 - INDEX_NAME：
Vector Search Index的資源名稱。格式：projects/{project}/locations/{location}/indexes/{index} - INDEX_ENDPOINT_NAME：
Vector Search Index Endpoint的資源名稱。格式：projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}
HTTP 方法和網址：
PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/CORPUS_ID
JSON 要求主體：
{
"display_name" : "CORPUS_DISPLAY_NAME",
"description": "CORPUS_DESCRIPTION",
"rag_vector_db_config": {
"vertex_vector_search": {
"index": "INDEX_NAME",
"index_endpoint": "INDEX_ENDPOINT_NAME",
}
}
}
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/CORPUS_ID"
PowerShell
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/CORPUS_ID" | Select-Object -Expand Content
列出 RAG 語料庫範例
這個範例說明如何列出專案中的所有 RAG 語料庫。
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的專案 ID。
- LOCATION：處理要求的區域。
- PAGE_SIZE：標準清單頁面大小。如要調整每頁傳回的
RagCorpora數量，請更新page_size參數。 - PAGE_TOKEN：標準清單頁面符記。在先前的
VertexRagDataService.ListRagCorpora呼叫中，從ListRagCorporaResponse.next_page_token取得這個權杖。
HTTP 方法和網址：
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora?page_size=PAGE_SIZE&page_token=PAGE_TOKEN
如要傳送要求，請選擇以下其中一個選項：
curl
執行下列指令：
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"
PowerShell
執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" | Select-Object -Expand Content
RagCorpora 清單。
取得 RAG 語料庫範例
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的專案 ID。
- LOCATION：處理要求的區域。
- RAG_CORPUS_ID：
RagCorpus資源的 ID。
HTTP 方法和網址：
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID
如要傳送要求，請選擇以下其中一個選項：
curl
執行下列指令：
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID"
PowerShell
執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID" | Select-Object -Expand Content
RagCorpus 資源。
刪除 RAG 語料庫範例
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的專案 ID。
- LOCATION：處理要求的區域。
- RAG_CORPUS_ID：
RagCorpus資源的 ID。
HTTP 方法和網址：
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID
如要傳送要求，請選擇以下其中一個選項：
curl
執行下列指令：
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID"
PowerShell
執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID" | Select-Object -Expand Content
DeleteOperationMetadata 資源。
檔案管理範例
本節提供範例，說明如何使用 API 管理 RAG 檔案。
上傳 RAG 檔案範例
REST
執行指令前，請替換下列變數： PROJECT_ID: Your project ID.
LOCATION: The region to process the request.
RAG_CORPUS_ID: The corpus ID of your RAG corpus.
LOCAL_FILE_PATH: The local path to the file to be uploaded.
DISPLAY_NAME: The display name of the RAG file.
DESCRIPTION: The description of the RAG file.
如要傳送要求，請使用下列指令：
curl -X POST \
-H "X-Goog-Upload-Protocol: multipart" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-F metadata="{'rag_file': {'display_name':' DISPLAY_NAME', 'description':'DESCRIPTION'}}" \
-F file=@LOCAL_FILE_PATH \
"https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload"
匯入 RAG 檔案範例
您可以從雲端硬碟或 Cloud Storage 匯入檔案和資料夾。
response.skipped_rag_files_count 是指匯入期間略過的檔案數。如果符合下列條件，系統會略過檔案：
- 檔案已匯入。
- 檔案未變更。
- 檔案的分塊設定未變更。
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的專案 ID。
- LOCATION：處理要求的區域。
- RAG_CORPUS_ID：
RagCorpus資源的 ID。 - GCS_URIS：Cloud Storage 位置清單。範例：
gs://my-bucket1, gs://my-bucket2。 - CHUNK_SIZE：(選用) 各分塊應有的權杖數量。
- CHUNK_OVERLAP：(選用) 區塊之間要重疊的權杖數量。
HTTP 方法和網址：
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import
JSON 要求主體：
{
"import_rag_files_config": {
"gcs_source": {
"uris": "GCS_URIS"
},
"rag_file_chunking_config": {
"chunk_size": CHUNK_SIZE,
"chunk_overlap": CHUNK_OVERLAP
}
}
}
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import"
PowerShell
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import" | Select-Object -Expand Content
ImportRagFilesOperationMetadata 資源。
<下列範例示範如何從 Cloud Storage 匯入檔案。在 ImportRagFiles 索引程序期間，使用 max_embedding_requests_per_min 控制欄位限制 RAG Engine 呼叫嵌入模型的速度。這個欄位的預設值為每分鐘 1000 次呼叫。
PROJECT_ID: Your project ID.
LOCATION: The region to process the request.
RAG_CORPUS_ID: The corpus ID of your RAG corpus.
GCS_URIS: A list of Cloud Storage locations. Example: gs://my-bucket1.
CHUNK_SIZE: Number of tokens each chunk should have.
CHUNK_OVERLAP: Number of tokens overlap between chunks.
EMBEDDING_MODEL_QPM_RATE: The QPM rate to limit RAGs access to your embedding model. Example: 1000.
// ImportRagFiles
// Import a single Cloud Storage file or all files in a Cloud Storage bucket.
// Input: LOCATION, PROJECT_ID, RAG_CORPUS_ID, GCS_URIS
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import \
-d '{
"import_rag_files_config": {
"gcs_source": {
"uris": "GCS_URIS"
},
"rag_file_chunking_config": {
"chunk_size": CHUNK_SIZE,
"chunk_overlap": CHUNK_OVERLAP
},
"max_embedding_requests_per_min": EMBEDDING_MODEL_QPM_RATE
}
}'
// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID: The operation ID you get from the response of the previous command.
poll_op_wait OPERATION_ID
下列範例說明如何從雲端硬碟匯入檔案。在 ImportRagFiles 索引程序期間，使用 max_embedding_requests_per_min 控制欄位限制 RAG 引擎呼叫嵌入模型的速率。這個欄位的預設值為每分鐘 1000 次呼叫。
PROJECT_ID: Your project ID.
LOCATION: The region to process the request.
RAG_CORPUS_ID: The corpus ID of your RAG corpus.
FOLDER_RESOURCE_ID: The resource ID of your Google Drive folder.
CHUNK_SIZE: Number of tokens each chunk should have.
CHUNK_OVERLAP: Number of tokens overlap between chunks.
EMBEDDING_MODEL_QPM_RATE: The QPM rate to limit RAGs access to your embedding model. Example: 1000.
// ImportRagFiles
// Import all files in a Google Drive folder.
// Input: LOCATION, PROJECT_ID, RAG_CORPUS_ID, FOLDER_RESOURCE_ID
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import \
-d '{
"import_rag_files_config": {
"google_drive_source": {
"resource_ids": {
"resource_id": "FOLDER_RESOURCE_ID",
"resource_type": "RESOURCE_TYPE_FOLDER"
}
},
"max_embedding_requests_per_min": EMBEDDING_MODEL_QPM_RATE
}
}'
// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID: The operation ID you get from the response of the previous command.
poll_op_wait OPERATION_ID
列出 RAG 檔案範例
這個範例說明如何列出 RAG 檔案。
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的專案 ID。
- LOCATION：處理要求的區域。
- RAG_CORPUS_ID：
RagCorpus資源的 ID。 - PAGE_SIZE：標準清單頁面大小。如要調整每頁傳回的
RagFiles數量，請更新page_size參數。 - PAGE_TOKEN：標準清單頁面符記。在先前的
VertexRagDataService.ListRagFiles呼叫中，從ListRagFilesResponse.next_page_token取得這個權杖。
HTTP 方法和網址：
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN
如要傳送要求，請選擇以下其中一個選項：
curl
執行下列指令：
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"
PowerShell
執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" | Select-Object -Expand Content
RAG_CORPUS_ID 的 RagFiles 清單。
取得 RAG 檔案範例
這個範例說明如何取得 RAG 檔案。
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的專案 ID。
- LOCATION：處理要求的區域。
- RAG_CORPUS_ID：
RagCorpus資源的 ID。 - RAG_FILE_ID：
RagFile資源的 ID。
HTTP 方法和網址：
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID
如要傳送要求，請選擇以下其中一個選項：
curl
執行下列指令：
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"
PowerShell
執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content
RagFile 資源。
刪除 RAG 檔案範例
這個範例說明如何刪除 RAG 檔案。
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的專案 ID。
- LOCATION：處理要求的區域。
- RAG_CORPUS_ID：
RagCorpus資源的 ID。 - RAG_FILE_ID：
RagFile資源的 ID。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}/ragFiles/{rag_file_id}。
HTTP 方法和網址：
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID
如要傳送要求，請選擇以下其中一個選項：
curl
執行下列指令：
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"
PowerShell
執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content
DeleteOperationMetadata 資源。
擷取和預測範例
擷取查詢範例
當您提供查詢時，RAG 中的檢索元件會搜尋知識庫，找出相關資訊。
REST
使用任何要求資料之前，請先替換以下項目：
- LOCATION：處理要求的區域。
- PROJECT_ID：您的專案 ID。
- RAG_CORPUS_RESOURCE：
RagCorpus資源的名稱。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}。 - VECTOR_DISTANCE_THRESHOLD：只傳回向量距離小於閾值的上下文。
- TEXT：用於取得相關脈絡的查詢文字。
- SIMILARITY_TOP_K：要擷取的重要上下文數量。
HTTP 方法和網址：
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts
JSON 要求主體：
{
"vertex_rag_store": {
"rag_resources": {
"rag_corpus": "RAG_CORPUS_RESOURCE"
},
"vector_distance_threshold": VECTOR_DISTANCE_THRESHOLD
},
"query": {
"text": "TEXT",
"similarity_top_k": SIMILARITY_TOP_K
}
}
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts"
PowerShell
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts" | Select-Object -Expand Content
RagFiles 清單。
生成範例
LLM 會根據檢索到的脈絡資訊，生成有依據的回覆。
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的專案 ID。
- LOCATION：處理要求的區域。
- MODEL_ID：用於生成內容的 LLM 模型。範例：
gemini-2.5-flash - GENERATION_METHOD：用於生成內容的 LLM 方法。選項：
generateContent、streamGenerateContent - INPUT_PROMPT：傳送至 LLM 的文字，用於生成內容。請嘗試使用與上傳的 RAG 檔案相關的提示。
- RAG_CORPUS_RESOURCE：
RagCorpus資源的名稱。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}。 - SIMILARITY_TOP_K：(選用) 要擷取的重要上下文數量。
- VECTOR_DISTANCE_THRESHOLD：(選填) 傳回向量距離小於閾值的上下文。
HTTP 方法和網址：
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD
JSON 要求主體：
{
"contents": {
"role": "user",
"parts": {
"text": "INPUT_PROMPT"
}
},
"tools": {
"retrieval": {
"disable_attribution": false,
"vertex_rag_store": {
"rag_resources": {
"rag_corpus": "RAG_CORPUS_RESOURCE"
},
"similarity_top_k": SIMILARITY_TOP_K,
"vector_distance_threshold": VECTOR_DISTANCE_THRESHOLD
}
}
}
}
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD"
PowerShell
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD" | Select-Object -Expand Content
專案管理範例
層級是專案層級的設定，位於「資源」RagEngineConfig下方，會影響使用 RagManagedDb 的 RAG 語料庫。如要取得層級設定，請使用 GetRagEngineConfig。如要更新層級設定，請使用 UpdateRagEngineConfig。
如要進一步瞭解如何管理層級設定，請參閱「管理層級」。
取得專案設定
以下範例說明如何讀取 RagEngineConfig：
主控台
- 前往 Google Cloud 控制台的「RAG Engine」頁面。
- 選取 RAG Engine 執行的區域。RAG 語料庫清單已更新。
- 按一下「設定 RAG Engine」。「設定 RAG Engine」窗格隨即顯示。您可以查看為 RAG 引擎選取的層級。
- 按一下「取消」。
Python
from vertexai import rag
import vertexai
PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)
rag_engine_config = rag.rag_data.get_rag_engine_config(
name=f"projects/{PROJECT_ID}/locations/{LOCATION}/ragEngineConfig"
)
print(rag_engine_config)
REST
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig
更新專案設定
本節提供如何變更層級的範例。
將 RagEngineConfig 更新為「已縮放」層級
以下範例說明如何將 RagEngineConfig 設為「已縮放」層級：
主控台
- 前往 Google Cloud 控制台的「RAG Engine」頁面。
- 選取 RAG Engine 執行的區域。RAG 語料庫清單已更新。
- 按一下「設定 RAG Engine」。「設定 RAG Engine」窗格隨即顯示。
- 選取要執行 RAG Engine 的層級。
- 按一下 [儲存]。
Python
from vertexai import rag
import vertexai
PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)
rag_engine_config_name=f"projects/{PROJECT_ID}/locations/{LOCATION}/ragEngineConfig"
new_rag_engine_config = rag.RagEngineConfig(
name=rag_engine_config_name,
rag_managed_db_config=rag.RagManagedDbConfig(tier=rag.Scaled()),
)
updated_rag_engine_config = rag.rag_data.update_rag_engine_config(
rag_engine_config=new_rag_engine_config
)
print(updated_rag_engine_config)
REST
curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig -d "{'ragManagedDbConfig': {'scaled': {}}}"
將 RagEngineConfig 更新為 Basic 方案
以下範例說明如何將 RagEngineConfig 設為 Basic 層級：
如果 RAG 語料庫的RagManagedDb資料量龐大，降級至 Basic 方案時，可能會因運算和儲存容量不足而失敗。
主控台
- 前往 Google Cloud 控制台的「RAG Engine」頁面。
- 選取 RAG Engine 執行的區域。RAG 語料庫清單已更新。
- 按一下「設定 RAG Engine」。「設定 RAG Engine」窗格隨即顯示。
- 選取要執行 RAG Engine 的層級。
- 按一下 [儲存]。
Python
from vertexai import rag
import vertexai
PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)
rag_engine_config_name=f"projects/{PROJECT_ID}/locations/{LOCATION}/ragEngineConfig"
new_rag_engine_config = rag.RagEngineConfig(
name=rag_engine_config_name,
rag_managed_db_config=rag.RagManagedDbConfig(tier=rag.Basic()),
)
updated_rag_engine_config = rag.rag_data.update_rag_engine_config(
rag_engine_config=new_rag_engine_config
)
print(updated_rag_engine_config)
REST
curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig -d "{'ragManagedDbConfig': {'basic': {}}}"
將 RagEngineConfig 更新為未佈建層級
以下範例說明如何將 RagEngineConfig 設為「未佈建」層級：
主控台
- 前往 Google Cloud 控制台的「RAG Engine」頁面。
- 選取 RAG Engine 執行的區域。RAG 語料庫清單已更新。
- 按一下「設定 RAG Engine」。「設定 RAG Engine」窗格隨即顯示。
- 按一下「刪除 RAG Engine」。即會顯示確認對話方塊。
- 輸入「delete」，確認要刪除 RAG 引擎中的資料，然後按一下「Confirm」。
- 按一下 [儲存]。
Python
from vertexai import rag
import vertexai
PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)
rag_engine_config_name=f"projects/{PROJECT_ID}/locations/{LOCATION}/ragEngineConfig"
new_rag_engine_config = rag.RagEngineConfig(
name=rag_engine_config_name,
rag_managed_db_config=rag.RagManagedDbConfig(tier=rag.Unprovisioned()),
)
updated_rag_engine_config = rag.rag_data.update_rag_engine_config(
rag_engine_config=new_rag_engine_config
)
print(updated_rag_engine_config)
REST
curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig -d "{'ragManagedDbConfig': {'unprovisioned': {}}}"
後續步驟
- 如要進一步瞭解支援的生成模型，請參閱支援 RAG 的生成式 AI 模型。
- 如要進一步瞭解支援的嵌入模型，請參閱「嵌入模型」。
- 如要進一步瞭解開放式模型，請參閱開放式模型。
- 如要進一步瞭解 RAG Engine，請參閱 RAG Engine 總覽。