JSON Toolkit

Ler JSON grande em Python com velocidade: benchmark de stdlib, orjson e msgspec

Resumo: O mesmo script de contagem de Stars em NDJSON leva 754 ms com a biblioteca json padrão e apenas 146 ms com a decodificação declarativa do msgspec, e o paralelismo multinúcleo adiciona mais uma ordem de grandeza. Este artigo testa passo a passo stdlib, orjson e msgspec em uma amostra de 61,4 MB e 300.000 linhas, explicando de onde vem cada aceleração e quando ela se esgota.

Avançado~6 min de leituraPublicado em 2026-11-15Atualizado em 2026-11-15
Comparação dos caminhos de aceleração do parsing de JSON grande em Python: stdlib, orjson, msgspec e paralelismo multinúcleo

O que deixa o parsing em Python lento nunca é o próprio texto JSON, e sim o custo de transformar cada campo em um objeto Python. Troque o parser padrão, construa menos objetos, use todos os núcleos — e a mesma tarefa de contagem salta de 0,08 GB/s para dezenas de GB/s.

Uma observação: o mesmo código, um ordem de grandeza de diferença

A tarefa é clássica: em um log NDJSON no estilo GitHub Events, contar quais repositórios recebem mais estrelas entre os registros cujo type é WatchEvent. Na minha máquina (Ubuntu 22.04, Python 3.12, orjson 3.13, msgspec 0.22), gerei um arquivo de amostra de 61,4 MB com 300.000 linhas e executei quatro implementações três vezes cada, guardando o melhor resultado:

Implementação Melhor tempo Throughput proporcional Relativo
json.loads linha a linha 754 ms 0,08 GB/s 1× (base)
orjson.loads linha a linha 248 ms 0,24 GB/s 3,0×
msgspec decodificando para dict 201 ms 0,30 GB/s 3,8×
msgspec Struct declarativo 146 ms 0,41 GB/s 5,2×

As quatro implementações produziram exatamente as mesmas contagens de estrelas (60.108 registros), então toda a diferença vem do próprio parsing. Dados de terceiros confirmam a mesma ordem de grandeza: em um benchmark publicado pela World Programming em 2026-11-14, a mesma estatística sobre 7,6 GB e 2,2 milhões de eventos do GitHub Archive rodava a 0,28 GB/s com a biblioteca padrão (cerca de 27 segundos), cerca de 8 vezes mais rápido com msgspec, enquanto o fastsimdjson, baseado em SIMD, processou todo o conjunto em 55 ms em 192 threads (138 GB/s), chegando a 277 GB/s em um único arquivo. Atenção: a máquina deles é uma AWS c8a.metal-48xl com 192 núcleos, então esses números não se transferem direto para um notebook — mas o formato da escada é o mesmo.

Onde a biblioteca padrão perde tempo

A abordagem de json.loads linha a linha faz uma "tradução completa" em cada etapa: o parser varre {"id": 1, "type": "WatchEvent", ...}, cria um dict novo, pelo menos sete objetos str e vários int para aquele único registro, e depois entrega as referências ao seu código. Trezentas mil linhas significam milhões de pequenas alocações de objetos, e você nunca toca na maioria delas — a tarefa de contagem lê apenas dois campos, type e repo.name.

O segundo limite é a GIL. No CPython, apenas uma thread executa bytecode Python por vez, e mesmo que o código C do parser libere a GIL, sua lógica de filtro e acumulação dentro do loop continua serial. Abrir oito threads no interpretador padrão não resolve nada; é preciso mudar a estratégia.

Primeiro nível de aceleração: troque o parser

É o passo com melhor custo-benefício — a única mudança é o import:

import json
import orjson
import msgspec

dec = msgspec.json.Decoder()

# Os três parsers compartilham quase a mesma interface, exceto dumps:
# orjson.dumps(...) retorna bytes, não 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

O orjson é escrito em Rust, produz bytes UTF-8 diretamente durante o parsing e faz uso intenso de instruções SIMD; na minha máquina ele foi três vezes mais rápido. Há uma armadilha de API que vale lembrar: orjson.dumps() retorna bytes e não str, então trate isso ao gravar arquivos ou concatenar strings.

A decodificação padrão do msgspec está no mesmo nível do orjson (3,8×), mas sua arma verdadeira é a decodificação declarativa — ela constrói objetos Python apenas para os campos declarados:

import msgspec

class Event(msgspec.Struct):
    type: str
    repo: msgspec.Raw          # ainda não decodificado, bytes crus mantidos

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

Assim que repo é declarado como msgspec.Raw, as 240.000 linhas sem WatchEvent pulam completamente a construção do objeto repo e apenas escaneiam tokens — é exatamente daí que vem o salto de 3,8× para 5,2×. Quanto mais campos tem um registro e maior a proporção descartada, maior o ganho desse passo.

Segundo nível: fragmentação multiprocesso, com ganhos decrescentes

Quando um único núcleo satura, a resposta clássica é um pool de processos: divida o arquivo em N faixas de bytes (alinhadas às fronteiras de linha), entregue cada fatia a um processo trabalhador e mescle os Counters no final. Cada processo devolve apenas uma pequena tabela de resultados, então o custo de comunicação é mínimo — a forma ideal de map-reduce.

O benchmark da World Programming mostra como esse caminho se comporta: o pool de processos msgspec atingiu o pico de 116 GB/s com 96 processos, e adicionar mais processos o deixava mais lento — os custos de escalonamento e mesclagem consumiam o ganho. Duas restrições práticas se aplicam: as fatias devem estar alinhadas aos caracteres de nova linha, senão a última linha de cada fatia falha no parsing; e tarefas de contagem (que devolvem resultados pequenos) são o melhor caso para um pool de processos. Se você precisa extrair e usar cada registro, a própria transferência entre processos se torna o novo gargalo.

