wehub-skill-sync
86 lines
6.2 KiB
Markdown
86 lines
6.2 KiB
Markdown
# 步骤 5：运行 `pixie test` 并修复机械问题
|
|
|
|
**为什么需要这一步**：运行 `pixie test` 并修复 QA 组件中的机械问题——数据集格式问题、可运行实现中的 bug 以及自定义评估器错误——直到每一条记录都产生真实评分。这一步**不**涉及评估结果质量或修复应用程序本身。
|
|
|
|
---
|
|
|
|
## 5a. 运行测试
|
|
|
|
```bash
|
|
uv run pixie test
|
|
```
|
|
|
|
如需包含每条用例评分和评估器推理的详细输出：
|
|
|
|
```bash
|
|
uv run pixie test -v
|
|
```
|
|
|
|
`pixie test` 在运行测试前会自动加载 `.env` 文件。
|
|
|
|
评估框架的执行流程如下：
|
|
|
|
1. 从数据集的 `runnable` 字段解析出 `Runnable` 类
|
|
2. 调用 `Runnable.create()` 构造实例，然后调用一次 `setup()`
|
|
3. 以**并发**方式运行所有数据集条目（最多 4 个并行）：
|
|
a. 从条目中读取 `input_data` 和 `eval_input`
|
|
b. 用 `eval_input` 数据填充 wrap 输入注册表
|
|
c. 初始化捕获注册表
|
|
d. 将 `input_data` 校验为 Pydantic 模型，然后调用 `Runnable.run(args)`
|
|
e. 应用中的 `wrap(purpose="input")` 调用返回注册表中的值，而不是调用外部服务
|
|
f. `wrap(purpose="output"/"state")` 调用捕获评估所需的数据
|
|
g. 从捕获的数据构建 `Evaluable`
|
|
h. 运行评估器
|
|
4. 调用一次 `Runnable.teardown()`
|
|
|
|
由于条目是并发运行的，Runnable 的 `run()` 方法必须是并发安全的。如果看到 `sqlite3.OperationalError`、`"database is locked"` 或类似错误，请为 Runnable 添加一个 `Semaphore(1)`（参见步骤 2 参考文档中的并发章节）。
|
|
|
|
## 5b. 仅修复机械问题
|
|
|
|
这一步严格限于修复你在前面步骤中构建的内容——数据集、runnable 以及任何自定义评估器。你修复的是阻止流水线运行的机械问题，而非评估或改进应用程序的输出质量。
|
|
|
|
**哪些属于机械问题**（需要修复）：
|
|
|
|
| 错误 | 原因 | 修复方法 |
|
|
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
| `WrapRegistryMissError: name='<key>'` | 数据集条目缺少 `eval_input` 项，其中 `name` 与应用中 `wrap(purpose="input", name="<key>")` 所期望的名称不匹配 | 在每个受影响的条目的 `eval_input` 中添加缺失的 `{"name": "<key>", "value": ...}` |
|
|
| `WrapTypeMismatchError` | 反序列化的类型与应用的期望不匹配 | 修复数据集中的值 |
|
|
| Runnable 解析失败 | `runnable` 路径或类名错误，或该类未实现 `Runnable` 协议 | 修复数据集中的 `filepath:ClassName`；确保该类包含 `create()` 和 `run()` 方法 |
|
|
| 导入错误 | 模块路径错误或 runnable/evaluator 中存在语法错误 | 修复引用的文件 |
|
|
| `ModuleNotFoundError: pixie_qa` | `pixie_qa/` 目录缺少 `__init__.py` | 运行 `pixie init` 重新创建 |
|
|
| `TypeError: ... is not callable` | 评估器名称指向一个不可调用的属性 | 评估器必须是函数、类或可调用实例 |
|
|
| `sqlite3.OperationalError` | 并发 `run()` 调用共享同一个 SQLite 连接 | 为 Runnable 添加 `asyncio.Semaphore(1)`（参见步骤 2 的并发章节） |
|
|
| 自定义评估器崩溃 | 自定义评估器实现中存在 bug | 修复评估器代码 |
|
|
|
|
**哪些不属于机械问题**（此处不要修复）：
|
|
|
|
- 应用程序输出错误或质量低下 → 属于应用程序行为，在步骤 6 中分析
|
|
- 评估器评分低 → 属于质量信号，在步骤 6 中分析
|
|
- 应用内部的 LLM 调用失败 → 在步骤 6 中报告，不要模拟或绕过
|
|
- 评估器评分在不同运行之间波动 → 正常的 LLM 非确定性，不是 bug
|
|
|
|
反复迭代——修复错误，重新运行，修复下一个错误——直到 `pixie test` 成功运行完毕，所有条目都产生真实的评估器评分。
|
|
|
|
## 输出
|
|
|
|
`pixie test` 成功完成后，结果会存储在按条目组织的目录结构中：
|
|
|
|
```
|
|
{PIXIE_ROOT}/results/<test_id>/
|
|
meta.json # 测试运行元数据
|
|
dataset-{idx}/
|
|
metadata.json # 数据集名称、路径、runnable
|
|
entry-{idx}/
|
|
config.json # 评估器、描述、预期结果
|
|
eval-input.jsonl # 提供给评估器的输入数据
|
|
eval-output.jsonl # 从应用捕获的输出数据
|
|
evaluations.jsonl # 评估结果（已评分 + 待评分）
|
|
trace.jsonl # LLM 调用追踪记录（如果已捕获）
|
|
```
|
|
|
|
`<test_id>` 会打印在控制台输出中。你将在步骤 6 中引用该目录。
|
|
|
|
---
|
|
|
|
> **如果在运行测试时遇到意外错误**（参数名称错误、导入失败、API 不匹配），请在猜测修复方法之前先阅读 `wrap-api.md`、`evaluators.md` 或 `testing-api.md` 获取权威 API 参考。
|