Ricerca file

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

Per rendere la ricerca di file semplice e conveniente per gli sviluppatori, rendiamo senza costi l'archiviazione dei file e la generazione di incorporamenti al momento della query. Paghi solo la creazione degli incorporamenti quando indicizzi per la prima volta i tuoi file (al costo del modello di incorporamento applicabile) e il normale costo dei token di input / output del modello Gemini. Questo nuovo paradigma di fatturazione rende lo strumento di ricerca dei file più semplice ed economico da creare e scalare.

Caricare direttamente nello store di File Search

Questo esempio mostra come caricare direttamente un file nell'archivio di ricerca dei file:

Python

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

client = genai.Client()

# File name will be visible in citations
file_search_store = client.file_search_stores.create(config={'display_name': 'your-fileSearchStore-name'})

operation = client.file_search_stores.upload_to_file_search_store(
  file='sample.txt',
  file_search_store_name=file_search_store.name,
  config={
      'display_name' : 'display-file-name',
  }
)

while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Can you tell me about [insert question]""",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                file_search=types.FileSearch(
                    file_search_store_names=[file_search_store.name]
                )
            )
        ]
    )
)

print(response.text)

JavaScript

const { GoogleGenAI } = require('@google/genai');

const ai = new GoogleGenAI({});

async function run() {
  // File name will be visible in citations
  const fileSearchStore = await ai.fileSearchStores.create({
    config: { displayName: 'your-fileSearchStore-name' }
  });

  let operation = await ai.fileSearchStores.uploadToFileSearchStore({
    file: 'file.txt',
    fileSearchStoreName: fileSearchStore.name,
    config: {
      displayName: 'file-name',
    }
  });

  while (!operation.done) {
    await new Promise(resolve => setTimeout(resolve, 5000));
    operation = await ai.operations.get({ operation });
  }

  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "Can you tell me about [insert question]",
    config: {
      tools: [
        {
          fileSearch: {
            fileSearchStoreNames: [fileSearchStore.name]
          }
        }
      ]
    }
  });

  console.log(response.text);
}

run();

Per saperne di più, consulta il riferimento API per uploadToFileSearchStore.

Importazione di file

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

Python

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

client = genai.Client()

# File name will be visible in citations
sample_file = client.files.upload(file='sample.txt', config={'name': 'display_file_name'})

file_search_store = client.file_search_stores.create(config={'display_name': 'your-fileSearchStore-name'})

operation = client.file_search_stores.import_file(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name
)

while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Can you tell me about [insert question]""",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                file_search=types.FileSearch(
                    file_search_store_names=[file_search_store.name]
                )
            )
        ]
    )
)

print(response.text)

JavaScript

const { GoogleGenAI } = require('@google/genai');

const ai = new GoogleGenAI({});

async function run() {
  // File name will be visible in citations
  const sampleFile = await ai.files.upload({
    file: 'sample.txt',
    config: { name: 'file-name' }
  });

  const fileSearchStore = await ai.fileSearchStores.create({
    config: { displayName: 'your-fileSearchStore-name' }
  });

  let operation = await ai.fileSearchStores.importFile({
    fileSearchStoreName: fileSearchStore.name,
    fileName: sampleFile.name
  });

  while (!operation.done) {
    await new Promise(resolve => setTimeout(resolve, 5000));
    operation = await ai.operations.get({ operation: operation });
  }

  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "Can you tell me about [insert question]",
    config: {
      tools: [
        {
          fileSearch: {
            fileSearchStoreNames: [fileSearchStore.name]
          }
        }
      ]
    }
  });

  console.log(response.text);
}

run();

Per saperne di più, consulta il riferimento API per importFile.

Configurazione del chunking

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

Python

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

JavaScript

let operation = await ai.fileSearchStores.uploadToFileSearchStore({
  file: 'file.txt',
  fileSearchStoreName: fileSearchStore.name,
  config: {
    displayName: 'file-name',
    chunkingConfig: {
      whiteSpaceConfig: {
        maxTokensPerChunk: 200,
        maxOverlapTokens: 20
      }
    }
  }
});

