一个很典型的场景是你让 AI 助手帮你完成一个机器学习任务它很快给出了一套流程从数据清洗到模型训练再到评估看起来逻辑完整。但当你真正运行之后发现它在特征工程环节跳过了关键步骤导致整个实验白跑。问题出在哪里答案往往不是代码能力而是规划。很多开发者在引入 Agent 时习惯让它“全自动”结果流程一长链路上的小偏差就会在最后放大成不可控的结果。今天想聊一个更值得关注的方向TraceML也就是对机器学习开发过程中人类与 AI 智能体协作规划的实证分析。它要研究的不是某个模型指标提升了多少而是“在真实 ML 开发过程里人和 Agent 一起做计划时流程是怎么发生的、计划如何被人类修正、最终对开发效率和结果产生了什么影响”。这不是一个具体可安装的框架也不是某个开箱即用的工具而是一种把“开发过程本身”当作研究对象的方法论。读完这篇文章你会理解人机协同规划的核心问题能设计一套最小可用的过程追踪方案也能在工程实践中减少 Agent 偏离目标的概率。我会用一个小型示例来演示如何记录规划、获取人类反馈并计算基础指标你可以直接把这个思路迁移到自己的项目里。1. 这篇文章真正要解决的问题机器学习开发从来不是一条直线。真实项目里最常见的状态是数据探索到一半发现缺字段回到清洗阶段补数据模型训练后效果不达标又回去换特征评估指标不稳定再从头检查数据切分。这些环节之间的跳转非常频繁而且高度依赖人的判断。一个人单打独斗时规划存在于脑子里一个团队协作时规划会沉淀在文档和工单里。但当 AI Agent 加入后规划变成了一个需要显式管理的问题。AI Agent 的优势是生成速度快能够同时给出数据清洗、特征工程、模型选择、超参数调优的多步计划。但它的问题也很明显它对“当前项目上下文”的理解是有限的容易生成看似合理、实际上不符合数据情况的步骤。如果开发者不做干预Agent 就会沿着自己生成的计划一路执行直到在某个不可逆的地方产生偏差比如把时间特征当作字符串直接删除、在目标列里引入了未来信息或者把大量样本错误地划分到验证集。这里真正容易踩坑的地方是很多团队把 Agent 的规划能力等同于写代码能力以为模型能自动生成代码就一定擅长制定研发流程。实际上代码生成错误是显性的运行时报错可以定位规划错误是隐性的它会悄悄污染整个后续流程。TraceML 的价值就在于它把这种隐性错误转化成可以追踪、可以度量、可以改进的对象。所以这篇文章真正要解决的问题是当人类和 AI 智能体共同参与机器学习开发生命周期时我们应该如何描述、记录和评估“规划”这个环节。它适合三类读者第一类正在做 MLOps 或 AI 辅助开发工具的工程师第二类在项目里引入了 Agent但发现协作效率忽高忽低的团队第三类想深入理解人机协作边界的研究者。2. 基础概念与核心原理2.1 机器学习开发生命周期先统一一下语境。一个典型的机器学习项目通常包含以下阶段业务理解与问题定义、数据获取与探索、数据清洗与预处理、特征工程、模型选择与训练、模型评估与调优、部署与监控、迭代维护。在实践中这些阶段不是顺序执行的而是大量回跳和并行的。传统软件工程以版本管理、构建、测试为核心而机器学习开发还多了一层“实验管理”的概念。每一次数据切分、特征组合、超参数变化都会产生一个新的实验版本。在缺少规范流程时开发者很容易迷失在大量实验记录里。2.2 Human-Agent Planning 的概念Human-Agent Planning即人类与智能体协作规划指的是一个 AI System 与人类开发者共同制定行动计划的过程。这里有三种典型模式第一种人类手动规划Agent 只负责执行。开发者把完整步骤写清楚Agent 按指令运行。这种模式可控性最高但人类负担重。第二种Agent 自动规划人类在关键节点审批。Agent 先给出计划人类可以修改、驳回或直接批准。这种模式是目前 LLM Agent 工具的主流交互方式。第三种Agent 完全自治自主决定一切步骤。这种模式效率高但风险也最大尤其在数据敏感、业务复杂的场景中。TraceML 研究的重点就是第二种和第三种模式下Plan 是怎么被提出、修订、执行和验证的。2.3 为什么要把“规划”单独拿出来分析我们可以把 Agent 的工作过程拆成几个层面意图理解、计划生成、工具调用、代码执行、结果反馈。大多数学术研究和工程工具关注的是工具调用和代码执行因为它们可观测、可评测。但规划层面长期以来被忽略了原因在于它难以量化。一个计划到底好不好不能只看“最后模型 AUC 是多少”。实验条件不同、数据质量不同指标本身不具备可比性。TraceML 的思路是把开发过程中产生的轨迹记录下来比如 Agent 生成了哪些步骤、人类修改了哪些步骤、执行到哪一步时发生了返工然后对这些轨迹做统计分析。这样可以回答更细的问题Agent 的规划在哪个环节最容易出现偏差人类更倾向于修正计划里的哪类错误计划修改后成功率提高了多少2.4 核心概念对照概念通俗解释关键技术点计划生成Agent 根据任务目标把大目标拆成子步骤LLM 的拆解能力、上下文长度、工具约束人类反馈开发者对计划进行修改、补充或否决人机交互设计、反馈时机、反馈形式轨迹追踪记录整个开发过程的每一步操作和状态日志结构、状态机、可重放性规划偏差Agent 计划与实际执行的差距步骤覆盖率、执行顺序变化、返工次数干预频率人类对计划或执行过程进行干预的次数干预类型、干预后成功率在接下来的章节里我会围绕这些概念设计一个最小实验并用代码演示如何记录和处理这类数据。3. 为什么需要实证分析从经验直觉到可度量很多团队在评估 AI 编程助手时用的方法是“我觉得它挺快的”“它在我的例子上表现不错”。这种经验直觉在简单任务上有效但在复杂 ML 项目里很容易失真。原因有两个第一ML 项目的偶发性很强一次实验跑得好不代表整体规划合理第二人的记忆会美化过程问题出现在第几环节、人类干预了几次、哪些计划被推翻重来这些细节如果不实时记录事后很难还原。实证分析的意义是把“感觉”变成“数据”。TraceML 的核心主张是把开发轨迹当作和模型指标一样重要的实验数据来对待。模型指标回答“最终好不好”开发轨迹回答“过程是否合理”。两者结合才能真正定位瓶颈。举个例子一个团队发现 Agent 在图像分类任务上总是忽略类别不平衡问题。从最终指标看准确率不低但召回率很差。如果只看结果人可能会去调损失函数如果查看轨迹你会发现 Agent 的计划里压根没有“检查类别分布”这一步。这时候问题不是模型能力而是规划缺失。没有过程数据这种归因非常困难。实证分析还需要定义基础指标。比较常用的是计划完成率计划中所有步骤里实际执行成功的占比。人类干预率人类修改或拒绝步骤数占总步骤数的比例。返工率因为某个环节结果不合格导致前面步骤重新执行的次数。规划偏差Agent 原始计划与最终执行方案之间的差异程度。恢复时间一旦执行失败从发现失败到重新进入稳定状态所需的时间。这些指标在不同任务、不同团队之间会有波动但它们的价值在于提供横向和纵向比较的基准。你可以用同一批任务对比不同 Agent 配置也可以用同一 Agent 对比不同的提示策略。这就是 TraceML 视角下的实验方法。4. 环境准备与实验设计要复现本文的思路不一定要跑一个庞大的研究系统。我们可以从最小实验开始只做三件事让 Agent 生成计划让人类对计划进行修订然后记录整个过程的轨迹。4.1 环境准备建议使用 Python 3.10 及以上版本。核心依赖包括openai 或其他大模型 SDK用于调用对话模型生成初始计划pandas用于最终指标汇总pydantic 或 dataclasses用于定义规划记录的数据结构。如果本地不方便调用大模型 API可以用规则模板模拟 Agent 的规划输出。重点是流程本身而不是模型。你完全可以在笔记本上跑通整个示例。安装依赖时用虚拟环境隔离比较稳妥python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate pip install openai pandas注意如果只是做数据分析pandas 可以换成标准库 csv。实际生产项目再根据团队技术栈选择组件。4.2 实验任务设定我们用一个简单的流失预测任务作为实验样本。任务描述给定一份客户数据集包含年龄、收入、使用时长、投诉次数、是否流失等字段。要求完成数据探索、清洗、特征工程、模型训练和评估最终输出一个可用于业务解释的分类模型。这个任务足够小但覆盖了 ML 开发的核心环节。Agent 需要生成一份计划人类可以选择修改。所有操作都会被记录到结构化日志里。4.3 日志目录结构建议把每一次实验的轨迹保存为一个独立目录包含原始计划、人类反馈、执行记录、最终评估四个文件。experiments/ run_20250101_120000/ initial_plan.json feedback.json execution_log.json evaluation.json这样做的好处是方便回溯。任何时候出了结果问题都能重新打开对应目录查看当时规划在哪个节点发生了偏离。5. 核心流程拆解5.1 步骤一任务定义任务定义是整个实验的起点。需要明确几项内容业务目标、数据集说明、成功标准、约束条件。如果任务定义不清晰Agent 很容易把计划设计成通用模板这对后续分析没有价值。比如同样一个流失预测任务如果成功标准是“模型召回率不低于 0.8”Agent 就会在计划中增加类别不平衡处理和阈值调整如果成功标准是“模型可解释性优先”计划就会偏向逻辑回归或决策树。因此任务定义必须写入轨迹数据它会影响所有后续判断。5.2 步骤二Agent 初始规划生成让 Agent 根据任务定义输出一份结构化计划。这里的关键是限定输出格式建议用 JSON 而不是自由文本方便后续解析。计划中每个步骤应包含阶段、动作描述、输入条件、产出物、可能的风险。这一步可能会遇到的问题是 Agent 生成步骤过多或者过少。步骤过多执行成本高步骤过少信息不足。这本身就是一个可分析的特征不同模型规划粒度的差异会在后面的指标里体现出来。5.3 步骤三人类反馈人类反馈不能只是“通过”或“拒绝”最好可以逐条修改。例如Agent 计划的第五步是“直接使用随机森林训练模型”人类可以修改为“先尝试逻辑回归和随机森林并通过交叉验证比较”。这类反馈应该结构化记录为对某一步的替换、新增或删除。真实场景中人类反馈的质量对规划效果影响极大。TraceML 实验可以在这一步要求参与者在每次修改时写下原因为后续定性分析提供素材。5.4 步骤四执行与追踪计划执行过程中需要记录每个步骤的开始时间、结束时间、状态成功、失败、跳过、产物路径、关键日志。这个环节最关键的是时间戳。没有时间戳就无法计算阶段耗时和返工率。如果 Agent 在步骤三的执行中发现需要返回步骤二补充操作这里应当记录一次“返工事件”。这个事件对规划质量评估非常关键。5.5 步骤五结果分析读取所有轨迹记录汇总成表格计算规划指标。分析可以分为两层单次任务分析看这次协作是否顺利多次任务分析看整体模式下哪类规划偏差最频繁。TraceML 的价值在多层分析单次只能形成假设多次才能验证规律。6. 完整示例代码实现下面提供一套最小可运行代码帮助你理解 TraceML 的实验思路。这里用规则模板模拟 Agent 规划用字典模拟人类反馈重点放在数据结构和指标计算上。6.1 定义规划数据结构文件路径tracelml/models.pyfrom dataclasses import dataclass, field from typing import List, Optional from datetime import datetime dataclass class PlanStep: step_id: str phase: str description: str status: str pending # pending / done / failed / skipped owner: str agent # agent / human / mixed started_at: Optional[str] None finished_at: Optional[str] None return_to: Optional[str] None # 如果返工返回到哪一步 dataclass class Plan: task: str steps: List[PlanStep] field(default_factorylist) created_at: str field(default_factorylambda: datetime.now().isoformat()) owner: str agent dataclass class HumanFeedback: step_id: str action: str # approve / modify / reject feedback_text: str timestamp: str field(default_factorylambda: datetime.now().isoformat())这个结构覆盖了规划的核心要素。return_to字段专门用来记录返工这在后续分析里非常有用。6.2 模拟 Agent 生成计划和人类反馈文件路径tracelml/simulate.pyimport json from .models import Plan, PlanStep, HumanFeedback def generate_initial_plan(task: str) - Plan: 这里用规则模拟 LLM Agent 自动生成计划。 真实应用中可以替换为对大模型接口的调用。 plan Plan(tasktask) plan.steps [ PlanStep(step_ids1, phasedata_exploration, description加载数据集查看字段分布和缺失值), PlanStep(step_ids2, phasedata_cleaning, description处理缺失值删除重复记录), PlanStep(step_ids3, phasefeature_engineering, description生成统计特征例如使用时长与投诉次数的比例), PlanStep(step_ids4, phasemodel_training, description使用随机森林训练基线模型), PlanStep(step_ids5, phaseevaluation, description评估模型准确率与召回率), ] return plan def apply_human_feedback(plan: Plan, feedback: HumanFeedback) - Plan: 将人类反馈应用到计划上。 approve 表示批准原步骤modify 表示替换步骤描述reject 表示删除步骤。 for idx, step in enumerate(plan.steps): if step.step_id feedback.step_id: if feedback.action modify: step.description feedback.feedback_text step.owner human elif feedback.action reject: plan.steps.pop(idx) elif feedback.action approve: step.owner human break return plan这里的模拟代码没有真实调用模型但保留了替换点。你可以在generate_initial_plan里调用大模型解析返回的 JSON并构建Plan对象。6.3 模拟执行过程并记录轨迹文件路径tracelml/executor.pyimport json from datetime import datetime from copy import deepcopy def record_plan(plan: Plan, path: str): with open(path, w, encodingutf-8) as f: json.dump([ { step_id: s.step_id, phase: s.phase, description: s.description, status: s.status, owner: s.owner, } for s in plan.steps ], f, ensure_asciiFalse, indent2) def simulate_execution(plan: Plan) - dict: 模拟执行计划并记录一次“从 s3 返工到 s2”的事件。 真实项目中这一步应该由实际执行环境触发。 logs [] for idx, step in enumerate(plan.steps): step.started_at datetime.now().isoformat() if step.step_id s3: # 假设特征工程发现数据清洗不彻底返工到 s2 step.status failed step.return_to s2 logs.append({ step_id: step.step_id, event: return_to, return_to: s2, timestamp: datetime.now().isoformat(), }) # 将 s2 置为 failed表示需要重新执行 plan.steps[idx - 1].status failed plan.steps[idx - 1].return_to s2 else: step.status done step.finished_at datetime.now().isoformat() execution_summary { total_steps: len(plan.steps), done_steps: sum(1 for s in plan.steps if s.status done), failed_steps: sum(1 for s in plan.steps if s.status failed), return_events: logs, } return execution_summary这个模拟器很简单但它说明了轨迹数据应该记录什么每步状态、时间点、返工事件。真实接入时可以把这些逻辑分布到不同的 Task 执行器里。6.4 计算 TraceML 指标文件路径tracelml/metrics.pydef compute_planning_metrics(execution_summary: dict, plan: Plan) - dict: total len(plan.steps) done execution_summary[done_steps] failed execution_summary[failed_steps] return_events execution_summary[return_events] plan_completion_rate done / total if total 0 else 0.0 human_owner_steps sum(1 for s in plan.steps if s.owner human) human_owner_ratio human_owner_steps / total if total 0 else 0.0 rework_rate len(return_events) / total if total 0 else 0.0 return { plan_completion_rate: round(plan_completion_rate, 3), human_owner_ratio: round(human_owner_ratio, 3), rework_rate: round(rework_rate, 3), return_events: return_events, }你可以把execution_summary和plan对象传入得到一组结果。在此基础上还可以扩展“规划偏差”“干预频次”等指标但上面三个已经足够启动一个小型实验。6.5 主流程启动文件文件路径tracelml/main.pyfrom .models import HumanFeedback from .simulate import generate_initial_plan, apply_human_feedback from .executor import record_plan, simulate_execution from .metrics import compute_planning_metrics def run_experiment(): task 客户流失预测模型开发 plan generate_initial_plan(task) # 人类反馈修改模型训练步骤 feedback HumanFeedback( step_ids4, actionmodify, feedback_text同时训练逻辑回归和随机森林并用 5 折交叉验证比较, ) plan apply_human_feedback(plan, feedback) record_plan(plan, experiments/initial_plan.json) summary simulate_execution(plan) metrics compute_planning_metrics(summary, plan) print(metrics) if __name__ __main__: run_experiment()运行方式cd tracelml python -m tracelml.main如果你的项目结构不同只要保证 Python 能找到包路径即可。7. 运行结果与效果验证运行上面代码后预期会输出类似如下的指标{ plan_completion_rate: 0.8, human_owner_ratio: 0.2, rework_rate: 0.2, return_events: [ { step_id: s3, event: return_to, return_to: s2, timestamp: 2025-01-01T12:00:00.123456 } ] }从结果可以看出计划完成率是 80%因为 s2 和 s3 各自因为返工被标记为 failed。人类负责人占比 20%表示五个步骤中有一个步骤被人类修改。返工率 20%说明五个步骤里发生了一次返工。这些数字在一两次运行中意义不大但如果多次运行并汇总就能看出 Agent 在哪个环节最容易引发返工。如何判断实验是否成功第一轨迹文件是否完整生成了experiments/initial_plan.json第二指标输出是否符合预期第三返工事件是否被正确捕获。如果你在模拟执行里改变了返工逻辑指标也应该相应变化这样才能证明追踪链路是通的。如果运行失败建议先做三件事检查tracelml目录下是否缺少__init__.py文件导致包无法导入检查 Python 版本dataclasses在 Python 3.7 可用但本文示例在 3.10 环境验证更稳妥检查当前工作目录确认experiments目录存在否则写文件会报错。8. 常见问题与排查思路问题现象可能原因排查方式解决方案生成的计划步骤太多难以落地提示词中缺少对步骤数量和粒度的约束查看 Agent 原始输出统计步骤数在提示词中明确“步骤数不超过 10 步每步描述包含产出物”人类反馈没有被记录到最终计划反馈应用逻辑只修改了对象副本检查内存中 plan 对象的 id 是否一致使用不可变结构或深拷贝确保反馈后返回新计划轨迹数据没有时间戳无法统计耗时日志字段设计时遗漏 started_at / finished_at查看执行器代码在每步 start 和 finish 时写入当前时间同一实验多次运行结果不一致实验包含随机种子未固定检查数据划分和模型训练部分固定随机种子或记录每次运行的环境信息开发模式服务被误用于生产使用 Flask 等自带开发服务器部署检查服务启动命令生产环境使用正式 Web 服务器并关闭 debug 模式这里的“开发服务器”警告值得多说一句。如果你在实验里用 Flask 写了一个追踪面板只用于本地查看轨迹那么app.run()默认启动的是开发服务器。开发服务器不适合生产部署不是因为功能弱而是因为它在设计上优先考虑开发调试性能和安全性都没有针对生产环境优化。在团队协作时建议把轨迹分析面板放到内网测试环境并用正式 WSGI 服务器启动。另一个常见问题是缺少反馈原因记录。只记录“人类修改了某一步”不记录“为什么修改”后续分析会很难深入。建议在反馈数据结构中增加reason字段即使一开始只是自由文本也能在归纳分析时提供重要线索。9. 最佳实践与工程建议9.1 明确人机分工避免全自动Agent 的最大风险不是“能力不足”而是“方向不对时跑得太快”。在 ML 开发中涉及数据理解、特征合理性、业务逻辑判断的节点都应该设置为人工确认点。例如数据探索完成后的“是否清洗”、特征工程完成后的“特征是否都来自训练时可得的信息”、模型训练后的“指标是否满足业务要求”。这些节点如果不加设防Agent 可能会一路带着偏差跑到底。9.2 把规划轨迹当作实验数据管理很多团队记录了 model artifact、metrics、config但忘记了记录“Planning Process”。TraceML 的工程实践之一是把计划、反馈、执行日志、评估结果一起纳入版本管理。这样任何一次实验的复现都不仅仅是复现代码而是复现整个决策过程。建议每条轨迹都包含任务定义原文Agent 初始计划人类反馈的每一步修改和原因实际执行日志最终评估结果。9.3 从失败轨迹中学习成功轨迹只能告诉你“哪条路走通了”失败轨迹才能告诉你“哪里容易走偏”。在建设团队内部 Agent 应用时不要只收集成功的案例。那些导致返工、延误、数据泄漏的问题轨迹价值往往更高。定期复盘时优先看返工率最高的阶段。9.4 小步实验建立基线不要一开始就想建设完整的人机协同平台。可以先挑一个高频重复的 ML 任务搭建最小轨迹记录计算几项基础指标跑三到五轮实验形成基线。之后再逐步增加反馈类型、优化提示词、调整人工确认点。这样可以避免“为了分析而分析”的过度设计。9.5 注意安全与合规边界在真实业务数据上做实验时要遵守最小权限原则。不要因为 Agent 需要“查看数据”就把生产库的完整访问权限交给它。建议使用脱敏数据集或样本数据调试流程正式实验前经过审批。涉及用户信息的数据要避免写入明文日志。轨迹记录中如果包含敏感字段应做脱敏处理后再存储。9.6 让反馈机制更轻量人类反馈如果过于复杂会降低开发者使用意愿。如果每次修改都需要填写长表单很快就没人愿意干预 Agent 了。最低成本的反馈是允许直接用自然语言修改某一步甚至允许“合并两步”“复制一步再改”。反馈越轻量轨迹越完整后续分析越有价值。10. 总结与后续学习方向TraceML 本质上是一种视角转换不再只盯着模型的最终表现而是把人和 Agent 共同完成 ML 开发任务的过程当作研究对象。它的核心是“可追踪、可度量、可回放”。只要能把计划生成、人类反馈、执行状态和返工事件记录下来就已经进入了 TraceML 的实践轨道。下一步你可以从三个方向深入。第一研究可解释规划如何让 Agent 在生成步骤时同时输出“为什么这样做”辅助人类更快做出审批决策。第二动态规划当执行结果与预期不一致时Agent 如何重新规划而不是继续一条路走到黑。第三构建轨迹数据集把多次实验的轨迹整理成标准格式用于训练更擅长协作的 Agent 模型。在实际项目中不用一开始就追求大而全。我的建议是从小处开始给自己的下一个 ML 任务加一个简单日志记录下你什么时候决定修改 Agent 的计划、为什么修改以及修改后结果是否变好了。这种“先记录再优化”的思路远比相信感觉更可靠。
机器学习开发中的TraceML：让人机协同规划过程可追踪、可度量
一个很典型的场景是你让 AI 助手帮你完成一个机器学习任务它很快给出了一套流程从数据清洗到模型训练再到评估看起来逻辑完整。但当你真正运行之后发现它在特征工程环节跳过了关键步骤导致整个实验白跑。问题出在哪里答案往往不是代码能力而是规划。很多开发者在引入 Agent 时习惯让它“全自动”结果流程一长链路上的小偏差就会在最后放大成不可控的结果。今天想聊一个更值得关注的方向TraceML也就是对机器学习开发过程中人类与 AI 智能体协作规划的实证分析。它要研究的不是某个模型指标提升了多少而是“在真实 ML 开发过程里人和 Agent 一起做计划时流程是怎么发生的、计划如何被人类修正、最终对开发效率和结果产生了什么影响”。这不是一个具体可安装的框架也不是某个开箱即用的工具而是一种把“开发过程本身”当作研究对象的方法论。读完这篇文章你会理解人机协同规划的核心问题能设计一套最小可用的过程追踪方案也能在工程实践中减少 Agent 偏离目标的概率。我会用一个小型示例来演示如何记录规划、获取人类反馈并计算基础指标你可以直接把这个思路迁移到自己的项目里。1. 这篇文章真正要解决的问题机器学习开发从来不是一条直线。真实项目里最常见的状态是数据探索到一半发现缺字段回到清洗阶段补数据模型训练后效果不达标又回去换特征评估指标不稳定再从头检查数据切分。这些环节之间的跳转非常频繁而且高度依赖人的判断。一个人单打独斗时规划存在于脑子里一个团队协作时规划会沉淀在文档和工单里。但当 AI Agent 加入后规划变成了一个需要显式管理的问题。AI Agent 的优势是生成速度快能够同时给出数据清洗、特征工程、模型选择、超参数调优的多步计划。但它的问题也很明显它对“当前项目上下文”的理解是有限的容易生成看似合理、实际上不符合数据情况的步骤。如果开发者不做干预Agent 就会沿着自己生成的计划一路执行直到在某个不可逆的地方产生偏差比如把时间特征当作字符串直接删除、在目标列里引入了未来信息或者把大量样本错误地划分到验证集。这里真正容易踩坑的地方是很多团队把 Agent 的规划能力等同于写代码能力以为模型能自动生成代码就一定擅长制定研发流程。实际上代码生成错误是显性的运行时报错可以定位规划错误是隐性的它会悄悄污染整个后续流程。TraceML 的价值就在于它把这种隐性错误转化成可以追踪、可以度量、可以改进的对象。所以这篇文章真正要解决的问题是当人类和 AI 智能体共同参与机器学习开发生命周期时我们应该如何描述、记录和评估“规划”这个环节。它适合三类读者第一类正在做 MLOps 或 AI 辅助开发工具的工程师第二类在项目里引入了 Agent但发现协作效率忽高忽低的团队第三类想深入理解人机协作边界的研究者。2. 基础概念与核心原理2.1 机器学习开发生命周期先统一一下语境。一个典型的机器学习项目通常包含以下阶段业务理解与问题定义、数据获取与探索、数据清洗与预处理、特征工程、模型选择与训练、模型评估与调优、部署与监控、迭代维护。在实践中这些阶段不是顺序执行的而是大量回跳和并行的。传统软件工程以版本管理、构建、测试为核心而机器学习开发还多了一层“实验管理”的概念。每一次数据切分、特征组合、超参数变化都会产生一个新的实验版本。在缺少规范流程时开发者很容易迷失在大量实验记录里。2.2 Human-Agent Planning 的概念Human-Agent Planning即人类与智能体协作规划指的是一个 AI System 与人类开发者共同制定行动计划的过程。这里有三种典型模式第一种人类手动规划Agent 只负责执行。开发者把完整步骤写清楚Agent 按指令运行。这种模式可控性最高但人类负担重。第二种Agent 自动规划人类在关键节点审批。Agent 先给出计划人类可以修改、驳回或直接批准。这种模式是目前 LLM Agent 工具的主流交互方式。第三种Agent 完全自治自主决定一切步骤。这种模式效率高但风险也最大尤其在数据敏感、业务复杂的场景中。TraceML 研究的重点就是第二种和第三种模式下Plan 是怎么被提出、修订、执行和验证的。2.3 为什么要把“规划”单独拿出来分析我们可以把 Agent 的工作过程拆成几个层面意图理解、计划生成、工具调用、代码执行、结果反馈。大多数学术研究和工程工具关注的是工具调用和代码执行因为它们可观测、可评测。但规划层面长期以来被忽略了原因在于它难以量化。一个计划到底好不好不能只看“最后模型 AUC 是多少”。实验条件不同、数据质量不同指标本身不具备可比性。TraceML 的思路是把开发过程中产生的轨迹记录下来比如 Agent 生成了哪些步骤、人类修改了哪些步骤、执行到哪一步时发生了返工然后对这些轨迹做统计分析。这样可以回答更细的问题Agent 的规划在哪个环节最容易出现偏差人类更倾向于修正计划里的哪类错误计划修改后成功率提高了多少2.4 核心概念对照概念通俗解释关键技术点计划生成Agent 根据任务目标把大目标拆成子步骤LLM 的拆解能力、上下文长度、工具约束人类反馈开发者对计划进行修改、补充或否决人机交互设计、反馈时机、反馈形式轨迹追踪记录整个开发过程的每一步操作和状态日志结构、状态机、可重放性规划偏差Agent 计划与实际执行的差距步骤覆盖率、执行顺序变化、返工次数干预频率人类对计划或执行过程进行干预的次数干预类型、干预后成功率在接下来的章节里我会围绕这些概念设计一个最小实验并用代码演示如何记录和处理这类数据。3. 为什么需要实证分析从经验直觉到可度量很多团队在评估 AI 编程助手时用的方法是“我觉得它挺快的”“它在我的例子上表现不错”。这种经验直觉在简单任务上有效但在复杂 ML 项目里很容易失真。原因有两个第一ML 项目的偶发性很强一次实验跑得好不代表整体规划合理第二人的记忆会美化过程问题出现在第几环节、人类干预了几次、哪些计划被推翻重来这些细节如果不实时记录事后很难还原。实证分析的意义是把“感觉”变成“数据”。TraceML 的核心主张是把开发轨迹当作和模型指标一样重要的实验数据来对待。模型指标回答“最终好不好”开发轨迹回答“过程是否合理”。两者结合才能真正定位瓶颈。举个例子一个团队发现 Agent 在图像分类任务上总是忽略类别不平衡问题。从最终指标看准确率不低但召回率很差。如果只看结果人可能会去调损失函数如果查看轨迹你会发现 Agent 的计划里压根没有“检查类别分布”这一步。这时候问题不是模型能力而是规划缺失。没有过程数据这种归因非常困难。实证分析还需要定义基础指标。比较常用的是计划完成率计划中所有步骤里实际执行成功的占比。人类干预率人类修改或拒绝步骤数占总步骤数的比例。返工率因为某个环节结果不合格导致前面步骤重新执行的次数。规划偏差Agent 原始计划与最终执行方案之间的差异程度。恢复时间一旦执行失败从发现失败到重新进入稳定状态所需的时间。这些指标在不同任务、不同团队之间会有波动但它们的价值在于提供横向和纵向比较的基准。你可以用同一批任务对比不同 Agent 配置也可以用同一 Agent 对比不同的提示策略。这就是 TraceML 视角下的实验方法。4. 环境准备与实验设计要复现本文的思路不一定要跑一个庞大的研究系统。我们可以从最小实验开始只做三件事让 Agent 生成计划让人类对计划进行修订然后记录整个过程的轨迹。4.1 环境准备建议使用 Python 3.10 及以上版本。核心依赖包括openai 或其他大模型 SDK用于调用对话模型生成初始计划pandas用于最终指标汇总pydantic 或 dataclasses用于定义规划记录的数据结构。如果本地不方便调用大模型 API可以用规则模板模拟 Agent 的规划输出。重点是流程本身而不是模型。你完全可以在笔记本上跑通整个示例。安装依赖时用虚拟环境隔离比较稳妥python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate pip install openai pandas注意如果只是做数据分析pandas 可以换成标准库 csv。实际生产项目再根据团队技术栈选择组件。4.2 实验任务设定我们用一个简单的流失预测任务作为实验样本。任务描述给定一份客户数据集包含年龄、收入、使用时长、投诉次数、是否流失等字段。要求完成数据探索、清洗、特征工程、模型训练和评估最终输出一个可用于业务解释的分类模型。这个任务足够小但覆盖了 ML 开发的核心环节。Agent 需要生成一份计划人类可以选择修改。所有操作都会被记录到结构化日志里。4.3 日志目录结构建议把每一次实验的轨迹保存为一个独立目录包含原始计划、人类反馈、执行记录、最终评估四个文件。experiments/ run_20250101_120000/ initial_plan.json feedback.json execution_log.json evaluation.json这样做的好处是方便回溯。任何时候出了结果问题都能重新打开对应目录查看当时规划在哪个节点发生了偏离。5. 核心流程拆解5.1 步骤一任务定义任务定义是整个实验的起点。需要明确几项内容业务目标、数据集说明、成功标准、约束条件。如果任务定义不清晰Agent 很容易把计划设计成通用模板这对后续分析没有价值。比如同样一个流失预测任务如果成功标准是“模型召回率不低于 0.8”Agent 就会在计划中增加类别不平衡处理和阈值调整如果成功标准是“模型可解释性优先”计划就会偏向逻辑回归或决策树。因此任务定义必须写入轨迹数据它会影响所有后续判断。5.2 步骤二Agent 初始规划生成让 Agent 根据任务定义输出一份结构化计划。这里的关键是限定输出格式建议用 JSON 而不是自由文本方便后续解析。计划中每个步骤应包含阶段、动作描述、输入条件、产出物、可能的风险。这一步可能会遇到的问题是 Agent 生成步骤过多或者过少。步骤过多执行成本高步骤过少信息不足。这本身就是一个可分析的特征不同模型规划粒度的差异会在后面的指标里体现出来。5.3 步骤三人类反馈人类反馈不能只是“通过”或“拒绝”最好可以逐条修改。例如Agent 计划的第五步是“直接使用随机森林训练模型”人类可以修改为“先尝试逻辑回归和随机森林并通过交叉验证比较”。这类反馈应该结构化记录为对某一步的替换、新增或删除。真实场景中人类反馈的质量对规划效果影响极大。TraceML 实验可以在这一步要求参与者在每次修改时写下原因为后续定性分析提供素材。5.4 步骤四执行与追踪计划执行过程中需要记录每个步骤的开始时间、结束时间、状态成功、失败、跳过、产物路径、关键日志。这个环节最关键的是时间戳。没有时间戳就无法计算阶段耗时和返工率。如果 Agent 在步骤三的执行中发现需要返回步骤二补充操作这里应当记录一次“返工事件”。这个事件对规划质量评估非常关键。5.5 步骤五结果分析读取所有轨迹记录汇总成表格计算规划指标。分析可以分为两层单次任务分析看这次协作是否顺利多次任务分析看整体模式下哪类规划偏差最频繁。TraceML 的价值在多层分析单次只能形成假设多次才能验证规律。6. 完整示例代码实现下面提供一套最小可运行代码帮助你理解 TraceML 的实验思路。这里用规则模板模拟 Agent 规划用字典模拟人类反馈重点放在数据结构和指标计算上。6.1 定义规划数据结构文件路径tracelml/models.pyfrom dataclasses import dataclass, field from typing import List, Optional from datetime import datetime dataclass class PlanStep: step_id: str phase: str description: str status: str pending # pending / done / failed / skipped owner: str agent # agent / human / mixed started_at: Optional[str] None finished_at: Optional[str] None return_to: Optional[str] None # 如果返工返回到哪一步 dataclass class Plan: task: str steps: List[PlanStep] field(default_factorylist) created_at: str field(default_factorylambda: datetime.now().isoformat()) owner: str agent dataclass class HumanFeedback: step_id: str action: str # approve / modify / reject feedback_text: str timestamp: str field(default_factorylambda: datetime.now().isoformat())这个结构覆盖了规划的核心要素。return_to字段专门用来记录返工这在后续分析里非常有用。6.2 模拟 Agent 生成计划和人类反馈文件路径tracelml/simulate.pyimport json from .models import Plan, PlanStep, HumanFeedback def generate_initial_plan(task: str) - Plan: 这里用规则模拟 LLM Agent 自动生成计划。 真实应用中可以替换为对大模型接口的调用。 plan Plan(tasktask) plan.steps [ PlanStep(step_ids1, phasedata_exploration, description加载数据集查看字段分布和缺失值), PlanStep(step_ids2, phasedata_cleaning, description处理缺失值删除重复记录), PlanStep(step_ids3, phasefeature_engineering, description生成统计特征例如使用时长与投诉次数的比例), PlanStep(step_ids4, phasemodel_training, description使用随机森林训练基线模型), PlanStep(step_ids5, phaseevaluation, description评估模型准确率与召回率), ] return plan def apply_human_feedback(plan: Plan, feedback: HumanFeedback) - Plan: 将人类反馈应用到计划上。 approve 表示批准原步骤modify 表示替换步骤描述reject 表示删除步骤。 for idx, step in enumerate(plan.steps): if step.step_id feedback.step_id: if feedback.action modify: step.description feedback.feedback_text step.owner human elif feedback.action reject: plan.steps.pop(idx) elif feedback.action approve: step.owner human break return plan这里的模拟代码没有真实调用模型但保留了替换点。你可以在generate_initial_plan里调用大模型解析返回的 JSON并构建Plan对象。6.3 模拟执行过程并记录轨迹文件路径tracelml/executor.pyimport json from datetime import datetime from copy import deepcopy def record_plan(plan: Plan, path: str): with open(path, w, encodingutf-8) as f: json.dump([ { step_id: s.step_id, phase: s.phase, description: s.description, status: s.status, owner: s.owner, } for s in plan.steps ], f, ensure_asciiFalse, indent2) def simulate_execution(plan: Plan) - dict: 模拟执行计划并记录一次“从 s3 返工到 s2”的事件。 真实项目中这一步应该由实际执行环境触发。 logs [] for idx, step in enumerate(plan.steps): step.started_at datetime.now().isoformat() if step.step_id s3: # 假设特征工程发现数据清洗不彻底返工到 s2 step.status failed step.return_to s2 logs.append({ step_id: step.step_id, event: return_to, return_to: s2, timestamp: datetime.now().isoformat(), }) # 将 s2 置为 failed表示需要重新执行 plan.steps[idx - 1].status failed plan.steps[idx - 1].return_to s2 else: step.status done step.finished_at datetime.now().isoformat() execution_summary { total_steps: len(plan.steps), done_steps: sum(1 for s in plan.steps if s.status done), failed_steps: sum(1 for s in plan.steps if s.status failed), return_events: logs, } return execution_summary这个模拟器很简单但它说明了轨迹数据应该记录什么每步状态、时间点、返工事件。真实接入时可以把这些逻辑分布到不同的 Task 执行器里。6.4 计算 TraceML 指标文件路径tracelml/metrics.pydef compute_planning_metrics(execution_summary: dict, plan: Plan) - dict: total len(plan.steps) done execution_summary[done_steps] failed execution_summary[failed_steps] return_events execution_summary[return_events] plan_completion_rate done / total if total 0 else 0.0 human_owner_steps sum(1 for s in plan.steps if s.owner human) human_owner_ratio human_owner_steps / total if total 0 else 0.0 rework_rate len(return_events) / total if total 0 else 0.0 return { plan_completion_rate: round(plan_completion_rate, 3), human_owner_ratio: round(human_owner_ratio, 3), rework_rate: round(rework_rate, 3), return_events: return_events, }你可以把execution_summary和plan对象传入得到一组结果。在此基础上还可以扩展“规划偏差”“干预频次”等指标但上面三个已经足够启动一个小型实验。6.5 主流程启动文件文件路径tracelml/main.pyfrom .models import HumanFeedback from .simulate import generate_initial_plan, apply_human_feedback from .executor import record_plan, simulate_execution from .metrics import compute_planning_metrics def run_experiment(): task 客户流失预测模型开发 plan generate_initial_plan(task) # 人类反馈修改模型训练步骤 feedback HumanFeedback( step_ids4, actionmodify, feedback_text同时训练逻辑回归和随机森林并用 5 折交叉验证比较, ) plan apply_human_feedback(plan, feedback) record_plan(plan, experiments/initial_plan.json) summary simulate_execution(plan) metrics compute_planning_metrics(summary, plan) print(metrics) if __name__ __main__: run_experiment()运行方式cd tracelml python -m tracelml.main如果你的项目结构不同只要保证 Python 能找到包路径即可。7. 运行结果与效果验证运行上面代码后预期会输出类似如下的指标{ plan_completion_rate: 0.8, human_owner_ratio: 0.2, rework_rate: 0.2, return_events: [ { step_id: s3, event: return_to, return_to: s2, timestamp: 2025-01-01T12:00:00.123456 } ] }从结果可以看出计划完成率是 80%因为 s2 和 s3 各自因为返工被标记为 failed。人类负责人占比 20%表示五个步骤中有一个步骤被人类修改。返工率 20%说明五个步骤里发生了一次返工。这些数字在一两次运行中意义不大但如果多次运行并汇总就能看出 Agent 在哪个环节最容易引发返工。如何判断实验是否成功第一轨迹文件是否完整生成了experiments/initial_plan.json第二指标输出是否符合预期第三返工事件是否被正确捕获。如果你在模拟执行里改变了返工逻辑指标也应该相应变化这样才能证明追踪链路是通的。如果运行失败建议先做三件事检查tracelml目录下是否缺少__init__.py文件导致包无法导入检查 Python 版本dataclasses在 Python 3.7 可用但本文示例在 3.10 环境验证更稳妥检查当前工作目录确认experiments目录存在否则写文件会报错。8. 常见问题与排查思路问题现象可能原因排查方式解决方案生成的计划步骤太多难以落地提示词中缺少对步骤数量和粒度的约束查看 Agent 原始输出统计步骤数在提示词中明确“步骤数不超过 10 步每步描述包含产出物”人类反馈没有被记录到最终计划反馈应用逻辑只修改了对象副本检查内存中 plan 对象的 id 是否一致使用不可变结构或深拷贝确保反馈后返回新计划轨迹数据没有时间戳无法统计耗时日志字段设计时遗漏 started_at / finished_at查看执行器代码在每步 start 和 finish 时写入当前时间同一实验多次运行结果不一致实验包含随机种子未固定检查数据划分和模型训练部分固定随机种子或记录每次运行的环境信息开发模式服务被误用于生产使用 Flask 等自带开发服务器部署检查服务启动命令生产环境使用正式 Web 服务器并关闭 debug 模式这里的“开发服务器”警告值得多说一句。如果你在实验里用 Flask 写了一个追踪面板只用于本地查看轨迹那么app.run()默认启动的是开发服务器。开发服务器不适合生产部署不是因为功能弱而是因为它在设计上优先考虑开发调试性能和安全性都没有针对生产环境优化。在团队协作时建议把轨迹分析面板放到内网测试环境并用正式 WSGI 服务器启动。另一个常见问题是缺少反馈原因记录。只记录“人类修改了某一步”不记录“为什么修改”后续分析会很难深入。建议在反馈数据结构中增加reason字段即使一开始只是自由文本也能在归纳分析时提供重要线索。9. 最佳实践与工程建议9.1 明确人机分工避免全自动Agent 的最大风险不是“能力不足”而是“方向不对时跑得太快”。在 ML 开发中涉及数据理解、特征合理性、业务逻辑判断的节点都应该设置为人工确认点。例如数据探索完成后的“是否清洗”、特征工程完成后的“特征是否都来自训练时可得的信息”、模型训练后的“指标是否满足业务要求”。这些节点如果不加设防Agent 可能会一路带着偏差跑到底。9.2 把规划轨迹当作实验数据管理很多团队记录了 model artifact、metrics、config但忘记了记录“Planning Process”。TraceML 的工程实践之一是把计划、反馈、执行日志、评估结果一起纳入版本管理。这样任何一次实验的复现都不仅仅是复现代码而是复现整个决策过程。建议每条轨迹都包含任务定义原文Agent 初始计划人类反馈的每一步修改和原因实际执行日志最终评估结果。9.3 从失败轨迹中学习成功轨迹只能告诉你“哪条路走通了”失败轨迹才能告诉你“哪里容易走偏”。在建设团队内部 Agent 应用时不要只收集成功的案例。那些导致返工、延误、数据泄漏的问题轨迹价值往往更高。定期复盘时优先看返工率最高的阶段。9.4 小步实验建立基线不要一开始就想建设完整的人机协同平台。可以先挑一个高频重复的 ML 任务搭建最小轨迹记录计算几项基础指标跑三到五轮实验形成基线。之后再逐步增加反馈类型、优化提示词、调整人工确认点。这样可以避免“为了分析而分析”的过度设计。9.5 注意安全与合规边界在真实业务数据上做实验时要遵守最小权限原则。不要因为 Agent 需要“查看数据”就把生产库的完整访问权限交给它。建议使用脱敏数据集或样本数据调试流程正式实验前经过审批。涉及用户信息的数据要避免写入明文日志。轨迹记录中如果包含敏感字段应做脱敏处理后再存储。9.6 让反馈机制更轻量人类反馈如果过于复杂会降低开发者使用意愿。如果每次修改都需要填写长表单很快就没人愿意干预 Agent 了。最低成本的反馈是允许直接用自然语言修改某一步甚至允许“合并两步”“复制一步再改”。反馈越轻量轨迹越完整后续分析越有价值。10. 总结与后续学习方向TraceML 本质上是一种视角转换不再只盯着模型的最终表现而是把人和 Agent 共同完成 ML 开发任务的过程当作研究对象。它的核心是“可追踪、可度量、可回放”。只要能把计划生成、人类反馈、执行状态和返工事件记录下来就已经进入了 TraceML 的实践轨道。下一步你可以从三个方向深入。第一研究可解释规划如何让 Agent 在生成步骤时同时输出“为什么这样做”辅助人类更快做出审批决策。第二动态规划当执行结果与预期不一致时Agent 如何重新规划而不是继续一条路走到黑。第三构建轨迹数据集把多次实验的轨迹整理成标准格式用于训练更擅长协作的 Agent 模型。在实际项目中不用一开始就追求大而全。我的建议是从小处开始给自己的下一个 ML 任务加一个简单日志记录下你什么时候决定修改 Agent 的计划、为什么修改以及修改后结果是否变好了。这种“先记录再优化”的思路远比相信感觉更可靠。
