TRACER Python API完全参考:fit、update、load_router、predict每个参数详解

原创2026-10-15 18:13:302,132 阅读

TRACER Python API完全参考:fit、update、load_router、predict每个参数详解

TRACER 是一款开源的 LLM 推理路由工具,能把昂贵的 LLM 调用轨迹(traces)蒸馏成快速的混合式 System 1 代理模型,并对不确定的请求做校准后的延迟(deferred)交给教师大模型处理。本文为 TRACER Python API 完全参考,逐个拆解 fit、update、load_router、predict 四个核心函数的参数与返回值,帮助你从数据准备一路走到生产部署,少走弯路。

TRACER LLM 路由动机图:并非每个请求都需要调用最昂贵的大模型

TRACER Python API 总览:一条数据流看懂 4 个函数

TRACER 的 Python API 围绕"训练 → 更新 → 加载 → 预测"这条主线设计:

阶段 函数 一句话说明
首次训练 tracer.fit() 用教师模型轨迹训练路由策略,产出 .tracer/ 工件目录
持续学习 tracer.update() 追加新轨迹并原地重训
生产加载 tracer.load_router() 从工件目录加载 Router 实例
线上预测 router.predict() / router.predict_batch() 单条或批量路由:handled 或 deferred

所有函数的权威文档见 docs/api.md,完整实现位于 src/tracer/api.py。想跑通全流程的,可以直接看 notebooks/02-static-tracer.ipynb(静态训练)和 notebooks/03-dynamic-tracer.ipynb(动态更新)两个示例 Notebook。

tracer.fit() 首次训练:4 个参数详解

result = tracer.fit("traces.jsonl")  # 最简调用

fit() 从教师轨迹中拟合一个路由策略,在目标"教师一致率"(teacher agreement)约束下挑选能覆盖最多流量、成本最低的代理模型。它是整个 API 的起点。

参数一览表

参数 类型 默认值 说明
trace_path str | Path 必填 轨迹 JSONL 文件路径,每行含 input_text 与 teacher_label
artifact_dir str | Path ".tracer" 工件输出目录,存放管线、索引、清单等产物
embeddings np.ndarray | None None 预计算嵌入矩阵 (n, dim);为 None 时自动在同目录查找 traces.npy 或 traces_embeddings.npy
config FitConfig | None None 训练配置,缺省使用 FitConfig()

新手最常踩的坑:embeddings 既没传、旁边又没有 .npy 文件时会抛出 FileNotFoundError。推荐做法是先用 tracer.embed(texts) 计算好嵌入再传入。

FitConfig:5 个关键训练开关

FitConfig 定义在 src/tracer/config.py,控制 fit() 与 update() 的行为:

字段 默认值 作用
target_teacher_agreement 0.90 一致率门槛。被代理处理的流量中,至少要有这个比例与教师模型判定一致
frontier_targets (0.85, 0.90, 0.95) 多档目标探索,最终在 target_teacher_agreement 档位取覆盖最高者
min_deploy_coverage 0.05 可部署的最低覆盖率,低于此值的方案不采纳
max_fit_labels 8000 大数据集分层抽样上限,加速训练
seed 42 随机种子,保证可复现

源码中还有两个进阶字段:verbose(默认 True,在 stderr 打印逐候选进度)和 skip_candidates(跳过指定候选模型,例如多标签场景下可跳过耗时的 "gbt")。

FitResult:训练结果里看什么

返回值 FitResult 是后续一切判断的依据(定义见 src/tracer/types.py):

  • result.manifest.selected_method:中选方法,"global"、"l2d"、"rsb" 或 None(None 表示没有方案达标,需要更多数据或更低的 target_teacher_agreement)
  • result.manifest.coverage_cal:校准覆盖率,例如 0.928 表示 92.8% 的流量可由代理处理
  • result.manifest.teacher_agreement_cal:校准教师一致率
  • result.qualitative_report:自动生成的可解释性报告(切片统计、边界样例、代表性案例)
  • result.notes:人类可读的训练备注
  • result.get_sankey():一键生成路由流量 Sankey 图(需 pip install tracer-llm[viz])

下图就是 fit() 后 Sankey 图的典型样子:左侧是各个业务标签,绿色主干流向 Surrogate(代理模型),粉红色细流是延迟给 LLM 教师的少量流量。

TRACER 路由流量 Sankey 图:91% 的请求由本地代理模型处理,9% 延迟到 LLM 教师模型

tracer.update() 增量更新:让路由跟着业务进化

result = tracer.update("traces_day2.jsonl", new_embeddings=X_day2)

流量分布会漂移,update() 用持续学习的思路解决:它读取 .tracer/ 中的历史轨迹,把新轨迹拼接到全量数据上后整体重训,并原地更新工件目录。

