Dateisuche

Die Gemini API ermöglicht Retrieval Augmented Generation („RAG“) über das Tool „File Search“. Bei der Dateisuche werden Ihre Daten importiert, in Chunks aufgeteilt und indexiert, damit relevante Informationen basierend auf dem Prompt eines Nutzers schnell abgerufen werden können. Diese Informationen werden dann als Kontext für das Modell bereitgestellt, sodass es genauere und relevantere Antworten geben kann.

Mit der uploadToFileSearchStore API können Sie eine vorhandene Datei direkt in Ihren Dateisuchspeicher hochladen oder eine Datei separat hochladen und dann importieren, wenn Sie die Datei gleichzeitig erstellen möchten.

Direkt in den Dateisuchspeicher hochladen

In diesem Beispiel wird gezeigt, wie Sie eine Datei direkt in einen Dateispeicher hochladen:

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)

Dateien importieren

Alternativ können Sie eine vorhandene Datei hochladen und in Ihren Dateispeicher importieren:

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)

Konfiguration der Aufteilung in Blöcke

Wenn Sie eine Datei in einen Dateisuchspeicher importieren, wird sie automatisch in Chunks zerlegt, eingebettet, indexiert und in Ihren Dateisuchspeicher hochgeladen. Wenn Sie mehr Kontrolle über die Chunking-Strategie benötigen, können Sie eine chunking_config-Einstellung angeben, um eine maximale Anzahl von Tokens pro Chunk und eine maximale Anzahl von sich überschneidenden Tokens festzulegen.

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

Wenn Sie Ihren Dateisuchspeicher verwenden möchten, übergeben Sie ihn als Tool an die generateContent-Methode, wie in den Beispielen Upload und Import gezeigt.

Funktionsweise

Bei der Dateisuche wird ein Verfahren namens „semantische Suche“ verwendet, um Informationen zu finden, die für den Nutzer-Prompt relevant sind. Im Gegensatz zur herkömmlichen stichwortbasierten Suche versteht die semantische Suche die Bedeutung und den Kontext Ihrer Anfrage.

Wenn Sie eine Datei importieren, wird sie in numerische Darstellungen umgewandelt, die als Einbettungen bezeichnet werden und die semantische Bedeutung des Texts erfassen. Diese Einbettungen werden in einer speziellen Datenbank für die Dateisuche gespeichert. Wenn Sie eine Anfrage stellen, wird diese ebenfalls in eine Einbettung umgewandelt. Anschließend führt das System eine Dateisuche durch, um die ähnlichsten und relevantesten Dokument-Chunks aus dem Dateisuchspeicher zu finden.

So verwenden Sie die File Search uploadToFileSearchStore API:

1. Dateisuchspeicher erstellen: Ein Dateisuchspeicher enthält die verarbeiteten Daten aus Ihren Dateien. Er ist der persistente Container für die Einbettungen, auf denen die semantische Suche ausgeführt wird.

2. Datei hochladen und in einen Dateisuchspeicher importieren: Sie können eine Datei gleichzeitig hochladen und die Ergebnisse in Ihren Dateisuchspeicher importieren. Dadurch wird ein temporäres File-Objekt erstellt, das eine Referenz zu Ihrem Rohdokument ist. Diese Daten werden dann in Chunks aufgeteilt, in Einbettungen für die Dateisuche umgewandelt und indexiert. Das File-Objekt wird nach 48 Stunden gelöscht. Die in den Dateisuchspeicher importierten Daten werden dagegen auf unbestimmte Zeit gespeichert, bis Sie sie löschen.

3. Abfrage mit der Dateisuche: Schließlich verwenden Sie das Tool FileSearch in einem generateContent-Aufruf. In der Toolkonfiguration geben Sie einen FileSearchRetrievalResource an, der auf den FileSearchStore verweist, den Sie durchsuchen möchten. Dadurch wird das Modell angewiesen, eine semantische Suche in diesem bestimmten Dateisuchspeicher durchzuführen, um relevante Informationen für die Fundierung der Antwort zu finden.

Im Diagramm stellt die gepunktete Linie von Dokumente zu Einbettungsmodell (mit gemini-embedding-001) die uploadToFileSearchStore-API dar (Dateispeicher wird umgangen). Andernfalls wird durch die separate Erstellung und den anschließenden Import von Dateien mit der Files API der Indexierungsprozess von Dokumente zu Dateispeicher und dann zu Embedding-Modell verschoben.

Dateisuchspeicher

Ein Dateisuchspeicher ist ein Container für Ihre Dokumenteinbettungen. Rohdateien, die über die File API hochgeladen werden, werden nach 48 Stunden gelöscht. Die in einen Dateisuchspeicher importierten Daten werden jedoch unbegrenzt gespeichert, bis Sie sie manuell löschen. Sie können mehrere Dateisuchspeicher erstellen, um Ihre Dokumente zu organisieren. Mit der FileSearchStore API können Sie Ihre Dateisuchspeicher erstellen, auflisten, abrufen und löschen. Dateisuchspeichernamen sind global.

Hier sind einige Beispiele für die Verwaltung Ihrer Dateisuchspeicher:

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

Dateimetadaten

Sie können Ihren Dateien benutzerdefinierte Metadaten hinzufügen, um sie zu filtern oder zusätzlichen Kontext bereitzustellen. Metadaten sind eine Reihe von Schlüssel/Wert-Paaren.

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

Das ist nützlich, wenn Sie mehrere Dokumente in einem Dateisuchspeicher haben und nur in einer Teilmenge davon suchen möchten.

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

Eine Anleitung zur Implementierung der Listenfiltersyntax für metadata_filter finden Sie unter google.aip.dev/160.

Zitationen

Wenn Sie die Dateisuche verwenden, kann die Antwort des Modells Zitationen enthalten, in denen angegeben wird, welche Teile Ihrer hochgeladenen Dokumente zum Generieren der Antwort verwendet wurden. Das hilft bei der Überprüfung von Fakten und der Bestätigung.

Sie können über das Attribut grounding_metadata der Antwort auf Zitationsinformationen zugreifen.

print(response.candidates[0].grounding_metadata)

Unterstützte Modelle

Die folgenden Modelle unterstützen die Dateisuche:

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

Unterstützte Dateitypen

Die Dateisuche unterstützt eine Vielzahl von Dateiformaten, die in den folgenden Abschnitten aufgeführt sind.

Ratenlimits

Die File Search API unterliegt den folgenden Einschränkungen, um die Stabilität des Dienstes zu gewährleisten:

• Maximale Dateigröße / Beschränkung pro Dokument: 100 MB
• Dateisuchen, die pro Projekt gespeichert werden: 10
• Gesamtgröße der Suchspeicher für Projektdateien (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 Dateisuchspeichers auf unter 20 GB, um optimale Abruflatenzen zu erzielen.

Preise

• Entwicklern werden Einbettungen zum Zeitpunkt der Indexierung basierend auf den bestehenden Preisen für Einbettungen (0,15 $ pro 1 Million Tokens) in Rechnung gestellt.
• Die Speicherung ist kostenlos.
• Einbettungen zur Abfragezeit sind kostenlos.
• Abgerufene Dokument-Tokens werden als reguläre Kontext-Tokens abgerechnet.