Per utilizzare il tuo negozio di ricerca 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 ricerca standard 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 della ricerca di file.

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

  1. Crea un archivio di ricerca file: un archivio di ricerca 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 file: carica contemporaneamente un file e importa i risultati nell'archivio di ricerca file. Viene creato un oggetto File temporaneo, che è un riferimento al documento non elaborato. Questi dati vengono poi suddivisi in blocchi, convertiti in embedding di File Search e indicizzati. L'oggetto File viene eliminato dopo 48 ore, mentre i dati importati nell'archivio di ricerca dei file vengono archiviati a tempo indeterminato finché non decidi 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 specifico di ricerca di file per trovare informazioni pertinenti su cui basare la risposta.

Il processo di indicizzazione ed esecuzione di query di Ricerca file
Procedura di indicizzazione e query di Ricerca file

In questo diagramma, la linea tratteggiata da Documents a Embedding model (utilizzando gemini-embedding-001) rappresenta l'API uploadToFileSearchStore (ignorando File storage). 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.

Negozi 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 file vengono archiviati a tempo indeterminato finché non li elimini manualmente. Puoi creare più archivi di ricerca 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 file hanno ambito globale.

Ecco alcuni esempi di come gestire i tuoi negozi di ricerca di file:

Python

file_search_store = client.file_search_stores.create(config={'display_name': 'my-file_search-store-123'})

for file_search_store in client.file_search_stores.list():
    print(file_search_store)

my_file_search_store = client.file_search_stores.get(name='fileSearchStores/my-file_search-store-123')

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

JavaScript

const fileSearchStore = await ai.fileSearchStores.create({
  config: { displayName: 'my-file_search-store-123' }
});

const fileSearchStores = await ai.fileSearchStores.list();
for await (const store of fileSearchStores) {
  console.log(store);
}

const myFileSearchStore = await ai.fileSearchStores.get({
  name: 'fileSearchStores/my-file_search-store-123'
});

await ai.fileSearchStores.delete({
  name: 'fileSearchStores/my-file_search-store-123',
  config: { force: true }
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/fileSearchStores?key=${GEMINI_API_KEY}" \
    -H "Content-Type: application/json" 
    -d '{ "displayName": "My Store" }'

curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores?key=${GEMINI_API_KEY}" \

curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123?key=${GEMINI_API_KEY}"

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123?key=${GEMINI_API_KEY}"

Il riferimento API File Search Documents per metodi e campi correlati alla gestione dei documenti nei tuoi archivi di file.

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.

Python

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

JavaScript

let operation = await ai.fileSearchStores.importFile({
  fileSearchStoreName: fileSearchStore.name,
  fileName: sampleFile.name,
  config: {
    customMetadata: [
      { key: "author", stringValue: "Robert Graves" },
      { key: "year", numericValue: 1934 }
    ]
  }
});

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

Python

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=Robert Graves",
                )
            )
        ]
    )
)

print(response.text)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "Tell me about the book 'I, Claudius'",
  config: {
    tools: [
      {
        fileSearch: {
          fileSearchStoreNames: [fileSearchStore.name],
          metadataFilter: 'author="Robert Graves"',
        }
      }
    ]
  }
});

console.log(response.text);

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${GEMINI_API_KEY}" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
            "contents": [{
                "parts":[{"text": "Tell me about the book I, Claudius"}]          
            }],
            "tools": [{
                "file_search": { 
                    "file_search_store_names":["'$STORE_NAME'"],
                    "metadata_filter": "author = \"Robert Graves\""
                }
            }]
        }' 2> /dev/null > response.json

cat response.json

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ò facilita la verifica dei fatti.

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

Python

print(response.candidates[0].grounding_metadata)

JavaScript

console.log(JSON.stringify(response.candidates?.[0]?.groundingMetadata, null, 2));

Modelli supportati

I seguenti modelli supportano la ricerca di file:

Tipi di file supportati

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

Tipi di file dell'applicazione

  • application/dart
  • application/ecmascript
  • application/json
  • application/ms-java
  • application/msword
  • application/pdf
  • application/sql
  • application/typescript
  • application/vnd.curl
  • application/vnd.dart
  • application/vnd.ibm.secure-container
  • application/vnd.jupyter
  • application/vnd.ms-excel
  • application/vnd.oasis.opendocument.text
  • application/vnd.openxmlformats-officedocument.presentationml.presentation
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.wordprocessingml.template
  • application/x-csh
  • application/x-hwp
  • application/x-hwp-v5
  • application/x-latex
  • application/x-php
  • application/x-powershell
  • application/x-sh
  • application/x-shellscript
  • application/x-tex
  • application/x-zsh
  • application/xml
  • application/zip

