Data-Juicer 智能体轨迹连贯性评估：agent_trace_coherence

人工智能
大模型
数据工程
数据清洗
数据增强
数据质检

【免费下载链接】data-juicer

Data processing for and with foundation models! 🍎 🍋 🌽 ➡️ ➡️🍸 🍹 🍷

项目地址：https://gitcode.com/gh_mirrors/da/data-juicer

本文基于仓库文档 agent_trace_coherence_mapper 算子说明，并结合其源码实现、单元测试与真实配置示例，系统讲解 Data-Juicer 中该 LLM 评估算子的定位、参数、工作原理与实战用法。

agent_trace_coherence_mapper是 Data-Juicer 中面向Agent 交互日志的 LLM 评估类 mapper 算子，用于对展平后的会话轨迹text进行1–5 分的连贯性打分（聚焦目标、少有偏题），并将score、reason、eval_kind写入样本的meta字段。它通常与agent_dialog_normalize_mapper等算子搭配，构成 Agent 数据质检流水线中“轨迹质量”维度的关键一环。读完本文，你将掌握该算子的全部参数语义、底层评分流程、输出元数据格式，以及如何在真实配置中启用并验证它。

算子定位：评估什么、在什么场景使用

依据文档与源码 agent_trace_coherence_mapper.py，该算子属于mapper类型，标签为cpu, api, text——即纯 CPU 推理编排、依赖外部 LLM API、作用于文本字段。

其核心职责是：

Coherence of the flattened sessiontext(goal focus, few detours). 展平后的会话text的连贯性（聚焦目标，少有偏题）。

也就是说，它评判的是一整段 Agent 会话轨迹（而非单轮对话）是否始终围绕用户目标推进：目标是否清晰、是否频繁绕路/偏题、是否在合理推进子目标。其设计灵感来自 OpenJudge 的 trajectory 风格评测（源码 docstring 中注明了参考TrajectoryAccuracyGrader，但 Data-Juicer 统一采用 1–5 分制，并对摘录长度做了封顶截断）。

典型应用场景：

Agent 数据质量筛选：在 Agent 交互日志数据集中，把轨迹连贯性作为质量轴，配合阈值过滤低质量样本；
Bad-case 归因分析：将分数写入meta后，可与 demos/agent 中的 bad-case 报告、洞察分析流程联动，定位“偏题/兜圈子”类问题；
数据洞察与可视化：与其他dialog_*评分轴一同构成 Agent 交互质量的量化画像。

输入与输出约定

输入字段

算子默认读取样本的text字段（由text_key指定），该字段应为已展平的会话轨迹文本。最直接的来源是前置算子agent_dialog_normalize_mapper（见 agent_dialog_normalize_mapper.py），它会把原始messages/choices结构归一化为text、dialog_history、query、response四个字段，其中text即“用户/助手交替的扁平化会话文本”，可能包含工具调用摘要与工具结果。

输出：写入 meta 的评分对象

算子为每个样本执行一次 LLM API 调用，然后把结果写入meta[MetaKeys.agent_trace_coherence]，即meta["agent_trace_coherence"]（键名定义见 constant.py）。写入对象包含：

字段	说明
`score`	1–5 的浮点分数（越高效用越好）
`reason`	简短理由（默认英文，可通过`preferred_output_lang`切换为简体中文，最长 2000 字符）
`eval_kind`	固定为`"agent_trace"`，标识该评分属于轨迹评估轴

特殊情况下还会写入：

输入为空文本：{"skipped": True, "reason": "empty_input"}
LLM 连续多次返回空响应：{"error": "empty_llm_response"}
无法解析出合法 JSON：{"error": "json_parse_failed", "raw": raw[:8000]}

（以上逻辑见基类 dialog_quality_llm_base.py 的process_single。）

参数配置详解

原文档列出的全部参数如下表，下面结合源码逐一说明语义与注意事项（基类实现见 dialog_quality_llm_base.py）：

