本頁面的部分或所有資訊可能不適用於 S3NS 的 Cloud de Confiance。詳情請參閱「與 Google Cloud 的差異」。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

依據中繼資料搜尋篩選

本頁面說明如何使用 Gemini Enterprise Agent Platform 的 RAG Engine，透過結構定義進行中繼資料搜尋。您可以為語料庫定義中繼資料結構定義、將中繼資料附加至語料庫中的檔案，並在擷取期間使用這項中繼資料篩選脈絡。

事前準備

如要使用中繼資料搜尋功能，您必須擁有現有的 RAG 語料庫和 RAG 檔案。如要瞭解如何建立語料庫及上傳檔案，請參閱「管理 RAG 知識庫」。

建立語料庫或上傳檔案時，API 會傳回數值 RAG_CORPUS_ID 和 RAG_FILE_ID (例如 123456789)。您必須備妥這些 ID，才能管理中繼資料資源。

中繼資料資源

中繼資料搜尋功能會使用下列資源階層：

RagCorpus：頂層資源，內含 RAG 檔案及其設定。
- RagDataSchema：RagCorpus 的子項資源，用於定義語料庫中使用的單一中繼資料欄位結構。每個結構定義都會指定鍵 (例如 year) 和資料類型 (INTEGER、FLOAT、STRING、DATETIME、BOOLEAN 或 LIST)。您必須為每個要用於篩選的中繼資料鍵定義 RagDataSchema。
- RagFile：RagCorpus 的子資源，代表單一擷取的檔案。
  - RagMetadata：RagFile 的子項資源，代表附加至特定檔案 (例如 year=2024) 的單一鍵值中繼資料組合。RagMetadata 資源中使用的鍵必須對應至父項語料庫的 RagDataSchema 中定義的鍵。多個 RagMetadata 資源可附加至單一檔案。

管理中繼資料架構

建立 RAG 語料庫後，請使用語料庫層級的 RagDataSchema 資源定義中繼資料結構。您也可以查看及刪除定義的結構定義。

定義中繼資料結構定義

定義結構定義時，請指定鍵和資料類型。金鑰的有效類型包括：

INTEGER：以 int_value 形式傳遞中繼資料值。
FLOAT：以 float_value 形式傳遞中繼資料值。
STRING：以 str_value 形式傳遞中繼資料值。
DATETIME：以 datetime_value 形式傳遞的中繼資料值 (RFC 3339 格式的字串，例如「2024-01-01T00:00:00Z」)。
BOOLEAN：以 bool_value 形式傳遞中繼資料值。
LIST：以 list_value 形式傳遞中繼資料值。以下 REST 範例說明如何批次建立中繼資料結構定義，為語料庫定義 year 和 month 欄位。

REST

請替換下列變數：

PROJECT_ID：專案 ID。
LOCATION：處理要求的區域。
RAG_CORPUS_ID：RAG 語料庫的 ID。

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_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}/ragDataSchemas:batchCreate \
-d '{
  "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
  "requests": [
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
      "rag_data_schema": {
        "key": "year",
        "schema_details": {"type": "INTEGER"}
      }
    },
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
      "rag_data_schema": {
        "key": "month",
        "schema_details": {"type": "STRING"}
      }
    }
  ]
}'

列出中繼資料結構定義

下列 REST 範例說明如何列出為語料庫定義的中繼資料結構。

REST

請替換下列變數：

PROJECT_ID：專案 ID。
LOCATION：處理要求的區域。
RAG_CORPUS_ID：RAG 語料庫的 ID。

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
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}/ragDataSchemas

刪除中繼資料結構定義

下列 REST 範例說明如何從語料庫中批次刪除中繼資料結構定義。

REST

請替換下列變數：

PROJECT_ID：專案 ID。
LOCATION：處理要求的區域。
RAG_CORPUS_ID：RAG 語料庫的 ID。
RAG_DATA_SCHEMA_KEY_1：要刪除的第一個中繼資料結構定義的鍵名。
RAG_DATA_SCHEMA_KEY_2：要刪除的第二個中繼資料結構定義的鍵名。

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_DATA_SCHEMA_KEY_1=RAG_DATA_SCHEMA_KEY_1
RAG_DATA_SCHEMA_KEY_2=RAG_DATA_SCHEMA_KEY_2
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}/ragDataSchemas:batchDelete \
-d '{
  "names": [
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragDataSchemas/'"${RAG_DATA_SCHEMA_KEY_1}"'",
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragDataSchemas/'"${RAG_DATA_SCHEMA_KEY_2}"'"
  ]
}'