Terceiro nível: SIMD e Python sem GIL

O fastsimdjson segue outro caminho: 8 GB/s em um único núcleo (cerca de 3,5 vezes o msgspec), porque se apoia na indexação estruturada do simdjson — ele pré-escaneia a pontuação para localizar cada token sem construir uma árvore completa de objetos; combinado com fields=["/type", "/repo/name"], lê apenas os caminhos JSON Pointer declarados, e o callback recebe somente esses dois valores.

Ele também é multithread: combinado com o build free-threaded do Python 3.14 (python3.14t, a tentativa oficial da PEP 703 de remover a GIL), 192 threads processaram 7,6 GB em 55 ms. Em seis arquivos públicos de benchmark de cerca de 1 GB cada, quatro ultrapassaram 100 GB/s e o mais rápido, o dataset twitter, alcançou 277 GB/s. Lembre que essas são remedições independentes além das afirmações do fornecedor, e que a amostra é o cenário mais favorável — "ler um ou dois campos por registro". Documentos profundamente aninhados não chegam a esses números; um deles ficou perto de 20 GB/s.

Tabela de escolha rápida e ordem de adoção

Caminho Mecanismo Throughput (local / referência) Melhor para
json (stdlib) construção total de objetos, um núcleo 0,08 GB/s arquivos pequenos, zero dependências
orjson Rust + SIMD, construção total 0,24 GB/s substituição em poucas linhas
msgspec dict Rust, construção total 0,30 GB/s escolher um entre orjson e msgspec
msgspec Struct decodifica só os campos declarados 0,41 GB/s arrays grandes, alta taxa de descarte
msgspec multiprocesso paralelismo por fatias referência 116 GB/s agregações, conjuntos de resultados pequenos
fastsimdjson índice estrutural + threads referência 138-277 GB/s extração de campos de NDJSON, 3.14t

Uma ordem de adoção sensata: primeiro troque para msgspec ou orjson (poucos minutos de trabalho por um 3-5× de graça); se não bastar, converta os campos do caminho quente em Struct; adicione um pool de processos para tarefas de contagem; considere fastsimdjson apenas quando extrair campos linha a linha de NDJSON e seu ambiente permitir. Se o gargalo é memória e não velocidade — o arquivo é grande demais para ler inteiro — a direção muda: passe para o streaming com ijson, ou para o jq --stream na linha de comando; veja Processar JSON grande em streaming com jq e Parsing, renderização e streaming de JSON grande. Para as regras de NDJSON linha a linha, veja O manual prático de arquivos JSONL.

Disciplina de medição e três armadilhas

Primeiro, fixe sua metodologia de cronometragem: neste artigo cada implementação roda três vezes e vale o melhor resultado (para filtrar a oscilação do agendador), e o arquivo está totalmente gerado antes do início da medição. Ao citar números de terceiros, indique a especificação da máquina — nunca compare 138 GB/s em 192 núcleos com um núcleo do seu notebook.

Segundo, valide a corretude em cruzamento: as quatro implementações contaram 60.108 estrelas. Qualquer "aceleração" que mude a contagem alterou a semântica do parsing (tratamento de chaves duplicadas, precisão de inteiros grandes), não ficou mais rápida. Alinhe primeiro os resultados, depois as velocidades.

Terceiro, três armadilhas comuns: orjson.dumps() retorna bytes, e misturá-lo com str produz silenciosamente dados sujos com o prefixo b'...'; as fatias do pool de processos devem estar alinhadas às fronteiras de linha — após f.seek(offset), descarte primeiro a linha parcial; inteiros grandes acima de 2^53 são seguros em qualquer parser Python, mas se o resultado vai para o lado JavaScript, o problema de precisão o espera lá.

FAQ

Devo escolher orjson ou msgspec?

Se você só quer um loads mais rápido, ambos entregam 3× ou mais — escolha pela atividade de manutenção e pela familiaridade da equipe. Escolha o msgspec quando precisar de decodificação parcial (msgspec.Struct + Raw), validação de tipos ou saída TypedDict/dataclass; sua decodificação declarativa adiciona um ganho independente em arrays grandes.

Multiprocesso é sempre mais rápido que um núcleo?

Não. Divisão, inicialização de processos e mesclagem têm custos fixos, e com um arquivo de algumas dezenas de MB geralmente dá prejuízo. Tarefas que devolvem resultados grandes (você precisa de cada registro) perdem o ganho na transferência. Como regra prática: troque a biblioteca primeiro em um núcleo, e paralelize só na escala de GB em tarefas de pura contagem.

Por que meu benchmark do orjson não mostra 3×?

Três razões comuns: a amostra é pequena demais (o tempo de parsing se afoga na leitura do arquivo e no custo do loop); o gargalo real é rede ou disco, não o parsing; ou os dados são quase todos strings longas, então a construção de objetos tem peso pequeno. Use uma amostra maior, envolva apenas o loop de parsing em time.perf_counter e só então conclua.

Qual é a relação do ijson com essas bibliotecas?

O ijson é um iterador em streaming: ele sacrifica throughput por memória constante e serve para arquivos muito maiores que a RAM; orjson/msgspec buscam throughput mas transformam cada registro em objetos. Os dois não conflitam: NDJSON na escala de GB se resolve lendo linha a linha com decodificação rápida do msgspec; ijson ou jq --stream só é necessário para um único documento JSON enorme.