Ricerca file

L'API Gemini consente la Retrieval Augmented Generation ("RAG") tramite lo strumento di ricerca file. La ricerca di file importa, suddivide in blocchi e indicizza i tuoi dati per consentire il recupero rapido di informazioni pertinenti in base al prompt di un utente. Queste informazioni vengono poi fornite come contesto al modello, consentendogli di fornire risposte più accurate e pertinenti.

Puoi utilizzare l'API uploadToFileSearchStore per caricare direttamente un file esistente nel tuo archivio di ricerca dei file oppure caricare e importare separatamente un file se vuoi creare il file contemporaneamente.

Caricamento diretto nell'archivio di ricerca dei file

Questo esempio mostra come caricare direttamente un file in un archivio di file:

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)

Importazione di file

In alternativa, puoi caricare un file esistente e importarlo nell'archivio file:

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)

Configurazione del chunking

Quando importi un file in un archivio di ricerca dei file, questo viene suddiviso automaticamente in blocchi, incorporato, indicizzato e caricato nell'archivio di ricerca dei file. Se hai bisogno di un maggiore controllo sulla strategia di suddivisione, puoi specificare un'impostazione chunking_config per impostare un numero massimo di token per blocco e un numero massimo di token sovrapposti.

# 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
          }
        }
    }
)

Per utilizzare l'archivio di ricerca dei file, passalo come strumento al metodo generateContent, come mostrato negli esempi di caricamento e importazione.

Come funziona

La ricerca di file utilizza una tecnica chiamata ricerca semantica per trovare informazioni pertinenti al prompt dell'utente. A differenza della tradizionale ricerca basata su parole chiave, la ricerca semantica comprende il significato e il contesto della query.

Quando importi un file, questo viene convertito in rappresentazioni numeriche chiamate embedding, che acquisiscono il significato semantico del testo. Questi incorporamenti vengono archiviati in un database di ricerca di file specializzato. Quando esegui una query, viene convertita anche in un embedding. Il sistema esegue quindi una ricerca di file per trovare i blocchi di documenti più simili e pertinenti nell'archivio di ricerca dei file.

Ecco una suddivisione della procedura per utilizzare l'API File Search uploadToFileSearchStore:

1. Crea un archivio di ricerca di file: un archivio di ricerca di file contiene i dati elaborati dai tuoi file. È il contenitore persistente per gli embedding su cui opererà la ricerca semantica.

2. Carica un file e importalo in un archivio di ricerca di file: carica contemporaneamente un file e importa i risultati nell'archivio di ricerca di file. In questo modo viene creato un oggetto File temporaneo, che è un riferimento al documento non elaborato. Questi dati vengono poi suddivisi in blocchi, convertiti in embedding di ricerca di file e indicizzati. L'oggetto File viene eliminato dopo 48 ore, mentre i dati importati nell'archivio di ricerca dei file verranno archiviati a tempo indeterminato finché non scegli di eliminarli.

3. Query con la ricerca di file: infine, utilizzi lo strumento FileSearch in una chiamata generateContent. Nella configurazione dello strumento, specifichi un FileSearchRetrievalResource, che punta al FileSearchStore che vuoi cercare. In questo modo, il modello esegue una ricerca semantica nell'archivio di ricerca di file specifico per trovare informazioni pertinenti su cui basare la risposta.

In questo diagramma, la linea tratteggiata da Documenti a Modello di incorporamento (utilizzando gemini-embedding-001) rappresenta l'API uploadToFileSearchStore (ignorando Archiviazione file). In caso contrario, l'utilizzo dell'API Files per creare e poi importare separatamente i file sposta il processo di indicizzazione da Documenti a Spazio di archiviazione file e poi a Modello di incorporamento.

Archivi di ricerca file

Un archivio di ricerca di file è un contenitore per gli incorporamenti dei documenti. Mentre i file non elaborati caricati tramite l'API File vengono eliminati dopo 48 ore, i dati importati in un archivio di ricerca dei file vengono archiviati a tempo indeterminato finché non li elimini manualmente. Puoi creare più archivi di ricerca di file per organizzare i tuoi documenti. L'API FileSearchStore consente di creare, elencare, ottenere ed eliminare per gestire i tuoi archivi di ricerca di file. I nomi degli store di ricerca dei file hanno ambito globale.

Ecco alcuni esempi di come gestire gli archivi di ricerca dei file:

# 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})

File di metadati

Puoi aggiungere metadati personalizzati ai tuoi file per filtrarli o fornire un contesto aggiuntivo. I metadati sono un insieme di coppie chiave-valore.

# 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}
    ]
)

È utile quando hai più documenti in un archivio di ricerca di file e vuoi cercare solo un sottoinsieme.

# 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)

Le indicazioni per l'implementazione della sintassi dei filtri di elenco per metadata_filter sono disponibili all'indirizzo google.aip.dev/160

Citazioni

Quando utilizzi la ricerca di file, la risposta del modello potrebbe includere citazioni che specificano quali parti dei documenti caricati sono state utilizzate per generare la risposta. Ciò favorisce la verifica dei fatti.

Puoi accedere alle informazioni sulle citazioni tramite l'attributo grounding_metadata della risposta.

print(response.candidates[0].grounding_metadata)

Modelli supportati

I seguenti modelli supportano la ricerca di file:

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

Tipi di file supportati

La ricerca di file supporta un'ampia gamma di formati di file, elencati nelle sezioni seguenti.

Limiti di frequenza

L'API File Search presenta i seguenti limiti per garantire la stabilità del servizio:

• Dimensioni massime del file / limite per documento: 100 MB
• Ricerca di file memorizzati per progetto: 10
• Dimensioni totali degli archivi di ricerca dei file di progetto (in base al livello utente):
  • Senza costi: 1 GB
  • Livello 1: 10 GB
  • Livello 2: 100 GB
  • Livello 3: 1 TB
• Consiglio: limita le dimensioni di ogni archivio di ricerca dei file a meno di 20 GB per garantire latenze di recupero ottimali.

Prezzi

• Gli sviluppatori pagano gli incorporamenti al momento dell'indicizzazione in base ai prezzi degli incorporamenti (0,15 $ per 1 milione di token).
• Il deposito è senza costi.
• Gli embedding al momento della query sono senza costi.
• I token del documento recuperati vengono addebitati come token di contesto� normali.