Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

collections_search ja file_search Responses API:ssa

Oppitunti 11 / 16 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Integroi haku suoraan keskusteluihin
  2. collections_search-työkalu
  3. file_search-työkalu
  4. Kaksi mekanismia, kaksi kustannusrakennetta
  5. Yhdistä useita työkaluja
  6. Hienosäädä työkalujen toimintaa
  7. Keskeiset asiat

Integroi haku suoraan keskusteluihin

POST /v1/documents/search -päätepiste toimii hyvin erillisissä kysymyksissä, mutta se jättää koko orkestroinnin sinun harteillesi: kyselyn muotoilun, otteiden hakemisen, niiden syöttämisen kehotteeseen ja mallin kutsumisen. Responses API kääntää tämän taakan. Kun määrität kokoelmasi työkaluksi, annat Grokin päättää, milloin se hakee tietoa, mitä se etsii ja miten se muuntaa löydökset vastaukseksi. Siirryt putkesta, jota ohjaat itse, avustajaan, joka etsii dokumenteistasi itsenäisesti.

collections_search-työkalu

Tarvitset vain lisätä objektin tools-listaan ottaaksesi tämän käyttöön:

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"]
        }
    ]
)

Tämän yhden kutsun takana Grok analysoi kysymyksen, muotoilee kokoelmaan räätälöidyn hakukyselyn, noutaa asiaankuuluvat kohdat, tiivistää ne ja citeeraa käytetyt dokumentit. Käytännössä yllä olevaan kysymykseen se kääntää “isyydenvapaa” hauksi kokoelmassa col_rh_policies, poimii kappaleet yrityssopimuksesta ja palauttaa päivien määrän lähteineen ilman, että sinun tarvitsee kirjoittaa riviäkään noutologiiikkaa.

file_search-työkalu

Vastaava toiminto on olemassa yksittäisille tiedostoille, joita ei ole tallennettu kokoelmaan. Sitä ei tarvitse erikseen määrittää: se aktivoituu automaattisesti, kun pyyntösi sisältää input_file-parametrin.

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?"
        }
    ]
)

Taustalla aktivoituu attachment_search-työkalu, joka vastaa file_search-toimintoa. Tämä implisiittinen käyttäytyminen selittää yleisen hämmennyksen: käyttäjät ihmettelevät, miksi file_search-määrittelyllä tools-listassa ei näytä olevan vaikutusta, vaikka se on yksinkertaisesti tarpeeton.

Kaksi mekanismia, kaksi kustannusrakennetta

Näkökulmacollections_searchfile_search / attachment_search
LähdeIndeksoidyt kokoelmatYksittäiset tiedostot
MäärittelyEksplisiittinen tools-listassaAutomaattinen input_file:n kanssa
IndeksointiEsilaskettuReaaliaikainen
Kustannus2,50 $ / 1 00010 $ / 1 000
SuorituskykyNopea (olemassa oleva indeksi)Hitaampi (reaaliaikainen indeksointi)
KäyttötarkoitusPysyvä tietopankkiKertaluonteinen analyysi

“Indeksointi”-rivi määrittää kaikki muut. Kokoelma indeksoidaan kerran ja lopullisesti, joten jokainen kysymys hyödyntää tätä työtä: se on nopeaa ja hinnoiteltu 2,50 dollarin mukaan tuhatta kutsua kohden. Liitetty tiedosto indeksoidaan jokaisen pyynnön yhteydessä, mikä aiheuttaa lisäviivettä ja 10 dollarin hinnan tuhannelta. Sopimus, jonka lakimiehesi analysoi kerran, kuuluu jälkimmäiseen kategoriaan; HR-arkisto, jota kysellään sata kertaa päivässä, kuuluu显然 ensimmäiseen.

Yhdistä useita työkaluja

Tämän lähestymistavan todellinen hyöty paljastuu, kun annat Grokille useita työkaluja ja annat sen valita kysymykseen sopivat.

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"
        }
    ]
)

Tämä kysymys vaatii kahta peräkkäistä liikettä: Grok hakee ensin kokoelmasta sisäisen käytäntönne, käynnistää sitten verkkohaun ajankohtaisista eurooppalaisista määräyksistä ja vertaa näitä kahta vastauksessaan. Ei orkestrointia sinun puoleltasi, ei if-lauseita päättämässä, kumpi lähde on relevantti – ja jos kysymys olisi keskittynyt pelkästään sisäiseen käytäntöönne, verkkohakua ei olisi käytetty.

Hienosäädä työkalujen toimintaa

Kolme parametria antaa sinun tarkentaa tools-listassa määriteltyä hakua.

tools=[
    {
        "type": "collections_search",
        "collection_ids": ["col_docs_1", "col_docs_2"],
        "max_results": 10,
        "retrieval_mode": "hybrid"
    }
]
  • collection_ids: kysy useista kokoelmista samanaikaisesti
  • max_results: rajoita tulosten määrää vähentääksesi syötettyä kontekstia
  • retrieval_mode: valitse hakutila (oletuksena hybrid)

max_results ansaitsee erityistä huomiota: jokainen palautettu ote vie kontekstitilaa ja maksaa tokeneita. Tukiavustajassa, jossa vastaukset mahtuvat yleensä kahteen tai kolmeen kohtaan, oletusarvon pudottaminen viiteen tulokseen vähentää kustannuksia heikentämättä koettua laatua.

Hinnoittelu 5. elokuuta 2026 – hinnat muuttuvat säännöllisesti: ennen minkään budjetin laskemista tarkista ajantasainen hinnoittelu xAI:n viralliselta mallien ja hinnoittelun sivulta.

Keskeiset asiat

  • collections_search antaa Grokin kysyä kokoelmistasi automaattisesti keskustelun aikana
  • file_search / attachment_search aktivoituu automaattisesti yksittäisille tiedostoille
  • Kokoelmat ovat neljä kertaa edullisempia ja nopeampia kuin tiedostoliitteet
  • Voit yhdistää collections_search-toiminnon web_search-haun ja muiden työkalujen kanssa
  • Grok valitsee automaattisesti, mitkä työkalut se käyttää kysymyksen perusteella