input_file și attachment_search în API-ul Responses
Pe această pagină
Două căi către același bloc
API-ul Grok Responses acceptă un document în două moduri: prin file_id, adică un fișier pe care l-ați încărcat anterior, sau prin file_url, o adresă publică pe care xAI o preia la momentul solicitării. Blocul poartă același nume în ambele cazuri, input_file, iar procesarea ulterioară este identică: Grok activează instrumentul attachment_search și extrage pasajele care răspund întrebării dumneavoastră. Ceea ce se schimbă este ciclul de viață al documentului, confidențialitatea acestuia și costul fiecărei apelări repetate.
Calea file_id
Odată ce ați trimis fișierul prin POST /v1/files, îl referenciați prin identificatorul său, alături de întrebarea dumneavoastră în text simplu:
{
"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?"
}
]
}
Această abordare are sens în trei situații. Prima este interogarea repetată: dacă echipa juridică formulează cincisprezece întrebări successive despre același contract, o singură încărcare urmată de cincisprezece referințe este mai eficientă decât cincisprezece transferuri ale aceluiași PDF. A doua este confidențialitatea, atunci când documentul nu trebuie expus printr-un URL accesibil oricui deține linkul. A treia este arhitectura aplicației dumneavoastră: dacă fișierele sunt pre-încărcate în timpul ingestiei nocturne, solicitările dumneavoastră gestionează doar identificatori.
Calea file_url
Când documentul este deja publicat undeva, încărcarea devine un pas inutil și puteți indica direct adresa:
{
"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."
}
]
}
Cazurile de utilizare tipice includ documentația deschisă pe care nu aveți motiv să o stocați, un fișier găzduit pe propria infrastructură în spatele unui URL temporar sau un test rapid în care doriți să verificați o ipoteză fără a configura un întreg pipeline de încărcare.
Această comoditate vine cu trei limitări, care vă costă toate în producție. URL-ul trebuie să fie cu adevărat public, fără autentificare: o adresă protejată printr-un token sau un cookie returnează o pagină de eroare către xAI, pe care modelul o va analiza cu sârguință în locul documentului dumneavoastră. Descărcarea se adaugă timpului de procesare a solicitării, făcând PDF-urile mari semnificativ mai lente decât în cazul utilizării file_id. În final, nu există cache din partea xAI: fiecare apel redeschide fișierul, astfel încât un singur document interogat de cincizeci de ori pe zi traversează rețeaua de cincizeci de ori.
Ce face attachment_search
De îndată ce un input_file apare în solicitarea dumneavoastră, Grok declanșează attachment_search fără nicio configurație din partea dumneavoastră. Procesarea se desfășoară în patru pași:
- Extragerea conținutului din fișier: text, tabele, structură
- Indexarea temporară a acestui conținut, pe durata solicitării
- Căutarea pasajelor relevante pe baza întrebării dumneavoastră
- Injectarea excerptelor în contextul modelului
Concentrați-vă pe adjectivul „temporar“ din al doilea pas, deoarece acesta explică o diferență de cost pe care mulți o descoperă prea târziu: indexul este reconstruit la fiecare apel și dispare ulterior. Aceasta este exact problema pe care o rezolvă colecțiile prin indexare persistentă. Rețineți, de asemenea, că modelul citează pasajele pe care le-a folosit efectiv în răspunsul său, permițându-vă să îi verificați activitatea în loc să luați de bun cuvântul său.
Combinarea mai multor documente
Nimic nu vă obligă să vă limitați la un singur fișier per solicitare. Prin stivuirea mai multor blocuri input_file, cereți modelului să raționeze pe baza setului:
{
"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 analizează ambele documente și corelează informațiile pentru a răspunde, ceea ce deschide ușa către comparații trimestriale, revizuiri ale versiunilor successive ale contractelor sau confruntări între o specificație și implementarea sa.
Alegerea între cele două
| Criteriu | file_id | file_url |
|---|---|---|
| Încărcare prealabilă | Da | Nu |
| Fișier confidențial | Recomandat | Descurajat |
| Interogări repetate | Performant (1 încărcare) | Lent (redescărcare) |
| Fișier public | Posibil | Ideal |
| Gestionarea ciclului de viață | Controlați dumneavoastră | Depinde de gazdă |
Puncte cheie
input_filecufile_idface referire la un fișier încărcat, iarfile_urlla un document public- Instrumentul
attachment_searchse activează automat pentru a extrage conținutul relevant - Puteți combina mai multe fișiere într-o singură solicitare
- Preferați
file_idpentru fișierele confidențiale sau interogate frecvent - Preferați
file_urlpentru documentele publice sau testele rapide