Timber

将经典机器学习模型编译为原生 C 语言代码，实现实时推理。

文档 · 变更日志 · PyPI · 技术论文 · 代理技能

---

Timber 接受经过训练的机器学习模型——XGBoost、LightGBM、scikit-learn、CatBoost、ONNX（树集成、线性模型、SVM）或 URDF 机器人描述——通过多遍优化编译器处理后，生成一个自包含的 C99 推理工件，且无运行时依赖。内置的 HTTP 服务器（兼容 Ollama API）允许您只需一条命令即可部署任何模型——无论是本地文件还是远程 URL。

单样本推理约 2 微秒 · 比 Python XGBoost 快约 336 倍 · 工件大小约 48 KB · 无运行时依赖

---

实际演示

只需指向任意 URL，Timber 就会自动下载、编译并部署，无需任何配置。

$ pip install timber-compiler
$ timber serve https://raw.githubusercontent.com/kossisoroyce/timber/main/examples/breast_cancer_model.json

  ✓ 下载              breast_cancer_model.json
  ✓ 检测到格式         xgboost
  ✓ 解析模型            50 棵树 · 30 个特征 · 二分类: logistic
  ✓ 优化               应用了 3/5 轮优化
  ✓ 生成 C99           169 行
  ✓ 编译二进制文件     47.9 KB

  正在服务    breast_cancer_model
  端点       http://localhost:11434
  框架       xgboost  ·  50 棵树  ·  30 个特征

  POST  http://localhost:11434/api/predict
  GET   http://localhost:11434/api/models
  GET   http://localhost:11434/api/health

立即预测：

$ curl -s http://localhost:11434/api/predict \
    -H 'Content-Type: application/json' \
    -d '{"model": "breast_cancer_model", "inputs": [[1.799e+01, 1.038e+01, 1.228e+02, 1.001e+03, 0.1184, 0.2776, 0.3001, 0.1471, 0.2419, 0.07871, 1.095, 0.9053, 8.589, 153.4, 0.006399, 0.04904, 0.05373, 0.01587, 0.03003, 0.006193, 2.538e+01, 1.733e+01, 1.846e+02, 2.019e+03, 0.1622, 0.6656, 0.7119, 0.2654, 0.4601, 0.1189]]}'

{"model": "breast_cancer_model", "outputs": [[0.9971]], "n_samples": 1}

或者从本地文件加载并按名称部署：

$ timber load fraud_model.json --name fraud-detector
$ timber serve fraud-detector

---

目录

• 适用人群
• 工作原理
• 快速入门
• 支持的格式
• 性能
• 运行时对比
• API 参考
• CLI 参考
• 示例
• 限制
• 路线图
• 开发
• 引用
• 社区与治理
• 许可证

---

适用人群

Timber 专为需要快速、可预测且可移植推理的团队打造：

• 欺诈与风险团队 — 在亚毫秒级交易路径中运行经典模型，无需 Python 开销
• 边缘与 IoT 部署 — 将约 48 KB 的 C 工件部署到网关、微控制器或 ARM Cortex-M 设备上
• 受监管行业 — 金融、医疗和汽车行业的团队，需要确定性、可审计的推理工件
• 平台与基础设施团队 — 完全消除关键路径中的 Python 模型推理栈

---

工作原理

  ┌─────────────────────────────────────────────────────────┐
  │                     timber load                         │
  │                                                         │
  │  模型文件  ──►  解析器  ──►  Timber IR  ──►  优化器│
  │  (.json/.pkl/                  (类型化 AST)   (去除死叶  │
  │   .txt/.onnx)                               量化、分支排序) │
  │                                              branch-sort) │
  │                                     │                    │
  │                                     ▼                    │
  │                               C99 生成器                │
  │                                     │                    │
  │                    ┌────────────────┼────────────────┐   │
  │                    ▼                ▼                ▼   │
  │               model.c         model.h        model_data.c│
  │               (推理)     (公共 API)   (树结构数据)  │
  │                    │                                     │
  │                    └──► gcc / clang ──► model.so         │
  └─────────────────────────────────────────────────────────┘
                              │
                              ▼
                      timber serve <name>
                   http://localhost:11434/api/predict

编译器流程：

