Rechercher des documents dans un data store

Le pipeline d'ingestion géré importe des fichiers de documents et de vidéos depuis des datastores dans Agent Retrieval en tant qu'objets de données et collections que vous pouvez rechercher à l'aide de requêtes textuelles. Il gère automatiquement l'analyse, la segmentation, l'embedding et l'indexation pour vous.

Formats de documents acceptés

Le tableau suivant liste les formats et extensions de fichiers de document compatibles.

Type de document File extension (Extension de fichier)
HTML .html, .htm
JSON .json
PDF .pdf
Texte brut .txt
Markdown .md
Microsoft Excel .xlsx
Microsoft Excel (compatible avec les macros) .xlsm (les scripts et les macros sont ignorés)
Microsoft PowerPoint .pptx
Microsoft Word .docx
XML .xml

Formats vidéo et codecs compatibles

Le tableau suivant liste les formats et extensions de fichiers vidéo compatibles.

Format vidéo File extension (Extension de fichier)
AVI .avi
Matroska .mkv
Flux de transport MPEG et MPEG-2 .ts, .m2ts
MPEG-4 Part 14 .mp4
MXF (OP1A uniquement) .mxf
QuickTime .mov
WebM .webm
Windows Media (ASF) .wmv

Les codecs suivants sont compatibles :

  • DNxHD
  • DV
  • H.264, H.265
  • MPEG-1, MPEG-2, MPEG-4 part 2
  • ProRes
  • Theora
  • VC-1
  • VP8, VP9
  • XAVC
  • XDCAM

Prérequis

Avant de commencer, vous devez :

Exemples

Les exemples de cette page s'appuient sur les exemples de fichiers suivants.

curl

PROJECT=acme-prod
LOCATION=us-east4
BASE=https://vectorsearch.googleapis.com/v1alpha
INGEST=${BASE}/projects/${PROJECT}/locations/${LOCATION}
AUTH="Authorization: Bearer $(gcloud auth print-access-token)"

Python

import time
import google.auth
from google.auth.transport.requests import AuthorizedSession

PROJECT = "acme-prod"          # Replace with your project ID
LOCATION = "us-east4"          # Replace with your region

credentials, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
session = AuthorizedSession(credentials)

BASE = "https://vectorsearch.googleapis.com/v1alpha"
INGEST = BASE + "/projects/" + PROJECT + "/locations/" + LOCATION

def wait(operation, poll_seconds=10):
    """Poll a long-running operation until it finishes, then return it."""
    name = operation["name"]
    while True:
        op = session.get(BASE + "/" + name).json()
        if op.get("done"):
            if "error" in op:
                raise RuntimeError(op["error"])
            return op
        meta = op.get("metadata", {})
        print("in progress:", meta)
        time.sleep(poll_seconds)

Pipeline d'ingestion géré

Le pipeline d'ingestion géré importe des documents et des vidéos de votre data store dans Agent Retrieval et effectue la majeure partie du travail de configuration des objets de données et des collections pour vous.

Pour cela, il vous suffit de suivre ces étapes :

  1. Préparez vos fichiers de document ou de vidéo.

  2. Créez un datastore.

  3. Importez vos fichiers vidéo ou de document.

  4. Recherchez dans vos fichiers à l'aide de requêtes textuelles.

1. Préparer vos fichiers de document ou de vidéo

Créez un bucket et ajoutez les fichiers de document ou de vidéo que vous souhaitez rechercher. Vous n'avez pas besoin de créer un fichier manifeste.

Ingestion gérée de documents :

  • Ignore les fichiers de document de plus de 200 Mo.

  • Importe jusqu'à 100 000 documents à la fois.

  • Ignore les macros et les scripts dans les fichiers de document Microsoft Excel (.xlsm) compatibles avec les macros.

Ingestion gérée des vidéos :

  • Ignore les fichiers vidéo de plus de 600 Go.

  • Ignore les fichiers vidéo de plus de 15 heures. Pour les formats vidéo lisibles en streaming, les fichiers sont ignorés si la durée estimée est supérieure à la limite ou ne peut pas être déterminée.

  • Importer jusqu'à 100 vidéos à la fois

  • Ignore les fichiers vidéo sans flux vidéo.

2. Créer un datastore

