Mit der Metadatensuche filtern

Auf dieser Seite wird beschrieben, wie Sie die schemabasierte Metadatensuche in der RAG Engine auf der Gemini Enterprise Agent Platform verwenden. Sie können ein Metadatenschema für einen Korpus definieren, Metadaten an Dateien in diesem Korpus anhängen und diese Metadaten verwenden, um Kontexte beim Abrufen zu filtern.

Hinweis

Wenn Sie die Metadatensuche verwenden möchten, benötigen Sie einen vorhandenen RAG-Korpus und RAG-Dateien. Informationen zum Erstellen eines Corpus und zum Hochladen von Dateien finden Sie unter RAG-Wissensdatenbank verwalten.

Wenn Sie einen Korpus erstellen oder eine Datei hochladen, gibt die API eine numerische RAG_CORPUS_ID und RAG_FILE_ID zurück (z. B. 123456789). Sie benötigen diese IDs, um Ihre Metadatenressourcen zu verwalten.

Metadaten-Ressourcen

Für die Metadatensuche wird die folgende Ressourcenhierarchie verwendet:

  • RagCorpus:Die Ressource der obersten Ebene, die Ihre RAG-Dateien und deren Konfigurationen enthält.

    • RagDataSchema:Eine untergeordnete Ressource von RagCorpus. Sie definiert die Struktur für ein einzelnes Metadatenfeld, das im Korpus verwendet wird. Jedes Schema gibt einen Schlüssel (z. B. year) und einen Datentyp (INTEGER, FLOAT, STRING, DATETIME, BOOLEAN oder LIST) an. Sie müssen für jeden Metadatenschlüssel, den Sie zum Filtern verwenden möchten, einen RagDataSchema definieren.

    • RagFile:Eine untergeordnete Ressource von RagCorpus, die ein einzelnes aufgenommenes Dokument darstellt.

      • RagMetadata:Eine untergeordnete Ressource von RagFile. Sie stellt ein einzelnes Schlüssel/Wert-Metadatenpaar dar, das an diese bestimmte Datei angehängt ist (z. B. year=2024). Der in einer RagMetadata-Ressource verwendete Schlüssel muss einem Schlüssel entsprechen, der in einer RagDataSchema für den übergeordneten Korpus definiert ist. An eine einzelne Datei können mehrere RagMetadata-Ressourcen angehängt werden.

Metadatenschemas verwalten

Nachdem Sie einen RAG-Korpus erstellt haben, definieren Sie die Metadatenstruktur mit der RagDataSchema-Ressource auf Korpusebene. Sie können die von Ihnen definierten Schemas auch ansehen und löschen.

Metadatenschemas definieren

Wenn Sie ein Schema definieren, geben Sie einen Schlüssel und einen Datentyp an. Die gültigen Typen für einen Schlüssel sind:

  • INTEGER: Übergebene Metadatenwerte als int_value.
  • FLOAT: Übergebene Metadatenwerte als float_value.
  • STRING: Übergebene Metadatenwerte als str_value.
  • DATETIME: Übergebene Metadatenwerte als datetime_value (RFC 3339-formatierter String, z. B. „2024-01-01T00:00:00Z“).
  • BOOLEAN: Übergebene Metadatenwerte als bool_value.
  • LIST: Übergebene Metadatenwerte als list_value. Im folgenden REST-Beispiel wird gezeigt, wie Sie Metadatenschemas im Batch erstellen, die die Felder year und month für einen Korpus definieren.

REST

Ersetzen Sie die folgenden Variablen:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
  • RAG_CORPUS_ID: Die ID des RAG-Korpus.
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"}
      }
    }
  ]
}'

Metadatenschemas auflisten

Im folgenden REST-Beispiel wird gezeigt, wie Sie die für einen Korpus definierten Metadatenschemas auflisten.

REST

Ersetzen Sie die folgenden Variablen:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
  • RAG_CORPUS_ID: Die ID des RAG-Korpus.
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

