Recherche de fichiers

L'API Gemini permet la génération augmentée par récupération (RAG) grâce à l'outil de recherche de fichiers. La recherche de fichiers importe, segmente et indexe vos données pour permettre une récupération rapide des informations pertinentes en fonction de la requête d'un utilisateur. Ces informations sont ensuite fournies au modèle en tant que contexte, ce qui lui permet de fournir des réponses plus précises et pertinentes.

Vous pouvez utiliser l'API uploadToFileSearchStore pour importer directement un fichier existant dans votre data store de recherche de fichiers, ou importer un fichier séparément après l'avoir importé si vous souhaitez le créer en même temps.

Importer directement dans le magasin de recherche de fichiers

Cet exemple montre comment importer directement un fichier dans un magasin de fichiers :

from google import genai
from google.genai import types
import time

client = genai.Client()

# Create the file search store with an optional display name that shows in the grounding metadata
file_search_store = client.file_search_stores.create(config={'display_name': 'your-fileSearchStore-name'})

# Upload and import a file into the file search store, supply a unique file name which will be visible in citations
operation = client.file_search_stores.upload_to_file_search_store(
  file='path/to/your/file.txt',
  file_search_store_name='unique_file_name'
)

# Wait until import is complete
while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

# Ask a question about the file
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Can you tell me about Robert Graves""",
    config=types.GenerateContentConfig(
        tools=[
            file_search=(
                  file_search_store_names=[file_search_store.name]
            )
        ]
    )
)

print(response.text)

Importation de fichiers

Vous pouvez également importer un fichier existant dans votre espace de stockage de fichiers :

from google import genai
from google.genai import types
import time

client = genai.Client()

# Upload the file using the Files API, supply a unique file name which will be visible in citations
sample_file = client.files.upload(file='sample.txt', config={'name': 'unique_file_name'})

# Create the file search store with an optional display name that shows in the grounding metadata
file_search_store = client.file_search_stores.create(config={'display_name': 'your-fileSearchStore-name'})

# Import the file into the file search store
operation = client.file_search_stores.import_file(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name
)

# Wait until import is complete
while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

# Ask a question about the file
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Can you tell me about Robert Graves""",
    config=types.GenerateContentConfig(
        tools=[
            file_search=(
                  file_search_store_names=[file_search_store.name]
            )
        ]
    )
)

print(response.text)

Configuration de la fragmentation

Lorsque vous importez un fichier dans un magasin de recherche de fichiers, il est automatiquement divisé en blocs, intégré, indexé et importé dans votre magasin de recherche de fichiers. Si vous avez besoin de plus de contrôle sur la stratégie de segmentation, vous pouvez spécifier un paramètre chunking_config pour définir un nombre maximal de jetons par segment et un nombre maximal de jetons qui se chevauchent.

# Upload and import and upload the file into the file search store with a custom chunking configuration
operation = client.file_search_stores.upload_to_file_search_store(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name,
    config={
        'chunking_config': {
          'white_space_config': {
            'max_tokens_per_chunk': 200,
            'max_overlap_tokens': 20
          }
        }
    }
)

Pour utiliser votre magasin de recherche de fichiers, transmettez-le en tant qu'outil à la méthode generateContent, comme indiqué dans les exemples Importer et Importer.

Fonctionnement

La recherche de fichiers utilise une technique appelée recherche sémantique pour trouver des informations pertinentes par rapport à la requête de l'utilisateur. Contrairement à la recherche traditionnelle basée sur les mots clés, la recherche sémantique comprend la signification et le contexte de votre requête.

Lorsque vous importez un fichier, il est converti en représentations numériques appelées embeddings, qui capturent la signification sémantique du texte. Ces embeddings sont stockés dans une base de données de recherche de fichiers spécialisée. Lorsque vous effectuez une requête, elle est également convertie en embedding. Le système effectue ensuite une recherche de fichiers pour trouver les blocs de documents les plus similaires et les plus pertinents dans le magasin de recherche de fichiers.

Voici le détail du processus d'utilisation de l'API File Search uploadToFileSearchStore :

1. Créez un datastore de recherche de fichiers : un datastore de recherche de fichiers contient les données traitées de vos fichiers. Il s'agit du conteneur persistant pour les embeddings sur lesquels la recherche sémantique fonctionnera.

2. Importer un fichier et l'ajouter à un magasin de recherche de fichiers : importez simultanément un fichier et les résultats dans votre magasin de recherche de fichiers. Cela crée un objet File temporaire, qui est une référence à votre document brut. Ces données sont ensuite segmentées, converties en embeddings de recherche de fichiers et indexées. L'objet File est supprimé au bout de 48 heures, tandis que les données importées dans le fichier de recherche sont stockées indéfiniment, jusqu'à ce que vous décidiez de les supprimer.

