用途 该技能用于为 Python 编写的 AI 应用搭建自动化评测流水线:像真实用户一样用真实输入端到端运行应用,再用评测器对其输出打分,通过 pixie test 产出通过/失败结果。被评测的对象是应用代码本身——请求处理、上下文组装(如何收集数据、构建提示词、管理会话状态)、路由和响应格式化。由于应用使用 LLM,输出是不确定的,因此用评测器(LLM 作为裁判、相似度评分)替代 assertEqual。
主要能力与工作流 整个过程分六个步骤,需按序执行,中间不需要用户确认:
- 理解应用并定义评测标准:先检查用户提示中的规格文档、指定数据集或评测维度并优先采纳;随后完成项目分析、入口点与执行流程、评测标准三个子步骤,分别输出 pixie_qa/00-project-analysis.md、01-entry-point.md、02-eval-criteria.md。
- 插桩、运行应用并采集参考 trace:在数据边界添加 wrap() 调用注入受控输入并捕获输出;实现 Runnable 类调用应用真实入口;运行并采集轨迹,产出 pixie_qa/reference-trace.jsonl,其中应出现预期的 wrap 条目和 llm_span 条目。
- 定义评测器:把定性的评测标准转成可运行的评分函数,映射到内置评测器、agent 评测器(语义或定性标准的默认选择)或手动自定义函数(仅用于正则、字段存在性等机械/确定性检查),并写出 pixie_qa/03-evaluator-mapping.md。
- 构建数据集:以第 2 步的参考 trace 作为数据形态与字段名的依据,创建测试场景,覆盖能力清单中的条目并包含针对失败模式的条目;数据集写入 pixie_qa/datasets/<name>.json,且每个 input wrap 都必须在 eval_input 中有预捕获内容。
- 运行 pixie test 并修复机械性问题:跑通整条流水线,修复 pixie QA 组件(数据集、runnable、自定义评测器)的设置与数据问题,而不是修应用本身或评判结果质量;当每个条目都有真实评测分数后即进入第 6 步。
- 分析结果:分三阶段结构化分析,完成所有 pending 评测(在 evaluations.jsonl 中写入带分数与推理的结果),为每个数据集目录写出 analysis.md 与 analysis-summary.md,为测试运行根目录写出 action-plan.md 与 action-plan-summary.md,并运行技能资源目录中的第 6 步校验脚本确认成功。
使用方式 先识别并激活项目对应的虚拟环境,再运行技能资源中的 setup.sh。该脚本会更新 eval-driven-dev 技能与 pixie-qa Python 包、在未初始化时初始化 pixie 工作目录、并在后台启动 Web 服务器展示进度。setup 的错误处理规则:技能更新失败可继续;pixie-qa 已安装但升级失败可继续;pixie-qa 未安装且安装失败必须停止求助;pixie init 失败必须停止求助;pixie start(Web 服务器)失败必须停止求助,可查看 pixie 根目录下的 server.log 排查(常见原因:端口冲突、缺少依赖、环境过慢)。不要在没有 Web 服务器的情况下继续,用户需要它查看评测结果。
规则与限制 应用代码在评测中真实执行(路由、提示词组装、LLM 调用、响应格式化),不做 mock 或 stub;外部数据源(数据库、缓存、第三方 API、语音流)通过 instrumentation 替换为测试指定值。应用的 LLM 调用必须指向真实 LLM,禁止用假实现替换、mock、stub 或拦截,因为替换会使用评测变得同义反复、分数失去意义;项目自身单元测试中的 LLM mock 模式不得用于评测 Runnable。遇到以下阻塞应立即停止求助:应用因缺少环境变量或配置无法运行、应用导入失败表明项目损坏(缺系统依赖或 Python 版本不兼容)、入口点存在多个同等合理的候选无法判断。应当自行解决的阻塞包括:缺少 Python 包(安装)、缺少 pixie 包(安装)、端口冲突(换端口)、文件权限问题(修复)。每轮 pixie test 都会生成 pixie_qa/results/<test_id> 并开启新的分析周期,在编辑应用代码、提示词、数据集、评测器或重跑前,须先完成该结果目录的第 6 步分析。
适用场景 适合为基于 Python、依赖真实 LLM 调用的 AI 应用建立可重复、可评分的端到端自动化评测,尤其关注上下文组装、路由、请求处理等应用层逻辑的质量与失败模式。工具更新、初始化等命令因资料未提供具体命令内容,暂未提供。