Die Gemini API ermöglicht Retrieval-Augmented Generation (RAG) über das Tool „Dateisuche“. Mit der Dateisuche werden Ihre Daten importiert, in Blöcke aufgeteilt und indexiert, um relevante Informationen basierend auf einem angegebenen Prompt schnell abrufen zu können. Diese Informationen werden dann als Kontext für das Modell verwendet, sodass das Modell genauere und relevantere Antworten geben kann.
Damit die Dateisuche für Entwickler einfach und kostengünstig ist, sind die Dateispeicherung und die Einbettungsgenerierung zur Abfragezeit kostenlos. Sie zahlen nur für das Erstellen von Einbettungen, wenn Sie Ihre Dateien zum ersten Mal indexieren (zu den entsprechenden Kosten für das Einbettungsmodell) und für die normalen Kosten für Eingabe-/Ausgabetokens des Gemini-Modells. Durch dieses neue Abrechnungsmodell ist das Tool „Dateisuche“ einfacher und kostengünstiger zu erstellen und zu skalieren.
Direkt in den Dateispeicher hochladen
In diesem Beispiel wird gezeigt, wie Sie eine Datei direkt in den Dateispeicher hochladen:
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();
Weitere Informationen finden Sie in der API-Referenz für uploadToFileSearchStore.
Dateien importieren
Alternativ können Sie eine vorhandene Datei hochladen und in Ihren Dateispeicher importieren:
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();
Weitere Informationen finden Sie in der API-Referenz für importFile.
Konfiguration der Blockaufteilung
Wenn Sie eine Datei in einen Dateispeicher importieren, wird sie automatisch in Blöcke aufgeteilt, eingebettet, indexiert und in Ihren Dateispeicher hochgeladen. Wenn Sie
mehr Kontrolle über die Strategie zur Blockaufteilung benötigen, können Sie die
chunking_config Einstellung
verwenden, um eine maximale Anzahl von Tokens pro Block und maximale Anzahl von überlappenden
Tokens festzulegen.
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.");
Wenn Sie Ihren Dateispeicher verwenden möchten, übergeben Sie ihn wie in den Beispielen zum Hochladen und Importieren als Tool an die generateContent
Methode.
Funktionsweise
Bei der Dateisuche wird eine Technik namens semantische Suche verwendet, um Informationen zu finden, die für den Prompt des Nutzers relevant sind. Im Gegensatz zur standardmäßigen stichwortbasierten Suche werden bei der semantischen Suche die Bedeutung und der Kontext Ihrer Abfrage berücksichtigt.
Wenn Sie eine Datei importieren, wird sie in numerische Darstellungen umgewandelt, die als Einbettungenbezeichnet werden und die semantische Bedeutung von Text erfassen. Diese Einbettungen werden in einer speziellen Dateispeicherdatenbank gespeichert. Wenn Sie eine Abfrage senden, wird sie ebenfalls in eine Einbettung umgewandelt. Anschließend führt das System eine Dateisuche durch, um die ähnlichsten und relevantesten Dokumentblöcke aus dem Dateispeicher zu finden.
Für Einbettungen und Dateien gibt es keine Gültigkeitsdauer (Time To Live, TTL). Sie bleiben so lange erhalten, bis sie manuell gelöscht werden oder das Modell eingestellt wird.
Hier ist eine Aufschlüsselung des Prozesses für die Verwendung der uploadToFileSearchStore API der Dateisuche:
Dateispeicher erstellen: Ein Dateispeicher enthält die verarbeiteten Daten aus Ihren Dateien. Er ist der dauerhafte Container für die Einbettungen, auf die sich die semantische Suche bezieht.
Datei hochladen und in einen Dateispeicher importieren: Laden Sie gleichzeitig eine Datei hoch und importieren Sie die Ergebnisse in Ihren Dateispeicher. Dadurch wird ein temporäres
File-Objekt erstellt, das einen Verweis auf Ihr Rohdokument darstellt. Diese Daten werden dann in Blöcke aufgeteilt, in Einbettungen für die Dateisuche umgewandelt und indexiert. DasFile-Objekt wird nach 48 Stunden gelöscht. Die in den Dateispeicher importierten Daten werden jedoch so lange gespeichert, bis Sie sie löschen.Mit der Dateisuche abfragen: Schließlich verwenden Sie das
FileSearchTool in einemgenerateContentAufruf. In der Toolkonfiguration geben Sie eineFileSearchRetrievalResourcean, die auf denFileSearchStoreverweist, in dem Sie suchen möchten. Dadurch wird das Modell angewiesen, eine semantische Suche in diesem bestimmten Dateispeicher durchzuführen, um relevante Informationen zu finden, die als Grundlage für die Antwort dienen.
In diesem Diagramm stellt die gepunktete Linie von Dokumente zu Einbettungsmodell
(mit gemini-embedding-001)
die uploadToFileSearchStore API dar (ohne Dateispeicher).
Wenn Sie die Files API verwenden, um Dateien separat zu erstellen
und dann zu importieren, wird der Indexierungsprozess von Dokumente zu
Dateispeicher und dann zu Einbettungsmodell verschoben.
Dateispeicher
Ein Dateispeicher ist ein Container für Ihre Dokumenteinbettungen. Rohdateien, die über die File API hochgeladen werden, werden nach 48 Stunden gelöscht. Die in einen Dateispeicher importierten Daten werden jedoch so lange gespeichert, bis Sie sie manuell löschen. Sie können mehrere Dateispeicher erstellen, um Ihre Dokumente zu organisieren. Mit der FileSearchStore API können Sie Ihre Dateispeicher erstellen, auflisten, abrufen und löschen. Namen von Dateispeichern sind global.
Hier sind einige Beispiele für die Verwaltung Ihrer Dateispeicher:
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}"
Dateisuchdokumente
Mit der
File Search Documents API können Sie einzelne Dokumente in Ihren Dateispeichern verwalten. Sie können jedes Dokument
in einem Dateispeicher list auflisten, Informationen zu einem Dokument get abrufen und ein
Dokument anhand des Namens delete löschen.
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}"
Dateimetadaten
Sie können Ihren Dateien benutzerdefinierte Metadaten hinzufügen, um sie zu filtern oder zusätzlichen Kontext bereitzustellen. Metadaten bestehen aus einer Reihe von Schlüssel/Wert-Paaren.
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 }
]
}
});
Das ist nützlich, wenn Sie mehrere Dokumente in einem Dateispeicher haben und nur in einer Teilmenge davon suchen möchten.
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
Eine Anleitung zur Implementierung der Syntax für Listenfilter für metadata_filter finden Sie
unter google.aip.dev/160
Zitationen
Wenn Sie die Dateisuche verwenden, kann die Antwort des Modells Zitationen enthalten, die angeben, welche Teile Ihrer hochgeladenen Dokumente zum Generieren der Antwort verwendet wurden. Das hilft bei der Faktenprüfung und Verifizierung.
Sie können über das Attribut grounding_metadata der Antwort auf Zitationsinformationen zugreifen.
Python
print(response.candidates[0].grounding_metadata)
JavaScript
console.log(JSON.stringify(response.candidates?.[0]?.groundingMetadata, null, 2));
Ausführliche Informationen zur Struktur der Fundierungsmetadaten finden Sie in den Beispielen im File Search Cookbook oder im Abschnitt zur Fundierung in der Dokumentation zur Fundierung mit der Google Suche.
Strukturierte Ausgabe
Ab den Gemini 3-Modellen können Sie das Tool „Dateisuche“ mit strukturierten Ausgaben kombinieren.
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"]
}
}
}'
Unterstützte Modelle
Die folgenden Modelle unterstützen die Dateisuche:
| Modell | Dateisuche |
|---|---|
| Gemini 3.1 Pro (Vorschau) | ✔️ |
| Gemini 3.1 Flash-Lite (Vorschau) | ✔️ |
| Gemini 3 Flash (Vorschau) | ✔️ |
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
Unterstützte Toolkombinationen
Gemini 3-Modelle unterstützen die Kombination von integrierten Tools (z. B. Dateisuche) mit benutzerdefinierten Tools (Funktionsaufrufe). Weitere Informationen finden Sie auf der Seite Toolkombinationen.
Unterstützte Dateitypen
Die Dateisuche unterstützt eine Vielzahl von Dateiformaten, die in den folgenden Abschnitten aufgeführt sind.
Anwendungsdateitypen
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
Textdateitypen
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
Beschränkungen
- Live API: Die Dateisuche wird in der Live API nicht unterstützt.
- Toolinkompatibilität: Die Dateisuche kann derzeit nicht mit anderen Tools wie Fundierung mit der Google Suche, URL-Kontext usw. kombiniert werden.
Ratenlimits
Die File Search API hat die folgenden Limits, um die Stabilität des Dienstes zu gewährleisten:
- Maximale Dateigröße / Limit pro Dokument: 100 MB
- Gesamtgröße der Dateispeicher des Projekts (basierend auf der Nutzerstufe):
- Kostenlos: 1 GB
- Stufe 1: 10 GB
- Stufe 2: 100 GB
- Stufe 3: 1 TB
- Empfehlung: Beschränken Sie die Größe jedes Dateispeichers auf unter 20 GB, um optimale Abruflatenzen zu gewährleisten.
Preise
- Entwicklern werden Einbettungen zum Zeitpunkt der Indexierung basierend auf den bestehenden Preisen für Einbettungen berechnet (0,15 $ pro 1 Million Tokens).
- Die Speicherung ist kostenlos.
- Einbettungen zur Abfragezeit sind kostenlos.
- Abgerufene Dokumenttokens werden als reguläre Kontexttokens berechnet.
Nächste Schritte
- API-Referenz für Dateispeicher und Dateisuchdokumente