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-安装-重试循环之前先捕获缺失的包。

# 创建一个包含输入数据的 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：

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 一行：

{"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 以数据集条目格式查看数据：

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：

世界数据检查：对于每个 wrap(purpose="input") 字段，数据是否具有真实的复杂度？与 00-project-analysis.md 的「真实输入特征」进行比较。如果分析说明输入为 5KB–500KB，而你的输入小于 5KB，则说明不具代表性。
LLM span 检查：llm_span 条目是否出现？如果没有出现，说明应用程序的 LLM 调用未触发——Runnable 可能配置错误，或者 LLM 被 mock/伪造。在继续之前修复此问题。
复杂度检查：Trace 是否涉及 00-project-analysis.md 中的困难问题？如果它只覆盖了快乐路径，请使用更难的输入捕获额外的 Trace。

如果任何检查失败，请返回修复输入或 Runnable，然后重新捕获。

输出

pixie_qa/reference-trace.jsonl——包含所有预期 wrap 事件和 LLM span 的参考 Trace
针对不同输入的其他 Trace 文件

5.7 KiB Raw Permalink Blame History Unescape Escape