Salt la conținutul principal
Română— Alege o limbă
Meniu

input_file și attachment_search în API-ul Responses

Lecția 4 din 16 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Două căi către același bloc
  2. Calea file_id
  3. Calea file_url
  4. Ce face attachment_search
  5. Combinarea mai multor documente
  6. Alegerea între cele două
  7. Puncte cheie

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.

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:

  1. Extragerea conținutului din fișier: text, tabele, structură
  2. Indexarea temporară a acestui conținut, pe durata solicitării
  3. Căutarea pasajelor relevante pe baza întrebării dumneavoastră
  4. 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ă

Criteriufile_idfile_url
Încărcare prealabilăDaNu
Fișier confidențialRecomandatDescurajat
Interogări repetatePerformant (1 încărcare)Lent (redescărcare)
Fișier publicPosibilIdeal
Gestionarea ciclului de viațăControlați dumneavoastrăDepinde de gazdă

Puncte cheie

  • input_file cu file_id face referire la un fișier încărcat, iar file_url la un document public
  • Instrumentul attachment_search se activează automat pentru a extrage conținutul relevant
  • Puteți combina mai multe fișiere într-o singură solicitare
  • Preferați file_id pentru fișierele confidențiale sau interogate frecvent
  • Preferați file_url pentru documentele publice sau testele rapide