API Gemini позволяет использовать функцию расширенной генерации данных (RAG) с помощью инструмента поиска файлов. Поиск файлов импортирует, разделяет и индексирует данные, обеспечивая быстрый поиск необходимой информации по запросу. Эта информация затем используется в качестве контекста для модели, что позволяет ей выдавать более точные и релевантные ответы.
Чтобы сделать поиск файлов простым и доступным для разработчиков, мы делаем хранение файлов и генерацию встраиваемых данных во время запроса бесплатными. Вы платите только за создание встраиваемых данных при первой индексации файлов (по стоимости соответствующей модели встраиваемых данных) и по стандартной стоимости входных/выходных токенов модели Gemini. Эта новая парадигма тарификации делает инструмент поиска файлов проще и экономичнее в разработке и масштабировании.
Прямая загрузка в хранилище поиска файлов
В этом примере показано, как напрямую загрузить файл в хранилище поиска файлов :
Питон
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-2.5-flash",
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-2.5-flash",
contents: "Can you tell me about [insert question]",
config: {
tools: [
{
fileSearch: {
fileSearchStoreNames: [fileSearchStore.name]
}
}
]
}
});
console.log(response.text);
}
run();
Для получения более подробной информации ознакомьтесь со справочником API для uploadToFileSearchStore .
Импорт файлов
Кроме того, вы можете загрузить существующий файл и импортировать его в хранилище поиска файлов :
Питон
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-2.5-flash",
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-2.5-flash",
contents: "Can you tell me about [insert question]",
config: {
tools: [
{
fileSearch: {
fileSearchStoreNames: [fileSearchStore.name]
}
}
]
}
});
console.log(response.text);
}
run();
Более подробную информацию см. в справочнике API для importFile .
Конфигурация фрагментации
При импорте файла в хранилище поиска файлов он автоматически разбивается на фрагменты, встраивается, индексируется и загружается в хранилище поиска файлов. Если вам требуется больше контроля над стратегией разбиения на фрагменты, вы можете указать параметр chunking_config , чтобы задать максимальное количество токенов на фрагмент и максимальное количество перекрывающихся токенов.
Питон
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
}
}
}
)
JavaScript
let operation = await ai.fileSearchStores.uploadToFileSearchStore({
file: 'file.txt',
fileSearchStoreName: fileSearchStore.name,
config: {
displayName: 'file-name',
chunkingConfig: {
whiteSpaceConfig: {
maxTokensPerChunk: 200,
maxOverlapTokens: 20
}
}
}
});
Чтобы использовать хранилище поиска файлов, передайте его в качестве инструмента методу generateContent , как показано в примерах загрузки и импорта .
Как это работает
Поиск файлов использует метод, называемый семантическим поиском, для нахождения информации, релевантной запросу пользователя. В отличие от стандартного поиска по ключевым словам, семантический поиск учитывает смысл и контекст вашего запроса.
При импорте файла он преобразуется в числовые представления, называемые вложениями (embeddings) , которые отражают семантическое значение текста. Эти вложения хранятся в специализированной базе данных поиска файлов. При выполнении запроса они также преобразуются во вложения. Затем система выполняет поиск файлов, чтобы найти наиболее похожие и релевантные фрагменты документов в хранилище поиска файлов.
Ниже приведено описание процесса использования API uploadToFileSearchStore для поиска файлов:
Создайте хранилище для поиска файлов : хранилище для поиска файлов содержит обработанные данные из ваших файлов. Это постоянный контейнер для вложений, с которыми будет работать семантический поиск.
Загрузка файла и импорт в хранилище поиска файлов : одновременно загрузите файл и импортируйте результаты в хранилище поиска файлов. Это создаст временный объект
File, который является ссылкой на ваш необработанный документ. Затем эти данные будут разделены на фрагменты, преобразованы во вложения поиска файлов и индексированы. ОбъектFileбудет удален через 48 часов, а данные, импортированные в хранилище поиска файлов, будут храниться неограниченное время, пока вы не удалите их.Запрос с поиском файлов : Наконец, вы используете инструмент
FileSearchв вызовеgenerateContent. В конфигурации инструмента вы указываетеFileSearchRetrievalResource, указывающий на хранилищеFileSearchStore, в котором требуется выполнить поиск. Это указывает модели выполнить семантический поиск в этом хранилище FileSearch, чтобы найти релевантную информацию для обоснования своего ответа.

