Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Memfilter dengan penelusuran metadata

Halaman ini menunjukkan cara menggunakan fitur penelusuran metadata berbasis skema di RAG Engine di Gemini Enterprise Agent Platform. Anda dapat menentukan skema metadata untuk korpus, melampirkan metadata ke file dalam korpus tersebut, dan menggunakan metadata ini untuk memfilter konteks selama pengambilan.

Sebelum memulai

Untuk menggunakan penelusuran metadata, Anda harus memiliki korpus RAG dan file RAG yang ada. Untuk mempelajari cara membuat korpus dan mengupload file, lihat Mengelola basis pengetahuan RAG Anda.

Saat Anda membuat korpus atau mengupload file, API akan menampilkan RAG_CORPUS_ID dan RAG_FILE_ID numerik (misalnya, 123456789). Anda harus memiliki ID ini untuk mengelola resource metadata.

Resource metadata

Fitur penelusuran metadata menggunakan hierarki resource berikut:

RagCorpus: Resource tingkat teratas yang berisi file RAG dan konfigurasinya.
- RagDataSchema: Resource turunan dari RagCorpus. Objek ini menentukan struktur untuk satu kolom metadata yang digunakan dalam korpus. Setiap skema menentukan kunci (misalnya, year) dan jenis data (INTEGER, FLOAT, STRING, DATETIME, BOOLEAN, atau LIST). Anda harus menentukan RagDataSchema untuk setiap kunci metadata yang ingin digunakan untuk pemfilteran.
- RagFile: Resource turunan RagCorpus yang merepresentasikan satu dokumen yang di-ingest.
  - RagMetadata: Resource turunan dari RagFile. Objek ini merepresentasikan satu pasangan metadata key-value yang dilampirkan ke file tertentu tersebut (misalnya, year=2024). Kunci yang digunakan dalam resource RagMetadata harus sesuai dengan kunci yang ditentukan dalam RagDataSchema untuk korpus induk. Beberapa resource RagMetadata dapat dilampirkan ke satu file.

Kelola skema metadata

Setelah membuat korpus RAG, tentukan struktur metadata menggunakan resource RagDataSchema di tingkat korpus. Anda juga dapat melihat dan menghapus skema yang Anda tentukan.

Menentukan skema metadata

Saat menentukan skema, Anda menentukan kunci dan jenis data. Jenis yang valid untuk kunci adalah:

INTEGER: Nilai metadata yang diteruskan sebagai int_value.
FLOAT: Nilai metadata yang diteruskan sebagai float_value.
STRING: Nilai metadata yang diteruskan sebagai str_value.
DATETIME: Nilai metadata yang diteruskan sebagai datetime_value (string berformat RFC 3339, misalnya, "2024-01-01T00:00:00Z").
BOOLEAN: Nilai metadata yang diteruskan sebagai bool_value.
LIST: Nilai metadata yang diteruskan sebagai list_value. Contoh REST berikut menunjukkan cara membuat batch skema metadata yang menentukan kolom year dan month untuk korpus.

REST

Ganti variabel berikut:

PROJECT_ID: Project ID Anda.
LOCATION: Region untuk memproses permintaan.
RAG_CORPUS_ID: ID korpus RAG.

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"}
      }
    }
  ]
}'

Mencantumkan skema metadata

Contoh REST berikut menunjukkan cara mencantumkan skema metadata yang ditentukan untuk korpus.

REST

Ganti variabel berikut:

PROJECT_ID: Project ID Anda.
LOCATION: Region untuk memproses permintaan.
RAG_CORPUS_ID: ID korpus RAG.

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

Menghapus skema metadata

Contoh REST berikut menunjukkan cara menghapus skema metadata secara batch dari korpus.

REST

Ganti variabel berikut:

PROJECT_ID: Project ID Anda.
LOCATION: Region untuk memproses permintaan.
RAG_CORPUS_ID: ID korpus RAG.
RAG_DATA_SCHEMA_KEY_1: Nama kunci skema metadata pertama yang akan dihapus.
RAG_DATA_SCHEMA_KEY_2: Nama kunci skema metadata kedua yang akan dihapus.

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}"'"
  ]
}'

