Timber是一款把 XGBoost、LightGBM、scikit-learn、CatBoost 等经典机器学习模型编译为原生 C99 推理代码的 AOT 编译器，并提供一套Ollama 兼容的 REST 推理 API。只需两条命令，你的模型就能通过http://localhost:11434/api/predict这样的标准 HTTP 接口对外提供微秒级推理服务。本文将带你快速上手Timber 推理 API，逐个讲解/api/predict、/api/models、/api/health等接口的请求格式、返回字段与常见错误。

为什么用 Ollama 兼容接口？

• 🎯端口一致：默认监听11434端口，与 Ollama 完全相同，客户端代码几乎可以无缝替换；
• 🔄别名兼容：/api/generate是/api/predict的别名，专门兼容 Ollama 客户端库；
• ⚡微秒级延迟：Python 只负责 HTTP 与 JSON 处理，真正的推理由编译后的 C 代码完成，单次推理约 2 µs，整条 HTTP 链路约 91 µs；
• 🌐开箱即用：服务器自带 CORS 头（Access-Control-Allow-Origin: *），浏览器端可直接调用。

服务端实现位于 timber/serve.py，完整的接口文档见 website/docs/api-reference/http-api.md。

快速上手：三步开启 Timber 推理服务

前置条件：Python 3.10+、一台装有gcc/clang的机器，以及一个训练好的树模型文件。

第一步：安装 Timber

pip install timber-compiler

第二步：加载并编译模型

timber load model.json --name my-model

Timber 会自动识别框架（XGBoost / LightGBM 等），经过 6 个优化 pass 后生成 C99 代码并编译成原生动态库，缓存在本地模型仓库中。

第三步：启动服务并验证

timber serve my-model # 默认监听 0.0.0.0:11434 curl http://localhost:11434/api/health # {"status": "ok", "version": "0.1.0"}

启动后终端会打印出所有可用端点清单，并附带一条 curl 示例。服务支持--host与--port参数自定义绑定地址，例如timber serve my-model --port 8080。

Timber 推理 API 端点总览

核心接口：POST /api/predict 详解

请求格式

curl http://localhost:11434/api/predict \ -H "Content-Type: application/json" \ -d '{"model": "my-model", "inputs": [[1.0, 2.0, 3.0, 4.0, 5.0]]}'

💡 小提示：inputs传入一维数组（单个样本）也会被自动处理成[1, n_features]形状。

返回字段

{ "model": "my-model", "outputs": [0.87], "n_samples": 1, "latency_us": 91.0, "done": true }

批量推理

一次请求可携带多个样本，显著降低网络往返开销：

curl http://localhost:11434/api/predict \ -d '{ "model": "my-model", "inputs": [ [1.0, 2.0, 3.0, 4.0, 5.0], [5.0, 4.0, 3.0, 2.0, 1.0], [2.5, 3.5, 1.5, 4.5, 0.5] ] }'

Python 客户端调用示例（完整可运行版见 examples/quickstart_client.py）：

import requests resp = requests.post("http://localhost:11434/api/predict", json={ "model": "my-model", "inputs": [[1.0, 2.0, 3.0, 4.0, 5.0]], }) print(resp.json()["outputs"])

JavaScript、Go、Rust 等多语言调用示例可以参考 website/docs/examples/http-client.md。

GET /api/models：查看已加载模型

curl http://localhost:11434/api/models

{ "models": [ { "name": "fraud-detector", "n_features": 30, "n_outputs": 1, "n_trees": 50, "objective": "binary:logistic", "framework": "xgboost", "version": "0.1.0" } ] }

拿到n_features后，你就能立刻知道/api/predict的inputs每行需要多少个特征值。/api/tags是它的别名；GET /api/model/:name则返回单个模型的上述元数据，模型不存在时返回 404。

常见错误码速查

Ollama 兼容性与架构内幕

/api/generate别名、11434默认端口、"done": true字段，都是为了让现有 Ollama 客户端代码改几个字就能指向 Timber 服务。

架构上，服务做了清晰分工：Python 处理 HTTP 解析、JSON 序列化与 CORS，编译后的 C 代码负责全部推理计算（通过ctypes调用.so动态库）。Python 从不进入推理热路径，这正是 Timber 能比 Python 原生推理快 336 倍的关键。

生产环境部署建议

内置服务器基于 Python 标准库实现，适合开发与中小流量场景。大规模生产环境建议加一层 Nginx 反向代理，配置示例见 website/docs/guides/serving-models.md：

location /api/ { proxy_pass http://127.0.0.1:11434; }

另外两点实用建议：

• 用GET /api/health做负载均衡器探活，响应{"status": "ok"}即服务健康；
• 批量推理时把多个样本合并到一次请求，比逐条调用更快。

总结

现在你可以照着 website/docs/getting-started.md 走一遍完整流程：timber load加载模型 →timber serve启动服务 →curl /api/predict拿到预测结果，全程不到一分钟。更多接口细节可查阅 website/docs/api-reference/http-api.md 与 docs/api-reference.md，模型管理与 CLI 参考见 docs/api-reference.md 中的 CLI 部分。