На этой диаграмме пунктирная линия от модели «Документы» к модели «Встраивание» (с использованием gemini-embedding-001 ) представляет API uploadToFileSearchStore (минуя хранилище файлов ). В противном случае, использование API «Файлы» для отдельного создания и импорта файлов переносит процесс индексации из модели «Документы» в хранилище файлов , а затем в модель «Встраивание» .
Магазины поиска файлов
Хранилище поиска файлов — это контейнер для встроенных файлов. Необработанные файлы, загруженные через API File, удаляются через 48 часов, а данные, импортированные в хранилище поиска файлов, хранятся неограниченное время, пока вы не удалите их вручную. Вы можете создать несколько хранилищ поиска файлов для упорядочивания документов. API FileSearchStore позволяет создавать, просматривать, получать и удалять данные для управления хранилищами поиска файлов. Имена хранилищ поиска файлов имеют глобальную область действия.
Вот несколько примеров того, как управлять хранилищами поиска файлов:
Питон
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 }
});
ОТДЫХ
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}"
Справочник API поиска документов по методам и полям, связанным с управлением документами в хранилищах файлов.
Метаданные файла
Вы можете добавлять пользовательские метаданные к своим файлам, чтобы упростить их фильтрацию или предоставить дополнительный контекст. Метаданные — это набор пар «ключ-значение».
Питон
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 }
]
}
});
Это полезно, когда в хранилище поиска файлов находится несколько документов и вы хотите выполнить поиск только по их подмножеству.
Питон
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=Robert Graves",
)
)
]
)
)
print(response.text)
JavaScript
const response = await ai.models.generateContent({
model: "gemini-2.5-flash",
contents: "Tell me about the book 'I, Claudius'",
config: {
tools: [
{
fileSearch: {
fileSearchStoreNames: [fileSearchStore.name],
metadataFilter: 'author="Robert Graves"',
}
}
]
}
});
console.log(response.text);
ОТДЫХ
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash: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
Руководство по реализации синтаксиса фильтра списков для metadata_filter можно найти на сайте google.aip.dev/160.
Цитаты
При использовании поиска файлов ответ модели может включать ссылки, указывающие, какие части загруженных вами документов были использованы для получения ответа. Это помогает при проверке фактов и верификации.
Доступ к информации о цитировании можно получить через атрибут grounding_metadata ответа.
Питон
print(response.candidates[0].grounding_metadata)
JavaScript
console.log(JSON.stringify(response.candidates?.[0]?.groundingMetadata, null, 2));
Поддерживаемые модели
Следующие модели поддерживают поиск файлов:
-
gemini-3-pro-preview -
gemini-2.5-pro -
gemini-2.5-flashи его предварительные версии -
gemini-2.5-flash-liteи его предварительные версии
Поддерживаемые типы файлов
Поиск файлов поддерживает широкий спектр форматов файлов, перечисленных в следующих разделах.
Типы файлов приложений
-
application/dart -
application/ecmascript -
application/json -
application/ms-java -
application/msword -
application/pdf -
application/sql -
application/typescript -
application/vnd.curl -
application/vnd.dart -
application/vnd.ibm.secure-container -
application/vnd.jupyter -
application/vnd.ms-excel -
application/vnd.oasis.opendocument.text -
application/vnd.openxmlformats-officedocument.presentationml.presentation -
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet -
application/vnd.openxmlformats-officedocument.wordprocessingml.document -
application/vnd.openxmlformats-officedocument.wordprocessingml.template -
application/x-csh -
application/x-hwp -
application/x-hwp-v5 -
application/x-latex -
application/x-php -
application/x-powershell -
application/x-sh -
application/x-shellscript -
application/x-tex -
application/x-zsh -
application/xml -
application/zip
Типы текстовых файлов
-
text/1d-interleaved-parityfec -
text/RED -
text/SGML -
text/cache-manifest -
text/calendar -
text/cql -
text/cql-extension -
text/cql-identifier -
text/css -
text/csv -
text/csv-schema -
text/dns -
text/encaprtp -
text/enriched -
text/example -
text/fhirpath -
text/flexfec -
text/fwdred -
text/gff3 -
text/grammar-ref-list -
text/hl7v2 -
text/html -
text/javascript -
text/jcr-cnd -
text/jsx -
text/markdown -
text/mizar -
text/n3 -
text/parameters -
text/parityfec -
text/php -
text/plain -
text/provenance-notation -
text/prs.fallenstein.rst -
text/prs.lines.tag -
text/prs.prop.logic -
text/raptorfec -
text/rfc822-headers -
text/rtf -
text/rtp-enc-aescm128 -
text/rtploopback -
text/rtx -
text/sgml -
text/shaclc -
text/shex -
text/spdx -
text/strings -
text/t140 -
text/tab-separated-values -
text/texmacs -
text/troff -
text/tsv -
text/tsx -
text/turtle -
text/ulpfec -
text/uri-list -
text/vcard -
text/vnd.DMClientScript -
text/vnd.IPTC.NITF -
text/vnd.IPTC.NewsML -
text/vnd.a -
text/vnd.abc -
text/vnd.ascii-art -
text/vnd.curl -
text/vnd.debian.copyright -
text/vnd.dvb.subtitle -
text/vnd.esmertec.theme-descriptor -
text/vnd.exchangeable -
text/vnd.familysearch.gedcom -
text/vnd.ficlab.flt -
text/vnd.fly -
text/vnd.fmi.flexstor -
text/vnd.gml -
text/vnd.graphviz -
text/vnd.hans -
text/vnd.hgl -
text/vnd.in3d.3dml -
text/vnd.in3d.spot -
text/vnd.latex-z -
text/vnd.motorola.reflex -
text/vnd.ms-mediapackage -
text/vnd.net2phone.commcenter.command -
text/vnd.radisys.msml-basic-layout -
text/vnd.senx.warpscript -
text/vnd.sosi -
text/vnd.sun.j2me.app-descriptor -
text/vnd.trolltech.linguist -
text/vnd.wap.si -
text/vnd.wap.sl -
text/vnd.wap.wml -
text/vnd.wap.wmlscript -
text/vtt -
text/wgsl -
text/x-asm -
text/x-bibtex -
text/x-boo -
text/xc -
text/x-c++hdr -
text/x-c++src -
text/x-cassandra -
text/x-chdr -
text/x-coffeescript -
text/x-component -
text/x-csh -
text/x-csharp -
text/x-csrc -
text/x-cuda -
text/xd -
text/x-diff -
text/x-dsrc -
text/x-emacs-lisp -
text/x-erlang -
text/x-gff3 -
text/x-go -
text/x-haskell -
text/x-java -
text/x-java-properties -
text/x-java-source -
text/x-kotlin -
text/x-lilypond -
text/x-lisp -
text/x-literate-haskell -
text/x-lua -
text/x-moc -
text/x-objcsrc -
text/x-pascal -
text/x-pcs-gcd -
text/x-perl -
text/x-perl-script -
text/x-python -
text/x-python-script -
text/xr-markdown -
text/x-rsrc -
text/x-rst -
text/x-ruby-script -
text/x-rust -
text/x-sass -
text/x-scala -
text/x-scheme -
text/x-script.python -
text/x-scss -
text/x-setext -
text/x-sfv -
text/x-sh -
text/x-siesta -
text/x-sos -
text/x-sql -
text/x-swift -
text/x-tcl -
text/x-tex -
text/x-vbasic -
text/x-vcalendar -
text/xml -
text/xml-dtd -
text/xml-external-parsed-entity -
text/yaml
Ограничения по скорости
API поиска файлов имеет следующие ограничения для обеспечения стабильности работы сервиса:
- Максимальный размер файла/ограничение на один документ : 100 МБ
- Общий размер хранилищ поиска файлов проекта (в зависимости от уровня пользователя):
- Бесплатно : 1 ГБ
- Уровень 1 : 10 ГБ
- Уровень 2 : 100 ГБ
- Уровень 3 : 1 ТБ
- Рекомендация : Ограничьте размер каждого хранилища поиска файлов до 20 ГБ, чтобы обеспечить оптимальные задержки поиска.
Цены
- С разработчиков взимается плата за встраивание во время индексации на основе существующих цен на встраивание (0,15 долл. США за 1 млн токенов).
- Хранение бесплатное.
- Встраивание во время запроса осуществляется бесплатно.
- Полученные токены документов тарифицируются как обычные токены контекста .
Что дальше?
- Посетите справочник API для хранилищ файлов и документов поиска файлов.