1. 解析 — 将原生模型格式读取为框架无关的 Timber IR
2. 优化 — 去除死叶节点、阈值量化、常量特征折叠、分支排序
3. 生成 — 生成确定性、可移植的 C99 代码，无动态内存分配且无递归调用
4. 编译 — 使用 gcc/clang 生成可通过 ctypes 加载的共享库
5. 部署 — 兼容 Ollama 的 HTTP API 包装二进制文件，便于直接集成

---

快速入门

pip install timber-compiler

直接从 URL 提供任何模型——无需预先下载步骤：

timber serve https://yourhost.com/models/fraud_model.json

或者加载本地模型并按名称提供服务：

timber load fraud_model.json --name fraud-detector
timber serve fraud-detector

预测：

curl -s http://localhost:11434/api/predict \
  -H "Content-Type: application/json" \
  -d '{"model": "fraud-detector", "inputs": [[1.2, 0.4, 3.1, 0.9]]}'

{"model": "fraud-detector", "outputs": [[0.031]], "latency_us": 1.8}

就是这样。 无需配置模型服务器，也无需在关键路径中使用 Python 运行时。

或者从 URDF 文件提供机器人的正运动学：

timber serve robot.urdf

curl -s http://localhost:11434/api/predict \
  -H "Content-Type: application/json" \
  -d '{"model": "robot", "inputs": [[0.1, 0.2, 0.3, -0.4, 0.5, -0.6, 0.7]]}'

{"model": "robot", "outputs": [[0.082, -0.982, 0.170, 0.310, 0.959, 0.031, -0.283, 0.053, 0.272, 0.187, 0.944, 1.180, 0.0, 0.0, 0.0, 1.0]], "latency_us": 65.0}

---

支持的格式

框架	文件格式	备注
XGBoost	.json	所有目标；多分类、二分类、回归；XGBoost 3.1+ 的每类 base_score
LightGBM	.txt, .model, .lgb	所有目标，包括多分类
scikit-learn	.pkl, .pickle	GradientBoostingClassifier/Regressor、RandomForest、ExtraTrees、DecisionTree、Pipeline
ONNX	.onnx	TreeEnsembleClassifier/Regressor、LinearClassifier/Regressor、SVMClassifier/Regressor、Normalizer、Scaler
CatBoost	.json	JSON 导出（save_model(..., format='json')）
URDF	.urdf	机器人描述 → 正运动学；输出 4×4 齐次变换；输入为关节角度

---

性能

基准测试在 Apple M2 Pro · 16 GB 内存 · macOS 上运行，使用 XGBoost 二分类器，50 棵树，最大深度 4，30 个特征（sklearn breast_cancer 数据集），先预热 1,000 次迭代，再进行 10,000 次计时迭代。

运行时	单样本延迟	吞吐量	相比 Python 的加速倍数
Timber（原生 C）	~2 µs	~500,000 / 秒	336×
ONNX Runtime	~80–150 µs	~10,000 / 秒	~5×
Treelite（编译后）	~10–30 µs	~50,000 / 秒	~20×
Python XGBoost	~670 µs	~1,500 / 秒	1×（基准）
Python scikit-learn	~900 µs	~1,100 / 秒	0.7×

延迟是 进程内 的（不是 HTTP 往返）。网络开销会根据你的堆栈增加约 50–200 µs。

重现这些数据

python benchmarks/run_benchmarks.py --output benchmarks/results.json
python benchmarks/render_table.py   --input  benchmarks/results.json

完整的方法论、硬件采集脚本以及可选的 ONNX Runtime / Treelite / lleaves 对比，请参阅 benchmarks/。

---

运行时比较

	Timber	Python 服务	ONNX Runtime	Treelite	lleaves
延迟	~2 µs	数百 µs–ms	~100 µs	~10–30 µs	~50 µs
运行时依赖	无	Python + 框架	ONNX Runtime 库	Treelite 运行时	Python + LightGBM
工件大小	~48 KB	50–200+ MB 进程	MB 级别	MB 规模	Python 环境
格式	5 种（树模型 + 线性模型 + SVM）	各框架专用	仅 ONNX	GBDT	仅 LightGBM
C 导出	是（C99）	否	否	是	否
LLVM IR 导出	是	否	否	否	否
边缘/嵌入式	是（Cortex-M4/M33、RISC-V）	否	部分支持	部分支持	否
MISRA-C 输出	是	否	否	否	否
差分隐私	是	否	否	否	否

