input_file i attachment_search w API Responses
Na tej stronie
Dwie ścieżki do tego samego bloku
API Responses Grok przyjmuje dokument na dwa sposoby: poprzez file_id, czyli plik, który wcześniej przesłałeś, lub poprzez file_url, czyli publiczny adres, który xAI pobiera w momencie żądania. W obu przypadkach blok nosi tę samą nazwę – input_file, a przetwarzanie downstream jest identyczne: Grok aktywuje narzędzie attachment_search i wydobywa fragmenty odpowiadające na Twoje pytanie. Różnica dotyczy cyklu życia dokumentu, jego poufności oraz kosztu każdego powtórzonego wywołania.
Ścieżka file_id
Gdy wyślesz plik za pomocą POST /v1/files, odwołujesz się do niego za pomocą jego identyfikatora, dodając swoje pytanie w postaci zwykłego tekstu:
{
"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?"
}
]
}
Ta ścieżka ma sens w trzech sytuacjach. Pierwsza to powtarzające się zapytania: jeśli Twój zespół prawny zadaje piętnaście kolejnych pytań dotyczących tej samej umowy, pojedyncze przesłanie pliku, a następnie piętnaście odwołań do niego, jest lepsze niż piętnastokrotne przesyłanie tego samego PDF-a. Druga to poufność – gdy dokument nie może być udostępniony pod adresem URL dostępnym dla każdego, kto posiada link. Trzecia to architektura Twojej aplikacji: jeśli pliki są przesyłane wcześniej podczas nocnego ingestowania, Twoje żądania operują wyłącznie na identyfikatorach.
Ścieżka file_url
Gdy dokument jest już gdzieś opublikowany, przesyłanie staje się zbędne i możesz wskazać bezpośrednio jego adres:
{
"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."
}
]
}
Typowe przypadki użycia to otwarta dokumentacja, której nie masz powodu przechowywać, plik hostowany na Twojej infrastrukturze za tymczasowym adresem URL lub szybki test, w którym chcesz zweryfikować hipotezę bez konfigurowania całego potoku przesyłania plików.
Z tą wygodą wiążą się trzy ograniczenia, z których każde kosztuje Cię w środowisku produkcyjnym. Adres URL musi być naprawdę publiczny, bez żadnej autentyfikacji: adres chroniony tokenem lub plikiem cookie zwróci stronę błędu dla xAI, którą model sumiennie przeanalizuje zamiast Twojego dokumentu. Pobieranie wydłuża czas przetwarzania żądania, przez co duże pliki PDF są znacznie wolniejsze niż w przypadku file_id. Wreszcie, po stronie xAI nie ma pamięci podręcznej: każde wywołanie powoduje ponowne pobranie pliku, więc pojedynczy dokument odpytywany pięćdziesiąt razy dziennie pokonuje sieć pięćdziesiąt razy.
Jak działa attachment_search
Gdy tylko w Twoim żądaniu pojawi się input_file, Grok automatycznie uruchamia attachment_search bez żadnej konfiguracji z Twojej strony. Przetwarzanie odbywa się w czterech krokach:
- Ekstrakcja zawartości z pliku: tekst, tabele, struktura
- Tymczasowe indeksowanie tej zawartości na czas trwania żądania
- Wyszukiwanie odpowiednich fragmentów na podstawie Twojego pytania
- Wstrzyknięcie fragmentów do kontekstu modelu
Zwróć uwagę na przymiotnik „tymczasowe“ w drugim kroku, ponieważ wyjaśnia on różnicę w kosztach, którą wielu odkrywa zbyt późno: indeks jest odbudowywany przy każdym wywołaniu i znika afterward. To właśnie problem, który kolekcje rozwiązują dzięki trwałemu indeksowaniu. Zauważ również, że model cytuje fragmenty, których faktycznie użył w swojej odpowiedzi, co pozwala Ci zweryfikować jego pracę, zamiast polegać wyłącznie na jego słowach.
Łączenie wielu dokumentów
Nic nie zmusza Cię do ograniczania się do jednego pliku na żądanie. Układając wiele bloków input_file jeden po drugim, prosisz model o rozumowanie na podstawie całego zestawu:
{
"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 analizuje oba dokumenty i krzyżuje informacje, aby udzielić odpowiedzi, co otwiera drogę do porównań kwartalnych, przeglądów kolejnych wersji umów lub konfrontacji specyfikacji z jej implementacją.
Wybór między obiema opcjami
| Kryterium | file_id | file_url |
|---|---|---|
| Wcześniejsze przesłanie | Tak | Nie |
| Plik poufny | Zalecane | Odradzane |
| Powtarzające się zapytania | Wydajne (1 przesłanie) | Wolne (ponowne pobieranie) |
| Plik publiczny | Możliwe | Idealne |
| Zarządzanie cyklem życia | Ty kontrolujesz | Zależy od hosta |
Kluczowe wnioski
input_filezfile_idodwołuje się do przesłanego pliku, afile_urldo dokumentu publicznego- Narzędzie
attachment_searchaktywuje się automatycznie, aby wydobyć odpowiednią zawartość - Możesz łączyć wiele plików w jednym żądaniu
- Preferuj
file_iddla plików poufnych lub często odpytywanych - Preferuj
file_urldla dokumentów publicznych lub szybkich testów