LLM令牌优化转换器

TONL-MCP Bridge是一款TypeScript库和CLI工具,用于将JSON/YAML数据转换为TONL格式,减少大型语言模型(LLM)的令牌使用,从而降低成本和提高性能。适用于日志处理、向量数据库、RAG系统等场景。

  • by giordano137
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 kryptomrx/tonl-mcp-bridge

使用说明

TONL-MCP电桥

使用TONL格式将LLM令牌成本降低40-60%(针对高容量日志和重复数据结构进行了优化)

概述

TONL-MCP Bridge是一个生产级TypeScript库和CLI工具,可将JSON/YAML数据转换为TONL(令牌优化自然语言)格式。通过消除JSON的结构开销,TONL减少了大型语言模型上下文窗口的令牌使用,从而直接降低了成本并提高了性能。

主要用例

  • RAG系统:优化检索增强生成管道
  • 矢量数据库:减少Milvus、Qdrant和ChromaDB查询的令牌开销
  • MCP服务器:构建高效的模型上下文协议集成
  • 实时流媒体:具有恒定内存的进程日志和事件流
  • 企业合规性:GDPR/HIPAA就绪数据匿名化

当TONL表现出色时

✅ 表格/结构化数据 (日志、事件、分析)
✅ 重复的字段结构 (API响应、数据库查询)
✅ 大型数据集 (100+条记录,模式一致)
✅ 高场密度 (每条记录>10个字段)

何时使用JSON

❌ 单对象转换 (标题开销>节省)
❌ 高度异构的数据 (许多可选字段导致稀疏表)
❌ 深巢树木 (具有复杂层次结构的配置文件)
❌ 小型有效载荷 (<1KB,开销占主导地位)

阅读完整文档

问题

LLM按令牌收费。JSON的冗长直接影响成本:

[
  {
    "id": 1,
    "name": "Alice Johnson",
    "age": 25,
    "email": "alice@example.com",
    "active": true
  },
  {
    "id": 2,
    "name": "Bob Smith",
    "age": 30,
    "email": "bob@example.com",
    "active": false
  }
]

成本:118个代币

解决方案

TONL格式在消除冗余的同时保持了结构:

data[2]{id:i32,name:str,age:i32,email:str,active:bool}:
  1, "Alice Johnson", 25, alice@example.com, true
  2, "Bob Smith", 30, bob@example.com, false

成本:75个代币(减少36.4%)

节省与数据量成正比——对于具有100多条记录和一致模式的数据集,节省率可达50-60%。

代币节省(通过基准验证)

TONL的架构是为了 结构还原节省与字段名(结构)与值(内容)的比率直接相关。

用例 典型节省 最适合。..
企业日志 40-50% Kubernetes、CloudWatch、审计日志(详细密钥)
表格数据 15-25% SQL导出、用户列表、CSV样式数据
文件/RAG 5-10% 非结构化文本、文章(内容占主导地位)

基准测试结果(v1.1.0)

已在Apple M4/Node v25.2.1上验证,使用 cl100k_base 标记器(GPT-4o)。

数据集类型 记录 JSON令牌 TONL令牌 缩减 无损?
企业日志(详细) 1,000 172,603 92,054 46.7% ✅ 是的
用户(简单) 1,000 28,848 22,754 21.1% ✅ 是的
RAG(混合) 200 43,997 41,343 6.0% ✅ 是的

专业提示: 为了最大限度地节省成本,对具有重复、冗长键的数据使用TONL(例如。, http_request_duration_ms, kubernetes_pod_name_identifier).对于原始文本繁重的负载,标准JSON或Markdown就足够了。

为什么会有变化?

  • 企业日志 在数千条记录中重复15个以上的详细字段名
  • 表格数据 具有适中的字段名(5-10个字段)和简单的值
  • RAG文件 内容繁重,结构<总令牌的10%

现实世界影响

示例:中型测井基础设施

基于GPT-4o的定价(截至2025年12月,每100万输入代币2.50美元)

脚本: 云可观察性平台处理Kubernetes日志

  • 100000个日志事件/天
  • 每个事件15个字段(详细键如 distributed_trace_correlation_id)
  • JSON有效载荷:每个事件约170个令牌

之前(JSON):

  • 每日代币:1700万代币(10万×170)
  • 每日费用:42.50美元(2.50美元×17美元)
  • 每月费用:约1275美元

之后(吨减少47%):

  • 每日代币:900万代币(10万×90)
  • 每日费用:22.50美元(2.50美元×9)
  • 每月费用:约675美元
  • 每月节省:600美元

