Agent 交互数据：Bad case 洞察#

从哪里读起：命令与排障 → [QUICKSTART_BAD_CASE.md](QUICKSTART_BAD_CASE.md)；仅 HTML 报告 → [BAD_CASE_REPORT.md](BAD_CASE_REPORT.md)；脚本参数 → [scripts/README.md](scripts/README.md)。总索引见 [README.md](README.md)。

Overview#

本文档对应数据菜谱 agent_interaction_quality_analysis.yaml：

  • 目标：基于交互数据，为模型和Agent（e.g.meta.agent_request_model）」产出分层可溯源线索及洞察

  • LLM 输出语言：各算子支持 kwargs preferred_output_lang: zh | en（实现见 data_juicer/utils/agent_output_locale.py）。全量菜谱默认 zh 以统一中文理由/说明；改英文流水线时在各 LLM 块改为 en 即可。第 10 步 insight 会将语言写入 meta.agent_pipeline_output_lang，供 generate_bad_case_report.py --report-lang auto 推断页面分档展示语言。

  • 第 9 步 agent_bad_case_signal_mapper：多源确定性信号 + 保守分层。

  • 第 10 步 agent_insight_llm_mapper（可选）：把数值 stats 与各类 LLM 评估文本二次综合成可解释 JSON（便于看板与人工质检）。

  • 覆盖隐私、agent能力、环境/工具交互、模型回复质量、任务成功率、用户满意度等信号，近40个DataJuicer算子

类别

算子数

核心功能

数据规范化

1

多格式 Agent 数据结构化（messages/choices → text/dialog_history/query/response）、血缘字段写入、工具技能标签提取、超长内容截断

PII 处理

2

规则层脱敏（路径/邮件/密钥/ID/手机/身份证/OpenID 等）+ LLM 嫌疑复核，保留可溯源证据 供审计

通用文本清洗

2

HTML 标签去除、版权声明清理

对话属性打标

4

（LLM辅助）意图识别、情感极性、话题分类、情感强度

模型用量与工具标签

4

token 用量统计、工具调用成功/失败统计、主工具类型归纳（top-k）、工具/技能洞察短语生成（LLM）

对话末轮 / 轨迹质检

9

（LLM辅助）记忆一致性、指代消解、话题漂移、错误恢复、澄清提问质量、主动性、去重复性、Agent 轨迹连贯性、工具-任务相关性

通用文本质量统计

10

文本长度、词数、语言置信度、字符重复率、词级重复率、特殊字符比率、停用词比率、字母数字比率、文本动作数、最大行长

LLM综合评分

3

回复质量四维 (准确性/语法/信息量/连贯性)、Agent 场景四维 (指令遵循/回复质量/有用性/安全性)、难度评估等

Bad case 分层

1

多信号融合保守分层（high_precision / watchlist / none），无额外 LLM 调用，基于上游 Meta 打标

LLM 可解释总览

1

对强怀疑/待观察样本自动生成自然语言根因洞察，写入 Insight 卡片供报告展示

Agent 对话形态：多段 assistant 与 tool#

智能体数据不是严格的「user → assistant → user → assistant」一轮一轮交替：

  • 常见模式：user → 若干次 (assistant + tool_calls) → tool → assistant → tool → … → 最终 assistant 文本或下一轮 user。

  • **agent_dialog_normalize_mapper** 将 messages 压成 dialog_history / query / response / text 时，对同一 user 回合内多段 assistant 必须拼接保留（含 tool summary）；可选 **history_*_max_chars** 对 tool/助手侧做首尾保留 + 明确的中段省略标记写回（与仅 prompt 截断不同），并打 **meta.agent_dialog_history_compressed。否则下游 **llm_quality_score_filter / llm_analysis_filter 只看到最后一次助手片段，容易误判「没干活」或「偏题」。

  • **tool_success_tagger_mapper** 按 每条 role=tool 消息计数；failed / No such file 等会记 fail。在探索性策略里单次失败可能随后被纠正——第 9 步提供 **min_tool_fail_count_for_signal（默认 1；菜谱可调到 2+）再抬 tool_message_error_pattern，并与 **meta.tool_unknown_count（无法-regex 分类的 tool 行）一起看。

  • Dialog 打标算子（意图/情感/主题/强度）在内存里用 build_dialog_turns_for_prompt 合并 dialog_history 与 query/response，不原地修改 dialog_history；末轮与 normalize 一致时不重复追加，避免历史被污染、API 轮次翻倍。

数据血缘字段（normalize 自动写入）#

原始字段

meta 键

用途

request_model

agent_request_model

按模型 cohort 分层、A/B

pt

agent_pt

同一时间桶 / 版本窗对比

total_cost_time

agent_total_cost_time_ms

与 token 等一起看「贵不贵」

Upstream 信号覆盖（第 9 步尽量吃满 pipeline）#

agent_bad_case_signal_mapper 在样本上读取（有则参与，无则跳过）：

来源

字段

默认行为

tool_success_tagger_mapper

tool_fail_count

high：tool_message_error_pattern（需 fail ≥ min_tool_fail_count_for_signal）

同上

tool_unknown_count

不参与 ratio；供排查「工具返回非典型文本/JSON」

同上

tool_success_ratio + 轮次数

medium：比例过低（≥min_tool_rounds_for_ratio_signal 轮；分母不含 unknown）

usage_counter_mapper

total_tokens 等

默认对相同 (prompt, completion, total) 快照去重后再汇总，避免 response_usage 与 choices[].usage 重复；可选绝对阈值 → medium

normalize 血缘

agent_total_cost_time_ms

可选绝对阈值 → medium

llm_analysis_filter