参数 类型 默认值 说明
new_trace_path str | Path 必填 新增轨迹的 JSONL 文件
artifact_dir str | Path ".tracer" 要更新的现有工件目录
new_embeddings np.ndarray | None None 仅针对新轨迹的嵌入 (n_new, dim);None 时按同样规则自动查找 .npy
config FitConfig | None None 为 None 时自动沿用清单里记录的原 target_teacher_agreement,保证更新前后门槛一致

两个实用细节:

  1. 更新后可以通过 qualitative_report.temporal_deltas 看到每个标签的处理率变化(TemporalDelta 含 previous_handled_rate / current_handled_rate / delta),这是观察"路由边界是否在漂移"的最快方式。
  2. update() 依赖 fit() 写下的 all_traces.jsonl。如果该文件被删,会收到明确的报错提示让你重跑 fit() 重建——这个失败是快速且可操作的。

tracer.load_router() 生产部署:一行代码加载路由

router = tracer.load_router(".tracer", embedder=embedder)

load_router() 从 .tracer/ 目录加载清单、管线和 FAISS 嵌入索引,返回一个可直接承接线上流量的 Router 实例(实现见 src/tracer/runtime/router.py)。

参数 类型 默认值 说明
artifact_dir str | Path ".tracer" 工件目录
embedder Embedder | None None 设置后 predict 可直接传入文本字符串;不设置则只能传嵌入向量

注意:如果 manifest.json 中 selected_method 为 null(训练时没有方案达标),load_router() 会抛出 ValueError 并提示你补充数据或降低 target_teacher_agreement 后重新 fit()——这是刻意的"安全阀"。

Router.predict() 单条预测:2 个参数,4 个返回值

out = router.predict("What is my balance?")
# 或
out = router.predict("What is my balance?",
                      fallback=lambda: call_my_llm("What is my balance?"))
参数 类型 说明
input str | np.ndarray 文本(需 embedder)或形状 (dim,) 的嵌入向量;维度与训练不符会抛 ValueError
fallback callable | None 请求被延迟(deferred)时以无参方式调用,其返回值作为最终 label 返回——生产里通常接你的教师 LLM 调用

返回字典的 4 个字段:

字段 含义
label 预测标签(延迟且无 fallback 时为 None)
decision "handled"(代理处理)或 "deferred"(延迟给教师)
accept_score 接受器置信度 0–1,越高说明代理越"敢接"
stage 由管线哪个阶段处理(-1 表示延迟)

一个常被忽略的安全机制:即使代理置信度很高,如果输入距离训练分布过远(kNN 距离超过 fit() 时校准的 OOD 阈值),Router 仍会强制 deferred。这是训练时写入 ood.json 的兜底闸门。

predict_batch() 批量预测

batch = router.predict_batch(["query 1", "query 2", "query 3"])
参数 说明
inputs 文本列表(需 embedder)或 (n, dim) 嵌入矩阵

返回 labels、decisions、handled(布尔数组)、preds(标签索引)、stage_id 五个键。统计覆盖率的典型用法:batch["handled"].sum()。

Embedder:让 predict 直接吃文本的 3 种工厂方法

如果不想每次手工调嵌入,给 load_router() 配一个 Embedder 即可(实现见 src/tracer/embeddings/embedder.py):

工厂方法 适用场景 关键参数
Embedder.from_sentence_transformers() 本地模型,离线可用 model(默认 "all-MiniLM-L6-v2")、device、batch_size、normalize
Embedder.from_endpoint() 调用外部 HTTP 嵌入服务 url、headers、input_key、output_key,支持批量键配置
Embedder.from_callable() 任何自定义嵌入函数 传入 fn(texts) -> (n, dim)

创建后有两个实例方法可用:embedder.embed(texts) 批量嵌入、embedder.embed_one(text) 单条嵌入。

TRACER Python API 参数速查表

函数 必填参数 可选参数 返回
tracer.fit() trace_path artifact_dir、embeddings、config FitResult
tracer.update() new_trace_path artifact_dir、new_embeddings、config FitResult
tracer.load_router() —(默认 .tracer) artifact_dir、embedder Router
router.predict() input fallback dict(label/decision/accept_score/stage)
router.predict_batch() inputs — dict(labels/decisions/handled/preds/stage_id)

围绕训练还有几个高频辅助函数值得一并记住:tracer.scan()(训练前的保守评估,回答"我的流量有多少能认证交给便宜模型")、tracer.report()(读取工件清单)、tracer.generate_html_report()(生成自包含 HTML 报告)、tracer.generate_sankey()(生成上面那种交互路由流量图)。

参考资料与源码路径

登录后查看全文
tracer