Après avoir préparé les fichiers sur lesquels vous souhaitez effectuer une recherche, vous devez créer un data store. Le data store fournit la source du pipeline d'ingestion géré et la configuration spécifiant comment vos fichiers sont ingérés.

L'ingestion gérée n'est disponible que pour les datastores situés dans la région us-east4 ou europe-west4.

Pour créer un data store, envoyez une requête POST à l'API dataStores et fournissez le paramètre suivant :

  • data_store_id : ID du data store en cours de création. Il doit commencer par une lettre minuscule, se terminer par une lettre minuscule ou un chiffre, ne contenir que des lettres minuscules, des chiffres et des traits d'union, et comporter entre 1 et 63 caractères.

La charge utile JSON contient les paramètres de configuration JSON que l'ingestion gérée utilise pour créer le data store et traiter les fichiers que vous avez préparés.

La charge utile JSON doit inclure la propriété de premier niveau document_type. Cela spécifie les types de fichiers à importer à partir du data store. Les valeurs possibles sont les suivantes :

  • UNSTRUCTURED : le data store contient des fichiers de document. Consultez la section Formats de documents compatibles pour obtenir la liste des formats compatibles.

  • VIDEO : le data store contient des fichiers vidéo. Consultez la section Formats vidéo compatibles pour obtenir la liste des formats et des codecs compatibles.

Les propriétés suivantes sont facultatives :

  • display_name (STRING) : nom à afficher du data store. La taille maximale est de 1 024 octets. La valeur par défaut est une chaîne vide.

  • description : (STRING) Description du data store. La taille maximale est de 1 024 octets. La valeur par défaut est une chaîne vide.

  • labels : (tableau STRING) Tableau de paires clé/valeur. Pour en savoir plus, consultez Organiser des ressources à l'aide d'étiquettes. La valeur par défaut est un tableau vide.

  • processing_config (OBJECT) : configuration de la manière dont l'ingestion gérée traite les données dans le data store. Vous pouvez mettre à jour ce champ à l'aide d'une requête PATCH. Pour connaître les paramètres par défaut s'ils sont omis, consultez Paramètres facultatifs pour les datastores de documents.

  • document_metadata_schema (OBJECT) : schéma de métadonnées pour les métadonnées associées aux documents du datastore. Pour en savoir plus, consultez Ajouter un schéma de métadonnées. La valeur par défaut est un objet vide (aucun schéma de métadonnées).

Paramètres facultatifs pour les datastores de documents

Les paramètres facultatifs suivants sont disponibles pour les datastores de documents :

  • processing_config.unstructured_processing_config.segmentation_config : (OBJECT) Configuration d'ingestion pour segmenter le document (les résultats de recherche sont par segment, et non par document). Pour en savoir plus, consultez Segmentation de documents. Un objet vide entraîne le rejet de la requête avec l'état INVALID_ARGUMENT. Si vous l'indiquez, vous devez inclure un des éléments suivants :
    • page_segmentation_config : (OBJECT) Cet objet n'a pas de propriétés.
    • chunk_segmentation_config : (OBJECT) possède les propriétés suivantes :
      • chunk_size : (INTEGER) Nombre maximal de jetons dans un segment. La valeur minimale est de 300 et la valeur maximale est de 500. La valeur par défaut est 500.
      • include_ancestor_headings : (BOOL) ajoute une chaîne de titres de section à chaque fragment pour le contexte. La valeur par défaut est false.
  • processing_config.unstructured_processing_config.parsing_config : (OBJECT) Configuration d'ingestion pour l'analyse du document. Un objet vide entraîne le rejet de la requête avec l'état INVALID_ARGUMENT. Si vous l'indiquez, vous devez inclure un des éléments suivants :
    • layout_parsing_config : (OBJECT) l'analyse de la mise en page sera utilisée. Cet objet n'a pas de propriétés.
    • digital_parsing_config : (OBJECT) l'analyse numérique sera utilisée. Cet objet n'a pas de propriétés.
  • processing_config.unstructured_processing_config.embedding_config.mode (STRING) : mode d'embedding à utiliser. Valeurs autorisées :

    • TEXT : seul le texte extrait est intégré. Les images sont ignorées. La valeur par défaut est TEXT.

Vous pouvez également ajouter des métadonnées à votre data store. Pour en savoir plus, consultez Ajouter des métadonnées à vos fichiers.

