Поиск файлов

API Gemini позволяет использовать технологию дополненной генерации данных (RAG) с помощью инструмента поиска файлов. Поиск файлов импортирует, разделяет и индексирует данные, обеспечивая быстрый поиск релевантной информации по запросу пользователя. Эта информация затем предоставляется модели в качестве контекста, что позволяет ей выдавать более точные и релевантные ответы.

Вы можете использовать API uploadToFileSearchStore для непосредственной загрузки существующего файла в хранилище поиска файлов или отдельно загрузить и затем импортировать файл, если вы хотите создать файл одновременно.

Прямая загрузка в хранилище поиска файлов

В этом примере показано, как напрямую загрузить файл в хранилище файлов:

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)

Импорт файлов

Кроме того, вы можете загрузить существующий файл и импортировать его в свое хранилище файлов:

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)

Конфигурация фрагментации

При импорте файла в хранилище поиска файлов он автоматически разбивается на фрагменты, встраивается, индексируется и загружается в хранилище поиска файлов. Если вам требуется больше контроля над стратегией фрагментации, вы можете указать параметр chunking_config , чтобы задать максимальное количество токенов на фрагмент и максимальное количество перекрывающихся токенов.

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

Чтобы использовать хранилище поиска файлов, передайте его в качестве инструмента методу generateContent , как показано в примерах загрузки и импорта .

Как это работает

Поиск файлов использует метод семантического поиска для нахождения информации, релевантной запросу пользователя. В отличие от традиционного поиска по ключевым словам, семантический поиск учитывает смысл и контекст вашего запроса.

При импорте файла он преобразуется в числовые представления, называемые вложениями (embeddings ), которые отражают семантическое значение текста. Эти вложения хранятся в специализированной базе данных поиска файлов. При выполнении запроса они также преобразуются во вложения. Затем система выполняет поиск файлов, чтобы найти наиболее похожие и релевантные фрагменты документов в хранилище поиска файлов.

Ниже приведено описание процесса использования API uploadToFileSearchStore для поиска файлов:

1. Создайте хранилище для поиска файлов : хранилище для поиска файлов содержит обработанные данные из ваших файлов. Это постоянный контейнер для вложений, с которыми будет работать семантический поиск.

2. Загрузка файла и импорт в хранилище поиска файлов : одновременно загрузите файл и импортируйте результаты в хранилище поиска файлов. Это создаст временный объект File , который является ссылкой на ваш необработанный документ. Эти данные затем будут разделены на фрагменты, преобразованы во вложения для поиска файлов и индексированы. Объект File будет удален через 48 часов, в то время как данные, импортированные в хранилище поиска файлов, будут храниться неограниченное время, пока вы не удалите их.

3. Запрос с поиском файлов : Наконец, вы используете инструмент FileSearch в вызове generateContent . В конфигурации инструмента вы указываете FileSearchRetrievalResource , указывающий на хранилище FileSearchStore в котором требуется выполнить поиск. Это указывает модели выполнить семантический поиск в этом хранилище файлов, чтобы найти релевантную информацию для обоснования своего ответа.

На этой диаграмме пунктирная линия от модели «Документы» к модели «Встраивание» (с использованием gemini-embedding-001 ) представляет API uploadToFileSearchStore (минуя хранилище файлов ). В противном случае, использование API «Файлы» для отдельного создания и импорта файлов переносит процесс индексации из модели «Документы» в хранилище файлов , а затем в модель «Встраивание» .

Магазины поиска файлов

Хранилище поиска файлов — это контейнер для встроенных файлов. Необработанные файлы, загруженные через File API, удаляются через 48 часов, а данные, импортированные в хранилище поиска файлов, хранятся неограниченное время, пока вы не удалите их вручную. Вы можете создать несколько хранилищ поиска файлов для упорядочивания документов. API FileSearchStore позволяет создавать, просматривать, получать и удалять данные для управления хранилищами поиска файлов. Имена хранилищ поиска файлов имеют глобальную область действия.

Вот несколько примеров того, как управлять хранилищами поиска файлов:

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

Метаданные файла

Вы можете добавлять пользовательские метаданные к своим файлам, чтобы упростить их фильтрацию или предоставить дополнительный контекст. Метаданные — это набор пар «ключ-значение».

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

Это полезно, когда в хранилище файлов для поиска находится несколько документов и вы хотите выполнить поиск только по их подмножеству.

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

Руководство по реализации синтаксиса фильтра списков для metadata_filter можно найти на сайте google.aip.dev/160.

Цитаты

При использовании поиска файлов ответ модели может включать ссылки, указывающие, какие части загруженных вами документов были использованы для получения ответа. Это помогает при проверке фактов и верификации.

Доступ к информации о цитировании можно получить через атрибут grounding_metadata ответа.

print(response.candidates[0].grounding_metadata)

Поддерживаемые модели

Следующие модели поддерживают поиск файлов:

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

Поддерживаемые типы файлов

Поиск файлов поддерживает широкий спектр форматов файлов, перечисленных в следующих разделах.

Ограничения по скорости

API поиска файлов имеет следующие ограничения для обеспечения стабильности работы сервиса:

• Максимальный размер файла/ограничение на один документ : 100 МБ
• Количество магазинов поиска файлов на проект : 10
• Общий размер хранилищ поиска файлов проекта (в зависимости от уровня пользователя):
  • Бесплатно : 1 ГБ
  • Уровень 1 : 10 ГБ
  • Уровень 2 : 100 ГБ
  • Уровень 3 : 1 ТБ
• Рекомендация : Ограничьте размер каждого хранилища поиска файлов до 20 ГБ, чтобы обеспечить оптимальные задержки поиска.

Цены

• С разработчиков взимается плата за встраивание во время индексации на основе существующих цен на встраивание (0,15 долл. США за 1 млн токенов).
• Хранение бесплатное.
• Встраивание во время запроса осуществляется бесплатно.
• Полученные токены документов тарифицируются как обычные токены контекста .