在1M事件/天的规模下: 每月节省6000美元

运行自己的基准测试: npm run benchmark (参见 基准测试/README.md)

主要特点

核心功能

双向转换

  • JSON转换为TONL并返回(无损)
  • YAML到TONL并返回
  • 自动模式检测
  • 智能报价(仅在必要时)

类型系统

  • 优化的数字类型(i8、i16、i32、f32)
  • 原生支持字符串、布尔值、null
  • 通过点符号处理嵌套对象
  • 数组类型保存

生产特性(v1.0.0)

流媒体管道

  • 使用恒定内存处理千兆字节级文件
  • 250000行/秒吞吐量(在M1 MacBook Pro上测量,100字节行)
  • 用于NDJSON到TONL转换的HTTP端点
  • 背压处理和错误恢复

隐私与合规

  • 智能屏蔽(电子邮件、SSN、信用卡、电话)
  • 嵌套字段匿名化
  • GDPR/HIPAA合规支持
  • 可配置的编辑策略

可观测性

  • 普罗米修斯指标(业务和运营)
  • 实时监控仪表板(tonl top 命令)
  • Kubernetes的健康检查端点
  • Grafana仪表板模板

安全

  • 速率限制(可按IP配置)
  • 头盔安全头
  • 承载令牌身份验证(或自动生成的会话令牌)
  • 优雅的关机,连接排水

矢量数据库集成

本机适配器适用于:

  • 米尔维斯:搜索结果的自动TONL转换
  • Qdrant:优化查询格式
  • ChromaDB:集合发现和相似性搜索

每个适配器都包含内置的令牌统计信息和节省计算。

限制和边缘案例

稀疏数据/联合模式

当记录具有不同的字段时,TONL使用联合模式:

// Heterogeneous data
const data = [
  { type: "user", name: "Alice", age: 30 },
  { type: "product", name: "Widget", price: 9.99 }
];

// TONL handles via union schema
// @items|type:s,name:s,age:n?,price:n?
// user|Alice|30|null
// product|Widget|null|9.99
  • 标记为的可选字段 ? 后缀
  • 缺失值表示为 null
  • 代币节省减少,但仍然存在(通常为20-30%)

性能注意事项

  • 模式推理开销: 第一批约1-2ms
  • 类型检测成本: 混合类型字段增加
  • 标题大小: 与字段数成比例(10个字段≈50个令牌)
  • 内存: 无论文件大小如何,都会持续使用

有关完整的技术细节,请参阅 限制.md

安装

CLI工具(全局)

npm install -g tonl-mcp-bridge

图书馆(本地项目)

npm install tonl-mcp-bridge

MCP服务器

stdio模式(适用于克劳德桌面):

npm install -g tonl-mcp-bridge

# Configure in claude_desktop_config.json:
# {
#   "mcpServers": {
#     "tonl": {
#       "command": "npx",
#       "args": ["-y", "tonl-mcp-stdio"]
#     }
#   }
# }

HTTP/SSE模式(用于远程/Docker):

# With permanent token (production)
export TONL_AUTH_TOKEN=your-secure-token
npx tonl-mcp-server

# Without token (development)
# Server auto-generates session tokens (valid for 1 hour)
npx tonl-mcp-server

码头工人

docker run -d \
  -p 3000:3000 \
  -e TONL_AUTH_TOKEN=your-token \
  ghcr.io/kryptomrx/tonl-mcp-bridge:latest

# Verify health
curl http://localhost:3000/health

快速开始

CLI使用情况

# Basic conversion
tonl convert data.json

# With token statistics
tonl convert data.json -s

# Show all commands
tonl help

# Monitor server metrics
tonl top --url https://your-server.com

# Convert with anonymization
tonl convert users.json --anonymize email,ssn

程序化使用

import { jsonToTonl, tonlToJson } from 'tonl-mcp-bridge';

// Convert to TONL
const data = [
  { id: 1, name: "Alice", age: 25 },
  { id: 2, name: "Bob", age: 30 }
];

const tonl = jsonToTonl(data, "users");
// users[2]{id:i32,name:str,age:i32}:
//   1, Alice, 25
//   2, Bob, 30

// Convert back to JSON
const json = tonlToJson(tonl);

流媒体

import { pipeline } from 'stream/promises';
import { NdjsonParse, TonlTransform } from 'tonl-mcp-bridge/streams';
import { createReadStream, createWriteStream } from 'fs';

