A API Gemini permite a geração aumentada por recuperação (RAG, na sigla em inglês) usando a ferramenta de pesquisa de arquivos. A pesquisa de arquivos importa, divide e indexa seus dados para permitir a recuperação rápida de informações relevantes com base em um prompt fornecido. Essas informações são usadas como contexto para o modelo, permitindo que ele forneça respostas mais precisas e relevantes.
Para tornar a pesquisa de arquivos simples e acessível para desenvolvedores, estamos oferecendo o armazenamento de arquivos e a geração de embeddings no momento da consulta sem custo financeiro. Você só paga pela criação de embeddings quando indexa seus arquivos pela primeira vez (com o custo do modelo de embedding aplicável) e pelo custo normal dos tokens de entrada / saída do modelo Gemini. Esse novo paradigma de faturamento torna a ferramenta de pesquisa de arquivos mais fácil e econômica para criar e escalonar.
Fazer upload diretamente para o armazenamento de pesquisa de arquivos
Este exemplo mostra como fazer upload de um arquivo diretamente para o repositório de pesquisa de arquivos:
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();
Consulte a referência da API para uploadToFileSearchStore para mais informações.
Como importar arquivos
Como alternativa, você pode fazer upload de um arquivo atual e importá-lo para o armazenamento de pesquisa de arquivos:
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();
Consulte a referência da API para importFile para mais informações.
Configuração de divisão
Quando você importa um arquivo para um repositório de pesquisa de arquivos, ele é dividido automaticamente em partes, incorporado, indexado e enviado para o repositório de pesquisa de arquivos. Se você
precisar de mais controle sobre a estratégia de divisão, especifique uma
chunking_config configuração
para definir um número máximo de tokens por parte e um número máximo de tokens sobrepostos.
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.");
Para usar o armazenamento de pesquisa de arquivos, transmita-o como uma ferramenta para o generateContent
método, conforme mostrado nos exemplos de upload e importação.
Como funciona
A pesquisa de arquivos usa uma técnica chamada pesquisa semântica para encontrar informações relevantes para o prompt do usuário. Ao contrário da pesquisa padrão baseada em palavras-chave, a pesquisa semântica entende o significado e o contexto da consulta.
Quando você importa um arquivo, ele é convertido em representações numéricas chamadas embeddings, que capturam o significado semântico de o texto. Esses embeddings são armazenados em um banco de dados especializado de pesquisa de arquivos. Quando você faz uma consulta, ela também é convertida em um embedding. Em seguida, o sistema realiza uma pesquisa de arquivos para encontrar as partes de documentos mais semelhantes e relevantes no repositório de pesquisa de arquivos.
Não há tempo de vida (TTL) para embeddings e arquivos. Eles permanecem até serem excluídos manualmente ou quando o modelo é descontinuado.
Confira os detalhes do processo de uso da API uploadToFileSearchStore de pesquisa de arquivos:
Criar um repositório de pesquisa de arquivos: um repositório de pesquisa de arquivos contém os dados processados dos seus arquivos. É o contêiner persistente para os embeddings em que a pesquisa semântica vai operar.
Fazer upload de um arquivo e importar para um repositório de pesquisa de arquivos: faça upload de um arquivo e importe os resultados para o repositório de pesquisa de arquivos simultaneamente. Isso cria um objeto
Filetemporário, que é uma referência ao seu documento bruto. Esses dados são divididos, convertidos em embeddings de pesquisa de arquivos e indexados. O objetoFileé excluído após 48 horas, enquanto os dados importados para o repositório de pesquisa de arquivos são armazenados indefinidamente até que você os exclua.Consultar com a pesquisa de arquivos: por fim, você usa a ferramenta
FileSearchem uma chamadagenerateContent. Na configuração da ferramenta, especifique umFileSearchRetrievalResource, que aponta para oFileSearchStoreque você quer pesquisar. Isso informa ao modelo para realizar uma pesquisa semântica nesse armazenamento de pesquisa de arquivos específico para encontrar informações relevantes para fundamentar a resposta.
Neste diagrama, a linha pontilhada de Documentos para Modelo de embedding
(usando gemini-embedding-001)
representa a API uploadToFileSearchStore (ignorando o Armazenamento de arquivos).
Caso contrário, o uso da API Files para criar
e importar arquivos separadamente move o processo de indexação de Documentos para
Armazenamento de arquivos e, em seguida, para Modelo de embedding.
Armazenamentos de pesquisa de arquivos
Um repositório de pesquisa de arquivos é um contêiner para os embeddings de documentos. Embora os arquivos RAW enviados pela API File sejam excluídos após 48 horas, os dados importados para um repositório de pesquisa de arquivos são armazenados indefinidamente até que você os exclua manualmente. É possível criar vários armazenamentos de pesquisa de arquivos para organizar seus documentos. A API FileSearchStore permite criar, listar, receber e excluir para gerenciar seus armazenamentos de pesquisa de arquivos. Os nomes dos armazenamentos de pesquisa de arquivos têm escopo global.
Confira alguns exemplos de como gerenciar seus armazenamentos de pesquisa de arquivos:
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}"
Documentos de pesquisa de arquivos
É possível gerenciar documentos individuais nos seus armazenamentos de arquivos com a
API File Search Documents para list cada documento
em um armazenamento de pesquisa de arquivos, get informações sobre um documento e delete um
documento por 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}"
Metadados do arquivo
É possível adicionar metadados personalizados aos arquivos para ajudar a filtrá-los ou fornecer contexto adicional. Os metadados são um conjunto de pares de chave-valor.
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 }
]
}
});
Isso é útil quando você tem vários documentos em um repositório de pesquisa de arquivos e quer pesquisar apenas um subconjunto deles.
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
As orientações sobre como implementar a sintaxe de filtro de lista para metadata_filter podem ser encontradas
em google.aip.dev/160.
Citações
Ao usar a pesquisa de arquivos, a resposta do modelo pode incluir citações que especificam quais partes dos documentos enviados foram usadas para gerar a resposta. Isso ajuda na verificação de fatos.
É possível acessar informações de citação pelo atributo grounding_metadata da resposta.
Python
print(response.candidates[0].grounding_metadata)
JavaScript
console.log(JSON.stringify(response.candidates?.[0]?.groundingMetadata, null, 2));
Para informações detalhadas sobre a estrutura dos metadados de embasamento, consulte os exemplos no manual de pesquisa de arquivos ou a seção de embasamento dos documentos de embasamento com a Pesquisa Google .
Resposta estruturada
A partir dos modelos do Gemini 3, é possível combinar a ferramenta de pesquisa de arquivos com saídas estruturadas.
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"]
}
}
}'
Modelos compatíveis
Os seguintes modelos oferecem suporte à pesquisa de arquivos:
| Modelo | Pesquisa de arquivos |
|---|---|
| Pré-lançamento do Gemini 3.1 Pro | ✔️ |
| Pré-lançamento do Gemini 3.1 Flash-Lite | ✔️ |
| Pré-lançamento do Gemini 3 Flash | ✔️ |
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
Combinações de ferramentas compatíveis
Os modelos do Gemini 3 oferecem suporte à combinação de ferramentas integradas (como a pesquisa de arquivos) com ferramentas personalizadas (chamada de função). Saiba mais na página de combinações de ferramentas.
Tipos de arquivo compatíveis
A pesquisa de arquivos oferece suporte a uma ampla variedade de formatos de arquivo, listados nas seções a seguir.
Tipos de arquivo de aplicativo
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
Tipos de arquivo de texto
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
Limitações
- API Live: a pesquisa de arquivos está indisponível na API Live.
- Incompatibilidade de ferramentas:a pesquisa de arquivos não pode ser combinada com outras ferramentas como embasamento com a Pesquisa Google, contexto de URL etc.
Limites de taxas
A API File Search tem os seguintes limites para impor a estabilidade do serviço:
- Tamanho máximo do arquivo / limite por documento: 100 MB
- Tamanho total dos armazenamentos de pesquisa de arquivos do projeto (com base no nível do usuário):
- Sem custo financeiro: 1 GB
- Nível 1: 10 GB
- Nível 2: 100 GB
- Nível 3: 1 TB
- Recomendação: limite o tamanho de cada repositório de pesquisa de arquivos a menos de 20 GB para garantir latências de recuperação ideais.
Preços
- Os desenvolvedores são cobrados pelos embeddings no momento da indexação com base nos preços de embeddings existentes (US$ 0,15 por 1 milhão de tokens).
- O armazenamento é sem custo financeiro.
- Os embeddings de tempo de consulta são sem custo financeiro.
- Os tokens de documentos recuperados são cobrados como tokens de contexto normais .
A seguir
- Acesse a referência da API para armazenamentos de pesquisa de arquivos e documentos de pesquisa de arquivos.