collections_search i file_search w API Responses
Na tej stronie
Integracja wyszukiwania bezpośrednio z konwersacjami
Punkt końcowy POST /v1/documents/search sprawdza się przy izolowanych pytaniach, ale całą pracę orkiestracyjną pozostawia Tobie: sformułowanie zapytania, pobranie fragmentów, wstrzyknięcie ich do promptu i wywołanie modelu. API Responses odwraca ten ciężar. Deklarując swoje kolekcje jako narzędzie, pozwalasz Grokowi decydować, kiedy szukać, czego szukać i jak przekształcić to w odpowiedź. Przechodzisz od pipeline’u, którym sterujesz, do asystenta, który samodzielnie przeszukuje Twoje dokumenty.
Narzędzie collections_search
Aby włączyć ten dostęp, wystarczy dodać obiekt do listy 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"]
}
]
)
Za tym jednym wywołaniem Grok analizuje pytanie, formułuje zapytanie wyszukiwania dopasowane do kolekcji, pobiera odpowiednie fragmenty, podsumowuje je i cytuje użyte dokumenty. W praktyce, dla powyższego pytania, przetłumaczy „urlop ojcowski“ na wyszukiwanie w col_rh_policies, zachowa akapity z umowy zakładowej i zwróci liczbę dni wraz ze źródłem, bez konieczności pisania choćby jednej linii logiki pobierania danych.
Narzędzie file_search
Odpowiednik istnieje dla pojedynczych plików, które nie są przechowywane w kolekcji. Nie musisz go deklarować: aktywuje się automatycznie, gdy tylko Twoje żądanie zawiera 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?"
}
]
)
To narzędzie attachment_search, będące odpowiednikiem file_search, aktywuje się w tle. To niejawne zachowanie wyjaśnia częste nieporozumienia: użytkownicy zastanawiają się, dlaczego deklaracja file_search w tools wydaje się nie mieć efektu, podczas gdy jest po prostu zbędna.
Dwa mechanizmy, dwie struktury kosztów
| Aspekt | collections_search | file_search / attachment_search |
|---|---|---|
| Źródło | Zindeksowana kolekcja(e) | Pojedynczy plik(i) |
| Deklaracja | Jawna w tools | Automatyczna z input_file |
| Indeksowanie | Wstępnie obliczone | W locie (on the fly) |
| Koszt | 2,50 USD / 1000 | 10 USD / 1000 |
| Wydajność | Szybka (istniejący indeks) | Wolniejsza (indeksowanie w czasie rzeczywistym) |
| Przypadek użycia | Trwała baza wiedzy | Analiza jednorazowa |
Wiersz „indeksowanie“ determinuje wszystkie pozostałe. Kolekcja jest indeksowana raz na zawsze, więc każde pytanie wykorzystuje tę pracę: jest szybkie i rozliczane po 2,50 USD za tysiąc wywołań. Dołączony plik jest indeksowany przy każdym żądaniu, stąd dodatkowe opóźnienie i koszt 10 USD za tysiąc. Umowa analizowana raz przez dział prawny wpada do drugiej kategorii; repozytorium HR odpytywane sto razy dziennie oczywiście do pierwszej.
Łączenie wielu narzędzi
Prawdziwa korzyść z tego podejścia ujawnia się, gdy dasz Grokowi kilka z nich, pozwalając mu wybrać te, które służą danemu pytaniu.
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"
}
]
)
To pytanie wymaga dwóch kolejnych kroków: Grok najpierw odpytuje kolekcję, aby znaleźć Twoją wewnętrzną politykę, następnie uruchamia wyszukiwanie w sieci w celu uzyskania aktualnych przepisów europejskich, a na koniec zestawia obie informacje w swojej odpowiedzi. Żadna orkiestracja po Twojej stronie, żadne instrukcje if decydujące, które źródło jest istotne – a gdyby pytanie dotyczyło wyłącznie Twojej wewnętrznej polityki, sieć nie zostałaby użyta.
Doprecyzowanie zachowania narzędzia
Trzy parametry pozwalają Ci tightened wyszukiwanie zadeklarowane w tools.
tools=[
{
"type": "collections_search",
"collection_ids": ["col_docs_1", "col_docs_2"],
"max_results": 10,
"retrieval_mode": "hybrid"
}
]
- collection_ids: odpytuj wiele kolekcji jednocześnie
- max_results: ogranicz liczbę wyników, aby zmniejszyć wstrzykiwany kontekst
- retrieval_mode: wybierz tryb wyszukiwania (domyślnie hybrydowy)
max_results zasługuje na szczególną uwagę: każdy zwrócony fragment zajmuje kontekst i kosztuje tokeny. W przypadku asystenta wsparcia, gdzie odpowiedzi mieszczą się zazwyczaj w dwóch lub trzech fragmentach, zmniejszenie wartości domyślnej do pięciu wyników obniża koszt bez degradacji postrzeganej jakości.
Cennik na dzień 5 sierpnia 2026 r. – ceny zmieniają się regularnie: przed obliczeniem jakiegokolwiek budżetu sprawdź aktualny cennik na oficjalnej stronie modeli i cennika xAI.
Kluczowe wnioski
collections_searchpozwala Grokowi automatycznie odpytywać Twoje kolekcje podczas konwersacjifile_search/attachment_searchaktywuje się automatycznie dla pojedynczych plików- Kolekcje są czterokrotnie tańsze i szybsze niż załączniki plików
- Możesz łączyć
collections_searchzweb_searchi innymi narzędziami - Grok automatycznie wybiera, których narzędzi użyć, w zależności od pytania