await pipeline(
  createReadStream('logs.ndjson'),
  new NdjsonParse(),
  new TonlTransform({ collectionName: 'logs' }),
  createWriteStream('logs.tonl')
);

隐私和匿名

import { jsonToTonl } from 'tonl-mcp-bridge';

const users = [
  { 
    id: 1, 
    name: 'Alice', 
    email: 'alice@company.com',
    ssn: '123-45-6789' 
  }
];

// Smart masking (preserves format context)
const masked = jsonToTonl(users, 'users', {
  anonymize: ['email', 'ssn'],
  mask: true
});
// Output: a***@company.com, ***-**-6789

// Simple redaction
const redacted = jsonToTonl(users, 'users', {
  anonymize: ['email', 'ssn']
});
// Output: [REDACTED], [REDACTED]

建筑

组件

核心库

  • 类型检测和优化
  • 模式推理
  • 双向转换引擎
  • 使用js-tiktoken进行令牌计数

流媒体管道

  • 具有错误恢复功能的NDJSON解析器
  • 转换流以进行转换
  • 用于远程处理的HTTP端点

隐私模块

  • 基于模式的场检测
  • 可配置的屏蔽策略
  • 深度克隆(无副作用)
  • 嵌套对象支持

可观测性

  • Prometheus指标集合
  • 实时仪表盘
  • 健康终点
  • 平滑关闭

技术栈

  • 运行时:Node.js 18+
  • 语言:TypeScript 5.3
  • 测试:Vitest(385项测试通过)
  • HTTP框架:快递5
  • 安全:头盔,快递费率限制
  • 指标:舞会客户
  • 分词器:js tiktoken(gpt-4或toknizer)
  • 协议:MCP、SSE、HTTP

生产部署

码头工人

# docker-compose.yml
version: '3.8'
services:
  tonl-server:
    image: ghcr.io/kryptomrx/tonl-mcp-bridge:latest
    ports:
      - "3000:3000"
    environment:
      - TONL_AUTH_TOKEN=${TONL_AUTH_TOKEN}
      - NODE_ENV=production
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tonl-mcp-bridge
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: tonl-server
        image: ghcr.io/kryptomrx/tonl-mcp-bridge:latest
        ports:
        - containerPort: 3000
        env:
        - name: TONL_AUTH_TOKEN
          valueFrom:
            secretKeyRef:
              name: tonl-secrets
              key: auth-token
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /ready
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 10

文档

综合文件可在 tonl-mcp-bridge-docs.vercel.app

指南

api参考

发展

# Clone repository
git clone https://github.com/kryptomrx/tonl-mcp-bridge.git
cd tonl-mcp-bridge

# Install dependencies
npm install

# Run tests (385 passing)
npm test

# Build
npm run build

# Run local server
npm run mcp:start

路线图

已完成(v1.0.0)

  • 具有类型优化的核心转换引擎
  • MCP服务器与自动生成的会话令牌集成
  • 矢量数据库适配器(Milvus、Qdrant、ChromaDB)
  • 流媒体管道(250k线/秒)
  • 智能屏蔽的隐私和匿名化
  • 生产可观察性(普罗米修斯、健康检查)
  • 安全(限速、安全帽、优雅关机)
  • 全面的CLI tonl help 命令

计划中(发布v1.0.0)

  • LangChain集成
  • LlamaIdex插件
  • VS代码扩展
  • 无服务器部署模板(AWS Lambda、Cloudflare Workers)
  • 附加矢量数据库适配器(Pinecone、Weaviate)

查看详细路线图

贡献

欢迎捐款。请通过GitHub提交问题和拉取请求。

  1. 分叉存储库
  2. 创建要素分支
  3. 提交您的更改
  4. 推到分支
  5. 打开拉取请求

许可证

MIT许可证-请参阅 许可证 详情

链接

  • npm: https://www.npmjs.com/package/tonl-mcp-bridge
  • GitHub: https://github.com/kryptomrx/tonl-mcp-bridge
  • 文档: https://tonl-mcp-bridge-docs.vercel.app/
  • 命令: https://github.com/kryptomrx/tonl-mcp-bridge/blob/main/COMMANDS.md
  • 问题: https://github.com/kryptomrx/tonl-mcp-bridge/issues

定价信息已于2025年12月11日验证。基于GPT-4o令牌化器(js tiktoken)的令牌计算。基准数据来自 基准测试/README.md.

由厌倦了为JSON的冗长付费的开发人员构建。如果这为您的组织节省了资金,请考虑在GitHub上展示该项目。