wehub-skill-sync
119 lines
5.7 KiB
Markdown
119 lines
5.7 KiB
Markdown
# Step 2c：捕获并验证参考 Trace
|
||
|
||
**目标**：通过 Runnable 运行应用程序，捕获一个 Trace，并验证插桩和 Runnable 正常工作。Trace 证明一切已正确连接，并为步骤 4 的数据集创建提供精确的数据结构。
|
||
|
||
---
|
||
|
||
## 选择 Trace 输入
|
||
|
||
Trace 输入决定了捕获哪些代码路径。一个简单的输入会产生一个简单的 Trace，从而错过应用程序的真实行为。
|
||
|
||
输入必须符合你在步骤 2b 中阅读的 `pixie_qa/00-project-analysis.md` 中「真实输入特征」部分的要求。
|
||
|
||
输入包含两部分——理解它们之间的边界：
|
||
|
||
- **用户提供的参数**（你编写）：真实用户键入或配置的内容——提示词、查询、配置标志、URL、模式定义。编写这些内容时应使其具有代表性，反映真实使用场景。
|
||
- **世界数据**（从生产代码中捕获，而非虚构）：应用程序在执行过程中从外部来源获取的内容——数据库记录、API 响应、文件等。运行一次生产代码以将此数据捕获到 Trace 中。仅在以下情况下才使用合成数据生成：
|
||
- 用户明确指示你使用合成数据，或者
|
||
- 从真实来源获取数据不可行（获取次数过多、产生实际金钱成本、或耗时过长——超过约 30 分钟）
|
||
|
||
**编写输入前的快速检查**：「真实用户会创建这些数据，还是应用程序会从其他地方获取它？」如果数据由应用程序获取，就让生产代码运行并捕获它。
|
||
|
||
| 应用类型 | 用户提供（你编写） | 世界提供（你获取） |
|
||
| ---------------- | ----------------------------------------- | ----------------------------------------- |
|
||
| 网页爬虫 | URL + 提示词 + 模式定义 | HTML 页面内容 |
|
||
| 研究代理 | 研究问题 + 范围约束 | 源文档、搜索结果 |
|
||
| 客服机器人 | 客户的语音消息 | CRM 中的客户资料、会话存储中的对话历史 |
|
||
| 代码审查工具 | PR URL + 审查标准 | 实际差异、文件内容、CI 结果 |
|
||
|
||
### 捕获多个 Trace
|
||
|
||
在构建数据集之前，**至少捕获 2 个**具有不同输入特征的 Trace：
|
||
|
||
- 不同的复杂度（简单情况 vs. 复杂情况）
|
||
- 不同的能力（参见 `00-project-analysis.md` 的能力清单）
|
||
- 不同的边缘条件（缺少可选数据、异常大的输入）
|
||
|
||
这种校准可以防止数据集的同质性——你能看到应用程序在处理各种输入时的实际表现。
|
||
|
||
---
|
||
|
||
## 运行 `pixie trace`
|
||
|
||
**首先**，验证应用程序可以被导入：`python -c "from <module> import <class>"`。在进入 trace-安装-重试循环之前先捕获缺失的包。
|
||
|
||
```bash
|
||
# 创建一个包含输入数据的 JSON 文件
|
||
echo '{"user_message": "一个真实的示例输入"}' > pixie_qa/sample-input.json
|
||
|
||
uv run pixie trace --runnable pixie_qa/run_app.py:AppRunnable \
|
||
--input pixie_qa/sample-input.json \
|
||
--output pixie_qa/reference-trace.jsonl
|
||
```
|
||
|
||
`--input` 标志接收一个 JSON **文件路径**（而非内联 JSON）。JSON 的键将成为 Pydantic 模型的 kwargs。
|
||
|
||
对于额外的 Trace：
|
||
|
||
```bash
|
||
uv run pixie trace --runnable pixie_qa/run_app.py:AppRunnable \
|
||
--input pixie_qa/sample-input-complex.json \
|
||
--output pixie_qa/trace-complex.jsonl
|
||
```
|
||
|
||
---
|
||
|
||
## 验证 Trace
|
||
|
||
### 快速检查
|
||
|
||
Trace JSONL 包含每个 `wrap()` 事件一行和每个 LLM span 一行：
|
||
|
||
```jsonl
|
||
{"type": "kwargs", "value": {"user_message": "你们的营业时间是什么？"}}
|
||
{"type": "wrap", "name": "customer_profile", "purpose": "input", "data": {...}, ...}
|
||
{"type": "llm_span", "request_model": "gpt-4o", "input_messages": [...], ...}
|
||
{"type": "wrap", "name": "response", "purpose": "output", "data": "我们的营业时间是..."}
|
||
```
|
||
|
||
检查以下内容：
|
||
|
||
- 预期的 `wrap` 条目出现（代码中每个 `wrap()` 调用对应一个）
|
||
- 至少出现一个 `llm_span` 条目（确认进行了真实的 LLM 调用）
|
||
- 缺失的条目表明执行路径与预期不同——在继续之前修复
|
||
|
||
### 格式化并验证覆盖率
|
||
|
||
运行 `pixie format` 以数据集条目格式查看数据：
|
||
|
||
```bash
|
||
pixie format --input trace.jsonl --output dataset_entry.json
|
||
```
|
||
|
||
输出显示：
|
||
|
||
- `input_data`：Runnable 参数的精确键/值
|
||
- `eval_input`：来自 `wrap(purpose="input")` 调用的数据
|
||
- `eval_output`：实际的应用输出（来自 `wrap(purpose="output")`）
|
||
|
||
对于 `pixie_qa/02-eval-criteria.md` 中的每个评估标准，验证格式化输出包含所需的数据。如果某个数据点缺失，返回步骤 2a 并添加 `wrap()` 调用。
|
||
|
||
### Trace 审计
|
||
|
||
在进入步骤 3 之前，审计每个 Trace：
|
||
|
||
1. **世界数据检查**：对于每个 `wrap(purpose="input")` 字段，数据是否具有真实的复杂度？与 `00-project-analysis.md` 的「真实输入特征」进行比较。如果分析说明输入为 5KB–500KB，而你的输入小于 5KB，则说明不具代表性。
|
||
|
||
2. **LLM span 检查**：`llm_span` 条目是否出现？如果没有出现，说明应用程序的 LLM 调用未触发——Runnable 可能配置错误，或者 LLM 被 mock/伪造。在继续之前修复此问题。
|
||
|
||
3. **复杂度检查**：Trace 是否涉及 `00-project-analysis.md` 中的困难问题？如果它只覆盖了快乐路径，请使用更难的输入捕获额外的 Trace。
|
||
|
||
如果任何检查失败，请返回修复输入或 Runnable，然后重新捕获。
|
||
|
||
---
|
||
|
||
## 输出
|
||
|
||
- `pixie_qa/reference-trace.jsonl`——包含所有预期 wrap 事件和 LLM span 的参考 Trace
|
||
- 针对不同输入的其他 Trace 文件
|