JSON Toolkit

Швидке читання великих JSON у Python: stdlib, orjson і msgspec на практиці

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

Просунутий~6 хв читанняОпубліковано 2026-11-15Оновлено 2026-11-15
Порівняння шляхів прискорення парсингу великих JSON у Python: stdlib, orjson, msgspec та багатоядерність

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-документа.