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

input_file ja attachment_search Responses API:ssa

Oppitunti 4 / 16 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Kaksi polkua samaan lohkoon
  2. file_id-polku
  3. file_url-polku
  4. Mitä attachment_search tekee
  5. Useiden dokumenttien yhdistäminen
  6. Valinta kahden välillä
  7. Keskeiset asiat

Kaksi polkua samaan lohkoon

Grok Responses API hyväksyy dokumentin kahdella tavalla: joko file_id:n kautta, mikä tarkoittaa aiemmin lataamaasi tiedostoa, tai file_url:n kautta, joka on julkinen osoite, jonka xAI noutaa pyynnön yhteydessä. Lohkon nimi on molemmissa tapauksissa sama, input_file, ja jatkokäsittely on identtinen: Grok aktivoi attachment_search-työkalun ja poimii kysymykseesi vastaavat kohdat. Eroavaisuudet liittyvät dokumentin elinkaareen, luottamuksellisuuteen ja jokaisen toistetun kutsun kustannuksiin.

file_id-polku

Kun olet lähettänyt tiedoston komennolla POST /v1/files, viittaat siihen tunnisteella yhdessä kysymyksesi kanssa pelkkänä tekstinä:

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_id": "file_abc123"
    },
    {
      "type": "input_text",
      "text": "What are the main risks mentioned in this report?"
    }
  ]
}

Tämä polku on järkevä kolmessa tilanteessa. Ensimmäinen on toistuvat kyselyt: jos lakitiimisi esittää viisitoista peräkkäistä kysymystä samasta sopimuksesta, yksi lataus ja viisitoista viittausta on tehokkaampaa kuin saman PDF-tiedoston viisitoista siirtoa. Toinen syy on luottamuksellisuus, kun dokumenttia ei saa altistaa URL-osoitteelle, joka on kaikkien linkin haltijoiden saatavilla. Kolmas syy on sovellusarkkitehtuurisi: jos tiedostot ladataan ennalta yöttisen ingestoinnin aikana, pyyntösi käsittelevät vain tunnisteita.

file_url-polku

Kun dokumentti on jo julkaistu jossakin, lataus on tarpeeton vaihe, ja voit viitata suoraan osoitteeseen:

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_url": "https://exemple.com/specifications-api.pdf"
    },
    {
      "type": "input_text",
      "text": "Summarize the endpoints described in this documentation."
    }
  ]
}

Tyypillisiä käyttötapauksia ovat avoin dokumentaatio, jota sinulla ei ole syytä tallentaa, omassa infrastruktuurissasi väliaikaisen URL-osoitteen takana isännöity tiedosto tai nopea testi, jossa haluat varmistaa hypoteesin ilman koko latausputken pystyttämistä.

Tähän mukavuuteen liittyy kolme rajoitusta, ja ne kaikki maksavat tuotantoympäristössä. URL-osoitteen on oltava aidosti julkinen ilman tunnistautumista: osoite, joka on suojattu tokenilla tai evästeellä, palauttaa xAI:lle virhesivun, jonka malli analysoi ahkerasti varsinaisen dokumenttisi sijaan. Lataus lisää pyynnön käsittelyaikaa, joten suurten PDF-tiedostojen käsittely on huomattavasti hitaampaa kuin file_id:tä käytettäessä. Lopuksi, xAI:n puolella ei ole välimuistia: jokainen kutsu lataa tiedoston uudelleen, joten sama dokumentti, jota kysytään viisikymmentä kertaa päivässä, kulkee verkon yli viisikymmentä kertaa.

Mitä attachment_search tekee

Heti kun pyyntöösi ilmestyy input_file, Grok käynnistää attachment_search-toiminnon ilman mitään konfigurointia puoleltasi. Käsittely tapahtuu neljässä vaiheessa:

  1. Sisällön ekstraktio tiedostosta: teksti, taulukot, rakenne
  2. Väliaikainen indeksointi tälle sisällölle pyynnön keston ajaksi
  3. Relevanttien kohtien haku kysymyksesi perusteella
  4. Otteen injektointi mallin kontekstiin

Kiinnitä huomiota adjektiiviin “väliaikainen” toisessa vaiheessa, sillä se selittää kustannuseron, jonka monet huomaavat liian myöhään: indeksi rakennetaan uudelleen jokaisella kutsulla ja katoaa sen jälkeen. Tämä on juuri se ongelma, jonka kokoelmat (collections) ratkaisevat pysyvällä indeksoinnilla. Huomaa myös, että malli siteeraa vastauksessaan niitä kohtia, joita se todella käytti, jolloin voit varmistaa sen työn sen sijaan, että luottaisit sokeasti sen sanaan.

Useiden dokumenttien yhdistäminen

Mikään ei pakota sinua käyttämään vain yhtä tiedostoa pyyntöä kohden. Pinottamalla useita input_file-lohkoja pyydät mallia päättelemään koko joukon yli:

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_id": "file_rapport_q1"
    },
    {
      "type": "input_file",
      "file_id": "file_rapport_q2"
    },
    {
      "type": "input_text",
      "text": "Compare the Q1 and Q2 results."
    }
  ]
}

Grok analysoi molemmat dokumentit ja ristiviittaa tietoja vastatakseen, mikä avaa oven vuosineljännesvertailuille, peräkkäisten sopimusversioiden tarkasteluille tai spesifikaation ja sen toteutuksen vastakkainasettelulle.

Valinta kahden välillä

Kriteriofile_idfile_url
Ennalta latausKylläEi
Luottamuksellinen tiedostoSuositeltavaaEpäsuositeltavaa
Toistuvat kyselytSuorituskykyinen (1 lataus)Hidas (uudelleenlataus)
Julkinen tiedostoMahdollistaIhanteellista
Elinkaaren hallintaSinun kontrollissasiRiippuu isännöijästä

Keskeiset asiat

  • input_file käyttäen file_id:tä viittaa ladattuun tiedostoon, file_url julkiseen dokumenttiin
  • attachment_search-työkalu aktivoituu automaattisesti relevantin sisällön poimimiseksi
  • Voit yhdistää useita tiedostoja samaan pyyntöön
  • Suosi file_id:tä luottamuksellisille tai usein kysytyille tiedostoille
  • Suosi file_url:ää julkisille dokumenteille tai nopeille testeille