Szybkie czytanie dużych JSON w Pythonie: testy stdlib, orjson i msgspec
Podsumowanie: Ten sam skrypt zliczający Stars z NDJSON zajmuje 754 ms ze standardową biblioteką json, a tylko 146 ms z deklaratywnym dekodowaniem msgspec — a wielordzeniowy paralelizm dodaje jeszcze jeden rząd wielkości. Artykuł krok po kroku testuje stdlib, orjson i msgspec na próbce 61,4 MB i 300 000 wierszy, wyjaśniając, skąd bierze się każde przyspieszenie i kiedy się wyczerpuje.

Parsowanie w Pythonie spowalnia nigdy sam tekst JSON, lecz koszt zamiany każdego pola w obiekt Pythona. Wymień domyślny parser, buduj mniej obiektów, użyj wszystkich rdzeni — i to samo zadanie zliczania wzrośnie z 0,08 GB/s do dziesiątek GB/s.
Obserwacja: ten sam kod, różnica o rząd wielkości
Zadanie klasyczne: w logu NDJSON w stylu GitHub Events policzyć, które repozytoria najczęściej dostają gwiazdki wśród rekordów, gdzie type równa się WatchEvent. Na mojej maszynie (Ubuntu 22.04, Python 3.12, orjson 3.13, msgspec 0.22) wygenerowałem plik próbkowy o rozmiarze 61,4 MB i 300 000 wierszy i uruchomiłem cztery implementacje po trzy razy, licząc najlepszy wynik:
| Implementacja | Najlepszy czas | Przeliczona przepustowość | Względnie |
|---|---|---|---|
json.loads po wierszu |
754 ms | 0,08 GB/s | 1× (baza) |
orjson.loads po wierszu |
248 ms | 0,24 GB/s | 3,0× |
msgspec dekodowanie do dict |
201 ms | 0,30 GB/s | 3,8× |
msgspec deklaratywny Struct |
146 ms | 0,41 GB/s | 5,2× |
Wszystkie cztery implementacje wydały dokładnie te same liczby gwiazdek (60 108 rekordów), więc cała różnica pochodzi z samego parsowania. Dane stron trzecich potwierdzają ten sam rząd: w teście opublikowanym przez World Programming 2026-11-14 ta sama statystyka po 7,6 GB i 2,2 milionach zdarzeń GitHub Archive szła ze standardową biblioteką z prędkością 0,28 GB/s (około 27 sekund), z msgspec około 8× szybciej, a fastsimdjson oparty na SIMD przetworzył cały zbiór w 55 ms na 192 wątkach (138 GB/s), osiągając 277 GB/s na pojedynczym pliku. Uwaga: ich maszyna to AWS c8a.metal-48xl ze 192 rdzeniami, więc liczby nie przenoszą się wprost na laptopa — ale forma drabiny jest ta sama.
Gdzie standardowa biblioteka traci czas
Podejście json.loads po wierszu robi na każdym kroku „pełne tłumaczenie”: parser przechodzi przez {"id": 1, "type": "WatchEvent", ...}, tworzy dla tego jednego rekordu nowy dict, co najmniej siedem obiektów str i kilka int, a potem przekazuje referencje Twojemu kodowi. Trzysta tysięcy wierszy to miliony drobnych alokacji obiektów, których większości nigdy nie dotkniesz — zadanie zliczania czyta tylko dwa pola, type i repo.name.
Drugim ograniczeniem jest GIL. W CPython w każdej chwili tylko jeden wątek wykonuje bajtkod Pythona, i nawet jeśli kod C parsera zwalnia GIL, Twoja logika filtrowania i sumowania w pętli pozostaje szeregowa. Osiem wątków na domyślnym interpreterze nie rozwiązuje nic; potrzebna jest inna strategia.
Pierwszy stopień przyspieszenia: wymień parser
To krok z najlepszym stosunkiem efektu do wysiłku — jedyna zmiana to import:
import json
import orjson
import msgspec
dec = msgspec.json.Decoder()
# Trzy parsery mają prawie ten sam interfejs, poza dumps:
# orjson.dumps(...) zwraca bytes, nie str
for name, load in [("stdlib", json.loads), ("orjson", orjson.loads), ("msgspec", dec.decode)]:
stars = {}
with open("events.ndjson", "rb") as f:
for line in f:
e = load(line)
if e["type"] == "WatchEvent":
stars[e["repo"]["name"]] = stars.get(e["repo"]["name"], 0) + 1
orjson jest napisany w Rust, podczas parsowania od razu tworzy bajty UTF-8 i hojnie używa instrukcji SIMD; na mojej maszynie był trzy razy szybszy. Warta zapamiętania pułapka API: orjson.dumps() zwraca bytes, a nie str — uwzględnij to przy zapisie plików czy sklejaniu stringów.
Domyślne dekodowanie msgspec jest w jednej klasie z orjson (3,8×), ale jego prawdziwą bronią jest dekodowanie deklaratywne — obiekty Pythona buduje tylko dla zadeklarowanych pól:
import msgspec
class Event(msgspec.Struct):
type: str
repo: msgspec.Raw # jeszcze nie zdekodowane, zachowywane są surowe bajty
dec = msgspec.json.Decoder(Event)
stars = {}
with open("events.ndjson", "rb") as f:
for line in f:
e = dec.decode(line)
if e.type == "WatchEvent":
name = msgspec.json.decode(e.repo)["name"]
stars[name] = stars.get(name, 0) + 1
Gdy tylko repo jest zadeklarowane jako msgspec.Raw, 240 000 wierszy bez WatchEvent całkowicie pomija budowę obiektu repo i tylko skanuje tokeny — dokładnie stąd pochodzi skok z 3,8× na 5,2×. Im więcej rekord ma pól i im wyższy udział odrzucanych, tym większy zysk daje ten stopień.
Drugi stopień: podział między procesami o malejącym zysku
Gdy jedno jądro jest wyczerpane, klasyczna odpowiedź to pula procesów: podziel plik na N zakresów bajtów (wyrównanych do granic wierszy), każdy kawałek oddaj procesowi roboczemu, a na końcu połącz Counters. Każdy proces zwraca tylko małą tabelę wyników, więc koszt komunikacji jest minimalny — idealna postać map-reduce.
Test World Programming pokazuje, jak ta droga wygląda: pula procesów msgspec osiągnęła szczyt 116 GB/s przy 96 procesach, a dodawanie dalszych procesów go spowalniało — koszty szeregowania i scalania zjadały zysk. Obowiązują dwa praktyczne ograniczenia: kawałki muszą być wyrównane do znaków nowej linii, inaczej ostatni wiersz każdego kawałka nie sparsuje się; i zadania zliczające (zwracające małe wyniki) to najlepszy przypadek dla puli procesów. Jeśli musisz wyciągnąć i wykorzystać każdy rekord, sama transmisja między procesami staje się nowym wąskim gardłem.
Trzeci stopień: SIMD i Python bez GIL
fastsimdjson idzie inną drogą: 8 GB/s na jednym rdzeniu (około 3,5× msgspec), bo opiera się na strukturalnym indeksowaniu simdjson — z góry przeskanowuje interpunkcję i ustala pozycję każdego tokenu, nie budując pełnego drzewa obiektów; w połączeniu z fields=["/type", "/repo/name"] czyta tylko zadeklarowane ścieżki JSON Pointer, a callback dostaje tylko te dwie wartości.
Jest też wielowątkowy: w parze z buildem free-threaded Pythona 3.14 (python3.14t, oficjalna próba PEP 703 usunięcia GIL) 192 wątki przetworzyły 7,6 GB w 55 ms. Na sześciu publicznych plikach testowych około 1 GB cztery przekroczyły 100 GB/s, a najszybszy, zbiór twitter, osiągnął 277 GB/s. Pamiętaj, że to niezależne ponowne pomiary ponad twierdzenia producenta, a próbka to najkorzystniejszy scenariusz „czytać jedno-dwa pola na rekord”. Głęboko zagnieżdżone dokumenty nie sięgają takich liczb; jeden z nich trzymał się w okolicach 20 GB/s.
Ściągawka wyboru i kolejność wdrażania
| Droga | Mechanizm | Przepustowość (lokalna/referencyjna) | Najlepsze dla |
|---|---|---|---|
json (stdlib) |
pełna budowa obiektów, jedno jądro | 0,08 GB/s | małe pliki, bez zależności |
| orjson | Rust + SIMD, pełna budowa obiektów | 0,24 GB/s | wymiana w kilku wierszach |
| msgspec dict | Rust, pełna budowa obiektów | 0,30 GB/s | albo orjson, albo msgspec |
| msgspec Struct | dekoduje tylko zadeklarowane pola | 0,41 GB/s | duże tablice, wysoki udział odpadu |
| msgspec wieloprocesowy | paralelizm kawałkami | referencyjnie 116 GB/s | agregacje, małe wyniki |
| fastsimdjson | indeks strukturalny + wątki | referencyjnie 138-277 GB/s | wyciąganie pól z NDJSON, 3.14t |
Rozsądna kolejność wdrażania: najpierw przejdź na msgspec lub orjson (kilka minut pracy za 3-5× za darmo); jeśli mało, przekonwertuj pola gorącej ścieżki na Struct; dla zadań zliczających dodaj pulę procesów; fastsimdjson rozważaj tylko wtedy, gdy wyciągasz pola wiersz po wierszu z NDJSON, a środowisko na to pozwala. Jeśli wąskim gardłem jest pamięć, a nie szybkość — plik jest za duży, by przeczytać go w całości — kierunek się zmienia: przejdź na streamowanie z ijson albo na jq --stream w wierszu poleceń; zobacz Strumieniowa obróbka dużych JSON z jq i Parsowanie, renderowanie i strumieniowanie dużych JSON. O wierszowych zasadach NDJSON przeczytasz w Praktycznym podręczniku plików JSONL.
Dyscyplina pomiaru i trzy pułapki
Po pierwsze, ustal metodologię pomiaru czasu: w tym artykule każda implementacja uruchamiana jest trzy razy, liczy się najlepszy wynik (by odfiltrować drgania planisty), a plik jest w pełni wygenerowany przed rozpoczęciem pomiaru. Cytując cudze liczby, podawaj specyfikację maszyny — nigdy nie porównuj 138 GB/s na 192 rdzeniach z jednym rdzeniem swojego laptopa.
Po drugie, krzyżowo sprawdzaj poprawność: wszystkie cztery implementacje policzyły 60 108 gwiazdek. Każde „przyspieszenie”, które zmienia licznik, zmieniło semantykę parsowania (obsługa duplikatów kluczy, precyzja dużych liczb całkowitych), a nie przyspieszyło. Najpierw zrównaj wyniki, potem prędkości.
Po trzecie, trzy typowe pułapki: orjson.dumps() zwraca bytes, a zmieszanie ze str po cichu tworzy brudne dane z prefiksem b'...'; kawałki puli procesów muszą być wyrównane do granic wierszy — po f.seek(offset) najpierw odrzuć niepełny wiersz; duże liczby całkowite powyżej 2^53 są bezpieczne w każdym parserze Pythona, ale jeśli wynik idzie na stronę JavaScript, problem precyzji czeka już tam.
FAQ
Wybrać orjson czy msgspec?
Jeśli chcesz tylko szybszego loads, oba dają 3× i więcej — wybieraj według aktywności utrzymania i obycia zespołu. Weź msgspec, gdy potrzebujesz częściowego dekodowania (msgspec.Struct + Raw), walidacji typów lub wyjścia TypedDict/dataclass; jego dekleratywne dekodowanie przynosi na dużych tablicach dodatkowy, samodzielny zysk.
Czy wieloprocesowość jest zawsze szybsza od jednego jądra?
Nie. Dzielenie, uruchamianie procesów i scalanie mają stałe koszty, a przy pliku kilkudziesięcio MB to zwykle strata. Zadania zwracające duże wyniki (potrzebujesz każdego rekordu) tracą zysk na transmisji. Z praktycznej reguły: najpierw wymień bibliotekę na jednym jądrze, a równoległość stosuj dopiero w skali GB przy czystych zadaniach zliczania.
Dlaczego mój benchmark orjson nie pokazuje 3×?
Trzy zwykłe powody: próbka za mała (czas parsowania tonie w czytaniu pliku i kosztach pętli); prawdziwe wąskie gardło to sieć albo dysk, nie parsowanie; albo dane to prawie same długie łańcuchy, więc udział budowy obiektów jest mały. Weź większą próbkę, owiń tylko pętlę parsowania w time.perf_counter i dopiero wtedy wyciągaj wnioski.
Jak ijson się ma do tych bibliotek?
ijson to iterator strumieniowy: poświęca przepustowość za stałą pamięć i pasuje do plików znacznie większych niż RAM; orjson/msgspec gonią za przepustowością, ale każdy rekord zamieniają w obiekty. Nie kolidują: NDJSON w skali GB rozwiążesz czytaniem po wierszu i szybkim dekodowaniem msgspec; ijson albo jq --stream potrzebny jest tylko jednemu ogromnemu dokumentowi JSON.