Leggere JSON di grandi dimensioni in Python, velocemente: benchmark di stdlib, orjson e msgspec
In sintesi: Lo stesso script di conteggio delle stelle su NDJSON impiega 754 ms con la libreria json standard ma solo 146 ms con la decodifica dichiarativa di msgspec, e il parallelismo multi-core aggiunge un altro ordine di grandezza. Questo articolo testa passo passo stdlib, orjson e msgspec su un campione da 61,4 MB e 300.000 righe, spiegando da dove nasce ogni accelerazione e quando si esaurisce.

A rallentare il parsing in Python non è mai il testo JSON in sé, ma il costo di trasformare ogni campo in un oggetto Python. Sostituisci il parser predefinito, costruisci meno oggetti, usa tutti i core — e la stessa attività di conteggio passa da 0,08 GB/s a decine di GB/s.
Un'osservazione: lo stesso codice, un ordine di grandezza di distanza
Il compito è classico: in un log NDJSON in stile GitHub Events, contare quali repository ricevono più stelle tra i record il cui type è WatchEvent. Sulla mia macchina (Ubuntu 22.04, Python 3.12, orjson 3.13, msgspec 0.22) ho generato un file campione da 61,4 MB con 300.000 righe e ho eseguito quattro implementazioni tre volte ciascuna, tenendo il miglior risultato:
| Implementazione | Miglior tempo | Throughput scalato | Relativo |
|---|---|---|---|
json.loads riga per riga |
754 ms | 0,08 GB/s | 1× (base) |
orjson.loads riga per riga |
248 ms | 0,24 GB/s | 3,0× |
msgspec decodifica in dict |
201 ms | 0,30 GB/s | 3,8× |
msgspec Struct dichiarativo |
146 ms | 0,41 GB/s | 5,2× |
Le quattro implementazioni hanno prodotto esattamente gli stessi conteggi di stelle (60.108 record), quindi tutta la differenza viene dal parsing stesso. Dati di terzi confermano lo stesso ordine di grandezza: in un benchmark pubblicato da World Programming il 2026-11-14, la stessa statistica su 7,6 GB e 2,2 milioni di eventi GitHub Archive girava a 0,28 GB/s con la libreria standard (circa 27 secondi), circa 8 volte più veloce con msgspec, mentre fastsimdjson, basato su SIMD, ha completato l'intero dataset in 55 ms su 192 thread (138 GB/s), toccando 277 GB/s su un singolo file. Attenzione: la loro macchina è una AWS c8a.metal-48xl con 192 core, quindi i numeri non si trasferiscono direttamente su un laptop — ma la forma della scala è la stessa.
Dove la libreria standard perde tempo
L'approccio json.loads riga per riga esegue una "traduzione completa" a ogni passaggio: il parser scandisce {"id": 1, "type": "WatchEvent", ...}, crea un dict nuovo, almeno sette oggetti str e diversi int per quel solo record, poi passa i riferimenti al tuo codice. Trecentomila righe significano milioni di piccole allocazioni di oggetti, e la maggior parte non la tocchi mai — l'attività di conteggio legge solo due campi, type e repo.name.
Il secondo limite è la GIL. In CPython un solo thread esegue bytecode Python in ogni istante, e anche se il codice C del parser rilascia la GIL, la tua logica di filtro e accumulo dentro il ciclo resta seriale. Aprire otto thread sull'interprete predefinito non risolve nulla; serve una strategia diversa.
Primo gradino di accelerazione: cambia parser
È il passaggio con il miglior rapporto guadagno/sforzo — l'unica modifica è l'import:
import json
import orjson
import msgspec
dec = msgspec.json.Decoder()
# I tre parser condividono quasi la stessa interfaccia, tranne dumps:
# orjson.dumps(...) restituisce bytes, non 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 è scritto in Rust, produce direttamente byte UTF-8 durante il parsing e fa ampio uso di istruzioni SIMD; sulla mia macchina era tre volte più veloce. C'è una trappola API da ricordare: orjson.dumps() restituisce bytes e non str, quindi gestiscilo quando scrivi file o concateni stringhe.
La decodifica predefinita di msgspec è allo stesso livello di orjson (3,8×), ma la sua vera arma è la decodifica dichiarativa — costruisce oggetti Python solo per i campi dichiarati:
import msgspec
class Event(msgspec.Struct):
type: str
repo: msgspec.Raw # non ancora decodificato, byte grezzi conservati
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
Non appena repo è dichiarato come msgspec.Raw, le 240.000 righe senza WatchEvent saltano completamente la costruzione dell'oggetto repo e si limitano a scansionare i token — è esattamente da qui che nasce il salto da 3,8× a 5,2×. Più campi ha un record e maggiore è la quota scartata, più rende questo gradino.
Secondo gradino: suddivisione multiprocesso, a rendimento decrescente
Quando un solo core è saturo, la risposta classica è un pool di processi: dividi il file in N intervalli di byte (allineati ai confini di riga), affida ogni porzione a un processo worker e infine unisci i Counters. Ogni processo restituisce solo una piccola tabella di risultati, quindi il costo di comunicazione è minimo — la forma ideale del map-reduce.
Il benchmark di World Programming mostra come appare questa strada: il pool di processi msgspec ha raggiunto un picco di 116 GB/s con 96 processi, e aggiungerne altri lo rallentava — i costi di schedulazione e unione mangiavano il guadagno. Due vincoli pratici si applicano: le porzioni devono essere allineate ai caratteri di nuova riga, altrimenti l'ultima riga di ogni porzione fallisce il parsing; e le attività di conteggio (che restituiscono risultati piccoli) sono il caso migliore per un pool di processi. Se devi estrarre e usare ogni record, la trasmissione tra processi diventa essa stessa il nuovo collo di bottiglia.
Terzo gradino: SIMD e Python senza GIL
fastsimdjson prende un'altra strada: 8 GB/s su un singolo core (circa 3,5 volte msgspec), perché si basa sull'indicizzazione strutturata di simdjson — prescansiona la punteggiatura per localizzare ogni token senza costruire un albero di oggetti completo; combinato con fields=["/type", "/repo/name"] legge solo i percorsi JSON Pointer dichiarati, e il callback riceve solo quei due valori.
È anche multithread: abbinato alla build free-threaded di Python 3.14 (python3.14t, il tentativo ufficiale della PEP 703 di rimuovere la GIL), 192 thread hanno elaborato 7,6 GB in 55 ms. Su sei file di benchmark pubblici da circa 1 GB ciascuno, quattro hanno superato 100 GB/s e il più veloce, il dataset twitter, ha toccato 277 GB/s. Tieni presente che sono rimisure indipendenti oltre le affermazioni del fornitore, e che il campione è lo scenario più favorevole — "leggere uno o due campi per record". I documenti profondamente annidati non raggiungono quei numeri; uno di loro è rimasto intorno ai 20 GB/s.
Tabella di scelta e ordine di adozione
| Strada | Meccanismo | Throughput (locale / riferimento) | Meglio per |
|---|---|---|---|
json (stdlib) |
costruzione completa di oggetti, un core | 0,08 GB/s | file piccoli, zero dipendenze |
| orjson | Rust + SIMD, costruzione completa | 0,24 GB/s | sostituzione in poche righe |
| msgspec dict | Rust, costruzione completa | 0,30 GB/s | scegliere uno tra orjson e msgspec |
| msgspec Struct | decodifica solo i campi dichiarati | 0,41 GB/s | array grandi, alto tasso di scarto |
| msgspec multiprocess | parallelismo a porzioni | riferimento 116 GB/s | aggregazioni, piccoli insiemi di risultati |
| fastsimdjson | indice strutturale + thread | riferimento 138-277 GB/s | estrazione di campi da NDJSON, 3.14t |
Un ordine di adozione sensato: passa prima a msgspec o orjson (pochi minuti di lavoro per un 3-5× gratis); se non basta, converti i campi del percorso caldo in Struct; aggiungi un pool di processi per le attività di conteggio; considera fastsimdjson solo quando estrai campi riga per riga da NDJSON e il tuo ambiente lo permette. Se il collo di bottiglia è la memoria e non la velocità — il file è troppo grande per leggerlo tutto — la direzione cambia: passa allo streaming con ijson, o a jq --stream da riga di comando; vedi Elaborare JSON grandi in streaming con jq e Parsing, rendering e streaming di JSON grandi. Per le regole del NDJSON riga per riga, vedi Il manuale pratico dei file JSONL.
Disciplina di misurazione e tre insidie
Primo, fissa la metodologia di cronometraggio: in questo articolo ogni implementazione gira tre volte e vale il miglior risultato (per filtrare il tremolio dello scheduler), e il file è completamente generato prima dell'inizio della misurazione. Quando citi numeri di terzi, indica le specifiche della macchina — non confrontare mai 138 GB/s su 192 core con un core del tuo laptop.
Secondo, valida la correttezza in modo incrociato: le quattro implementazioni hanno contato 60.108 stelle. Qualsiasi "accelerazione" che cambia il conteggio ha cambiato la semantica del parsing (gestione delle chiavi duplicate, precisione dei grandi interi), non ha reso le cose più veloci. Allinea prima i risultati, poi le velocità.
Terzo, tre insidie comuni: orjson.dumps() restituisce bytes, e mescolarlo con str produce silenziosamente dati sporchi con il prefisso b'...'; le porzioni del pool di processi devono essere allineate ai confini di riga — dopo f.seek(offset), scarta prima la riga incompleta; i grandi interi oltre 2^53 sono al sicuro in ogni parser Python, ma se il risultato va verso un lato JavaScript, il problema di precisione ti aspetta lì.
FAQ
orjson o msgspec, quale scegliere?
Se vuoi solo un loads più veloce, entrambi offrono 3× o più — scegli in base all'attività di manutenzione e alla familiarità del team. Scegli msgspec se ti serve decodifica parziale (msgspec.Struct + Raw), validazione dei tipi o output TypedDict/dataclass; la sua decodifica dichiarativa aggiunge un guadagno indipendente sugli array grandi.
Il multiprocesso è sempre più veloce di un core?
No. Suddivisione, avvio dei processi e unione hanno costi fissi, e con un file di qualche decina di MB spesso si perdono soldi. Le attività che restituiscono risultati grandi (ti serve ogni record) perdono il guadagno nella trasmissione. Come regola pratica: cambia prima libreria su un solo core, e parallelizza solo alla scala dei GB su attività di puro conteggio.
Perché il mio benchmark di orjson non mostra 3×?
Tre ragioni usuali: il campione è troppo piccolo (il tempo di parsing annega nella lettura del file e nel costo del ciclo); il vero collo di bottiglia è la rete o il disco, non il parsing; o i dati sono quasi tutti stringhe lunghe, quindi la costruzione di oggetti pesa poco. Usa un campione più grande, avvolgi solo il ciclo di parsing in time.perf_counter e solo allora trae conclusioni.
Che relazione ha ijson con queste librerie?
ijson è un iteratore in streaming: sacrifica throughput per memoria costante e si adatta a file molto più grandi della RAM; orjson/msgspec inseguono il throughput ma trasformano ogni record in oggetti. I due non confliggono: NDJSON alla scala dei GB si risolve leggendo riga per riga e decodificando velocemente con msgspec; ijson o jq --stream servono solo per un singolo documento JSON enorme.