Mengelola metadata file

Setelah mengupload atau mengimpor file ke korpus, Anda dapat melampirkan, memperbarui, melihat, dan menghapus metadata yang terkait dengan file tersebut.

Melampirkan metadata ke file

Metadata terlampir harus sesuai dengan skema yang ditentukan untuk korpus. Contoh REST berikut menunjukkan cara melampirkan beberapa nilai metadata ke file.

REST

Ganti variabel berikut:

PROJECT_ID: Project ID Anda.
LOCATION: Region untuk memproses permintaan.
RAG_CORPUS_ID: ID korpus RAG.
RAG_FILE_ID: ID file RAG.

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" } }
      }
    }
  ]
}'

Mencantumkan metadata untuk file

Contoh REST berikut menunjukkan cara mencantumkan metadata yang dilampirkan ke file tertentu.

REST

Ganti variabel berikut:

PROJECT_ID: Project ID Anda.
LOCATION: Region untuk memproses permintaan.
RAG_CORPUS_ID: ID korpus RAG.
RAG_FILE_ID: ID file RAG.

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

Update metadata

Anda dapat memperbarui nilai metadata yang dilampirkan ke file. Contoh REST berikut menunjukkan cara memperbarui nilai metadata yang terkait dengan kunci year. RAG_METADATA_KEY adalah string yang digunakan saat Anda membuat metadata.

REST

Ganti variabel berikut:

PROJECT_ID: Project ID Anda.
LOCATION: Region untuk memproses permintaan.
RAG_CORPUS_ID: ID korpus RAG.
RAG_FILE_ID: ID file RAG.
RAG_METADATA_KEY: Nama kunci metadata yang akan diupdate.

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 } }
}'

Menghapus metadata dari file

Contoh REST berikut menunjukkan cara menghapus nilai metadata secara batch dari file.

REST

Ganti variabel berikut:

PROJECT_ID: Project ID Anda.
LOCATION: Region untuk memproses permintaan.
RAG_CORPUS_ID: ID korpus RAG.
RAG_FILE_ID: ID file RAG.
RAG_METADATA_KEY_1: Nama kunci nilai metadata pertama yang akan dihapus.
RAG_METADATA_KEY_2: Nama kunci nilai metadata kedua yang akan dihapus.

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}"'"
  ]
}'

Memfilter konteks dengan metadata

Untuk meningkatkan relevansi hasil, gunakan metadata file untuk mempersempit ruang penelusuran selama pengambilan konteks. Tambahkan ekspresi metadata_filter ke permintaan RetrieveContexts menggunakan CEL (Common Expression Language) (misalnya, year == 2024 && month == "May"). Hanya file dengan metadata yang cocok dengan ekspresi filter yang dipertimbangkan untuk pengambilan.

Contoh REST berikut menunjukkan cara mengambil konteks menggunakan filter metadata.

REST

Ganti variabel berikut:

PROJECT_ID: Project ID Anda.
LOCATION: Region untuk memproses permintaan.
RAG_CORPUS_ID: ID korpus RAG.

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\""
         }
      }
    }
}'

Langkah berikutnya

Untuk mempelajari lebih lanjut cara mengupload dan mengelola file, lihat Mengelola basis pengetahuan RAG Anda.
Untuk mempelajari penelusuran vektor standar di RAG lebih lanjut, lihat Menggunakan Penelusuran Vektor dengan RAG.

Memfilter dengan penelusuran metadata Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Resource metadata

Kelola skema metadata

Menentukan skema metadata

REST

Mencantumkan skema metadata

REST

Menghapus skema metadata

REST

Mengelola metadata file

Melampirkan metadata ke file

REST

Mencantumkan metadata untuk file

REST

Update metadata

REST

Menghapus metadata dari file

REST

Memfilter konteks dengan metadata

REST

Langkah berikutnya

Memfilter dengan penelusuran metadata