input_file és attachment_search a Responses API-ban
Ezen az oldalon
Két út ugyanahhoz a blokkhoz
A Grok Responses API kétféleképpen fogad el dokumentumot: a file_id segítségével, ami egy korábban feltöltött fájlra utal, vagy a file_url használatával, ami egy nyilvános cím, amelyet az xAI a kérés időpontjában lekér. Mindkét esetben a blokk neve ugyanaz: input_file, és a további feldolgozás is azonos: a Grok aktiválja az attachment_search eszközt, és kinyerje azokat a szakaszokat, amelyek választ adnak a kérdésedre. Ami változik, az a dokumentum életciklusa, a bizalmasság szintje és az ismételt hívások költsége.
A file_id alapú út
Miután elküldted a fájlt a POST /v1/files végponton keresztül, az azonosítójával hivatkozhatsz rá, a kérdésedet pedig egyszerű szövegként adjuk meg:
{
"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?"
}
]
}
Ez az út három helyzetben érdemes. Az első az ismételt lekérdezés: ha a jogi csapatod tizenöt egymást követő kérdést tesz fel ugyanarról a szerződésről, akkor egyetlen feltöltés és tizenöt hivatkozás jobb megoldás, mint ugyanannak a PDF-nek a tizenötszöri átvitele. A második a bizalmasság: amikor a dokumentumot nem szabad olyan URL mögé helyezni, amelyhez bárki hozzáférhet, aki ismeri a linket. A harmadik az alkalmazásod architektúrája: ha a fájlokat éjszakai betöltés során előre feltöltöd, akkor a kéréseid csak az azonosítókat kezelik.
A file_url alapú út
Amikor a dokumentum már valahol közzé van téve, a feltöltés felesleges lépés, és közvetlenül a címre mutathatsz:
{
"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."
}
]
}
Tipikus használati esetek közé tartozik a nyilvános dokumentáció, amelyet nincs okod tárolni, a saját infrastruktúrádon hosztolt fájl ideiglenes URL-lel, vagy egy gyors teszt, ahol hipotézist szeretnél ellenőrizni anélkül, hogy teljes feltöltési folyamatot állítanál be.
Ennek a kényelemnek három korlátja van, és mindegyik költségbe kerül éles környezetben. Az URL-nek valóban nyilvánosnak kell lennie, hitelesítés nélkül: egy token vagy süti által védett cím hibaoldalt ad vissza az xAI-nak, amelyet a modell szorgalmasan elemez majd a dokumentumod helyett. A letöltés növeli a kérés feldolgozási idejét, így a nagy PDF-ek jelentősen lassabbak lesznek, mint a file_id használata esetén. Végül nincs gyorsítótár az xAI oldalán: minden hívás újra letölti a fájlt, tehát egy egyetlen dokumentum, amelyet naponta ötvenszer kérdeznek le, ötvenszer halad át a hálózaton.
Mit csinál az attachment_search
Amint egy input_file megjelenik a kérésedben, a Grok automatikusan, bármilyen konfiguráció nélkül elindítja az attachment_search eszközt. A feldolgozás négy lépésben történik:
- Tartalom kinyerése a fájlból: szöveg, táblázatok, struktúra
- Ideiglenes indexelés ennek a tartalomnak a kérés időtartamára
- Releváns szakaszok keresése a kérdésed alapján
- Részletek beszúrása a modell kontextusába
Fókuszálj a „ideiglenes“ jelzőre a második lépésben, mert ez magyarázza azt a költségbeli különbséget, amelyet sokan túl későn fedeznek fel: az index minden híváskor újraépül, majd utána eltűnik. Pontosan ezt a problémát oldják meg a kollekciók a tartós indexeléssel. Jegyezd meg azt is, hogy a modell hivatkozik azokra a szakaszokra, amelyeket ténylegesen felhasznált a válaszában, így ellenőrizheted a munkáját, ahelyett, hogy vakon hinnél neki.
Több dokumentum kombinálása
Semmi sem kötelez arra, hogy kérésenként csak egy fájlt használj. Több input_file blokk egymásra helyezésével arra kéred a modellt, hogy a készlet alapján következtessen:
{
"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."
}
]
}
A Grok elemzi mindkét dokumentumot, és kereszthivatkozásokat készít az információk között a válaszadáshoz, ami lehetővé teszi a negyedéves összehasonlításokat, a szerződések egymást követő verzióinak áttekintését vagy egy specifikáció és annak megvalósítása közötti összevetést.
Döntés a két lehetőség között
| Kritérium | file_id | file_url |
|---|---|---|
| Előzetes feltöltés | Igen | Nem |
| Bizalmas fájl | Ajánlott | Nem ajánlott |
| Ismételt lekérdezések | Hatékony (1 feltöltés) | Lassú (újraletöltés) |
| Nyilvános fájl | Lehetséges | Ideális |
| Életciklus-kezelés | Te irányítod | A hosztolótól függ |
Főbb megállapítások
- Az
input_fileafile_id-vel egy feltöltött fájlra, afile_url-lal pedig egy nyilvános dokumentumra hivatkozik - Az
attachment_searcheszköz automatikusan aktiválódik a releváns tartalom kinyeréséhez - Több fájlt is kombinálhatsz egyetlen kérésben
- Részesítsd előnyben a
file_id-t bizalmas vagy gyakran lekérdezett fájlok esetén - Részesítsd előnyben a
file_url-t nyilvános dokumentumok vagy gyors tesztek esetén