Exemples

Les exemples suivants montrent comment créer un data store de documents.

curl

  curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "${INGEST}/dataStores?data_store_id=acme-financials" \
  -d '{
    "display_name": "Acme financial reports",
    "document_type": "UNSTRUCTURED",
    "processing_config": {
      "unstructured_processing_config": {
        "segmentation_config": {
          "chunk_segmentation_config": {
            "chunk_size": 300,
            "include_ancestor_headings": true
          }
        },
        "parsing_config": {
          "layout_parsing_config": {}
        }
      }
    }
  }'

Python

  op = session.post(
    INGEST + "/dataStores",
    params={"data_store_id": "acme-financials"},
    json={
        "display_name": "Acme financial reports",
        "document_type": "UNSTRUCTURED",
        "processing_config": {
            "unstructured_processing_config": {
                "segmentation_config": {
                    "chunk_segmentation_config": {
                        "chunk_size": 300,
                        "include_ancestor_headings": True,
                    }
                },
                "parsing_config": {"layout_parsing_config": {}},
            }
        },
    },
).json()

wait(op)

Exemple de réponse

{
  "name": "projects/acme-prod/locations/us-east4/dataStores/acme-financials",
  "documentType": "UNSTRUCTURED",
  "state": "ACTIVE",
  "collectionName": "projects/acme-prod/locations/us-east4/collections/google-acme-financials"
}

Paramètres facultatifs pour les datastores vidéo

Les paramètres facultatifs suivants sont disponibles pour les datastores vidéo :

  • processing_config.video_processing_config.segmentation_config : (OBJECT) Configuration d'ingestion pour la segmentation de la vidéo. Un objet vide entraîne le rejet de la requête avec l'état INVALID_ARGUMENT. Si elle est fournie, la configuration d'ingestion doit inclure :
    • fixed_window_config : (OBJECT) possède les propriétés suivantes :
      • segment_duration : (STRING) nombre maximal de secondes dans un segment. La valeur minimale est 5.01s et la valeur maximale 80s. La valeur par défaut est 30s.
  • processing_config.video_processing_config.embedding_config.audio_mode (STRING) : mode audio à utiliser. Compatible uniquement lorsque document_type est défini sur VIDEO. La valeur par défaut est DISABLED si elle n'est pas spécifiée. Pour en savoir plus, consultez Audio de la vidéo. Valeurs autorisées :
    • ENABLED : multiplexe la première piste audio dans l'embedding avec les images.
    • DISABLED : utilise uniquement des frames.
    • AUDIO_MODE_UNSPECIFIED : identique à DISABLED.

Exemples

Les exemples suivants montrent comment créer un data store de vidéos.

curl

  curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "${INGEST}/dataStores?data_store_id=acme-training-video" \
  -d '{
    "display_name": "Acme training video",
    "document_type": "VIDEO",
    "processing_config": {
      "video_processing_config": {
        "segmentation_config": {
          "fixed_window_config": {
            "segment_duration": "20s"
          }
        },
        "embedding_config": {
          "audio_mode": "ENABLED"
        }
      }
    }
  }'

Python

  op = session.post(
    INGEST + "/dataStores",
    params={"data_store_id": "acme-training-video"},
    json={
        "display_name": "Acme training video",
        "document_type": "VIDEO",
        "processing_config": {
            "video_processing_config": {
                "segmentation_config": {
                    "fixed_window_config": {"segment_duration": "20s"}
                },
                "embedding_config": {"audio_mode": "ENABLED"},
            }
        },
    },
  ).json()

  wait(op)

Exemple de réponse

{
  "name": "projects/acme-prod/locations/us-east4/dataStores/acme-training-video",
  "documentType": "VIDEO",
  "state": "ACTIVE",
  "collectionName": "projects/acme-prod/locations/us-east4/collections/google-acme-training-video"
}

Ajouter des métadonnées pour vos fichiers

Vous pouvez définir des propriétés de métadonnées pour les fichiers que vous souhaitez importer via l'ingestion gérée. Ces propriétés peuvent être récupérées à partir des objets de données correspondants créés par le pipeline et sont utiles pour filtrer les résultats de recherche.