管理檔案中繼資料

將檔案上傳或匯入語料庫後，您可以附加、更新、查看及刪除與這些檔案相關聯的中繼資料。

在檔案中附加中繼資料

附加的中繼資料必須符合為語料庫定義的結構定義。以下 REST 範例說明如何將多個中繼資料值附加至檔案。

REST

請替換下列變數：

PROJECT_ID：專案 ID。
LOCATION：處理要求的區域。
RAG_CORPUS_ID：RAG 語料庫的 ID。
RAG_FILE_ID：RAG 檔案的 ID。

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=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/${RAG_FILE_ID}/ragMetadata:batchCreate \
-d '{
  "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
  "requests": [
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
      "rag_metadata": {
        "user_specified_metadata": { "key": "year", "value": { "int_value": 2024 } }
      }
    },
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
      "rag_metadata": {
        "user_specified_metadata": { "key": "month", "value": { "str_value": "May" } }
      }
    }
  ]
}'

列出檔案的中繼資料

下列 REST 範例說明如何列出附加至特定檔案的中繼資料。

REST

請替換下列變數：

PROJECT_ID：專案 ID。
LOCATION：處理要求的區域。
RAG_CORPUS_ID：RAG 語料庫的 ID。
RAG_FILE_ID：RAG 檔案的 ID。

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
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}/ragMetadata

更新中繼資料

您可以更新附加至檔案的中繼資料值。下列 REST 範例說明如何更新與 year 鍵相關聯的中繼資料值。RAG_METADATA_KEY 是您建立中繼資料時使用的字串。

REST

請替換下列變數：

PROJECT_ID：專案 ID。
LOCATION：處理要求的區域。
RAG_CORPUS_ID：RAG 語料庫的 ID。
RAG_FILE_ID：RAG 檔案的 ID。
RAG_METADATA_KEY：要更新的中繼資料鍵名。

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
RAG_METADATA_KEY=RAG_METADATA_KEY
curl -X PATCH \
-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/${RAG_FILE_ID}/ragMetadata/${RAG_METADATA_KEY} \
-d '{
  "user_specified_metadata": { "key": "'"${RAG_METADATA_KEY}"'", "value": { "int_value": 2025 } }
}'

刪除檔案中的中繼資料

下列 REST 範例說明如何從檔案中批次刪除中繼資料值。

REST

請替換下列變數：

PROJECT_ID：專案 ID。
LOCATION：處理要求的區域。
RAG_CORPUS_ID：RAG 語料庫的 ID。
RAG_FILE_ID：RAG 檔案的 ID。
RAG_METADATA_KEY_1：要刪除的第一個中繼資料值的鍵名。
RAG_METADATA_KEY_2：要刪除的第二個中繼資料值的鍵名。

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
RAG_METADATA_KEY_1=RAG_METADATA_KEY_1
RAG_METADATA_KEY_2=RAG_METADATA_KEY_2
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/${RAG_FILE_ID}/ragMetadata:batchDelete \
-d '{
  "names": [
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'/ragMetadata/'"${RAG_METADATA_KEY_1}"'",
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'/ragMetadata/'"${RAG_METADATA_KEY_2}"'"
  ]
}'

依據中繼資料篩選結構定義

如要提高結果的關聯性，請在擷取背景資訊時使用檔案中繼資料縮小搜尋範圍。使用 CEL (一般運算語言)，將 metadata_filter 運算式新增至 RetrieveContexts 要求 (例如 year == 2024 && month == "May")。系統只會擷取中繼資料符合篩選運算式的檔案。

下列 REST 範例說明如何使用中繼資料篩選器擷取內容。

REST

請替換下列變數：

PROJECT_ID：專案 ID。
LOCATION：處理要求的區域。
RAG_CORPUS_ID：RAG 語料庫的 ID。

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
QUERY="except share amounts"
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}:retrieveContexts -d '{
    "vertex_rag_store": {
       "rag_resources": [
         {
           "rag_corpus": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'"
         }
       ]
    },    
    "query": {
      "text": "'"${QUERY}"'", 
      "rag_retrieval_config": {
         "top_k": 10,
         "filter": {
            "vector_distance_threshold": 0.5,
            "metadata_filter": "year == 2024 && month == \"May\""
         }
      }
    }
}'

後續步驟

如要進一步瞭解如何上傳及管理檔案，請參閱「管理 RAG 知識庫」。
如要進一步瞭解 RAG 中的標準向量搜尋，請參閱「運用 RAG 進行向量搜尋」。