Швидке читання великих JSON у Python: stdlib, orjson і msgspec на практиці
Головне: Той самий скрипт підрахунку Stars із NDJSON працює 754 мс зі стандартною бібліотекою json і лише 146 мс із декларативним декодуванням msgspec, а багатоядерний паралелізм додає ще порядку величини. У статті покроково протестовано stdlib, orjson і msgspec на вибірці 61.4 МБ і 300 000 рядків — і розказано, звідки береться кожне прискорення і коли воно вичерпується.

Python сповільнює парсинг не текст JSON сам по собі, а вартість перетворення кожного поля на об'єкт Python. Замініть парсер за замовчуванням, створюйте менше об'єктів, задійте всі ядра — і та сама задача підрахунку зросте з 0.08 GB/s до десятків GB/s.
Спостереження: той самий код, різниця в порядок величини
Задача типовa: у журналі NDJSON у стилі GitHub Events порахувати, які репозиторії найчастіше отримують зірки серед записів із type рівним WatchEvent. На моїй машині (Ubuntu 22.04, Python 3.12, orjson 3.13, msgspec 0.22) я згенерував файл-вибірку на 61.4 МБ і 300 000 рядків і прогнав чотири реалізації по три рази, беручи найкращий результат:
| Реалізація | Найкращий час | Пропускна здатність | Відносно |
|---|---|---|---|
json.loads рядок за рядком |
754 мс | 0.08 GB/s | 1× (базова) |
orjson.loads рядок за рядком |
248 мс | 0.24 GB/s | 3.0× |
msgspec декодування в dict |
201 мс | 0.30 GB/s | 3.8× |
msgspec декларативний Struct |
146 мс | 0.41 GB/s | 5.2× |
Усі чотири реалізації видали точно однакові лічильники зірок (60 108 записів), тож уся різниця походить від самого парсингу. Сторонні дані підтверджують той самий порядок: у тесті, опублікованому World Programming 2026-11-14, та сама статистика по 7.6 ГБ і 2.2 мільйона подій GitHub Archive виконувалася зі швидкістю 0.28 GB/s зі стандартною бібліотекою (близько 27 секунд), приблизно у 8 разів швидше з msgspec, а SIMD-орієнтований fastsimdjson обробив увесь набір за 55 мс на 192 потоках (138 GB/s), досягаючи піку 277 GB/s на одному файлі. Зверніть увагу: їхня машина — AWS c8a.metal-48xl зі 192 ядрами, тому числа не переносяться прямо на ноутбук — але форма драбини та сама.
Де стандартна бібліотека втрачає час
Підхід json.loads рядок за рядком виконує «повний переклад» на кожному кроці: парсер сканує {"id": 1, "type": "WatchEvent", ...}, створює новий dict, щонайменше сім об'єктів str і кілька int для того одного запису, а потім передає посилання вашому коду. Триста тисяч рядків означають мільйони дрібних виділень об'єктів, і більшість із них ви ніколи не торкаєтеся — задача підрахунку читає лише два поля, type і repo.name.
Друга межа — GIL. У CPython лише один потік виконує байткод Python у кожен момент, і навіть якщо C-код парсера відпускає GIL, ваша логіка фільтрації та накопичення всередині циклу залишається послідовною. Вісім потоків на інтерпретаторі за замовчуванням не вирішують нічого; потрібна інша стратегія.
Перший рівень прискорення: замініть парсер
Це крок із найвищою віддачею на зусилля — змінюється лише import:
import json
import orjson
import msgspec
dec = msgspec.json.Decoder()
# У трьох парсерів майже однаковий інтерфейс, окрім dumps:
# orjson.dumps(...) повертає bytes, а не 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 написаний на Rust, під час парсингу одразу створює байти UTF-8 і активно використовує SIMD-інструкції; на моїй машині він був у три рази швидшим. Є одна пастка API: orjson.dumps() повертає bytes, а не str, тож врахуйте це під час запису файлів чи конкатенації рядків.
Декодування msgspec за замовчуванням в одному класі з orjson (3.8×), але його справжня зброя — декларативне декодування: об'єкти Python створюються лише для оголошених полів:
import msgspec
class Event(msgspec.Struct):
type: str
repo: msgspec.Raw # ще не декодовано, зберігаються сирі байти
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
Щойно repo оголошено як msgspec.Raw, 240 000 рядків без WatchEvent повністю пропускають побудову об'єкта repo і лише сканують токени — саме звідси стрибок із 3.8× до 5.2×. Чим більше полів у записі і чим вища частка відкинутих, тим більша вигода від цього кроку.
Другий рівень: розподіл між процесами зі спадною віддачею
Коли одне ядро вичерпано, класична відповідь — пул процесів: файл ділиться на N діапазонів байтів (вирівняних по межах рядків), кожен шматок отримує окремий процес-працівник, а наприкінці Counters об'єднуються. Кожен процес повертає лише маленьку таблицю результатів, тож витрати на обмін мінімальні — ідеальна форма map-reduce.
Тест World Programming показує, як виглядає цей шлях: пул процесів msgspec досяг піку 116 GB/s на 96 процесах, а додавання ще процесів робило його повільнішим — накладні витрати на планування та злиття з'їдали виграш. Є два практичні обмеження: шматки мають бути вирівняні по символях нового рядка, інакше останній рядок кожного шматка не розбереться; і задачі підрахунку (які повертають малі результати) — найкращий випадок для пулу процесів. Якщо потрібно витягти й використати кожен запис, сама передача між процесами стає новим вузьким місцем.
Третій рівень: SIMD і Python без GIL
fastsimdjson іде іншою дорогою: 8 GB/s на одному ядрі (приблизно у 3.5 рази швидше за msgspec), бо він спирається на структурне індексування simdjson — попередньо сканує розділові знаки, щоб визначити позицію кожного токена, не будуючи повного дерева об'єктів; у поєднанні з fields=["/type", "/repo/name"] він читає лише оголошені шляхи JSON Pointer, і колбек отримує лише ці два значення.
Він також багатопотоковий: у парі з вільнопоточним збірком Python 3.14 (python3.14t, офіційна спроба PEP 703 прибрати GIL) 192 потоки обробили 7.6 ГБ за 55 мс. На шести публічних тестових файлах приблизно по 1 ГБ чотири перевищили 100 GB/s, а найшвидший, набір twitter, досяг 277 GB/s. Пам'ятайте, що це незалежні повторні виміри поза заявами виробника, і вибірка — найсприятливіший сценарій «читати одне-два поля на запис». Глибоко вкладені документи таких чисел не досягають; один із них тримався близько 20 GB/s.
Шпаргалка з вибору та порядок впровадження
| Шлях | Механізм | Пропускна здатність (локальна/довідкова) | Найкраще для |
|---|---|---|---|
json (stdlib) |
повне створення об'єктів, одне ядро | 0.08 GB/s | малі файли, без залежностей |
| orjson | Rust + SIMD, повне створення об'єктів | 0.24 GB/s | заміна за кілька рядків |
| msgspec dict | Rust, повне створення об'єктів | 0.30 GB/s | або orjson, або msgspec |
| msgspec Struct | декодує лише оголошені поля | 0.41 GB/s | великі масиви, високий відсоток відкинутих |
| msgspec багатопроцесний | паралелізм шматками | довідково 116 GB/s | агрегації, малі результати |
| fastsimdjson | структурний індекс + потоки | довідково 138-277 GB/s | витяг полів із NDJSON, 3.14t |
Розумний порядок впровадження: спочатку перейдіть на msgspec або orjson (кілька хвилин роботи за безкоштовні 3-5×); якщо замало — перетворіть поля гарячого шляху на Struct; для задач підрахунку додайте пул процесів; fastsimdjson розглядайте лише коли витягуєте поля рядок за рядком із NDJSON і ваше середовище це дозволяє. Якщо вузьке місце — пам'ять, а не швидкість (файл завеликий, щоб читати целиком), напрям змінюється: переходьте на потокове ijson або jq --stream у командному рядку; дивіться Потокова обробка великих JSON за допомогою jq та Парсинг, рендеринг і потокова обробка великих JSON. Про рядкові правила NDJSON читайте у Довіднику з файлів JSONL.
Дисципліна вимірювання і три пастки
По-перше, зафіксуйте методику хронометражу: у цій статті кожна реалізація запускається тричі, береться найкращий результат (щоб відсіяти тремтіння планувальника), а файл повністю згенеровано до початку вимірювання. Цитуючи сторонні числа, вказуйте специфікацію машини — ніколи не порівнюйте 138 GB/s на 192 ядрах з одним ядром свого ноутбука.
По-друге, перехресно перевіряйте коректність: усі чотири реалізації порахували 60 108 зірок. Будь-яке «прискорення», що змінює лічильник, змінило семантику парсингу (обробка дублікатів ключів, точність великих цілих), а не зробило швидше. Спершу звірте результати, потім швидкості.
По-третє, три типові пастки: orjson.dumps() повертає bytes, і змішування зі str тихо створює брудні дані з префіксом b'...'; шматки пулу процесів мають бути вирівняні по межах рядків — після f.seek(offset) спершу відкиньте неповний рядок; великі цілі понад 2^53 безпечні в кожному парсері Python, але якщо результат іде на сторону JavaScript, проблеми з точністю чекають уже там.
FAQ
Що вибрати: orjson чи msgspec?
Якщо потрібен лише швидший loads, обидва дають 3× і більше — обирайте за активністю підтримки та звичками команди. Обирайте msgspec, коли потрібне часткове декодування (msgspec.Struct + Raw), перевірка типів або вихід у TypedDict/dataclass; декларативне декодування додає окремий шар виграшу на великих масивах.
Чи багатопроцесність завжди швидша за одне ядро?
Ні. Розподіл, запуск процесів і злиття мають фіксовані витрати, і з файлом на кілька десятків МБ це зазвичай збиток. Задачі з великими результатами (потрібен кожен запис) втрачають виграш на передачі. За практичним правилом: спершу змініть бібліотеку на одному ядрі, а паралельтеся лише на масштабі ГБ у чистих задачах підрахунку.
Чому мій тест orjson не показує 3×?
Три типові причини: вибірка задрібна (час парсингу тоне у витратах на читання файлу та цикл); справжнє вузьке місце — мережа чи диск, а не парсинг; або дані переважно з довгих рядків, тож частка створення об'єктів мала. Візьміть більшу вибірку, обгорніть лише цикл парсинга в time.perf_counter і лише тоді робіть висновки.
Як ijson пов'язаний із цими бібліотеками?
ijson — потоковий ітератор: він жертвує пропускною здатністю заради сталої пам'яті й пасує файлам, значно більшим за RAM; orjson/msgspec гоняться за пропускною здатністю, але перетворюють кожен запис на об'єкти. Вони не конфліктують: для NDJSON на масштабі ГБ досить читати рядок за рядком і швидко декодувати msgspec; ijson чи jq --stream потрібні лише для одного величезного JSON-документа.