Pour définir des métadonnées :

  1. Créez un fichier JSONL. L'extension doit être json ou jsonl.

  2. Ajoutez un objet JSON à une nouvelle ligne pour chaque fichier que vous souhaitez importer, et incluez les propriétés suivantes :

    • name : nom du fichier dans le data store. Le dernier segment du nom est utilisé comme ID pour l'objet de données créé pour le fichier.

    • content.gcsUri : URI du fichier dans Cloud Storage.

    • metadata.value : métadonnées du fichier. Les propriétés des métadonnées sont définies dans un schéma que vous spécifiez lorsque vous créez votre data store. Pour en savoir plus, consultez Ajouter un schéma de métadonnées.

L'exemple suivant illustre un fichier JSONL de métadonnées avec les propriétés de métadonnées category, year, tags et issuer.

{"name":"projects/acme-prod/locations/us-east4/dataStores/acme-financials/documents/q3-earnings","content":{"gcsUri":"gs://acme-docs/reports/2025-q3-earnings.pdf"},"metadata":{"value":{"category":"earnings","year":2025,"tags":["revenue"],"issuer":{"country":"US"}}}}
{"name":"projects/acme-prod/locations/us-east4/dataStores/acme-financials/documents/covenants","content":{"gcsUri":"gs://acme-docs/reports/covenant-summary.docx"},"metadata":{"value":{"category":"covenant","year":2024,"tags":["credit","debt"]}}}

Les propriétés doivent correspondre à un schéma que vous fournissez lors de la création du data store.

Vous utiliserez les fichiers JSONL que vous avez créés en tant qu'URI d'entrée lorsque vous importerez vos fichiers.

Ajouter un schéma de métadonnées

Vous pouvez fournir un schéma de métadonnées dans la propriété document_metadata_schema de premier niveau de la configuration JSON du data store. Cela définit un contrat pour les métadonnées que vous pouvez associer à vos documents, qui peuvent être récupérées par fichier ou utilisées pour filtrer les résultats de recherche.

Les propriétés des métadonnées doivent correspondre au schéma que vous fournissez lors de la création du datastore. Le schéma suit de près le brouillon 7 du schéma JSON. Les types de données suivants sont acceptés :

  • string
  • number
  • integer
  • boolean
  • object (y compris les propriétés)
  • array

Les noms de propriétés ne peuvent contenir que des lettres, des chiffres, des traits de soulignement (_) et des traits d'union (-). Ils ne doivent pas commencer par google (quelle que soit la casse), qui est un préfixe réservé aux propriétés écrites par le service.

Vous pourrez ajouter des propriétés ultérieurement à l'aide d'une requête PATCH. Les propriétés du schéma ne peuvent pas être supprimées, et leur type de données ne peut pas être modifié. Pour en savoir plus, consultez Mettre à jour une configuration de traitement.

L'exemple suivant définit un schéma de métadonnées avec les propriétés de métadonnées category, year, tags et issuer.

"document_metadata_schema": {
  "schema": {
    "type": "object",
    "properties": {
      "category": {"type": "string"},
      "year":     {"type": "integer"},
      "tags":     {"type": "array", "items": {"type": "string"}},
      "issuer":   {"type": "object", "properties": {"country": {"type": "string"}}}
    }
  }
}

Les métadonnées sont particulièrement utiles pour les vidéos. L'exemple suivant définit un schéma de métadonnées pour une vidéo avec les propriétés de métadonnées series, language et year.

"document_metadata_schema": {
  "schema": {
    "type": "object",
    "properties": {
      "series":     {"type": "string"},
      "language":   {"type": "string"},
      "year":       {"type": "integer"}
    }
  }
}

Mettre à jour une configuration de traitement

Une fois votre data store créé, vous pouvez mettre à jour la configuration de traitement (processing_config) à l'aide d'une requête PATCH.

Les propriétés suivantes peuvent être mises à jour :

  • display_name
  • description
  • labels
  • document_metadata_schema (seules des propriétés supplémentaires peuvent être ajoutées)

Les propriétés en cours de mise à jour doivent être incluses dans le paramètre de requête update_mask.

Les exemples suivants montrent comment mettre à jour les propriétés display_name et document_metadata_schema d'une configuration de traitement.

curl

