Поиск файлов Google в API Gemini: практическое и полное руководство от RAG

Появление File Search в экосистеме Gemini API Это изменило правила игры для тех, кто хочет создавать приложения RAG без конфликтов инфраструктуры. Благодаря этому управляемому сервису Google автоматизирует хранение файлов, разбиение на фрагменты, встраивание и динамическое внедрение контекста во время генерации, чтобы вы могли сосредоточиться на создании продукта, а не на настройке конвейеров.

Помимо приема документов, File Search обеспечивает расширенный семантический поискСовместимость с различными форматами, автоматическое цитирование и простая структура ценообразованияА если вам нужна актуальная информация из Интернета, API ее тоже предлагает. google_search для заземления с помощью поиска Google, с очень полезные метаданные проверки для интерфейсов с отслеживаемыми назначениями.

Что именно представляет собой поиск файлов в API Gemini?

Поиск файлов — это полностью управляемое решение RAG Интегрировано в API Gemini. Фактически, вы загружаете файлы (или импортируете их из файлового сервиса), а система заботится обо всём остальном. разбить их на фрагменты, сгенерировать вложения, индексировать их в хранилище поиска файлов и использовать их в качестве основы для ответа на запросы пользователей через векторный поиск.

Цель состоит в том, чтобы вам не пришлось иметь дело с Векторные базы, очереди индексации или стратегии фрагментации самостоятельно. Инструмент основан на модели встраивания Google (например, gemini-embedding-001) и изначально интегрируется с generateContentгде вы объявляете Инструмент поиска файлов и магазин для проверки.

Как это работает: от документа до контекстного ответа

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

Наконец, в призыве к generateContent с инструментом FileSearch, вы добавляете один FileSearchRetrievalResource который указывает на конкретный магазин. Благодаря этому модель знает, что она должна восстановить контекст из вашего магазина и используйте его для поддержки вашего реагирования. Всё это происходит без необходимости планировать ручное восстановление или использовать внешние сервисы.

Загрузка и импорт документов: два совместимых пути

Чтобы добавить данные в свой магазин, у вас есть два варианта. Если вы хотите сразу перейти к сути, используйте API. uploadToFileSearchStore для загрузите файл напрямую и проиндексируйте его За одну операцию. Если вы предпочитаете разделить шаги, вы можете загрузить файл через Files API, а затем импортировать это c importFile в хранилище поиска файлов.

Когда вы выбираете одновременную загрузку и импорт, File временная ссылка на необработанный документ; это Через 48 часов объект удаляется.Однако индексированные данные остаются в хранилище до тех пор, пока вы не решите их удалить. Если Вы используете Files API Затем вы импортируете; конвейер проходит через файловое хранилище перед фазой встраивания.

Управление фрагментацией: точность и перекрытие

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

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

Хранилища поиска файлов: сохранение, область действия и управление

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

API FileSearchStore это позволяет вам создавать, перечислять, получать и удалять магазиныКроме того, существует API документов для управления содержимым в каждом магазине, и вы можете прикрепить пользовательские метаданные (пары "ключ-значение") в ваши файлы для фильтрации результатов поиска по подмножествам. Для фильтра используется следующий синтаксис: списки фильтров описано в google.aip.dev/160.

Подробный процесс использования API

В операционном плане типичный процесс состоит из трёх этапов. Во-первых, Вы создаете хранилище поиска файлов, После, загрузка и импорт файлов (Или вы загружаете, а затем импортируете.) Наконец, вопросы к модели с generateContent указание инструмента FileSearch и магазин назначения через FileSearchRetrievalResource.

В средах JavaScript/TypeScript общепринятой практикой является использование одновременные операции (например, Promise.all) для загрузки нескольких файлов одновременно и мониторинга operation.done Прежде чем продолжить. Магазин также часто ищут по его названию. отображаемое имя (удобочитаемый), если вы не помните идентификатор fileSearchStores/....

Управление документами: поиск, обновление и удаление

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

В ходе производственной практики многие рабочие процессы автоматизируют этот цикл: поиск → удаление → загрузкаИ когда вы закончите с ресурсами (например, в разработке), помните, что есть предел 10 магазинов на проектПоэтому, если они вам больше не нужны, их лучше почистить.

Ссылки и проверка: обоснование ваших документов

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

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

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

Поиск файлов поддерживает широкий выбор форматовСреди наиболее распространенных — application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document (ДОКС), application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (XLSX), application/vnd.openxmlformats-officedocument.presentationml.presentation (PPTX), application/json, application/xml, application/zip, в дополнение ко многим языкам programación y типы текста в качестве text/plain, text/html, text/css, text/csv, text/markdown, text/javascript, text/yaml, и т.д.