name 参数名	type 类型	default 默认值	desc 说明
`api_model`	str	`'qwen-turbo'`	调用的 LLM 模型名，通过`prepare_model(model_type="api", ...)`注册 API 模型
`api_endpoint`	Optional[str]	`None`	自定义 API endpoint；为空时使用`api_model`对应的默认服务地址
`response_path`	Optional[str]	`None`	从 API 返回结构中提取文本的路径（适配不同厂商的响应格式）
`history_key`	str	`'dialog_history'`	对话历史字段名（本算子为轨迹评估，该字段主要用于与同类算子保持一致的接口约定）
`query_key`	str	`'query'`	最后一轮用户消息字段名
`response_key`	str	`'response'`	最后一轮助手回复字段名
`text_key`	str	`'text'`	本算子实际打分的展平会话字段名
`max_round`	NonNegativeInt	`8`	参与评估的最大对话轮数（供轮级评估用，本算子主要受`trajectory_text_max_chars`约束）
`max_query_chars_for_prompt`	NonNegativeInt	`6000`	单条用户消息进 prompt 的最大字符数
`max_response_chars_for_prompt`	NonNegativeInt	`8000`	单条助手回复进 prompt 的最大字符数
`trajectory_text_max_chars`	NonNegativeInt	`12000`	轨迹文本进 prompt 的最大字符数，超过则截断，是控制该算子 token 开销的核心参数
`tool_types_key`	str	`'agent_tool_types'`	工具类型列表在 meta 中的键名（工具相关性评估用）
`primary_tool_key`	str	`'primary_tool_type'`	主要工具类型在 meta 中的键名（工具相关性评估用）
`try_num`	PositiveInt	`2`	API 调用的最大尝试次数；某次返回空串即重试
`overwrite`	bool	`False`	为`True`时即使`meta`中已有该键也重新评估；默认保留已有结果
`model_params`	Optional[Dict]	`None`	传给`prepare_model`的额外模型参数（如密钥配置、额外 header 等）
`sampling_params`	Optional[Dict]	`None`	采样参数；未指定时默认`{"max_tokens": 384, "temperature": 0.2}`，也可显式覆盖
`preferred_output_lang`	str	`'en'`	`reason`输出语言：`'en'`输出英文，`'zh'`（或`'zh-CN'`等 zh 前缀）输出简体中文；JSON 键名始终为英文
`kwargs`	``	透传给基类 Mapper 的其它关键字参数

要点解读：

trajectory_text_max_chars是成本与质量的平衡点：轨迹越长信息越全，但 token 开销越大。真实配置中常下调，例如 agent_interaction_quality_analysis.yaml 中设置为10000。
sampling_params默认低温度：基类会setdefault("max_tokens", 384)与setdefault("temperature", 0.2)，保证评分输出的稳定性；配置示例中也常显式给出{ max_tokens: 320, temperature: 0.15 }。
overwrite用于重复实验：流水线断点续跑时，若某样本meta已含agent_trace_coherence，默认直接跳过，避免重复烧钱；需要强制重评时置True。
语言参数只影响自由文本：由 agent_output_locale.py 可知，无论preferred_output_lang取值如何，要求 LLM 输出的 JSON键名（score/reason）始终保持英文以利于解析，仅reason的书写语言随设置切换。

工作原理：评分标准与提示词构造

1–5 分评分标准（系统提示词）

源码中_system_prompt()（agent_trace_coherence_mapper.py）定义了如下评分标准，直接透传给 LLM：

5 分：轨迹紧密贴合、清晰服务于用户目标；
3 分：完成了任务，但存在冗余或轻微偏离；
1 分：严重偏题、原地打转，或未能推进合理的子目标；
截断补偿规则：如果摘录看起来被截断或不完整，默认给出4–5 分（除非看到明确的不连贯证据），并在reason中说明；不能仅因为信息缺失就给 3 分。

这条“截断补偿”规则是该算子的关键设计：由于输入是有限长度摘录，LLM 不应因“看不到后续内容”而误判为低质量。

用户内容构造

_build_user_content()调用工具函数build_agent_trace_eval_user_content（见 dialog_quality_llm_utils.py）：

读取sample[text_key]，若非字符串或空白则返回空串（触发skipped分支）；
超过max_chars（即trajectory_text_max_chars）时调用clip_text_for_dialog_prompt做截断，并标注"text truncated"；
最终 prompt 用户块格式为：

### Session trace excerpt (may include tool output) <截断后的会话轨迹文本>

完整调用链

基类process_single（dialog_quality_llm_base.py）的执行流程：