Tipi di file di testo

  • text/1d-interleaved-parityfec
  • text/RED
  • text/SGML
  • text/cache-manifest
  • text/calendar
  • text/cql
  • text/cql-extension
  • text/cql-identifier
  • text/css
  • text/csv
  • text/csv-schema
  • text/dns
  • text/encaprtp
  • text/enriched
  • text/example
  • text/fhirpath
  • text/flexfec
  • text/fwdred
  • text/gff3
  • text/grammar-ref-list
  • text/hl7v2
  • text/html
  • text/javascript
  • text/jcr-cnd
  • text/jsx
  • text/markdown
  • text/mizar
  • text/n3
  • text/parameters
  • text/parityfec
  • text/php
  • text/plain
  • text/provenance-notation
  • text/prs.fallenstein.rst
  • text/prs.lines.tag
  • text/prs.prop.logic
  • text/raptorfec
  • text/rfc822-headers
  • text/rtf
  • text/rtp-enc-aescm128
  • text/rtploopback
  • text/rtx
  • text/sgml
  • text/shaclc
  • text/shex
  • text/spdx
  • text/strings
  • text/t140
  • text/tab-separated-values
  • text/texmacs
  • text/troff
  • text/tsv
  • text/tsx
  • text/turtle
  • text/ulpfec
  • text/uri-list
  • text/vcard
  • text/vnd.DMClientScript
  • text/vnd.IPTC.NITF
  • text/vnd.IPTC.NewsML
  • text/vnd.a
  • text/vnd.abc
  • text/vnd.ascii-art
  • text/vnd.curl
  • text/vnd.debian.copyright
  • text/vnd.dvb.subtitle
  • text/vnd.esmertec.theme-descriptor
  • text/vnd.exchangeable
  • text/vnd.familysearch.gedcom
  • text/vnd.ficlab.flt
  • text/vnd.fly
  • text/vnd.fmi.flexstor
  • text/vnd.gml
  • text/vnd.graphviz
  • text/vnd.hans
  • text/vnd.hgl
  • text/vnd.in3d.3dml
  • text/vnd.in3d.spot
  • text/vnd.latex-z
  • text/vnd.motorola.reflex
  • text/vnd.ms-mediapackage
  • text/vnd.net2phone.commcenter.command
  • text/vnd.radisys.msml-basic-layout
  • text/vnd.senx.warpscript
  • text/vnd.sosi
  • text/vnd.sun.j2me.app-descriptor
  • text/vnd.trolltech.linguist
  • text/vnd.wap.si
  • text/vnd.wap.sl
  • text/vnd.wap.wml
  • text/vnd.wap.wmlscript
  • text/vtt
  • text/wgsl
  • text/x-asm
  • text/x-bibtex
  • text/x-boo
  • text/x-c
  • text/x-c++hdr
  • text/x-c++src
  • text/x-cassandra
  • text/x-chdr
  • text/x-coffeescript
  • text/x-component
  • text/x-csh
  • text/x-csharp
  • text/x-csrc
  • text/x-cuda
  • text/x-d
  • text/x-diff
  • text/x-dsrc
  • text/x-emacs-lisp
  • text/x-erlang
  • text/x-gff3
  • text/x-go
  • text/x-haskell
  • text/x-java
  • text/x-java-properties
  • text/x-java-source
  • text/x-kotlin
  • text/x-lilypond
  • text/x-lisp
  • text/x-literate-haskell
  • text/x-lua
  • text/x-moc
  • text/x-objcsrc
  • text/x-pascal
  • text/x-pcs-gcd
  • text/x-perl
  • text/x-perl-script
  • text/x-python
  • text/x-python-script
  • text/x-r-markdown
  • text/x-rsrc
  • text/x-rst
  • text/x-ruby-script
  • text/x-rust
  • text/x-sass
  • text/x-scala
  • text/x-scheme
  • text/x-script.python
  • text/x-scss
  • text/x-setext
  • text/x-sfv
  • text/x-sh
  • text/x-siesta
  • text/x-sos
  • text/x-sql
  • text/x-swift
  • text/x-tcl
  • text/x-tex
  • text/x-vbasic
  • text/x-vcalendar
  • text/xml
  • text/xml-dtd
  • text/xml-external-parsed-entity
  • text/yaml

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
  • 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 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 normali token di contesto.

Passaggi successivi