collections_search и file_search в Responses API
На тази страница
Интегриране на търсенето директно в разговорите
Крайната точка POST /v1/documents/search работи добре за изолирани въпроси, но оставя цялата работа по оркестрацията на Вас: формулиране на заявката, извличане на откъси, вмъкването им в промпт и извикване на модела. Responses API обръща тази тежест. Чрез деклариране на Вашите колекции като инструмент, Вие позволявате на Grok да реши кога да търси, какво да търси и как да го превърне в отговор. Вие преминавате от пайплайн, който управлявате сами, към асистент, който сам търси във Вашите документи.
Инструментът collections_search
Трябва само да добавите обект към списъка tools, за да активирате този достъп:
response = await client.responses.create(
model="grok-4.5",
input="What is our paternity leave policy?",
tools=[
{
"type": "collections_search",
"collection_ids": ["col_rh_policies"]
}
]
)
Зад това единствено извикване, Grok анализира въпроса, формулира заявка за търсене, съобразена с колекцията, извлича съответните пасажи, обобщава ги и цитира използваните документи. На практика, за горния въпрос, той ще преведе „родителски отпуск“ в търсене в col_rh_policies, ще запази параграфите от корпоративното споразумение и ще върне брой дни заедно с източника, без Вие да пишете нито ред логика за извличане.
Инструментът file_search
Съответстващият инструмент съществува за отделни файлове, които не се съхраняват в колекция. Няма нужда да го декларирате: той се активира автоматично, щом Вашата заявка съдържа input_file.
response = await client.responses.create(
model="grok-4.5",
input=[
{
"type": "input_file",
"file_id": "file_contrat_abc"
},
{
"type": "input_text",
"text": "Does this contract contain a non-compete clause?"
}
]
)
Това е инструментът attachment_search, еквивалентен на file_search, който се активира във фонов режим. Това имплицитно поведение обяснява често срещано объркване: потребителите се чудят защо декларирането на file_search в tools сякаш няма ефект, когато то просто е излишно.
Два механизма, две ценови структури
| Аспект | collections_search | file_search / attachment_search |
|---|---|---|
| Източник | Индексирана колекция(и) | Отделен файл(ове) |
| Декларация | Явна в tools | Автоматична с input_file |
| Индексиране | Предварително изчислено | В реално време |
| Цена | $2.50 / 1,000 | $10 / 1,000 |
| Производителност | Бързо (съществуващ индекс) | По-бавно (индексиране в реално време) |
| Случай на употреба | Постоянна база знания | Еднократен анализ |
Редът „Индексиране“ определя всички останали. Колекцията се индексира веднъж завинаги, така че всеки въпрос преизползва тази работа: това е бързо и се таксува на $2.50 на хиляда извиквания. Прикаченият файл се индексира с всяка заявка, откъдето идва допълнителното забавяне и цената от $10 на хиляда. Договорът, който Вашият юридически съветник анализира веднъж, попада във втората категория; хранилището на човешките ресурси, към което се прави заявка сто пъти на ден, очевидно попада в първата.
Комбиниране на няколко инструмента
Истинската полза от този подход се проявява, когато дадете на Grok няколко от тях, позволявайки му да избере тези, които служат на въпроса.
response = await client.responses.create(
model="grok-4.5",
input="Compare our internal policy with the latest European regulations on the subject.",
tools=[
{
"type": "collections_search",
"collection_ids": ["col_politiques_internes"]
},
{
"type": "web_search"
}
]
)
Този въпрос изисква две последователни действия: Grok първо прави заявка към колекцията, за да открие Вашата вътрешна политика, след това стартира уеб търсене за текущите европейски разпоредби и накрая ги противопоставя в своя отговор. Никаква оркестрация от Ваша страна, никакво if условие за решаване кой от двата източника е релевантен – и ако въпросът беше фокусиран единствено върху Вашата вътрешна политика, уебът нямаше да бъде използван.
Прецизиране на поведението на инструмента
Три параметъра Ви позволяват да прецизирате търсенето, декларирано в tools.
tools=[
{
"type": "collections_search",
"collection_ids": ["col_docs_1", "col_docs_2"],
"max_results": 10,
"retrieval_mode": "hybrid"
}
]
- collection_ids: заявка към няколко колекции едновременно
- max_results: ограничаване на броя резултати за намаляване на инжектирания контекст
- retrieval_mode: избор на режим на търсене (hybrid по подразбиране)
max_results заслужава специално внимание: всеки върнат откъс заема контекст и струва токени. За асистент за поддръжка, където отговорите обикновено се побират в два или три пасажа, намаляването от стойността по подразбиране до пет резултата намалява разходите без влошаване на възприеманото качество.
Цени към 5 август 2026 г. – цените се променят редовно: преди да изчислите какъвто и да е бюджет, проверете текущите цени на официалната страница за модели и цени на xAI.
Ключови изводи
collections_searchпозволява на Grok автоматично да прави заявки към Вашите колекции по време на разговорfile_search/attachment_searchсе активира автоматично за отделни файлове- Колекциите са четири пъти по-евтини и по-бързи от прикачените файлове
- Можете да комбинирате collections_search с web_search и други инструменти
- Grok автоматично избира кои инструменти да използва въз основа на въпроса