curl -X PATCH -H "${AUTH}" -H "Content-Type: application/json" \
"${INGEST}/dataStores/acme-financials?update_mask=display_name,document_metadata_schema" \
-d '{"display_name": "Acme reports",
"document_metadata_schema": {"schema": {"type": "object", "properties": {
"category": {"type": "string"}, "year": {"type": "integer"},
"region": {"type": "string"}}}}}'

Segmentation de fichiers de documents

Lorsque vous créez votre datastore, vous pouvez spécifier comment le pipeline d'ingestion géré doit tenter de segmenter vos fichiers de document :

  • Segmentation des pages (processing_config.segmentation_config.page_segmentation_config) : l'ingestion gérée tente de segmenter les fichiers de document par page.

  • Segmentation des fragments (processing_config.segmentation_config.chunk_segmentation_config) : l'ingestion gérée segmente les fichiers de document en fragments distincts.

Si aucune valeur n'est spécifiée, la segmentation par fragments est utilisée par défaut. Si les deux sont spécifiés, la requête échoue.

Segmentation de page

La spécification de la segmentation des pages (processing_config.segmentation_config.page_segmentation_config) indique au pipeline d'ingestion géré de segmenter les documents par page ou par plage de pages. Si un document ne contient pas d'informations sur les pages, comme un fichier texte, il est segmenté en pages d'une taille maximale de 2,5 Mo.

La segmentation des pages est optimisée pour la récupération de documents, comme les applications qui renvoient des PDF ou des documents Word avec chaque résultat de recherche. Pour en savoir plus, consultez Segmenter des documents pour le RAG.

Segmentation des fragments

La spécification de la segmentation des fragments (processing_config.segmentation_config.chunk_segmentation_config) indique au pipeline d'ingestion géré de segmenter les documents en fragments de processing_config.segmentation_config.chunk_segmentation_config.chunk_size jetons maximum. Par défaut, la taille des fragments est de 500 jetons (taille maximale des fragments). La taille minimale d'un fragment est de 300.

Grands fragments :

  • Transporter plus de contexte.
  • Produisez moins de segments.
  • Peut couvrir plusieurs sujets qui ne correspondent pas à une requête, ce qui peut masquer des informations pertinentes.

Petits fragments :

  • Contiennent des morceaux de texte plus courts.
  • Elles sont plus susceptibles de ne contenir que les informations correspondant à une requête.
  • Ils contiennent moins de contexte, ce qui peut diviser les informations pertinentes en plusieurs segments.

Pour la plupart des contenus longs, une taille de fragment de 500 jetons est adaptée. Les tailles de fragments plus petites sont plus adaptées aux contenus courts et factuels ou à la récupération de passages de texte compacts et précis.

Segmentation de vidéos

Une courte durée de segment (10s à 20s) fournit des codes temporels et des réponses plus précis. C'est le bon choix lorsqu'une requête correspond à un moment spécifique : une étape de démonstration, une diapositive, une photo de produit.

Une longue durée de segment (60s à 80s) donne à chaque embedding un contexte plus large et produit beaucoup moins de segments à stocker et à rechercher.

La valeur par défaut (30s) offre un équilibre entre les deux.

Vous ne pouvez pas modifier la durée des segments après l'ingestion sans réimporter les données, mais vous pouvez PATCH le datastore et réimporter les données. L'ID de document de chaque fichier est stable, de sorte que la réimportation remplace les anciens segments au lieu de les ajouter.

Audio de la vidéo

Lorsque processing_config.video_processing_config.embedding_config.audio_mode est défini sur ENABLED, l'ingestion gérée utilise le contenu audio des dialogues de la vidéo pour générer des embeddings. La première piste audio est multiplexée dans le même embedding multimodal que le fichier vidéo dans lequel elle est contenue, et une requête de recherche correspond à la vidéo si elle correspond à l'audio du dialogue ou au contenu vidéo.

Seule la première piste audio est utilisée. Si une vidéo comporte plusieurs pistes audio, les autres pistes sont ignorées. Si vous devez utiliser une autre piste audio, ajoutez-la à un fichier vidéo distinct en tant que première piste audio, puis réimportez-la.

URI d'entrée

La propriété JSON gcs_source.input_uris est un tableau de chaînes qui spécifie les entrées d'une requête d'ingestion gérée, par exemple les fichiers à importer depuis votre data store ou les éléments à supprimer de la récupération de l'agent.