---

API 参考

Timber 的服务器默认在 http://localhost:11434 上暴露一个 与 Ollama 兼容的 REST API。

端点	方法	请求体 / 参数	描述
/api/predict	POST	{"model": str, "inputs": [[float]]}	运行推理
/api/generate	POST	与 /api/predict 相同	Ollama 别名
/api/models	GET	—	列出所有已加载模型
/api/model/:name	GET	—	模型元数据及架构
/api/health	GET	—	健康检查

示例——批量推理：

curl -s http://localhost:11434/api/predict \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fraud-detector",
    "inputs": [
      [1.2, 0.4, 3.1, 0.9],
      [0.1, 2.3, 1.0, 4.4]
    ]
  }'

---

CLI 参考

timber load   <path> --name <name>   编译并注册模型
timber serve  <name> [--port N]      启动推理服务器
timber list                          列出已注册模型
timber inspect <name>                显示模型 IR 摘要和架构
timber validate <name>               对源模型进行数值验证
timber bench  <name>                 基准测试延迟和吞吐量
timber pull   <url>  --name <name>   从 URL 下载并编译
timber remove <name>                 从注册表中移除模型

---

示例

可运行的端到端示例位于 examples/：

python examples/quickstart_xgboost.py   # 训练、编译并进行基准测试
python examples/quickstart_lightgbm.py
python examples/quickstart_sklearn.py

每个脚本都会训练一个模型，将其保存，然后运行 timber load，最后将预测结果与原始框架进行验证。

---

局限性

• ONNX — 支持 TreeEnsemble、LinearClassifier/Regressor、SVMClassifier/Regressor、Normalizer、Scaler；其他算子（如神经网络层）暂不支持。
• CatBoost — 需要 JSON 导出（save_model(..., format='json')）；不支持原生二进制格式。
• scikit-learn — 主要估计器和 Pipeline 包装器受支持；不常见的自定义估计器可能需要自定义前端。
• Pickle — 请遵循标准的 pickle 安全规范；仅从可信来源加载工件。
• XGBoost — 主要支持 JSON 模型格式；不支持二进制 booster 格式。
• LLVM IR — 目前以文本形式（.ll）输出；需要本地安装 LLVM/Clang 才能从中生成原生代码。
• MISRA-C — 内置合规性检查器覆盖了与生成代码最相关的规则；它不能替代经过认证的静态分析工具。

---

路线图

状态	项目
✅	XGBoost、LightGBM、scikit-learn、CatBoost、ONNX 前端
✅	多遍 IR 优化器（死节点消除、量化、分支排序、缩放器融合）
✅	支持 WebAssembly 目标的 C99 代码生成器
✅	兼容 Ollama 的多工作线程 FastAPI HTTP 推理服务器
✅	使用 OIDC 可信发布机制的 PyPI 打包
✅	ONNX Linear/SVM/Normalizer/Scaler 运算符支持
✅	ARM Cortex-M4/M33 和 RISC-V rv32imf/rv64gc 嵌入式部署配置文件
✅	符合 MISRA-C:2012 标准的输出模式，并内置合规性检查工具
✅	具有可配置目标三元组的 LLVM IR 后端
✅	差分隐私（拉普拉斯 + 高斯）推理模式
✅	更丰富的 bench 报告：P50/P95/P99/P999、CV%、JSON + HTML 输出
🔄	远程模型注册表（从托管模型库中使用 timber pull 下载模型）
🔲	神经网络运算符支持（MLPClassifier）
🔲	ONNX 导出路径（Timber IR → ONNX）
🔲	Rust 后端代码生成器

---

开发

git clone https://github.com/kossisoroyce/timber.git
cd timber
pip install -e ".[dev]"
pytest tests/ -v                    # 436 个测试用例
ruff check timber/                  # 代码风格检查

测试套件涵盖：解析器（sklearn、ONNX、XGBoost、LightGBM、CatBoost）、IR 层（序列化、深拷贝、所有阶段类型）、优化器 pass（正确性、幂等性、流水线融合数学）、C99/WASM/MISRA-C/LLVM IR 代码生成器（编译与数值精度）、差分隐私（统计正确性、所有数据类型）以及完整的端到端流水线。

完整开发指南请参阅 CONTRIBUTING.md。

---

引用