3. Interroger avec la recherche de fichiers : enfin, vous utilisez l'outil FileSearch dans un appel generateContent. Dans la configuration de l'outil, vous spécifiez un FileSearchRetrievalResource qui pointe vers le FileSearchStore que vous souhaitez rechercher. Cela indique au modèle d'effectuer une recherche sémantique dans ce magasin de recherche de fichiers spécifique pour trouver des informations pertinentes afin d'ancrer sa réponse.

Dans ce diagramme, la ligne en pointillés allant de Documents à Modèle d'embedding (à l'aide de gemini-embedding-001) représente l'API uploadToFileSearchStore (en contournant Stockage de fichiers). Sinon, l'utilisation de l'API Files pour créer et importer des fichiers séparément déplace le processus d'indexation de Documents vers Stockage de fichiers, puis vers Modèle d'embedding.

Magasins de recherche de fichiers

Un magasin de recherche de fichiers est un conteneur pour vos embeddings de documents. Les fichiers bruts importés via l'API File sont supprimés au bout de 48 heures, mais les données importées dans un magasin de recherche de fichiers sont stockées indéfiniment jusqu'à ce que vous les supprimiez manuellement. Vous pouvez créer plusieurs magasins de recherche de fichiers pour organiser vos documents. L'API FileSearchStore vous permet de créer, de lister, d'obtenir et de supprimer des magasins de recherche de fichiers pour les gérer. Les noms des magasins de recherche de fichiers ont une portée globale.

Voici quelques exemples de gestion de vos magasins de recherche de fichiers :

# Create a file search store (including optional display_name for easier reference)
file_search_store = client.file_search_stores.create(config={'display_name': 'my-file_search-store-123'})

# List all your file search stores
for file_search_store in client.file_search_stores.list():
    print(file_search_store)

# Get a specific file search store by name
my_file_search_store = client.file_search_stores.get(name='fileSearchStores/my-file_search-store-123')

# Delete a file search store
client.file_search_stores.delete(name='fileSearchStores/my-file_search-store-123', config={'force': True})

Métadonnées des fichiers

Vous pouvez ajouter des métadonnées personnalisées à vos fichiers pour les filtrer ou fournir un contexte supplémentaire. Les métadonnées sont un ensemble de paires clé/valeur.

# Import the file into the file search store with custom metadata
op = client.file_search_stores.import_file(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name,
    custom_metadata=[
        {"key": "author", "string_value": "Robert Graves"},
        {"key": "year", "numeric_value": 1934}
    ]
)

Cela est utile lorsque vous avez plusieurs documents dans un magasin de recherche de fichiers et que vous souhaitez n'en rechercher qu'un sous-ensemble.

# Use the metadata filter to search within a subset of documents
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Tell me about the book 'I, Claudius'""",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                file_search=types.FileSearch(
                  file_search_store_names=[file_search_store.name],
                  metadata_filter = 'author=Robet Graves',
                  )
            )
        ]
    )
)

print(response.text)

Pour savoir comment implémenter la syntaxe des filtres de liste pour metadata_filter, consultez google.aip.dev/160.

Citations

Lorsque vous utilisez la recherche de fichiers, la réponse du modèle peut inclure des citations qui précisent les parties de vos documents importés qui ont été utilisées pour générer la réponse. Cela permet de vérifier les faits.

Vous pouvez accéder aux informations de citation via l'attribut grounding_metadata de la réponse.

print(response.candidates[0].grounding_metadata)

Modèles compatibles

Les modèles suivants sont compatibles avec la recherche de fichiers :

• gemini-2.5-pro
• gemini-2.5-flash

Types de fichiers compatibles

La recherche de fichiers est compatible avec un large éventail de formats de fichiers, listés dans les sections suivantes.

Limites de débit

Pour assurer la stabilité du service, l'API File Search est soumise aux limites suivantes :

• Taille maximale des fichiers / limite par document : 100 Mo
• Nombre de recherches de fichiers stockées par projet : 10
• Taille totale des espaces de stockage de recherche de fichiers de projet (selon le niveau d'utilisateur) :
  • Sans frais : 1 Go
  • Niveau 1 : 10 Go
  • Niveau 2 : 100 Go
  • Niveau 3 : 1 To
• Recommandation : Limitez la taille de chaque magasin de recherche de fichiers à moins de 20 Go pour garantir des latences de récupération optimales.

Tarifs

• Les développeurs sont facturés pour les embeddings au moment de l'indexation, en fonction de la tarification des embeddings existante (0,15 $ par million de jetons).
• Le stockage est sans frais.
• Les embeddings au moment de la requête sont sans frais.
• Les jetons de documents récupérés sont facturés en tant que jetons de contexte standards.