Si gcs_source.source_format n'est pas spécifié ou est défini sur SOURCE_FORMAT_UNSPECIFIED (valeur par défaut), les URI d'entrée peuvent être :

  • Un ou plusieurs URI spécifiques.
  • Un ou plusieurs formats contenant des caractères génériques.
  • Un ou plusieurs fichiers texte.
    • Les ID de document sont définis à raison d'un par ligne. Les lignes vides sont ignorées et les espaces sont supprimés de chaque ligne.

Si gcs_source.source_format est défini sur SOURCE_FORMAT_DOCUMENT_JSON, les URI d'entrée sont définis au format JSONL. Pour en savoir plus, consultez Ajouter des métadonnées aux documents.

Caractères génériques

Modèle Correspondances
gs://acme/files/hello_world.xyz Le fichier spécifié.
gs://acme/files/* Tous les fichiers correspondant au document_type spécifié directement dans gs://acme/files/.
gs://acme/files/*.xyz Tous les fichiers portant l'extension .xyz.

Les caractères génériques ne sont pas récursifs. Par exemple, si vous spécifiez gs://acme/files/*, les fichiers situés sous gs://acme/files/2025/ ne seront pas importés. Le caractère générique ** est interprété de la même manière que *. Pour contourner ce problème, vous pouvez aplatir la hiérarchie ou transmettre un modèle par niveau.

Si un format ne correspond pas, la requête échoue. Par exemple, si vous transmettez quatre URI et que l'un d'eux contient une faute de frappe, l'importation ne se poursuit pas avec les trois autres URI. Assurez-vous que chaque URI est correct avant d'effectuer une demande d'importation.

3. Importer vos fichiers

L'étape suivante du pipeline consiste à appeler importDocuments avec les URI des fichiers de votre data store que vous souhaitez ingérer.

Les exemples suivants montrent comment importer des documents.

curl

curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "${INGEST}/dataStores/acme-financials:importDocuments" \
  -d '{
    "gcs_source": {
      "input_uris": ["gs://acme-docs/reports/*"]
    },
    "import_output_config": {
      "error_gcs_prefix": "gs://acme-docs/import-errors/"
    }
  }'

Python

op = session.post(
    INGEST + "/dataStores/acme-financials:importDocuments",
    json={
        "gcs_source": {"input_uris": ["gs://acme-docs/reports/*"]},
        "import_output_config": {
            "error_gcs_prefix": "gs://acme-docs/import-errors/"
        },
    },
).json()

result = wait(op)
print(result["metadata"]["successCount"], "imported")
# failureCount is not set on import metadata; check error files instead.

Vous pouvez éventuellement les importer avec des métadonnées. Pour en savoir plus, consultez Ajouter des métadonnées aux documents.

Les exemples suivants montrent comment importer les fichiers JSONL de métadonnées.

curl

gcloud storage cp docs.jsonl gs://acme-docs/manifests/docs.jsonl
curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "${INGEST}/dataStores/acme-financials:importDocuments" \
  -d '{
    "gcs_source": {
      "input_uris": ["gs://acme-docs/manifests/docs.jsonl"],
      "source_format": "SOURCE_FORMAT_DOCUMENT_JSON"
    },
    "import_output_config": {
      "error_gcs_prefix": "gs://acme-docs/import-errors-json/"
    }
  }'

Python

op = session.post(
    INGEST + "/dataStores/acme-financials:importDocuments",
    json={
        "gcs_source": {
            "input_uris": ["gs://acme-docs/manifests/docs.jsonl"],
            "source_format": "SOURCE_FORMAT_DOCUMENT_JSON",
        },
        "import_output_config": {
            "error_gcs_prefix": "gs://acme-docs/import-errors-json/"
        },
    },
).json()

result = wait(op)

L'ingestion gérée de collections crée

Lorsque vous créez votre data store, l'ingestion gérée crée une collection dans Agent Retrieval à l'aide des API Agent Retrieval publiques. Elle peut être utilisée comme n'importe quelle autre collection Agent Retrieval. La collection est vide jusqu'à la fin de l'opération d'importation.

Pour savoir comment interroger la collection, consultez Rechercher vos fichiers.

L'exemple suivant montre comment obtenir le nom de la collection à partir du data store.

curl

curl -H "${AUTH}" "${INGEST}/dataStores/acme-financials"

Python

