TRACER Python API完全参考:fit、update、load_router、predict每个参数详解
TRACER Python API完全参考:fit、update、load_router、predict每个参数详解
TRACER 是一款开源的 LLM 推理路由工具,能把昂贵的 LLM 调用轨迹(traces)蒸馏成快速的混合式 System 1 代理模型,并对不确定的请求做校准后的延迟(deferred)交给教师大模型处理。本文为 TRACER Python API 完全参考,逐个拆解 fit、update、load_router、predict 四个核心函数的参数与返回值,帮助你从数据准备一路走到生产部署,少走弯路。
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.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,保证更新前后门槛一致 |
两个实用细节:
- 更新后可以通过
qualitative_report.temporal_deltas看到每个标签的处理率变化(TemporalDelta含previous_handled_rate/current_handled_rate/delta),这是观察"路由边界是否在漂移"的最快方式。 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()(生成上面那种交互路由流量图)。
参考资料与源码路径
- API 完整文档:docs/api.md
- 公共 API 实现:src/tracer/api.py
- 训练配置
FitConfig:src/tracer/config.py - 生产路由
Router实现:src/tracer/runtime/router.py - 核心数据类型
FitResult/ArtifactManifest:src/tracer/types.py - 静态训练示例:notebooks/02-static-tracer.ipynb
- 动态更新示例:notebooks/03-dynamic-tracer.ipynb