若not overwrite且meta已有目标键 → 直接返回样本；
构造用户块；为空则写skipped；
拼接系统提示词 =_system_prompt()+ JSON 输出指令（dialog_score_json_instruction）+ 语言约束子句（rubric_reason_language_clause）；
通过get_model(self.model_key, rank=rank)拿到客户端，最多尝试try_num次调用；
extract_json_object从回复中提取{...}并json.loads（兼容 ```json 代码围栏，见 dialog_quality_llm_utils.py）；
normalize_score_1_5将分数强制钳位到[1.0, 5.0]、reason截断到 2000 字符，并写入eval_kind = "agent_trace"；
写回meta[agent_trace_coherence]。

值得注意：该算子被同时注册到TAGGING_OPS与OPERATORS两个注册表（装饰器@TAGGING_OPS.register_module(OP_NAME)、@OPERATORS.register_module(OP_NAME)），因此既可当作普通 mapper 执行，也可参与 tagging 类流程。

在真实流水线中的用法与配置示例

最小可运行链路

Agent 轨迹评估通常的链路是：agent_dialog_normalize_mapper（把原始 messages 展平成text）→agent_trace_coherence_mapper（评分）。参考 minimal_configs/06_one_dialog_mapper.yaml 的 normalize 写法：

project_name: agent-minimal-06 dataset_path: demos/local/demo-agent-data-content.jsonl np: 2 export_path: ./outputs/agent_minimal/06_one_dialog_mapper.jsonl text_keys: "id" process: - agent_dialog_normalize_mapper: messages_key: "messages" choices_key: "response_choices" text_key: "text" history_key: "dialog_history" query_key: "query" response_key: "response" extract_tool_skill_tags: true

官方示例中的轨迹连贯性配置

在 demos/agent/agent_interaction_quality_analysis.yaml 中，该算子与dialog_coreference_mapper、dialog_topic_shift_mapper、agent_tool_relevance_mapper等一组质量轴并列配置：

- agent_trace_coherence_mapper: api_model: "qwen-turbo" preferred_output_lang: zh trajectory_text_max_chars: 10000 try_num: 2 sampling_params: { max_tokens: 320, temperature: 0.15 } text_key: "text"

运行方式与 Data-Juicer 其它流水线一致，例如通过 tools/process_data.py 执行--config指向上述 YAML 即可。输出样本的meta中会出现"agent_trace_coherence": {"score": x, "reason": "...", "eval_kind": "agent_trace"}，后续可被llm_analysis_filter、bad-case 信号分析等下游算子消费（参见 demos/agent/scripts/bad_case_signal_support.py 中对agent_trace_coherence键的引用）。

测试验证

仓库单元测试 tests/ops/mapper/test_dialog_quality_llm.py 覆盖了该算子的核心行为：

test_agent_trace_coherence_mapper：mock LLM 客户端返回{"score": 4, "reason": "ok"}，断言process_single后meta[agent_trace_coherence]的score == 4.0、eval_kind == "agent_trace"，验证“评分写入 meta”的主链路；
test_agent_trace_skips_empty_text：对text为空白字符串的样本，断言 meta 中写入skipped，验证空输入短路逻辑；
同一测试文件还验证了分数归一化（normalize_score_1_5将 10 钳位为 5.0）与 JSON 提取（extract_json_object）等底层工具函数。

这些测试可在本地通过pytest tests/ops/mapper/test_dialog_quality_llm.py运行复现。

实践建议与注意事项

务必先做 normalize：text必须是展平的完整会话轨迹，否则评分对象缺失。agent_dialog_normalize_mapper会把同一用户回合内的多段 assistant（含 tool 调用摘要与 tool 结果）拼接保留，避免下游只见最后一段助手回复而误判“没干活/偏题”（见 demos/agent/BAD_CASE_INSIGHTS_ZH.md 的说明）。
合理设置trajectory_text_max_chars：默认 12000 字符；实际项目中可依据轨迹平均长度与成本预算下调（官方示例用 10000）。截断不会导致误判——评分标准明确要求截断摘录偏向 4–5 分。
善用overwrite与try_num：断点续跑时保持overwrite: False避免重复调用；网络不稳时可适当提高try_num（默认 2）。
控制采样随机性：评分类任务建议保持低temperature（默认 0.2），必要时显式覆盖sampling_params。
语言参数：若下游报告面向中文团队，设preferred_output_lang: zh让reason输出简体中文，JSON 键名不受影响，解析逻辑无需改动。
分数语义：score是 1–5 的连续浮点（模型输出整数也会被规范化），与dialog_*各质量轴口径一致，可统一用于阈值过滤与群体对比。