Wyszukiwanie plików

Interfejs Gemini API umożliwia generowanie rozszerzone przez wyszukiwanie w zapisanych informacjach („RAG”) za pomocą narzędzia File Search. Wyszukiwarka plików importuje, dzieli na części i indeksuje Twoje dane, aby umożliwić szybkie wyszukiwanie odpowiednich informacji na podstawie promptu użytkownika. Te informacje są następnie przekazywane do modelu jako kontekst, co pozwala mu udzielać dokładniejszych i trafniejszych odpowiedzi.

Za pomocą uploadToFileSearchStore interfejsu API możesz przesłać bezpośrednio istniejący plik do sklepu z wyszukiwarką plików lub przesłać i zaimportować plik osobno, jeśli chcesz utworzyć go w tym samym czasie.

Bezpośrednie przesyłanie do sklepu z wyszukiwarką plików

Ten przykład pokazuje, jak bezpośrednio przesłać plik do magazynu plików:

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)

Importowanie plików

Możesz też przesłać istniejący plik i zaimportować go do magazynu plików:

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)

Konfiguracja podziału na fragmenty

Gdy importujesz plik do sklepu z wyszukiwarką plików, jest on automatycznie dzielony na części, osadzany, indeksowany i przesyłany do sklepu z wyszukiwarką plików. Jeśli potrzebujesz większej kontroli nad strategią dzielenia na części, możesz określić ustawienie chunking_config, aby ustawić maksymalną liczbę tokenów na część i maksymalną liczbę nakładających się tokenów.

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

Aby użyć sklepu z wyszukiwaniem plików, przekaż go jako narzędzie do metody generateContent, jak pokazano w przykładach Prześlij i Importuj.

Jak to działa

Wyszukiwanie plików korzysta z techniki zwanej wyszukiwaniem semantycznym, aby znajdować informacje istotne dla promptu użytkownika. W przeciwieństwie do tradycyjnego wyszukiwania opartego na słowach kluczowych wyszukiwanie semantyczne rozumie znaczenie i kontekst Twojego zapytania.

Podczas importowania pliku jest on przekształcany w reprezentacje numeryczne zwane wektorami dystrybucyjnymi, które odzwierciedlają znaczenie semantyczne tekstu. Te osadzania są przechowywane w specjalistycznej bazie danych wyszukiwania plików. Gdy wysyłasz zapytanie, jest ono również przekształcane w wektor. Następnie system przeprowadza wyszukiwanie plików, aby znaleźć najbardziej podobne i trafne fragmenty dokumentów w magazynie wyszukiwania plików.

Oto opis procesu korzystania z interfejsu File Search uploadToFileSearchStore API:

1. Utwórz sklep wyszukiwania plików: sklep wyszukiwania plików zawiera przetworzone dane z Twoich plików. Jest to trwały kontener na wektory dystrybucyjne, na których będzie działać wyszukiwanie semantyczne.

2. Prześlij plik i zaimportuj go do sklepu z wyszukiwaniem plików: jednocześnie prześlij plik i zaimportuj wyniki do sklepu z wyszukiwaniem plików. Spowoduje to utworzenie tymczasowego obiektu File, który jest odwołaniem do Twojego dokumentu w formacie nieprzetworzonym. Te dane są następnie dzielone na części, przekształcane w wektory dystrybucyjne wyszukiwania plików i indeksowane. FileObiekt zostanie usunięty po 48 godzinach, a dane zaimportowane do magazynu wyszukiwania plików będą przechowywane bezterminowo, dopóki nie zdecydujesz się ich usunąć.

3. Zapytanie za pomocą wyszukiwania plików: na koniec używasz narzędzia FileSearch w wywołaniu generateContent. W konfiguracji narzędzia określasz FileSearchRetrievalResource, który wskazuje FileSearchStore, którego chcesz wyszukać. Dzięki temu model będzie mógł przeprowadzić wyszukiwanie semantyczne w tym konkretnym sklepie z wyszukiwanymi plikami, aby znaleźć odpowiednie informacje do udzielenia odpowiedzi.

Na tym diagramie linia przerywana od Dokumentów do Modelu osadzania (z użyciem gemini-embedding-001) reprezentuje interfejs API uploadToFileSearchStore (z pominięciem Pamięci plików). W przeciwnym razie użycie interfejsu Files API do oddzielnego tworzenia, a następnie importowania plików przenosi proces indeksowania z Dokumentów do pamięci plików, a następnie do modelu osadzania.

Sklepy z wyszukiwarkami plików

Magazyn wyszukiwania plików to kontener na osadzenia dokumentów. Surowe pliki przesłane za pomocą interfejsu File API są usuwane po 48 godzinach, ale dane zaimportowane do sklepu wyszukiwania plików są przechowywane bezterminowo, dopóki nie usuniesz ich ręcznie. Możesz utworzyć wiele sklepów wyszukiwania plików, aby uporządkować dokumenty. Interfejs APIFileSearchStore umożliwia tworzenie, wyświetlanie, pobieranie i usuwanie sklepów wyszukiwania plików w celu zarządzania nimi. Nazwy sklepów wyszukiwania plików mają zakres globalny.

Oto kilka przykładów zarządzania sklepami wyszukiwania plików:

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

Metadane pliku

Możesz dodać do plików niestandardowe metadane, aby ułatwić ich filtrowanie lub zapewnić dodatkowy kontekst. Metadane to zestaw par klucz-wartość.

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

Jest to przydatne, gdy w magazynie wyszukiwania plików masz wiele dokumentów i chcesz przeszukiwać tylko ich podzbiór.

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

Wskazówki dotyczące wdrażania składni filtra listy dla metadata_filter znajdziesz na stronie google.aip.dev/160

Cytaty

Gdy używasz wyszukiwania plików, odpowiedź modelu może zawierać cytaty, które wskazują, które części przesłanych dokumentów zostały użyte do wygenerowania odpowiedzi. Ułatwia to weryfikację informacji.

Informacje o cytowaniu są dostępne w atrybucie grounding_metadata odpowiedzi.

print(response.candidates[0].grounding_metadata)

Obsługiwane modele

Wyszukiwanie plików jest obsługiwane przez te modele:

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

Obsługiwane typy plików

Wyszukiwanie plików obsługuje szeroką gamę formatów plików, które są wymienione w kolejnych sekcjach.

Ograniczenia liczby żądań

Aby zapewnić stabilność usługi, interfejs File Search API ma te ograniczenia:

• Maksymalny rozmiar pliku / limit na dokument: 100 MB
• Liczba zapisanych wyszukiwań plików w projekcie: 10
• Całkowity rozmiar pamięci wyszukiwania plików projektu (w zależności od poziomu użytkownika):
  • Bezpłatnie: 1 GB
  • Poziom 1: 10 GB
  • Poziom 2: 100 GB
  • Poziom 3: 1 TB
• Rekomendacja: aby zapewnić optymalne opóźnienia pobierania, ogranicz rozmiar każdego sklepu wyszukiwania plików do poniżej 20 GB.

Ceny

• Opłaty za umieszczanie są naliczane w momencie indeksowania na podstawie obowiązujących cen umieszczania (0,15 USD za 1 mln tokenów).
• Przechowywanie jest bezpłatne.
• Wektory dystrybucyjne podczas zapytań są bezpłatne.
• Pobrane tokeny dokumentu są rozliczane jako zwykłe tokeny kontekstu.