如果您在研究或生产中使用 Timber，请引用随附的技术论文：

@misc{royce2026timber,
  title        = {Timber: 将经典机器学习模型编译为原生推理二进制文件},
  author       = {Kossiso Royce},
  year         = {2026},
  howpublished = {GitHub 仓库和技术论文},
  institution  = {Electricsheep Africa},
  url          = {https://github.com/kossisoroyce/timber}
}

完整论文可在 paper/timber_paper.pdf 获取。

---

社区与治理

• 贡献指南： CONTRIBUTING.md
• 行为准则： CODE_OF_CONDUCT.md
• 安全策略： SECURITY.md
• 变更日志： CHANGELOG.md

如遇问题或有功能需求，请 提交 issue。如有疑问，欢迎 发起讨论。

---

支持本项目

Timber 由 Electricsheep Africa 开发并维护。如果 Timber 能为您的团队节省工程时间，请考虑支持其持续开发：

我们也在构建一个托管的编译模型库——如果您有高性能模型希望贡献，欢迎 联系我们。

---

许可证

Apache-2.0 — 完整许可文本请参阅 LICENSE。

Timber 快速上手指南

Timber 是一个高性能编译器，能够将经典的机器学习模型（如 XGBoost、LightGBM、scikit-learn、CatBoost、ONNX）或 URDF 机器人描述文件编译为原生 C99 代码。它生成的推理工件无运行时依赖，单样本推理延迟低至 ~2 微秒，比 Python 实现快约 336 倍。

环境准备

• 操作系统: Linux, macOS, Windows (需配备 GCC 或 Clang 编译器)
• Python 版本: Python 3.8+
• 前置依赖:
  • pip (Python 包管理工具)
  • gcc 或 clang (用于编译生成的 C 代码，通常系统自带或在开发工具包中)
• 网络要求: 首次运行需联网下载模型或访问 PyPI。国内用户若遇网络问题，可配置 pip 国内镜像源。

安装步骤

使用 pip 安装 Timber 编译器：

pip install timber-compiler

提示: 如果下载速度较慢，推荐使用国内镜像源加速安装：

pip install timber-compiler -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

Timber 的核心优势在于“一键服务”：无需手动编译配置，直接指向模型文件即可启动高性能推理服务。

1. 直接通过 URL 启动服务

这是最简单的使用方式。Timber 会自动下载模型、检测格式、编译优化并启动 HTTP 服务器。

timber serve https://raw.githubusercontent.com/kossisoroyce/timber/main/examples/breast_cancer_model.json

启动成功后，终端会显示类似以下信息，表明服务正在 http://localhost:11434 运行：

✓ Downloaded              breast_cancer_model.json
✓ Format detected         xgboost
✓ Compiled binary         47.9 KB
Serving    breast_cancer_model
Endpoint   http://localhost:11434

2. 发送预测请求

使用 curl 或其他 HTTP 客户端向 API 发送 JSON 数据进行推理。Timber 兼容 Ollama API 格式。

curl -s http://localhost:11434/api/predict \
    -H 'Content-Type: application/json' \
    -d '{"model": "breast_cancer_model", "inputs": [[1.799e+01, 1.038e+01, 1.228e+02, 1.001e+03, 0.1184, 0.2776, 0.3001, 0.1471, 0.2419, 0.07871, 1.095, 0.9053, 8.589, 153.4, 0.006399, 0.04904, 0.05373, 0.01587, 0.03003, 0.006193, 2.538e+01, 1.733e+01, 1.846e+02, 2.019e+03, 0.1622, 0.6656, 0.7119, 0.2654, 0.4601, 0.1189]]}'

返回示例:

{"model": "breast_cancer_model", "outputs": [[0.9971]], "n_samples": 1}

3. 加载本地模型文件

如果你已有本地的模型文件（如 .json, .pkl, .onnx 等），可以先注册再启动：

# 加载本地模型并命名为 fraud-detector
timber load fraud_model.json --name fraud-detector

# 通过名称启动服务
timber serve fraud-detector

4. 常用 CLI 命令参考

命令	说明
timber serve <url_or_name>	启动推理服务器
timber load <path> --name <name>	编译并注册本地模型
timber list	列出已注册的模型
timber inspect <name>	查看模型结构和元数据
timber bench <name>	对模型进行延迟和吞吐量基准测试