L'API Gemini consente la Retrieval-Augmented Generation ("RAG") tramite lo strumento Ricerca file. Ricerca file importa, suddivide in blocchi e indicizza i 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 Ricerca file semplice e conveniente per gli sviluppatori, stiamo rendendo senza costi l'archiviazione dei file e la generazione di embedding al momento della query. Paghi solo per la creazione di embedding quando indicizzi i file per la prima volta (al costo del modello di embedding applicabile) e per il costo normale dei token di input / output del modello Gemini. Questo nuovo paradigma di fatturazione rende lo strumento Ricerca file più semplice ed economico da creare e scalare con.
Caricare direttamente nell'archivio di Ricerca file
Questo esempio mostra come caricare direttamente un file nell'archivio di ricerca 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-3-flash-preview",
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-3-flash-preview",
contents: "Can you tell me about [insert question]",
config: {
tools: [
{
fileSearch: {
fileSearchStoreNames: [fileSearchStore.name]
}
}
]
}
});
console.log(response.text);
}
run();
Per ulteriori informazioni, consulta il riferimento API per uploadToFileSearchStore.
Importazione di file
In alternativa, puoi caricare un file esistente e importarlo nell'archivio di ricerca 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-3-flash-preview",
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-3-flash-preview",
contents: "Can you tell me about [insert question]",
config: {
tools: [
{
fileSearch: {
fileSearchStoreNames: [fileSearchStore.name]
}
}
]
}
});
console.log(response.text);
}
run();
Per ulteriori informazioni, consulta il riferimento API per importFile.
Configurazione della suddivisione in blocchi
Quando importi un file in un archivio di Ricerca file, 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'
chunking_config impostazione
per impostare un numero massimo di token per blocco e un numero massimo di token sovrapposti.
Python
from google import genai
from google.genai import types
import time
client = genai.Client()
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
}
}
}
)
while not operation.done:
time.sleep(5)
operation = client.operations.get(operation)
print("Custom chunking complete.")
JavaScript
const { GoogleGenAI } = require('@google/genai');
const ai = new GoogleGenAI({});
let operation = await ai.fileSearchStores.uploadToFileSearchStore({
file: 'file.txt',
fileSearchStoreName: fileSearchStore.name,
config: {
displayName: 'file-name',
chunkingConfig: {
whiteSpaceConfig: {
maxTokensPerChunk: 200,
maxOverlapTokens: 20
}
}
}
});
while (!operation.done) {
await new Promise(resolve => setTimeout(resolve, 5000));
operation = await ai.operations.get({ operation });
}
console.log("Custom chunking complete.");
Per utilizzare l'archivio di Ricerca file, passalo come strumento al generateContent
metodo, come mostrato negli esempi di caricamento e importazione.
Come funziona
Ricerca 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, viene convertito in rappresentazioni numeriche chiamate embedding, che acquisiscono il significato semantico de l testo. Questi embedding vengono archiviati in un database di Ricerca file specializzato. Quando esegui una query, viene convertita anche in un embedding. Il sistema esegue quindi una ricerca file per trovare i blocchi di documenti più simili e pertinenti dall'archivio di Ricerca file.
Non esiste un Time To Live (TTL) per gli embedding e i file; rimangono finché non vengono eliminati manualmente o quando il modello viene ritirato.
Ecco una suddivisione della procedura per l'utilizzo dell'API Ricerca file
uploadToFileSearchStore:
Crea un archivio di Ricerca file: un archivio di Ricerca file contiene i dati elaborati dei file. È il container persistente per gli embedding su cui opererà la ricerca semantica.
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 temporaneo
File, che è un riferimento al documento non elaborato. Questi dati vengono quindi suddivisi in blocchi, convertiti in embedding di Ricerca file e indicizzati. L'oggettoFileviene eliminato dopo 48 ore, mentre i dati importati nell'archivio di Ricerca file vengono archiviati a tempo indeterminato finché non scegli di eliminarli.Esegui query con Ricerca file: infine, utilizza lo strumento
FileSearchin una chiamatagenerateContent. Nella configurazione dello strumento, specifica unFileSearchRetrievalResource, che rimanda alFileSearchStorein cui vuoi eseguire la ricerca. In questo modo, il modello esegue una ricerca semantica nell'archivio di Ricerca file specifico per trovare informazioni pertinenti per basare la risposta.
In questo diagramma, la linea tratteggiata da Documenti a Modello di embedding
(utilizzando gemini-embedding-001)
rappresenta l'API uploadToFileSearchStore (ignorando Archiviazione file).
In caso contrario, l'utilizzo dell'API Files per creare
e poi importare i file separatamente sposta la procedura di indicizzazione da Documenti a
Archiviazione file e poi a Modello di embedding.
Archivi di Ricerca file
Un archivio di Ricerca file è un container per gli embedding dei documenti. Sebbene i file non elaborati
caricati tramite l'API Files vengano 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 documenti. L'API
FileSearchStore consente di creare, elencare, recuperare ed eliminare gli archivi di ricerca file. I nomi degli archivi di Ricerca file hanno un ambito globale.
Ecco alcuni esempi di come gestire gli archivi di Ricerca 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}"
Documenti di ricerca file
Puoi gestire i singoli documenti negli archivi di file con l'
API File Search Documents per list ogni documento
in un archivio di ricerca file, get informazioni su un documento e delete un
documento per nome.
Python
for document_in_store in client.file_search_stores.documents.list(parent='fileSearchStores/my-file_search-store-123'):
print(document_in_store)
file_search_document = client.file_search_stores.documents.get(name='fileSearchStores/my-file_search-store-123/documents/my_doc')
print(file_search_document)
client.file_search_stores.documents.delete(name='fileSearchStores/my-file_search-store-123/documents/my_doc')
JavaScript
const documents = await ai.fileSearchStores.documents.list({
parent: 'fileSearchStores/my-file_search-store-123'
});
for await (const doc of documents) {
console.log(doc);
}
const fileSearchDocument = await ai.fileSearchStores.documents.get({
name: 'fileSearchStores/my-file_search-store-123/documents/my_doc'
});
await ai.fileSearchStores.documents.delete({
name: 'fileSearchStores/my-file_search-store-123/documents/my_doc'
});
REST
curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123/documents?key=${GEMINI_API_KEY}"
curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123/documents/my_doc?key=${GEMINI_API_KEY}"
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123/documents/my_doc?key=${GEMINI_API_KEY}"
File di metadati
Puoi aggiungere metadati personalizzati ai 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 }
]
}
});
Questa funzionalità è utile quando hai più documenti in un archivio di Ricerca file e vuoi cercare solo un sottoinsieme di documenti.
Python
response = client.models.generate_content(
model="gemini-3-flash-preview",
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-3-flash-preview",
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-3-flash-preview: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 sull'implementazione della sintassi del filtro di elenco per metadata_filter sono disponibili
all'indirizzo google.aip.dev/160
Citazioni
Quando utilizzi Ricerca file, la risposta del modello può includere citazioni che specificano quali parti dei documenti caricati sono state utilizzate per generare la risposta. Ciò aiuta a verificare i 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));
Output strutturato
A partire dai modelli Gemini 3, puoi combinare lo strumento di ricerca file con output strutturati.
Python
from pydantic import BaseModel, Field
class Money(BaseModel):
amount: str = Field(description="The numerical part of the amount.")
currency: str = Field(description="The currency of amount.")
response = client.models.generate_content(
model="gemini-3-flash-preview",
contents="What is the minimum hourly wage in Tokyo right now?",
config=types.GenerateContentConfig(
tools=[
types.Tool(
file_search=types.FileSearch(
file_search_store_names=[file_search_store.name]
)
)
],
response_mime_type="application/json",
response_schema=Money.model_json_schema()
)
)
result = Money.model_validate_json(response.text)
print(result)
JavaScript
import { z } from "zod";
const moneySchema = z.object({
amount: z.string().describe("The numerical part of the amount."),
currency: z.string().describe("The currency of amount."),
});
async function run() {
const response = await ai.models.generateContent({
model: "gemini-3-flash-preview",
contents: "What is the minimum hourly wage in Tokyo right now?",
config: {
tools: [
{
fileSearch: {
fileSearchStoreNames: [file_search_store.name],
},
},
],
responseMimeType: "application/json",
responseJsonSchema: z.toJSONSchema(moneySchema),
},
});
const result = moneySchema.parse(JSON.parse(response.text));
console.log(result);
}
run();
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [{"text": "What is the minimum hourly wage in Tokyo right now?"}]
}],
"tools": [
{
"fileSearch": {
"fileSearchStoreNames": ["$FILE_SEARCH_STORE_NAME"]
}
}
],
"generationConfig": {
"responseMimeType": "application/json",
"responseJsonSchema": {
"type": "object",
"properties": {
"amount": {"type": "string", "description": "The numerical part of the amount."},
"currency": {"type": "string", "description": "The currency of amount."}
},
"required": ["amount", "currency"]
}
}
}'
Modelli supportati
I seguenti modelli supportano Ricerca file:
| Modello | Ricerca file |
|---|---|
| Gemini 3.1 Pro (anteprima) | ✔️ |
| Gemini 3 Flash (anteprima) | ✔️ |
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
Tipi di file supportati
Ricerca file supporta un'ampia gamma di formati di file, elencati nelle seguenti sezioni.
Tipi di file di applicazione
application/dartapplication/ecmascriptapplication/jsonapplication/ms-javaapplication/mswordapplication/pdfapplication/sqlapplication/typescriptapplication/vnd.curlapplication/vnd.dartapplication/vnd.ibm.secure-containerapplication/vnd.jupyterapplication/vnd.ms-excelapplication/vnd.oasis.opendocument.textapplication/vnd.openxmlformats-officedocument.presentationml.presentationapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheetapplication/vnd.openxmlformats-officedocument.wordprocessingml.documentapplication/vnd.openxmlformats-officedocument.wordprocessingml.templateapplication/x-cshapplication/x-hwpapplication/x-hwp-v5application/x-latexapplication/x-phpapplication/x-powershellapplication/x-shapplication/x-shellscriptapplication/x-texapplication/x-zshapplication/xmlapplication/zip
Tipi di file di testo
text/1d-interleaved-parityfectext/REDtext/SGMLtext/cache-manifesttext/calendartext/cqltext/cql-extensiontext/cql-identifiertext/csstext/csvtext/csv-schematext/dnstext/encaprtptext/enrichedtext/exampletext/fhirpathtext/flexfectext/fwdredtext/gff3text/grammar-ref-listtext/hl7v2text/htmltext/javascripttext/jcr-cndtext/jsxtext/markdowntext/mizartext/n3text/parameterstext/parityfectext/phptext/plaintext/provenance-notationtext/prs.fallenstein.rsttext/prs.lines.tagtext/prs.prop.logictext/raptorfectext/rfc822-headerstext/rtftext/rtp-enc-aescm128text/rtploopbacktext/rtxtext/sgmltext/shaclctext/shextext/spdxtext/stringstext/t140text/tab-separated-valuestext/texmacstext/trofftext/tsvtext/tsxtext/turtletext/ulpfectext/uri-listtext/vcardtext/vnd.DMClientScripttext/vnd.IPTC.NITFtext/vnd.IPTC.NewsMLtext/vnd.atext/vnd.abctext/vnd.ascii-arttext/vnd.curltext/vnd.debian.copyrighttext/vnd.dvb.subtitletext/vnd.esmertec.theme-descriptortext/vnd.exchangeabletext/vnd.familysearch.gedcomtext/vnd.ficlab.flttext/vnd.flytext/vnd.fmi.flexstortext/vnd.gmltext/vnd.graphviztext/vnd.hanstext/vnd.hgltext/vnd.in3d.3dmltext/vnd.in3d.spottext/vnd.latex-ztext/vnd.motorola.reflextext/vnd.ms-mediapackagetext/vnd.net2phone.commcenter.commandtext/vnd.radisys.msml-basic-layouttext/vnd.senx.warpscripttext/vnd.sositext/vnd.sun.j2me.app-descriptortext/vnd.trolltech.linguisttext/vnd.wap.sitext/vnd.wap.sltext/vnd.wap.wmltext/vnd.wap.wmlscripttext/vtttext/wgsltext/x-asmtext/x-bibtextext/x-bootext/x-ctext/x-c++hdrtext/x-c++srctext/x-cassandratext/x-chdrtext/x-coffeescripttext/x-componenttext/x-cshtext/x-csharptext/x-csrctext/x-cudatext/x-dtext/x-difftext/x-dsrctext/x-emacs-lisptext/x-erlangtext/x-gff3text/x-gotext/x-haskelltext/x-javatext/x-java-propertiestext/x-java-sourcetext/x-kotlintext/x-lilypondtext/x-lisptext/x-literate-haskelltext/x-luatext/x-moctext/x-objcsrctext/x-pascaltext/x-pcs-gcdtext/x-perltext/x-perl-scripttext/x-pythontext/x-python-scripttext/x-r-markdowntext/x-rsrctext/x-rsttext/x-ruby-scripttext/x-rusttext/x-sasstext/x-scalatext/x-schemetext/x-script.pythontext/x-scsstext/x-setexttext/x-sfvtext/x-shtext/x-siestatext/x-sostext/x-sqltext/x-swifttext/x-tcltext/x-textext/x-vbasictext/x-vcalendartext/xmltext/xml-dtdtext/xml-external-parsed-entitytext/yaml
Limitazioni
- API Live: Ricerca file non è supportata nell' API Live.
- Incompatibilità degli strumenti: al momento, Ricerca file non può essere combinata con altri strumenti come Grounding con la Ricerca Google, Contesto URL e così via.
Limiti di frequenza
L'API Ricerca file 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 file del progetto (in base al livello utente):
- Senza costi: 1 GB
- Livello 1: 10 GB
- Livello 2: 100 GB
- Livello 3: 1 TB
- Consigli: limita le dimensioni di ogni archivio di Ricerca file a meno di 20 GB per garantire latenze di recupero ottimali.
Prezzi
- Agli sviluppatori vengono addebitati gli embedding al momento dell'indicizzazione in base ai prezzi degli embedding esistenti (0,15 $ per 1 milione di token).
- Lo spazio di archiviazione è senza costi.
- Gli embedding al momento della query sono senza costi.
- I token dei documenti recuperati vengono addebitati come normali token di contesto.
Passaggi successivi
- Visita il riferimento API per gli archivi di Ricerca file e i documenti di Ricerca file Documents.