leaves

简介

特性

通用

LightGBM

XGBoost

scikit-learn（实验性）

训练（v2.x，里程碑 T1–T5）

部署与观测

安装

go install github.com/linkerlin/leaves/v2/cmd/leaves@latest

快速上手

package main

import (
	"fmt"

	"github.com/linkerlin/leaves/v2"
)

func main() {
	m, err := leaves.LoadFromFile("lightgbm_model.txt", leaves.DefaultLoadOptions())
	if err != nil {
		panic(err)
	}

	fvals := []float64{1.0, 2.0, 3.0}
	p := m.PredictSingle(fvals, 0)
	fmt.Printf("对 %v 的预测: %f\n", fvals, p)
}

格式自动识别与支持等级

import "github.com/linkerlin/leaves/v2/io"

m, err := io.LoadFromFile("model.ubj", io.DefaultLoadOptions()) // AutoTransform = true

m, err = io.LoadFromFile("model.ubj", &io.LoadOptions{
	AutoTransform:      false, // 输出原始 margin
	LoadTransformation: true,  // 或者对所有目标强制启用变换
	Backend:            io.BackendAuto,
})

训练 API

dm, _ := leaves.LoadDataAuto("train.tsv") // 内容嗅探

learner, _ := leaves.NewLearner(leaves.TrainConfig{
	Objective: leaves.TrainObjectiveBinaryLogistic,
	NumRound:  50,
})
_ = learner.Fit(dm)
_ = learner.Save("out.leaves.json")

外存 DMatrix

bm, _ := data.SplitDense(dense, batchRows) // 也可以 data.NewBatchedMatrix(...)
learner, _ := train.FitExternal(train.Config{
	Objective:     train.ObjectiveBinaryLogistic,
	TreeMethod:    train.TreeMethodHist,
	HistBinPolicy: "global",
	NumRound:      10,
}, bm)

Checkpoint 续训

learner, _ := train.ResumeFit("ckpt.json", train.Config{
	Objective:  train.ObjectiveSquaredError,
	NumRound:   20, // 在 checkpoint 完成的轮次之上继续
	TreeMethod: train.TreeMethodExact,
}, dm)
score, _ := learner.Eval(dm)

训练数据 —— 自动嗅探

从参考模型反推 objective

learner, _ := leaves.NewLearnerFromModelAndData(
	"reference_model.json", // 只读 objective（XGB JSON / UBJ / leaves.json）
	"train.tsv",            // LoadDataAuto 嗅探
	leaves.TrainConfig{NumRound: 10, TreeMethod: leaves.TrainTreeMethodExact},
	data.DefaultFileLoadOptions(),
)
_ = learner.Save("out.leaves.json")

go run ./examples/train_from_model/ -model testdata/xgboost_smoke.json -data testdata/breast_cancer_train.tsv

survival:aft 区间删失

d, _ := data.NewDense(vals, n, nfeat, placeholderLabels, nil)
dm, _ := data.NewAFTDense(d, []data.AFTInterval{
	{1.5, 1.5},              // 事件
	{2, math.Inf(1)},        // 右删失
	{0, 4},                  // 左删失
	{1, 6},                  // 区间删失
})
learner, _ := train.NewLearner(train.Config{Objective: train.ObjectiveSurvivalAFT, ...})
_ = learner.Fit(dm)

单调约束

learner, _ := train.NewLearner(train.Config{
	Objective:           "reg:squarederror",
	MonotoneConstraints: []int{1, 0, -1}, // 特征 0 递增，特征 2 递减
	TreeMethod:          train.TreeMethodHist,
})

训练加速栈（T4+）

learner, _ := train.NewLearner(train.Config{
	Objective:     train.ObjectiveRankNDCG,
	TreeMethod:    train.TreeMethodGPUHist,
	AccelMode:     train.AccelModeWebGPU, // 也可走环境变量 LEAVES_TRAIN_ACCEL
	NumThreads:    4,
	HistBinPolicy: "global", // 默认；"per_node" 恢复旧的 per-node 切点
	NumRound:      50,
})
_ = learner.Fit(dm)

计算底座 —— Born

m, _ := leaves.LoadFromFile("model.json", &io.LoadOptions{
	Backend:  io.BackendBornCPU, // 或 BackendAuto + LEAVES_BACKEND_PROFILE=1 实测选型
	Workload: tree.WorkloadHint{BatchSize: 256, HasGPU: true},
})
// 可解释选型：tree.SelectBackendExplained(caps, hint) → Rule / Reason

后端选型速查（BackendAuto 2.1）

Tree SHAP 与可解释性

import (
	"github.com/linkerlin/leaves/v2"
	"github.com/linkerlin/leaves/v2/explain"
)

m, _ := leaves.LoadFromFile("model.json", leaves.DefaultLoadOptions())

x := [][]float64{{1.0, 2.0, 3.0}}
contrib, _ := m.Explain().TreeSHAP(x)        // margin 空间 SHAP
inter, _ := m.Explain().InteractionSHAP(x)   // 交互值矩阵
mc, _ := m.Explain().TreeSHAPMulticlass(x)   // 多类：[sample][feature][class]
base := m.Explain().ExpectedValue()          // 背景基线（全零特征）