data_store = session.get(INGEST + "/dataStores/acme-financials").json()
collection_name = data_store["collectionName"]
print(collection_name)

L'exemple JSON suivant illustre une réponse type.

{
  "name": "projects/acme-prod/locations/us-east4/dataStores/acme-financials",
  "documentType": "UNSTRUCTURED",
  "state": "ACTIVE",
  "collectionName": "projects/acme-prod/locations/us-east4/collections/google-acme-financials"
}

Suivre la progression de l'importation

Pour suivre la progression du job d'importation, interrogez l'opération au lieu de vérifier l'état du bucket. Le champ successCount de la réponse indique le nombre de fichiers qui ont bien été importés.

Vous pouvez corriger les erreurs et envoyer une autre demande d'importation pour réessayer. Pour en savoir plus, consultez Réexécuter une opération d'importation.

Les exemples suivants montrent comment interroger l'opération.

curl

curl -H "${AUTH}" "${BASE}/{OPERATION_NAME}"

Python

# To check once, without blocking, using the op returned by the import call:
status = session.get(BASE + "/" + op["name"]).json()
print(status.get("done"), status.get("metadata", {}))

L'exemple suivant montre comment obtenir la liste des fichiers importés une fois l'opération d'importation terminée.

curl

curl -H "${AUTH}" "${INGEST}/dataStores/acme-financials/documents"

Python

docs = session.get(INGEST + "/dataStores/acme-financials/documents").json()
print(len(docs.get("documents", [])))

Réexécuter une opération d'importation

L'exécution d'opérations d'importation supplémentaires sur le même bucket ne traite que les fichiers qui ont été modifiés ou ajoutés. Un fichier qui a déjà été importé et qui n'a pas été modifié est ignoré.

La collection créée par l'ingestion gérée est identique à une collection Agent Retrieval standard. Vous pouvez l'interroger et filtrer les résultats, reclasser, indexer, et plus encore.

Exemples

L'exemple suivant montre comment rechercher le contenu de fichiers importés à partir d'un data store.

curl

COLLECTION=projects/${PROJECT}/locations/${LOCATION}/collections/google-acme-financials

curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
  "https://vectorsearch.googleapis.com/v1/${COLLECTION}/dataObjects:search" \
  -d '{
    "semantic_search": {
      "search_text": "what is the total revenue?",
      "search_field": "multimodal_embedding",
      "task_type": "RETRIEVAL_QUERY",
      "top_k": 10,
      "output_fields": {
        "data_fields": ["google_document_id", "google_customer_uri", "google_unstructured_details.content_snippet"]
      }
    }
  }'

Python

from google.cloud import vectorsearch_v1

# Create the client
search_client = vectorsearch_v1.DataObjectSearchServiceClient()

# Initialize request argument(s)
semantic_search = vectorsearch_v1.SemanticSearch(
    search_text="what is the total revenue?",
    search_field="multimodal_embedding",
    task_type=vectorsearch_v1.EmbeddingTaskType.RETRIEVAL_QUERY,
    top_k=10,
    output_fields=vectorsearch_v1.OutputFields(
        data_fields=["google_document_id", "google_customer_uri", "google_unstructured_details.content_snippet"],
    ),
)
request = vectorsearch_v1.SearchDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    semantic_search=semantic_search,
)

# Make the request
response = search_client.search_data_objects(request=request)

# Handle the response
for hit in response.results:
    data = dict(hit.data_object.data)
    print(hit.distance, data["google_customer_uri"][0])
    print(data["google_unstructured_details"]["content_snippet"][:200])

Le parent est l'ID de la collection, et non du data store. Utilisez le nom de la collection obtenu dans la section précédente.

search_field doit être multimodal_embedding, que le data store contienne des fichiers de document ou de vidéo.

Résultats de recherche

Vous devez spécifier output_fields dans votre requête de recherche pour indiquer les propriétés que vous souhaitez renvoyer. Si vous ne spécifiez pas output_fields, seuls distance et data_object_id sont renvoyés.

Les résultats de recherche peuvent contenir les propriétés suivantes :

