文章标题:Jsonbit – 减少 AI 读取日志时的 token 用量
正文:
jsonbit
JsonBit 会在嵌套 JSON 到达你的 LLM 之前对其进行压缩。在一次提示中发送紧凑的摘要,或者让你的 agent 通过 SQL/MCP 在本地查询原始数据,只读取它需要的结果。
pip install jsonbit
jsonbit digest path/to/your-file.json
将输出传给 LLM,替代原始 JSON。(Rust cargo、Node.js npm/npx 以及独立二进制文件列在"安装与设置"下。)
jsonbit digest 的示例输出:
# orders[4](orderId,customer_name,customer_tier,status,total)
@stats: total[sum=619.00,avg=154.75,min=95.50,max=201.00]
ORD-101,Alice,pro,shipped,171.75
ORD-102,Bob,starter,pending,201
ORD-103,Cara,pro,shipped,95.5
ORD-104,Dan,pro,shipped,150.75
# orders_items[6] -> orders (sku,qty,price)
@stats: qty[sum=15,avg=2.5,min=1(n=1),max=4] price[sum=246.25,avg=41.04,min=10.50,max=74.50]
0:USB-C,2,10.5|MOUSE,3,50.25
1:MOUSE,4,50.25
2:HUB-4,1,74.5|USB-C,2,10.5
3:MOUSE,3,50.25
| 工作流 | 命令 / MCP 工具 | 最适合 | 保真度与保证 |
|---|---|---|---|
| 单轮压缩 | jsonbit digest / olap_digest | 单次提示的 LLM 调用以及模型需要每一行的整体摘要。 | 包含所有行、转义分隔符、提升的子表以及预计算统计信息的紧凑 LLM 文本视图(四舍五入的平均值是近似值)。 |
| Agent 本地查询 | jsonbit card + sql / olap_load + olap_sql | 编码 agent(OpenCode、Claude Code、Cursor)查询中型/大型 .json 或 .jsonl 文件。 | 输出紧凑的 schema 和统计摘要(与行数无关);在本地以微秒级运行精确的只读 SQL 和 BitVec64 过滤。 |
| 二进制存储 | jsonbit pack / jsonbit rehydrate | 在磁盘上归档或缓存规范化后的 .jsonbit 快照(在 W1 – W10 上相比压缩后的 JSON 减少 80.6%)。 | 在所有 33 个基准/对抗数据集和单元测试中验证了无损往返(保留 null、冲突键以及 u64 > i64::MAX)。 |
目录
- 安装与设置
- Agent 集成(OpenCode、Claude Code、Codex、Cursor)
- CLI 参考
- 架构
安装与设置
使用你喜欢的包管理器安装预构建的原生 jsonbit 二进制文件(Python 或 Node.js 无需 Rust 编译器):
Python(pip / uv)— 包含原生 CLI + Python SDK
pip install jsonbit
Rust(cargo)
cargo install jsonbit
Node.js(npm / npx)— 包含原生 CLI + TypeScript SDK
npm install -g @jsonbit/core
# or run directly without global install:
npx @jsonbit/core --help
预构建二进制文件与从源码构建
适用于 Linux(x64、arm64)、macOS(arm64、x64)和 Windows(x64)的独立二进制文件附加在每个 GitHub Release 上。
要从源码构建(需要 Rust 1.75+):
git clone https://github.com/prathikmurugan/jsonbit.git
cd jsonbit
cargo install --path .
验证安装:
jsonbit --version
Agent 集成
jsonbit 包含一个内置的 stdio JSON-RPC 2.0 MCP 服务器(jsonbit mcp),没有任何外部运行时依赖。它暴露五个工具:olap_load、olap_digest、olap_ask、olap_sql 和 olap_rehydrate。
OpenCode(opencode.json)
将以下内容添加到项目根目录的 opencode.json 中(或全局添加到 ~/.config/opencode/opencode.json):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"jsonbit": {
"type": "local",
"command": ["jsonbit", "mcp"],
"enabled": true
}
}
}
Claude Code(.mcp.json 或 CLI)
通过 Claude Code CLI 注册:
claude mcp add jsonbit -- jsonbit mcp
或包含在 .mcp.json 中:
{
"mcpServers": {
"jsonbit": {
"command": "jsonbit",
"args": ["mcp"]
}
}
}
Cursor 与 Windsurf
将上面的 .mcp.json 配置添加到 .cursor/mcp.json 或 ~/.codeium/windsurf/mcp_config.json。
OpenAI Codex CLI(AGENTS.md)
文章标题:Jsonbit – 减少 AI 读取日志时的 token 用量
正文: Codex 和终端 agent 会自动读取仓库根目录下的 AGENTS.md,以便在检查 .json、.jsonl 或 .jsonbit 文件时通过 CLI 或 MCP 调用 jsonbit。
CLI 参考
| 命令 | 参数 | 说明 |
|---|---|---|
| jsonbit card | <file.json│.jsonl│.jsonbit> | 打印紧凑的 3NF schema 和统计摘要(与行数无关)以及存储压缩统计。 |
| jsonbit digest | <file.json│.jsonl│.jsonbit> | 打印 1-Turn Factorized 3NF Holistic Digest(所有行、提升的子表以及预计算的汇总统计)。 |
| jsonbit ask | <file> "<question>" | 针对位图索引评估问题,并打印已验证的上下文切片。 |
| jsonbit answer | <file> "<question>" | 评估问题并只打印标量答案值。 |
| jsonbit sql | <file> "<SELECT ...>" | 针对 3NF 列式存储执行只读 SQL 查询( WHERE 、 IN 、 BETWEEN 、 LIKE 、 GROUP BY 、 ORDER BY 、 LIMIT 、 OFFSET 、 CSR JOIN )。 |
| jsonbit pack | <input.json> <output.jsonbit> | 将位打包的 3NF 表序列化为二进制 .jsonbit 快照。 |
| jsonbit rehydrate | <file.json│.jsonl│.jsonbit> | 重建并打印原始嵌套 JSON 文档。 |
| jsonbit mcp | (none) | 启动并发的 stdio JSON-RPC 2.0 MCP 服务器( olap_load 、 olap_digest 、 olap_ask 、 olap_sql 、 olap_rehydrate )。 |
Python(pip install jsonbit)
from jsonbit import JsonBit
with JsonBit("benchmarks/data/github-repos.json") as olap:
card = olap.card()
ans = olap.answer("How many repositories have more than 150000 stars and more than 30000 forks?")
rows = olap.sql("SELECT defaultBranch, COUNT(*) AS cnt FROM records GROUP BY defaultBranch ORDER BY cnt DESC")
olap.pack("repos.jsonbit")
TypeScript / Node.js(@jsonbit/core)
import { JsonBit, rehydrateFrom3NF } from '@jsonbit/core'
const engine = JsonBit.from(jsonData)
const card = engine.getDataCard().text
const rows = engine.sql(`SELECT orderId, customer.name, total FROM orders WHERE total > 500`)
const original = rehydrateFrom3NF(engine)
engine.close()
Rust 库(cargo add jsonbit)
use jsonbit::{execute_sql, JsonBitEngine};
let engine = JsonBitEngine::from_json(&serde_json::from_str(raw_json)?);
let card = engine.data_card();
let rows = execute_sql(&engine, "SELECT department, COUNT(*) AS cnt FROM employees GROUP BY department")?;
let restored = engine.rehydrate();
架构
flowchart TD
Input["Nested JSON / JSONL Input"] --> Normalizer["3NF Normalizer & CSR Indexer (rust/normalizer.rs)"]
Normalizer --> ColStore["Bit-Packed Columnar Store (rust/column.rs)"]
ColStore --> Bitmap["BitVec64 Bitmap Engine (rust/bitmap.rs)"]
Bitmap --> Card["OLAP Data Card (rust/engine.rs)"]
Bitmap --> SqlExec["SQL & Predicate Executor (rust/query_exec.rs)"]
ColStore --> Snapshot[".jsonbit Binary Snapshot (rust/snapshot.rs)"]
ColStore --> Rehydrate["Lossless 3NF Rehydrator (rust/normalizer.rs)"]
存储布局(rust/column.rs 与 rust/normalizer.rs)
- ForIntColumn(Frame-of-Reference 整数):计算每列的 [min_val, max_val],并将无符号增量 val - min_val 以每行 ceil(log2(max_val - min_val + 1)) 位打包进 Vec<u64> 缓冲区。列头存储 sum、min、max 和 non_null_count,以便在未过滤时实现 O(1) 聚合。
- DictStringColumn(字典 + 倒排位图):将唯一字符串驻留到字符串 arena 中,将字典 ID 以每行 ceil(log2(|D|)) 位进行位打包,并为每个类别(|D| <= 64)构建按 64 位字对齐的 BitVec64 倒排索引,以实现 O(1) 等值查找和 POPCNT 频率直方图。
- BoolBitmapColumn(1 位布尔值):将 64 个布尔值打包进每个 u64 字中,同时附带 1 位有效性掩码。
- CSR 一对多连接索引:子数组(例如 orders[].items[])被规范化到子表中,并使用连续的 csr_offsets: Vec<u32> 数组将每个父行 i 映射到其子切片 csr_offsets[i]..csr_offsets[i + 1]。
基准测试
所有基准测试均直接针对编译后的 Pure-Rust jsonbit 二进制文件(target/release/jsonbit)执行。
1. 跨 10 个真实工作负载的 Live gemini-3.8-flash 评估(27 个问题)
在 10 个生产工作负载(W1–W10)上评估 Raw JSON、Minified JSON、YAML、TOON(@toon-format/toon)和 jsonbit,包括扁平表、一对多电子商务订单、带自由文本消息的稀疏 .jsonl OpenTelemetry 日志、单例 Kubernetes 配置、IAM 原始类型数组、30 列宽表以及多字节 UTF-8 财务账本。在 27 个问题中,单提示 jsonbit digest 使用的估算 token 比 Minified JSON 少 57.4%(101,302 vs. 237,891),准确率为 26/27 vs. 13/27:
| 格式 / 工具 | 模式 | Live gemini-3.8-flash 准确率 | 估算 Token 数( o200k_base ) | 相对 Minified JSON 的减少 | 相对 Raw JSON 的减少 |
|---|---|---|---|---|---|
| Raw JSON (Pretty) | 单轮全文 | 55.6% (15/27) | 375,713 | +57.9% | — |
| Minified JSON | 单轮全文 | 48.1% (13/27) | 237,891 | — | -36.7% |
| YAML | 单轮全文 | 59.3% (16/27) | 293,690 | +23.5% | -21.8% |
| TOON v4( @toon-format/toon ) | 单轮全文 | 59.3% (16/27) | 169,627 | -28.7% | -54.9% |
| jsonbit Holistic Digest( olap_digest ) | 单轮(所有行 + 汇总统计) | 96.3% (26/27) | 101,302 | -57.4% | -73.0% |
Agentic 本地查询对比(独立工作流——模式摘要 + Rust SQL 执行,而非全行文本编码):
| 工具 | 模式 | Live gemini-3.8-flash 准确率 | 估算 Token 数( o200k_base ) | 相对 Minified JSON 的减少 |
|---|---|---|---|---|
| jsonbit Schema Card + SQL( olap_load + olap_sql ) | Agentic 模式摘要 + 本地 Rust SQL | 100.0% (27/27) | 11,729 | -95.1% |
方法说明:上述 token 计数为 gpt-tokenizer(o200k_base)估算值,用于可复现的跨格式比较;jsonbit SQL 路径总计包含模式摘要提示词加上生成的 SQL 查询 token。
单提示摘要准确率(W3、W4、W5、W10)
对于需要 LLM 在单轮中读取所有记录并撰写多事实执行摘要的定性任务(在 W3、W4、W5 和 W10 中列出所有部门、产品、微服务故障消息和国际交易对手):
| 整体综合任务 | TOON v4 保留事实 | jsonbit digest 保留事实 | TOON Token 数 | jsonbit digest Token 数 | 相对 TOON 的 Token 节省 |
|---|---|---|---|---|---|
| H1 — HR 目录执行摘要 | 8 / 9 | 9 / 9 (100%) | 4,881 | 4,372 | -10.4% |
| H2 — 电子商务目录与订单摘要 | 8 / 8 | 8 / 8 (100%) | 15,405 | 6,933 | -55.0% |
| H3 — 生产事故日志分诊报告 | 9 / 9 | 9 / 9 (100%) | 13,665 | 4,169 | -69.5% |
| H4 — 国际结算账本摘要 | 2 / 6 | 6 / 6 (100%) | 3,781 | 2,403 | -36.4% |
| 所有定性摘要总计 | 27 / 32 (84.4%) | 32 / 32 (100.0%) | 37,732 | 17,877 | -52.6% |
2. Token 扩展曲线(4 $\rightarrow$ 25,000 嵌套订单)
线性文本编码(Raw JSON、Minified JSON、YAML、TOON)的 token 数随行数按 $O(N)$ 扩展,在大规模时会超出 LLM 上下文窗口,而 jsonbit 保持 $O(1)$ 的提示词占用(约 67–473 token):
| 数据集规模(嵌套订单) | Raw JSON(Token) | YAML(Token) | TOON v4(Token) | jsonbit Rust Card(Token) | Rust 摄取时间 |
|---|---|---|---|---|---|
| 4 行(微型 API 负载) | 166 | 122 | 71 | 67 | 0.04 ms |
| 50 行(约 150 个行项目) | 7,780 | 5,801 | 4,783 | 445 | 0.51 ms |
| 500 行(约 1,500 个行项目) | 78,115 | 58,244 | 47,983 | 447 | 3.99 ms |
| 5,000 行(约 15,000 个行项目) | 783,443 | 366,356 | 293,972 | 470 | 55.56 ms |
| 25,000 行(约 75,000 个行项目) | 3,917,366 | 1,831,843 | 1,469,911 | 471 | 315.13 ms |
注:对于 5,000 行和 25,000 行负载(>2 MB),YAML 和 TOON 的 token 计数是根据 500 行精确编码按比例外推的;jsonbit card 的 token 数和 Rust 摄取时间是在完整数据集上直接测量的。
3. 内存占用与查询速度(纯 Rust jsonbit 与 jq CLI 对比)
| 工作负载 | 类别 | 压缩后 JSON 大小 | Rust 列式存储(内存) | 美化 JSON(Token 数) | TOON(100% 行) | jsonbit digest(100% 行) | jsonbit card($O(1)$) | 3NF 无损 |
|---|---|---|---|---|---|---|---|---|
| W1-tiny-api-response | 微小负载(<500B) | 0.3 KB | 0.1 KB | 166 | 71 | 67(-5.6%) | 67 | PASS |
| W2-singleton-k8s-config | 单例配置树 | 0.3 KB | 0.2 KB | 167 | 131 | 110(-16.0%) | 110 | PASS |
| W3-hr-payroll-directory | 表格型(200 行) | 28.4 KB | 4.5 KB | 14,064 | 4,847 | 4,327(-10.7%) | 270 | PASS |
| W4-ecommerce-orders-1toN | 一对多(150 个订单) | 48.3 KB | 4.5 KB | 25,466 | 15,372 | 6,892(-55.2%) | 470 | PASS |
| W5-otel-production-logs | 稀疏 .jsonl + 自由文本 | 44.4 KB | 4.7 KB | 17,439 | 13,632 | 4,132(-69.7%) | 224 | PASS |
| W6-github-repos-metrics | 高基数 + 范围 | 28.6 KB | 3.4 KB | 14,829 | 5,364 | 4,414(-17.7%) | 307 | PASS |
| W7-stripe-dispute-webhooks | 金融 Webhook | 28.9 KB | 3.1 KB | 14,333 | 4,104 | 4,341(+5.8%) | 248 | PASS |
| W8-iam-primitive-arrays | 原始类型数组 | 14.4 KB | 1.6 KB | 7,185 | 4,810 | 1,257(-73.9%) | 162 | PASS |
| W9-wide-enterprise-crm | 宽表(30 列) | 68.6 KB | 5.7 KB | 40,779 | 9,806 | 9,549(-2.6%) | 1,134 | PASS |
| W10-unicode-financial-ledger | UTF-8、空值与零 | 18.4 KB | 2.9 KB | 9,550 | 3,750 | 2,364(-37.0%) | 241 | PASS |
| 合计(10 个工作负载) | 所有类别 | 280.6 KB | 30.6 KB(-89.1%) | 143,978 | 61,887 | 37,453(-39.5%) | 3,233(-94.8%) | 10/10 PASS |
工作负载分解:在微小负载(W1)、单例配置(W2)、带有大量引号的金融 Webhook(W7,+5.8%)以及 30 列宽扁平表(W9,-2.6%)上,单轮 digest 接近 TOON。压缩幅度最大的是嵌套的一对多层级(W4,-55.2%)、稀疏 .jsonl 日志(W5,-69.7%)以及原始类型数组(W8,-73.8%),在这些场景中,3NF hoisting 以及前缀/字典因子化消除了重复结构。
- 存储核算(W1–W10):内存中位打包列式存储:280.6 KB(压缩后 JSON)$\rightarrow$ 30.6 KB(-89.1%)序列化到磁盘的 .jsonbit 快照(jsonbit pack):280.6 KB(压缩后 JSON)/ 427.7 KB(原始文件)$\rightarrow$ 54.3 KB(相较于压缩后 JSON 为 -80.6%,相较于原始文件为 -87.3%)
- 内存中位打包列式存储:280.6 KB(压缩后 JSON)$\rightarrow$ 30.6 KB(-89.1%)
- 序列化到磁盘的 .jsonbit 快照(jsonbit pack):280.6 KB(压缩后 JSON)/ 427.7 KB(原始文件)$\rightarrow$ 54.3 KB(相较于压缩后 JSON 为 -80.6%,相较于原始文件为 -87.3%)
- 查询延迟(热内存 Rust 引擎与冷 jq CLI 子进程对比):jq CLI(stedolan/jq,冷子进程,包含启动与 JSON 解析):每次查询平均 6,545.3 µs jsonbit 纯 Rust SQL(execute_sql,热内存引擎):每次查询平均 6.8 µs jsonbit 纯 Rust 位图切片(query_slice,热内存引擎):每次查询平均 19.9 µs
- jq CLI(stedolan/jq,冷子进程,包含启动与 JSON 解析):每次查询平均 6,545.3 µs
- jsonbit 纯 Rust SQL(execute_sql,热内存引擎):每次查询平均 6.8 µs
- jsonbit 纯 Rust 位图切片(query_slice,热内存引擎):每次查询平均 19.9 µs
- 标准 8 数据集基准测试套件:内存列式存储压缩:1,178,283 字节(压缩后 JSON)$\rightarrow$ 419,661 字节(-64.4%),8/8(100%)无损 3NF 还原。模式卡大小与完整数据集文本对比:334,046 token(TOON v4 完整文本)$\rightarrow$ 2,536 token(-99.24%,仅模式与统计摘要)。239 题评估准确率:99.16%(237/239)严格匹配,平均热查询延迟 8.0 µs。
- 内存列式存储压缩:1,178,283 字节(压缩后 JSON)$\rightarrow$ 419,661 字节(-64.4%),8/8(100%)无损 3NF 还原。
- 模式卡大小与完整数据集文本对比:334,046 token(TOON v4 完整文本)$\rightarrow$ 2,536 token(-99.24%,仅模式与统计摘要)。
文章标题:Jsonbit – 减少 AI 读取日志时的 token 用量
正文:
- 239 题评估准确率:99.16%(237/239)严格匹配,平均热查询延迟 8.0 µs。
4. 自主编码 Agent 正面对比(OpenCode v1.19.5)
在隔离目录中评估,零提示词提示、零 AGENTS.md/CLAUDE.md 文件(opencode/big-pickle),覆盖标准(启用 bash)与沙箱(bash: "deny")两种 agent 环境:
| Agent 模式 | jsonbit MCP(仅 opencode.json) | TOON v4(toon_encode / CLI) | 原始 JSON |
|---|---|---|---|
| 标准 Agent(6 场景,18 次运行) | 6/6(88.1s)· 0 个脚本 | 6/6(142.8s)· awk /Python 解析器 | 6/6(93.7s)· Python 脚本 |
| 沙箱只读(bash: "deny",8 场景) | 8/8(77.7s) | 7/8(333.8s)· 500 阶求和失败 | 7/8(345.4s)· 500 阶求和失败 |
License
MIT License。