Przejdź do głównej treści
Polski— Wybierz język
Menu

collections_search i file_search w API Responses

Lekcja 11 z 16 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Integracja wyszukiwania bezpośrednio z konwersacjami
  2. Narzędzie collections_search
  3. Narzędzie file_search
  4. Dwa mechanizmy, dwie struktury kosztów
  5. Łączenie wielu narzędzi
  6. Doprecyzowanie zachowania narzędzia
  7. Kluczowe wnioski

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.

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.

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

Aspektcollections_searchfile_search / attachment_search
ŹródłoZindeksowana kolekcja(e)Pojedynczy plik(i)
DeklaracjaJawna w toolsAutomatyczna z input_file
IndeksowanieWstępnie obliczoneW locie (on the fly)
Koszt2,50 USD / 100010 USD / 1000
WydajnośćSzybka (istniejący indeks)Wolniejsza (indeksowanie w czasie rzeczywistym)
Przypadek użyciaTrwała baza wiedzyAnaliza 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_search pozwala Grokowi automatycznie odpytywać Twoje kolekcje podczas konwersacji
  • file_search / attachment_search aktywuje się automatycznie dla pojedynczych plików
  • Kolekcje są czterokrotnie tańsze i szybsze niż załączniki plików
  • Możesz łączyć collections_search z web_search i innymi narzędziami
  • Grok automatycznie wybiera, których narzędzi użyć, w zależności od pytania