Metadatenschemas löschen

Im folgenden REST-Beispiel wird gezeigt, wie Metadatenschemas in einem Batch aus einem Korpus gelöscht werden.

REST

Ersetzen Sie die folgenden Variablen:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
  • RAG_CORPUS_ID: Die ID des RAG-Korpus.
  • RAG_DATA_SCHEMA_KEY_1: Der Schlüsselname des ersten zu löschenden Metadatenschemas.
  • RAG_DATA_SCHEMA_KEY_2: Der Schlüsselname des zweiten zu löschenden Metadatenschemas.
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}"'"
  ]
}'

Dateimetadaten verwalten

Nachdem Sie Dateien in Ihren Korpus hochgeladen oder importiert haben, können Sie Metadaten, die mit diesen Dateien verknüpft sind, anhängen, aktualisieren, ansehen und löschen.

Metadaten an eine Datei anhängen

Die angehängten Metadaten müssen dem für den Korpus definierten Schema entsprechen. Das folgende REST-Beispiel zeigt, wie Sie einer Datei mehrere Metadatenwerte zuweisen.

REST

Ersetzen Sie die folgenden Variablen:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
  • RAG_CORPUS_ID: Die ID des RAG-Korpus.
  • RAG_FILE_ID: Die ID der RAG-Datei.
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" } }
      }
    }
  ]
}'

Metadaten für eine Datei auflisten

Das folgende REST-Beispiel zeigt, wie die Metadaten einer bestimmten Datei aufgelistet werden.

REST

Ersetzen Sie die folgenden Variablen:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
  • RAG_CORPUS_ID: Die ID des RAG-Korpus.
  • RAG_FILE_ID: Die ID der RAG-Datei.
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

Metadaten aktualisieren

Sie können die Metadatenwerte aktualisieren, die einer Datei zugeordnet sind. Im folgenden REST-Beispiel wird gezeigt, wie der Metadatenwert aktualisiert wird, der dem Schlüssel year zugeordnet ist. RAG_METADATA_KEY ist der String, der beim Erstellen der Metadaten verwendet wurde.

REST

Ersetzen Sie die folgenden Variablen:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
  • RAG_CORPUS_ID: Die ID des RAG-Korpus.
  • RAG_FILE_ID: Die ID der RAG-Datei.
  • RAG_METADATA_KEY: Der Schlüsselname der zu aktualisierenden Metadaten.
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 } }
}'

Metadaten aus einer Datei löschen

Im folgenden REST-Beispiel wird gezeigt, wie Metadatenwerte aus einer Datei im Batch gelöscht werden.

REST

Ersetzen Sie die folgenden Variablen:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
  • RAG_CORPUS_ID: Die ID des RAG-Korpus.
  • RAG_FILE_ID: Die ID der RAG-Datei.
  • RAG_METADATA_KEY_1: Der Schlüsselname des ersten zu löschenden Metadatenwerts.
  • RAG_METADATA_KEY_2: Der Schlüsselname des zweiten zu löschenden Metadatenwerts.
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}"'"
  ]
}'

Kontexte mit Metadaten filtern

Um die Relevanz Ihrer Ergebnisse zu verbessern, können Sie die Dateimetadaten verwenden, um den Suchbereich beim Abrufen von Kontextinformationen einzugrenzen. Fügen Sie Ihrer RetrieveContexts-Anfrage einen metadata_filter-Ausdruck mit CEL (Common Expression Language) hinzu, z. B. year == 2024 && month == "May". Nur Dateien mit Metadaten, die dem Filterausdruck entsprechen, werden für den Abruf berücksichtigt.

Im folgenden REST-Beispiel wird gezeigt, wie Sie Kontexte mit einem Metadatenfilter abrufen.

REST

Ersetzen Sie die folgenden Variablen:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
  • RAG_CORPUS_ID: Die ID des RAG-Korpus.
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\""
         }
      }
    }
}'

Nächste Schritte