Obsługiwane formaty plików
Na tej stronie
Jedyne kryterium, które ma znaczenie
Zanim zapytasz, czy konkretny format zadziała, zadaj sobie prostsze pytanie: czy plik zawiera tekst możliwy do wyodrębnienia? Interfejs API xAI Files obsługuje pliki tekstowe. Jeśli dowolne narzędzie potrafi wyciągnąć z niego znaki bez konieczności stosowania optycznego rozpoznawania znaków (OCR), dokument zostanie prawdopodobnie zaakceptowany. Czyste pliki binarne – obrazy, audio, wideo – nie mają tu miejsca; w przypadku obrazu właściwym podejściem jest użycie input_image w Responses API, a nie w Files API.
To pojedyncze kryterium wyjaśnia większość odrzuceń, z jakimi się spotkasz. Wyjaśnia również, dlaczego raport finansowy w formacie PDF działa idealnie, podczas gdy PDF ze skanera biurkowego zawodzi: pierwszy zawiera warstwę tekstową, drugi to jedynie seria zdjęć stron.
Cztery obsługiwane kategorie
Obsługiwane formaty dzielą się na cztery kategorie, z których każda ma swoje preferowane zastosowania.
| Kategoria | Formaty | Co ekstrahuje Grok |
|---|---|---|
| Dokumenty biurowe | PDF, DOCX, ODT, EPUB, RTF | Tekst, tabele, struktura sekcji |
| Kod źródłowy | .py, .js, .ts, .java, .go, .rs, .cpp, HTML, CSS, XML i ponad 80 języków | Importy, zależności, struktura plików |
| Dane strukturalne | CSV, TSV, JSON, JSON-LD, vCard | Hierarchia pól, statystyki, trendy |
| Zwykły tekst | TXT, MD | Zawartość liniowa, nagłówki i listy Markdown |
Jeśli chodzi o dokumenty biurowe, PDF pozostaje najpopularniejszym formatem, a Grok ekstrahuje z niego tekst, tabele i podział na sekcje. Dokument Word DOCX zachowuje swoje formatowanie – pogrubienia, kursywę, listy – podczas ekstrakcji, podobnie jak jego otwartoźródłowy odpowiednik ODT. Format EPUB staje się interesujący, gdy pracujesz nad długimi publikacjami, white paperami lub całymi podręcznikami, natomiast RTF, choć starszy, nadal jest wystarczająco powszechny, aby go obsługiwać.
Kod źródłowy to obszar, w którym Files API najbardziej wyróżnia się na tle metody kopiuj-wklej. Wysłanie pełnego pliku payment.py, a nie izolowanej funkcji, zmienia charakter analizy: Grok widzi importy, zależności i organizację pliku, dzięki czemu może wykryć, że wyjątek jest przechwytywany trzydzieści linii wyżej lub że stała zdefiniowana na początku stoi w sprzeczności z komentarzem na końcu. Obsługiwanych jest ponad 80 języków opartych na składni tekstowej.
Formaty danych służą przede wszystkim analizie ilościowej. Plik CSV z miesięczną sprzedażą pozwala Grokowi obliczyć odchylenia, wykryć sezonowość i podsumować zbiór danych liczący kilka tysięcy wierszy; konfiguracja JSON lub odpowiedź API daje mu dostęp do hierarchii i relacji między polami, czego nie pokazałaby spłaszczona tabela. JSON-LD dodaje kontekst semantyczny do powiązanych danych, a vCard obsługuje wizytówki kontaktowe. Na koniec, TXT i MD działają zgodnie z oczekiwaniami, przy czym Markdown oferuje zaletę przekazywania lekkiej struktury nagłówków i list.
Typowe pułapki
W środowisku produkcyjnym stale pojawiają się cztery ograniczenia. Pierwszym jest rozmiar: 48 MB na plik; powyżej tego limitu musisz podzielić dokument. Drugim jest kodowanie: Twoje pliki muszą być w formacie UTF-8, a eksport w ISO-8859 lub Windows-1252 spowoduje uszkodzenie znaków akcentowanych, czasem w sposób subtelny – zamiana `é` na `é` w środku umowy może pozostać niezauważona, dopóki wyszukiwanie nie zwróci pustych wyników. Trzecim jest brak przetwarzania obrazów: PNG, JPG czy GIF nie należą do tego miejsca; musisz użyć input_image. Czwartym przypadkiem jest zeskanowany PDF bez warstwy tekstowej OCR, który zostanie zaakceptowany podczas przesyłania, ale nie zwróci żadnych wyników podczas zapytania.
Ta ostatnia sytuacja wymaga wyrobienia prostego nawyku: przed przesłaniem partii plików PDF o niepewnym pochodzeniu otwórz jeden z nich i spróbuj zaznaczyć myszą akapit. Jeśli nic się nie zaznacza, Twoje dokumenty muszą wcześniej przejść przez proces OCR.
Wybieraj możliwie najbardziej strukturalny format
Gdy te same informacje istnieją w wielu formach, zawsze wybieraj tę najbardziej strukturalną. Do analizy raportów preferuj oryginalny plik PDF lub DOCX, które zachowują hierarchię, zamiast płaskiego eksportu tekstowego. Do analizy danych plik CSV dla tabel i JSON dla danych hierarchicznych dadzą lepsze wyniki niż arkusz kalkulacyjny przekształcony w zwykły tekst. Podczas przeglądu kodu wyślij oryginalny plik źródłowy z jego właściwym rozszerzeniem. W przypadku dokumentacji sprawdza się Markdown lub PDF, w zależności od tego, co masz u źródła. Zasada sprowadza się do jednego zdania: każdy poziom struktury, który zachowasz, to poziom kontekstu, którego model nie będzie musiał rekonstruować.
Kluczowe wnioski
- Files API obsługuje dokumenty (PDF, DOCX, EPUB), kod (ponad 80 języków), dane (CSV, JSON) oraz zwykły tekst
- Limit to 48 MB na plik w kodowaniu UTF-8
- Obrazy i pliki binarne nie są obsługiwane – do obrazów użyj
input_image - Preferuj możliwie najbardziej strukturalny format, aby uzyskać lepszą analizę