imp := m.Explain().Importance(explain.ImportanceGain, nil)
text := m.Explain().DumpText(nil)
dot := m.Explain().DumpDOT(nil)

import "github.com/linkerlin/leaves/v2/predict"

nf := m.NFeatures()
nRows := 1

// 输出值（logistic 已变换，squarederror 仍为原始）
vals := make([]float64, nRows*m.NOutputGroups())
_ = m.PredictWithRequest(predict.Request{
	Matrix: predict.DenseMatrix{Values: flat, Rows: nRows, Cols: nf},
	Output: predict.OutputValue,
}, vals)

// 原始 margin（sigmoid / softmax 之前）
margins := make([]float64, nRows*m.NRawOutputGroups())
_ = m.PredictWithRequest(predict.Request{
	Matrix: predict.DenseMatrix{Values: flat, Rows: nRows, Cols: nf},
	Output: predict.OutputMargin,
}, margins)

// 叶节点索引（每棵树一个 int32）
nTrees := m.NTrees()
leaves := make([]int32, nRows*nTrees)
_ = m.PredictWithRequest(predict.Request{
	Matrix: predict.DenseMatrix{Values: flat, Rows: nRows, Cols: nf},
	Output: predict.OutputLeaf,
}, leaves)

// SHAP 贡献（margin 空间；二分类 [sample][feature+bias]）
out := make([]float64, (nf+1)*nRows)
_ = m.PredictWithRequest(predict.Request{
	Matrix: predict.DenseMatrix{Values: flat, Rows: nRows, Cols: nf},
	Output: predict.OutputContribution, // 也可 OutputApproxContribution / OutputInteraction
}, out)

评估指标 —— metrics/

import "github.com/linkerlin/leaves/v2/metrics"

rmse, _ := metrics.RMSE{}.Evaluate(yTrue, yPred)
m, _ := metrics.Resolve("ndcg@5", metrics.Options{Groups: []int{10, 10}})
ndcg, _ := m.Evaluate(yTrue, yPred)

排序学习

import (
	"github.com/linkerlin/leaves/v2/data"
	"github.com/linkerlin/leaves/v2/train"
)

dm, _ := data.LoadRankingTSV("rank_train.tsv", "\t") // qid label feat1 feat2 ...

learner, _ := train.NewLearner(train.Config{
	Objective:    train.ObjectiveRankNDCG, // 或 ObjectiveRankPairwise / ObjectiveRankListwise
	NumRound:     40,
	MaxDepth:     4,
	LearningRate: 0.1,
	NDCGK:        10,
	EvalMetric:   "ndcg@10",
})
_ = learner.Fit(dm)

cd testdata && python gen_rank_movielens.py
go run ./demos/movielens/cmd/train
go run ./demos/movielens/cmd/recommend -group 0 -topk 10
go test ./train/... -run TestRankMovieLens -v

训练回调与学习率调度

learner, _ := train.NewLearner(train.Config{
	Objective:    train.ObjectiveSquaredError,
	NumRound:     20,
	LearningRate: 0.3,
	LRScheduler:  train.ExponentialLRScheduler(0.95), // 每轮 ×0.95
	Callbacks: []train.TrainingCallback{
		train.FuncCallback(func(ctx *train.CallbackContext) error {
			// ctx.Round, ctx.LearningRate, ctx.TrainMetric, ctx.EvalMetric
			return nil
		}),
	},
})

推理 profiling 与热更新

if ne, ok := m.Engine().(*tree.NativeEngine); ok {
	prof, err := tree.ProfileNativeDense(ne, vals, nrows, ncols, preds, 0)
	_ = prof.Elapsed
}

// 线上原子切换模型
_ = m.Reload("/path/to/new.model", io.DefaultLoadOptions())

int8 阈值量化

qf, _ := quantize.QuantizeForest(m.Forest(), quantize.Config{})
res, err := quantize.CheckParityWithGate(m.Forest(), qf, samples, 0, quantize.DefaultGate())

eng, _ := quantize.NewEngine(qf, nil, tree.TransformRaw, m.NOutputGroups())
model.NewEnsemble(eng) // 替换线上 Ensemble 引擎

Agent 自动化（SKILL 驱动，无 MCP）

三步让 Agent 帮你训练（用户视角）

用 leaves-autotrain 技能，训练数据在 data/train.csv，
目标把 RMSE 降下来，收敛后发布到 release/v1。

sniff → [split] → train(--cv --runs --tag [--early-stop 默认 save-best] [--from-run])
  → runs/diagnose 读账本与 ASI 诊断 → 决策表调参 → 收敛 → compare/inspect → publish(--emit-repro-script)

go run ./cmd/leaves --error-format json sniff --data train.csv
go run ./cmd/leaves train --data train.csv --objective reg:squarederror --cv 5 --runs runs.jsonl --tag baseline
go run ./cmd/leaves train --data train.csv --from-run runs.jsonl --tag baseline --out-model m.leaves.json --metrics metrics.json
go run ./cmd/leaves publish --model m.leaves.json --out-dir release/ --quantize --export-xgb --metrics metrics.json --emit-repro-script both

CLI 入口（用哪条命令）

推荐生产闭环控制面（§十七 RC）

文档

兼容性

性能

局限

项目演进

联系方式

许可证