llm_analysis_score + llm_analysis_record.recommendation

discard + 低分 → high/medium（可 *_discard_must_be_strict）

llm_quality_score_filter

llm_quality_score + llm_quality_record

同上，信号码 llm_reply_quality_eval_low

dialog_sentiment_detection_mapper

dialog_sentiment_labels

signal_on_negative_sentiment_hint 开启时 → medium（易噪，报告里归「附录」类）

perplexity_filter + stats.perplexity

stats.perplexity

可选：KenLM；默认菜谱为关闭状态 filter + signal_on_high_perplexity: false

llm_difficulty_score_filter + quality

difficulty + llm_quality_score

默认关；signal_hard_query_poor_reply → medium

§5b 对话/轨迹质检算子

meta 中各 dialog_*、agent_trace_coherence、agent_tool_relevance（1–5）

signal_on_low_dialog_quality_meta：任一条目 score ≤ threshold 的轴数达标 → medium：dialog_turn_quality_meta_low（读已有 meta，无额外 LLM）

文本

query / response

长 query + 极短回复 → medium

分层：

  • **meta.agent_bad_case_signals**：{code, detail, weight}。

  • **meta.agent_bad_case_tier**（机器枚举，jq 仍用英文）：high_precision | watchlist | none。

    • 报告中译为 强怀疑（主证据） / 待观察（弱证据） / 未标记；**high_precision 不是「模型精度高」**，而是「强怀疑、建议优先复核」。

    • 长 agent 轨迹易出现 多次 tool 返回含 error 模式：若 **high_precision_on_tool_fail_alone: false（全量菜谱默认），仅凭 tool 计数不会单独升强怀疑档；可调 **min_tool_fail_count_for_signal 控制何时打出 tool 信号。

YAML 中请将 **llm_analysis_discard_must_be_strict** / **llm_text_quality_discard_must_be_strict** 保持为 true，避免把 review 当坏样本。

第 10 步：agent_insight_llm_mapper（auto-analyst）#

把一条样本打包为 JSON（token、工具、意图/主题/情感标签、三路 LLM eval 摘要、**dialog_quality_llm（§5b 各轴 1–5 分与短 reason 摘要）、agent_bad_case_*、query/response 截断预览），调用 API 模型输出严格 JSON**：

  • headline：一句话中文总览（适合卡片）

  • root_causes：factor + confidence + cited_fields（必须来自输入 JSON 的键路径）+ rationale_one_line

  • narrative_alignment：数值与文字 rationales 是否一致

  • human_review_priority：P0–P3

  • viz_facets：建议切片维度

写入 **meta.agent_insight_llm；解析失败时仍有占位结构，原文在 **meta.agent_insight_llm_raw。

成本控制：菜谱默认 run_for_tiers: [high_precision, watchlist]；要对全量跑可删掉该字段（等价于 null = 全部）。

为何不强依赖「用户不满意」单一视角#

  1. 硬证据优先：工具 error 模式、tool_fail_count。

  2. LLM 评估：discard + 极低分才抬 high_precision。

  3. 成本 / 长尾：用 demos/agent/scripts/compute_percentile_thresholds.py 算 P90/P95；可 **--write-calibration** 生成 JSON，在 agent_bad_case_signal_mapper 中设 **auto_calibrate_thresholds: true** 与 **calibration_json_path**，按 meta.agent_request_model 自动合并 default 与 by_request_model 的阈值（token / 延迟 / perplexity）。默认 **calibration_manual_overrides_auto: true**：YAML 里显式写的 max_* / perplexity 仍优先于文件；设为 false 则优先用校准文件。

深挖思路（按 model / pt）#

  • 跨模型：同一意图桶、同一工具族，对比 llm_analysis_score、llm_quality_score、token、tool 失败率。

  • 跨 pt：同一模型下看 P50/P90 与 high_precision 占比漂移。

  • 组合：优先 AND 多条独立证据。

Pipeline 之后的分析脚本#

见 **demos/agent/scripts/README.md**：

  • compute_percentile_thresholds.py：分位数报告；--write-calibration → 自动阈值 JSON。

  • analyze_bad_case_cohorts.py：按 model / pt / tier 汇总并可选 CSV。

  • slice_export_by_tier.py：按 tier（及可选 model）导出子集 jsonl。

jq 快速筛选#

Data-Juicer 导出里 **meta 字段名为 __dj__meta__（见 data_juicer.utils.constant.Fields）。若配置 **keep_stats_in_res_ds: true（本仓库 agent 菜谱已默认），主 processed.jsonl 每行自带该字段；否则 meta 仅在同级 **processed_stats.jsonl**，可用 demos/agent/scripts/dj_export_row.py 的合并逻辑或后处理脚本（verify / analyze / slice / compute_percentile 已自动按行合并 _stats 文件）。

jq 'select(."__dj__meta__".agent_bad_case_tier=="high_precision" and ."__dj__meta__".agent_request_model=="qwen3-max")' processed.jsonl | head
jq -c '."__dj__meta__".agent_insight_llm.headline, ."__dj__meta__".agent_bad_case_signals' processed.jsonl | head

相关算子#

  • tool_success_tagger_mapper、usage_counter_mapper

  • llm_analysis_filter、llm_quality_score_filter、llm_difficulty_score_filter

  • agent_bad_case_signal_mapper、agent_insight_llm_mapper

若需 按 session 聚合 再判坏，请在数据中带 session_id 并在分析脚本中 groupby；当前算子为逐条样本。

维护 / 合入上游：pre-commit、docs/Operators.md、归因表与单测清单见 [README.md](README.md) 中的 「合入 main 前（维护者速查）」。