武阳
730 lines
17 KiB
Markdown
730 lines
17 KiB
Markdown
下面是中文翻译：
|
||
|
||
# Data Agent 新工具提案
|
||
|
||
本文档列出了 data-agent 改造中建议新增的工具。范围刻意聚焦在第一阶段实现：数据 schema、生成、校验、格式转换、评审，以及后续在线挖掘。
|
||
|
||
## 设计原则
|
||
|
||
* 优先使用窄口径的数据工具，而不是通用 shell、SQL 或临时代码。
|
||
* 工具应该稳定数据格式和可重复操作。
|
||
* 开放式推理、聚类解释和生成策略可以保留在 Agent loop 中；工具负责提供结构化输入、校验和可重复转换。
|
||
* 每个工具都应该返回机器可读的 metadata，以及人类可读的摘要。
|
||
* 生成的数据集必须在导出或持久化前完成校验。
|
||
|
||
## 优先级
|
||
|
||
* `P0`：短期立即实现所必需。
|
||
* `P1`：很快需要，但可以在第一条 schema / 生成链路跑通后再加。
|
||
* `P2`：用于在线挖掘或生产级加固。
|
||
|
||
# P0：数据集 Schema 与格式工具
|
||
|
||
这些是基础工具，避免 Agent 手写脆弱的格式转换逻辑。
|
||
|
||
数据格式设计分两层：
|
||
|
||
1. **标准数据记录层**：验证数据要素是否完整。该层回答一个 record 是否具备所需的对话轮次、`query`、`tts` 和最终 label。数据生成和在线挖掘工具应该直接产出这一标准层，或者在进一步使用前先 normalize 到这一层。
|
||
2. **导出格式层**：把标准 records 转换成固定的下游格式。一旦标准 metadata 格式稳定，转换到 training JSONL、prompt/eval CSV、review tables、display markdown 和其他消费格式，就应该成为确定性的工具逻辑。
|
||
|
||
实际规则是：
|
||
|
||
```text
|
||
generation/mining output
|
||
-> canonical records
|
||
-> validation
|
||
-> dedup/review
|
||
-> deterministic exports
|
||
```
|
||
|
||
Agent 应该负责理解数据意图和编写计划，但 schema 校验和格式转换应该由工具负责。
|
||
|
||
## 标准 Record 层
|
||
|
||
这一层定义生成或挖掘数据的内部事实源。第一版应该足够严格，避免缺失关键元素；同时也要足够灵活，以支持单轮和多轮对话。
|
||
|
||
建议的标准 record 结构：
|
||
|
||
```json
|
||
{
|
||
"record_id": "optional-stable-id",
|
||
"conversation": [
|
||
{
|
||
"query": "...",
|
||
"tts": "...",
|
||
"metadata": {}
|
||
}
|
||
],
|
||
"label": {
|
||
"type": "function_or_agent",
|
||
"name": "...",
|
||
"arguments": {}
|
||
},
|
||
"source": {
|
||
"type": "generated|mined|eval_error|manual",
|
||
"task_id": "...",
|
||
"notes": "..."
|
||
},
|
||
"metadata": {}
|
||
}
|
||
```
|
||
|
||
待确认的 schema 问题：
|
||
|
||
* `tts` 是否应该每一轮都必填？还是当源数据没有 TTS 时可以为空？
|
||
* label type 是否应该标准化为 `function` 和 `agent` 这样的 enum？
|
||
* label arguments 应该是必填、可选，还是由目标格式决定？
|
||
* record-level metadata 是否应该包含 model version、device、date、source table、mining strategy、reviewer decision 等信息？
|
||
|
||
## `validate_dataset_records`
|
||
|
||
用途：校验 records 是否符合标准数据 schema。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"input_path": "artifacts/candidates.jsonl",
|
||
"schema_name": "router_conversation_v1",
|
||
"max_errors": 50
|
||
}
|
||
```
|
||
|
||
建议输出：
|
||
|
||
```json
|
||
{
|
||
"valid": true,
|
||
"record_count": 120,
|
||
"error_count": 0,
|
||
"errors": []
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 检查多轮对话、`query`、`tts`、最终 `label` 等必填字段。
|
||
* 应同时支持单轮和多轮 records。
|
||
* 应在生成 / 挖掘之后运行，并在 dedup、export 或 persistence 之前运行。
|
||
* 这是完整性和结构校验，不是下游格式校验。
|
||
|
||
## `normalize_dataset_records`
|
||
|
||
用途：把历史数据、生成数据、挖掘数据或 eval result 中略有差异的 record 形态转换成标准 record schema。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"input_path": "context/raw_cases.csv",
|
||
"output_path": "artifacts/normalized_cases.jsonl",
|
||
"source_format": "auto",
|
||
"schema_name": "router_conversation_v1",
|
||
"field_mapping": {
|
||
"query": "query",
|
||
"tts": "tts",
|
||
"label": "correct_label"
|
||
}
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 现有 eval 文件、文档和表格可能存在格式差异，因此这个工具有用。
|
||
* 不应该过度猜测。如果必填字段含义不明确，应返回 mapping error，让 Agent 向用户确认。
|
||
* 对于在线挖掘，挖掘工具最好直接输出标准 records。这个 normalizer 主要适合 legacy 文件和用户提供的表格。
|
||
|
||
## `generate_record_ids`
|
||
|
||
用途：为标准 records 填充稳定的 `record_id`。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"input_path": "artifacts/normalized_cases.jsonl",
|
||
"output_path": "artifacts/normalized_cases.with_ids.jsonl",
|
||
"id_strategy": "hash"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 稳定 ID 会让 review、dedup、export manifest 和 git diff 更容易处理。
|
||
* 默认策略可以对标准化后的 conversation 和 label 做 hash。
|
||
|
||
# 数据集质量层
|
||
|
||
这些工具在导出前作用于标准 records。
|
||
|
||
## `dedup_dataset_records`
|
||
|
||
用途：导出前删除或标记重复、近重复 records。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"input_path": "artifacts/eval_candidates.jsonl",
|
||
"output_path": "artifacts/eval_candidates_deduped.jsonl",
|
||
"keys": ["conversation.query", "label.name"],
|
||
"mode": "flag"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 在 eval set 中，重复样本会抬高指标，或让专项集看起来比实际更大。
|
||
* 在 training set 中，重复样本可能会无意中加重某种 pattern 的权重。
|
||
* MVP 可以先从精确重复检测开始。近重复检测可以放到 P1 / P2。
|
||
* `mode="flag"` 比直接删除更安全，因为 reviewer 可以检查哪些内容被移除了。
|
||
|
||
# 导出格式层
|
||
|
||
## `convert_dataset_format`
|
||
|
||
用途：把已校验的标准 records 转换成一个批准的下游格式。
|
||
|
||
建议格式：
|
||
|
||
```text
|
||
training_jsonl
|
||
eval_prompt_csv
|
||
review_table_csv
|
||
markdown_preview
|
||
```
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"input_path": "artifacts/eval_candidates.jsonl",
|
||
"output_path": "artifacts/eval_candidates.csv",
|
||
"target_format": "eval_prompt_csv",
|
||
"schema_name": "router_conversation_v1"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 这个工具和 validation 分开，因为不同转换目标可能有不同的列要求和布局要求。
|
||
* 它不应该改变语义内容。如果目标格式无法表达某个字段，工具应该在 metadata 中说明哪些字段被省略。
|
||
|
||
## `render_dataset_preview`
|
||
|
||
用途：把 records 渲染成人类评审用的格式。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"input_path": "artifacts/eval_candidates.jsonl",
|
||
"output_path": "artifacts/eval_candidates_preview.md",
|
||
"max_records": 50,
|
||
"group_by": "label"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* Review 格式应该对人友好，但不应被当作训练 / 评测的标准格式。
|
||
|
||
## `export_dataset`
|
||
|
||
用途：把已校验的标准 records 导出为一个或多个批准的 artifact 文件，并写入 export manifest。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"input_path": "artifacts/eval_candidates_deduped.jsonl",
|
||
"exports": [
|
||
{
|
||
"target_format": "training_jsonl",
|
||
"output_path": "artifacts/export/train.jsonl"
|
||
},
|
||
{
|
||
"target_format": "eval_prompt_csv",
|
||
"output_path": "artifacts/export/eval.csv"
|
||
},
|
||
{
|
||
"target_format": "markdown_preview",
|
||
"output_path": "artifacts/export/review.md"
|
||
}
|
||
],
|
||
"require_valid": true
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 这个工具可以在写入最终输出前内部调用 validation。
|
||
* 应生成 manifest，包含 record 数量、schema version、export paths 和 validation status。
|
||
* 这是基于确定性转换的便利性 / 编排工具。调试时，仍然可以直接调用 `convert_dataset_format`。
|
||
|
||
# P1：Eval 输入与错误分析工具
|
||
|
||
这些工具支撑任务 1：利用现有 eval errors 规划并生成针对性数据。
|
||
|
||
## `load_eval_results`
|
||
|
||
用途：从 CSV、JSONL 或类 spreadsheet 导出文件中加载 eval result，并转换成标准内部表。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"input_path": "context/eval_errors.csv",
|
||
"output_path": "artifacts/eval_results.normalized.jsonl",
|
||
"field_mapping": {
|
||
"query": "query",
|
||
"expected_label": "correct_label",
|
||
"predicted_label": "model_label"
|
||
}
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 应支持显式 field mapping。
|
||
* 可以支持 `field_mapping="auto"`，但应返回低置信度 mapping warning，而不是静默猜测。
|
||
|
||
## `profile_error_cases`
|
||
|
||
用途：从 eval errors 中产出结构化统计和切片分析。
|
||
|
||
这是比全自动聚类更安全的第一版。
|
||
|
||
建议输出：
|
||
|
||
```json
|
||
{
|
||
"total_errors": 328,
|
||
"by_expected_label": {},
|
||
"by_predicted_label": {},
|
||
"confusion_pairs": [],
|
||
"top_terms": [],
|
||
"sample_records": []
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 这个工具给 Agent 提供分析证据。
|
||
* 随后 Agent 可以写 `artifacts/error_analysis.md`。
|
||
|
||
## `cluster_error_cases`
|
||
|
||
用途：把相似错误样本分组，便于分析。
|
||
|
||
处置：`P1`，但应被视为辅助聚类，而不是最终事实。
|
||
|
||
难点：
|
||
|
||
* 输入文件格式不一致。
|
||
* 好的 cluster 经常需要人工解释。
|
||
* 之前的聚类是交互式的，这一点应该保留。
|
||
|
||
建议设计：
|
||
|
||
```json
|
||
{
|
||
"input_path": "artifacts/eval_results.normalized.jsonl",
|
||
"output_path": "artifacts/error_clusters.json",
|
||
"features": ["query", "expected_label", "predicted_label"],
|
||
"method": "heuristic",
|
||
"max_clusters": 20,
|
||
"include_examples": 10
|
||
}
|
||
```
|
||
|
||
推荐 MVP：
|
||
|
||
* 从 `profile_error_cases` 开始，再基于 confusion pair、label、keywords 或显式字段做简单分组。
|
||
* 由 Agent 在 markdown 中产出 cluster 名称和假设。
|
||
* 由人工评审、合并、拆分 clusters。
|
||
|
||
## `summarize_error_clusters`
|
||
|
||
用途：把 cluster 数据转换成人类可评审的报告。
|
||
|
||
与 `cluster_error_cases` 的关系：
|
||
|
||
* `cluster_error_cases` 创建结构化分组和代表样例。
|
||
* `summarize_error_clusters` 把这些分组转换成报告：cluster 标题、疑似根因、示例、建议的数据生成方向。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"clusters_path": "artifacts/error_clusters.json",
|
||
"output_path": "artifacts/error_cluster_summary.md"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 这个工具可能部分由 Agent 编写。工具可以渲染基础确定性报告；Agent 可以在其上补充推理。
|
||
|
||
## `create_review_packet`
|
||
|
||
用途：把分析结果打包成一个紧凑的人类评审 artifact。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"inputs": [
|
||
"artifacts/error_analysis.md",
|
||
"artifacts/error_cluster_summary.md"
|
||
],
|
||
"output_path": "artifacts/review_packet.md",
|
||
"questions_path": "memory/open_questions.md"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 在调用 `ask_user_question` 前有用。
|
||
* 可以让交互式评审始终基于文件内容展开。
|
||
|
||
# P1：数据规划与生成工具
|
||
|
||
这些工具支撑任务 1 和任务 2。
|
||
|
||
## `generate_data_plan`
|
||
|
||
用途：基于已评审的错误 clusters 或标签定义创建结构化生成计划。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"analysis_path": "artifacts/error_cluster_summary.md",
|
||
"constraints_path": "context/data_requirements.md",
|
||
"output_path": "artifacts/generation_plan.json"
|
||
}
|
||
```
|
||
|
||
建议输出形态：
|
||
|
||
```json
|
||
{
|
||
"batches": [
|
||
{
|
||
"name": "hard_negative_fast_direct",
|
||
"target_label": "SLOW_FILTER_RANK",
|
||
"count": 50,
|
||
"scenario": "...",
|
||
"requirements": [],
|
||
"negative_constraints": []
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 可以由 Agent 生成，再由工具校验。
|
||
* 短期内，这个工具可以先负责校验和规范化计划，而不是完整生成计划。
|
||
|
||
## `validate_data_plan`
|
||
|
||
用途：校验 generation plan 是否完整、可执行。
|
||
|
||
说明：
|
||
|
||
* 检查数量、标签、必填字段、schema names 和不支持的指令。
|
||
* 有助于保持交互式 plan review 稳定。
|
||
|
||
## `generate_dataset_records`
|
||
|
||
用途：根据已校验的 plan 和 data schema 生成 records。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"plan_path": "artifacts/generation_plan.json",
|
||
"output_path": "artifacts/generated_candidates.jsonl",
|
||
"schema_name": "router_conversation_v1",
|
||
"generation_mode": "llm_assisted"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 如果内部使用 LLM，工具输出仍然需要校验。
|
||
* 更简单的 MVP 是：Agent 生成候选 JSONL，然后调用 `validate_dataset_records`。
|
||
* 长期看，这个工具可以负责生成，减少格式漂移。
|
||
|
||
## `validate_label_coverage`
|
||
|
||
用途：检查生成数据是否覆盖了计划要求的 labels、scenarios 和 boundary types。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"dataset_path": "artifacts/generated_candidates.jsonl",
|
||
"plan_path": "artifacts/generation_plan.json",
|
||
"output_path": "artifacts/coverage_report.md"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 这和 schema validation 不同。
|
||
* Schema validation 问的是：“record 结构是否合法？”
|
||
* Coverage validation 问的是：“是否生成了计划中想要的数据？”
|
||
|
||
# P1：产品或标签定义工具
|
||
|
||
这些工具支撑任务 2。
|
||
|
||
## `load_definition_document`
|
||
|
||
用途：把产品或标签定义文档加载为标准 markdown / text。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"input_path": "context/product_definition.md",
|
||
"output_path": "artifacts/definition.normalized.md"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 可以支持 markdown、txt、csv，之后按需支持 docx / pdf。
|
||
|
||
## `extract_label_definition`
|
||
|
||
用途：抽取候选标签定义、正例、反例和模糊边界。
|
||
|
||
建议输出：
|
||
|
||
```json
|
||
{
|
||
"labels": [],
|
||
"positive_rules": [],
|
||
"negative_rules": [],
|
||
"ambiguous_boundaries": [],
|
||
"examples": []
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 可以由 LLM 辅助，但应输出结构化 JSON 和 markdown summary。
|
||
|
||
## `render_label_boundary_summary`
|
||
|
||
用途：基于抽取出的定义创建可评审的标签边界摘要。
|
||
|
||
建议输出：
|
||
|
||
```text
|
||
artifacts/label_boundary_summary.md
|
||
```
|
||
|
||
说明：
|
||
|
||
* 应接入 `ask_user_question` 或人工评审流程。
|
||
|
||
# P2：在线挖掘工具
|
||
|
||
这些工具支撑任务 3。应在 schema / generation 工具稳定后再添加。
|
||
|
||
## `analyze_badcases`
|
||
|
||
用途：总结输入 badcases 的共性特征。
|
||
|
||
建议输出：
|
||
|
||
* 常见 query patterns
|
||
* 涉及 labels
|
||
* 候选过滤条件
|
||
* 高风险 / 模糊字段
|
||
* 代表样例
|
||
|
||
## `build_mining_strategy`
|
||
|
||
用途：把 badcase 分析转换成结构化在线数据搜索策略。
|
||
|
||
建议输出形态：
|
||
|
||
```json
|
||
{
|
||
"filters": {
|
||
"date_range": {},
|
||
"device": [],
|
||
"agent_type": [],
|
||
"keywords": [],
|
||
"regex": [],
|
||
"domain": []
|
||
},
|
||
"sampling": {
|
||
"limit": 100,
|
||
"method": "diverse"
|
||
}
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* 大规模查询前，应支持人工评审。
|
||
|
||
## `search_online_sessions`
|
||
|
||
用途：通过受控、可审计的 filters 查询线上 sessions。
|
||
|
||
说明：
|
||
|
||
* Agent 不应该写原始 SQL。
|
||
* 工具 schema 应只暴露被批准的字段和过滤操作符。
|
||
* 敏感字段应在工具边界完成脱敏。
|
||
|
||
## `sample_online_candidates`
|
||
|
||
用途：从检索到的线上 sessions 中采样候选样本，供评审使用。
|
||
|
||
说明：
|
||
|
||
* 支持“先标注 100 条”的循环。
|
||
* 应包含确定性 sampling metadata，保证可复现。
|
||
|
||
## `create_annotation_batch`
|
||
|
||
用途：从采样候选中创建 review / annotation packet。
|
||
|
||
说明：
|
||
|
||
* MVP 可以是本地 markdown / CSV。
|
||
* 之后可以接入标注系统。
|
||
|
||
## `read_annotation_result`
|
||
|
||
用途：把人工评审结果读回 task workspace。
|
||
|
||
说明：
|
||
|
||
* 应规范化 review labels 和 comments。
|
||
|
||
## `evaluate_mining_precision`
|
||
|
||
用途：评估当前 mining strategy 的精度是否足够。
|
||
|
||
建议输出：
|
||
|
||
* 已评审数量
|
||
* 正样本数量
|
||
* Precision
|
||
* 主要误召 pattern
|
||
* 推荐的下一步过滤条件调整
|
||
|
||
## `refine_mining_strategy`
|
||
|
||
用途：根据评估结果生成修订版 mining strategy。
|
||
|
||
说明：
|
||
|
||
* 初期可以保留为 Agent 编写；工具负责校验 strategy JSON。
|
||
|
||
## `export_mined_dataset`
|
||
|
||
用途：把挖掘数据导出成 badcase set、eval set 或 training set 格式。
|
||
|
||
说明：
|
||
|
||
* 应调用或复用 validation、dedup、conversion 和 export 逻辑。
|
||
|
||
# 持久化与 Git 工具
|
||
|
||
## `persist_dataset_artifact`
|
||
|
||
用途：持久化已批准的数据集导出，并写入 manifest。
|
||
|
||
建议输入：
|
||
|
||
```json
|
||
{
|
||
"artifact_paths": [
|
||
"artifacts/export/train.jsonl",
|
||
"artifacts/export/eval.csv"
|
||
],
|
||
"manifest_path": "artifacts/export/manifest.json",
|
||
"destination": "workspace"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
* `destination="workspace"` 可作为 MVP。
|
||
* 之后 destination 可以包括对象存储、dataset registry 或内部平台。
|
||
|
||
## `prepare_dataset_git_commit`
|
||
|
||
用途：stage 已批准的数据集 artifacts，并生成 commit summary。
|
||
|
||
处置：`P1/P2`。
|
||
|
||
说明：
|
||
|
||
* 实际 git push 应需要人工确认。
|
||
* 这个工具应和 dataset export 分开。Export 负责创建文件；git persistence 负责发布或版本化。
|
||
|
||
# 建议的首批实现集合
|
||
|
||
当前短期工作建议先实现这些：
|
||
|
||
```text
|
||
validate_dataset_records
|
||
normalize_dataset_records
|
||
generate_record_ids
|
||
convert_dataset_format
|
||
render_dataset_preview
|
||
dedup_dataset_records
|
||
export_dataset
|
||
load_eval_results
|
||
profile_error_cases
|
||
validate_data_plan
|
||
persist_dataset_artifact
|
||
```
|
||
|
||
然后再添加：
|
||
|
||
```text
|
||
cluster_error_cases
|
||
summarize_error_clusters
|
||
generate_data_plan
|
||
generate_dataset_records
|
||
validate_label_coverage
|
||
load_definition_document
|
||
extract_label_definition
|
||
render_label_boundary_summary
|
||
```
|
||
|
||
最后添加在线挖掘工具：
|
||
|
||
```text
|
||
analyze_badcases
|
||
build_mining_strategy
|
||
search_online_sessions
|
||
sample_online_candidates
|
||
create_annotation_batch
|
||
read_annotation_result
|
||
evaluate_mining_precision
|
||
refine_mining_strategy
|
||
export_mined_dataset
|
||
```
|
||
|
||
# 开放问题
|
||
|
||
* 对话 records 的 canonical schema name 和 version 是什么？
|
||
* 确切接受哪些 export formats？需要哪些必填列？
|
||
* 生成 records 中的 `tts` 应该是必填、可选，还是派生字段？
|
||
* 哪些 labels 是合法的？label registry 存在哪里？
|
||
* 在线挖掘时，哪些字段允许用于过滤和导出？
|
||
* 哪些动作在持久化或 git push 前需要人工确认？ |