Propriété Type Description
google_document_id string Document d'où provient le segment.
google_customer_uri tableau de chaînes Votre URI gs:// d'origine pour la citation.
google_modality string UNSTRUCTURED ou VIDEO.
google_unstructured_details objet Détails du contenu non structuré. Vide si google_modality est défini sur VIDEO.
google_unstructured_details.content_snippet string Texte du segment.
google_unstructured_details.start_page/end_page entier Plage de pages du fragment. Renseigné uniquement avec la segmentation de page, qui nécessite une analyse numérique. Vide pour la segmentation de fragments.
google_video_details objet Détails du contenu vidéo. Vide si google_modality est défini sur UNSTRUCTURED.
google_video_details.start_offset_nanos/end_offset_nanos entier Durée d'un segment vidéo en nanosecondes.
multimodal_embedding Vectoriel, dense, 768 dimensions Embedding de fragment de gemini-embedding-2.
metadata objet Copié du document vers chacun de ses segments, sans préfixe et imbriqué comme déclaré (par exemple, category ou issuer.country).

Pour les fichiers de document, start_page et end_page ne sont renseignés que si la segmentation de page a été spécifiée lors de la création du data store.

Les décalages sont exprimés en nanosecondes et sont relatifs à la vidéo source. Divisez par 1 000 000 000 pour obtenir les secondes dont vous avez besoin pour créer un lien profond ou une recherche de lecteur.

Les propriétés de metadata correspondent au schéma JSON fourni lors de l'importation.

Pour les fichiers vidéo, plusieurs segments consécutifs de la même vidéo correspondent souvent à une requête. Regroupez les correspondances par google_document_id et conservez la première start_offset_nanos de chaque exécution si vous souhaitez obtenir un résultat par scène plutôt qu'un résultat par segment.

Supprimer définitivement des fichiers

Pour supprimer un fichier d'un data store, importez un ou plusieurs fichiers texte dans Cloud Storage, chaque ligne contenant l'ID d'un fichier que vous souhaitez supprimer. Transmettez les URI des fichiers texte à un purgeDocuments.

La réponse n'indique pas quels fichiers sont purgés. Pour vérifier qu'un fichier a été purgé, appelez GetDocument. La réponse renvoie l'état 404.

Définissez force sur false pour tester d'abord l'opération de suppression. Cette opération consigne les fichiers qui seront purgés dans le error_gcs_prefix que vous spécifiez.

Une fois les fichiers purgés, vous pouvez supprimer le datastore qui les contient.

Les exemples suivants montrent comment purger des fichiers.

curl

curl -X POST -H "${AUTH}" -H "Content-Type: application/json" \
"${INGEST}/dataStores/acme:purgeDocuments" \
-d '{
  "gcs_source": {
    "input_uris": ["gs://acme/purge/purge-ids.txt"]
  },
  "purge_output_config": {
    "error_gcs_prefix": "gs://acme/purge-force-errors/"
  },
  "force": true
}'

Python

op = session.post(
  INGEST + "/dataStores/acme:purgeDocuments",
  json={
      "gcs_source": {
            "input_uris": ["gs://acme/purge/purge-ids.txt"],
        },
        "purge_output_config": {
            "error_gcs_prefix": "gs://acme/purge-force-errors/",
        },
        "force": True,
    },
).json()

result = wait(op)

Supprimer un data store

Envoyez une requête DELETE avec l'URI du data store pour le supprimer. Si force est défini sur true et que le data store contient toujours des fichiers, la requête échoue avec l'état FAILED_PRECONDITION et le message DataStore deletion is not allowed because it still contains documents. Set force=true to delete the DataStore and all its Documents..

Définissez backing_collection_deleted sur true pour supprimer la collection et les objets de données créés après l'importation du data store. Si ce n'est pas fait, la collection et les objets de données sont conservés et continuent d'utiliser le quota. Toute requête de création d'un datastore avec le même ID échouera avec le message FAILED_PRECONDITION (BACKING_COLLECTION_ALREADY_EXISTS).

Lorsque la requête de suppression est en cours d'exécution, une requête get renvoie l'état DELETING et une erreur 404 une fois l'opération terminée.

L'exemple suivant montre comment supprimer un data store.

curl

curl -X DELETE -H "${AUTH}" \
  "${INGEST}/dataStores/acme-financials?force=true&backing_collection_deleted=true"

Python

op = session.delete(
  INGEST + "/dataStores/acme-financials",
  params={"force": "true", "backing_collection_deleted": "true"},
).json()

result = wait(op)