Он также охватывает множество конкретных типов (например, код и скрипты в качестве application/x-php, application/x-powershell, application/x-sh, application/x-tex, application/x-zshИ текстовый в качестве text/x-python, text/x-java, text/x-ruby-script, text/x-rust, text/x-go, text/x-kotlin, text/x-sql, text/x-c, text/x-csharp, text/x-swift, text/x-tex, text/x-scss, text/x-tcl, text/x-asm(среди многих других). Если в вашем случае требуется необычный тип, скорее всего, это созерцаемый в официальной документации.

Ограничения обслуживания и архитектурные рекомендации

Для поддержания стабильности обслуживания API устанавливает четкие ограничения: Максимальный размер файла — 100 МБ.Общий размер добавленных в магазины вещей зависит от уровня пользователя: Бесплатно 1 ГБ, Уровень 1 10 ГБ, Уровень 2 100 ГБ y Уровень 3 1 ТБ.

В качестве ориентира для производительности рекомендуется сохраняйте размер каждого хранилища менее 20 ГБ Для обеспечения оптимальной задержки. Обратите внимание, что размер хранилища рассчитывается на бэкэнде как размер входных данных. плюс вложениякоторые они обычно умножают приблизительно на три исходный объем данных.

Цены: простые и предсказуемые

Модель оплаты – прямая: Вы платите только за создание вложений в индексацию.по цене 0,15 долл. США за 1 млн токенов (в зависимости от стоимости применяемой модели встраивания). хранение и генерация вложений в запрос Они не требуют дополнительных затрат, и восстановленные токены При генерации они выставляются в счет как обычные токены контекста.

Эта схема упрощает составление бюджета: основные затраты сосредоточены в первоначальный прием (и в последующих обновлениях документа, если таковые имеются), минимизируя неожиданности в потреблении по объему запросов.

Совместимые модели для поиска файлов

Инструмент работает с текущими моделями семейства Gemini. В справочных материалах подчеркивается его доступность в Близнецы 2.5 Про y Близнецы 2.5 Флэш для поиска файлов, с поддержкой заземление, фильтры метаданных и цитаты для создания проверяемого опыта.

Что касается заземления с помощью поиска Google (обсуждается ниже), существует более широкий спектр поддерживаемых моделей, и указано, что Экспериментальные и предварительные модели Они не включены.

Заземление с помощью поиска Google: актуальная информация и веб-цитирования

Если в дополнение к вашим документам вам нужны веб-контент в реальном времениВы можете активировать инструмент google_searchМодель управляет весь поток: решить, целесообразно ли выполнять поиск, генерировать и выполнять запросы, обрабатывать результаты, синтезировать и возвращать ответ с заземляющими метаданными (консультации, результаты и цитаты).

При правильном заземлении реакция включает в себя: groundingMetadata с такими полями, как webSearchQueries (использованные консультации), searchEntryPoint (Для поисковых подсказок требуются HTML и CSS, требования к использованию подробно описаны в Условиях обслуживания), заземляющие куски (веб-источники с uri y title) А заземлениеОпоры (фрагменты, связывающие текстовые сегменты модели с индексами groundingChunks построить онлайн-цитирования).

Цены и модели заземления с помощью поиска Google

Использование El google_search счет для каждого запроса который активирует этот инструмент, даже если модель запускает несколько внутренних запросов для одного и того же запроса; все это считается одноразовое платное использованиеНиже перечислены модели, совместимые с этим инструментом. Близнецы 2.5 Про, Близнецы 2.5 Флэш, Gemini 2.5 Flash-Lite, Близнецы 2.0 Флэш, Близнецы 1.5 Про y Близнецы 1.5 Флэш.

Для моделей до версии 1.5 имеется устаревший инструмент. google_search_retrieval с режимом динамическийгде вы настраиваете динамический_порог (0.0–1.0) и модель решает, выполнять ли поиск или нет, основываясь на его уверенность где вам нужна актуальная информация.

Варианты использования: от внутренних помощников до службы поддержки клиентов

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

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

Операции и статус: работа с API

Поверхность REST предоставляет такие методы, как fileSearchStores.create (создает пустой магазин), fileSearchStores.delete (удаляет магазин), fileSearchStores.get (получает информацию из магазина), fileSearchStores.list (перечисляет пользовательские магазины) и importFile (это имеет значение File (от файлового сервиса до хранилища). Конечные точки операции позволяют вам проверить статус долгосрочные операции, с бланками заявлений, которые в ряде случаев идут пустой согласно спецификации.

На прямом подъеме по маршруту (uploadToFileSearchStoreНабор операции Специально разработано для оценки прогресса. Этот шаблон является типичным: копья операция, вы проверяете периодически, если он закончился и, когда полный, вы продолжаете поток (например, запускаете запросы RAG).

Лучшие практики: фильтры, маркировка и задержка

Если вы ожидаете много запросов, пометьте свои документы следующим образом: метаданных и нанимать metadataFilter Чтобы ограничить поиск соответствующими подмножествами. Храните хранилища в пределах рекомендация по размеру Это помогает снизить задержку и повысить стабильность. И если вы собираетесь заряжать полные папкиОн использует одновременное повышение температуры для сокращения времени приема пищи.

В технических сценариях определите стратегии фрагментации соответствующие содержанию: например, более короткие фрагменты с умеренным перекрытием для код (лучшая точность в функциях/классах), и несколько более длинные фрагменты в повествовательная документация для сохранения семантического контекста.

Совместимость с другими инструментами Gemini

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

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

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