Skip to content
Vieval

核心概念 ​

先了解 Vieval 如何根据项目配置生成用例结果,才能看清矩阵、重试和报告选项分别作用于哪个步骤:

text
比较 -> 工作区 -> 项目

项目
  -> 发现评测项及其任务
  -> 读取推理执行器、运行矩阵和评测矩阵

每个评测项 × 每个推理执行器 × 每行运行矩阵 × 每行评测矩阵
  -> 待调度任务
    -> 用例 -> 断言结果 / 分数 / 指标

任务执行
  -> 尝试
    -> 每个用例先执行一次
      -> 失败或超时时,按 autoRetry 重试该用例
  -> 仍有用例失败或超时时,按 autoAttempt 开始下一次尝试
    -> 重新执行全部用例

执行 --json -> 机器可读的标准输出
执行 -> 报告目录(默认为 .vieval/reports)-> 分析 / 比较

工作区是列出 projects 的配置,项目可以内联书写,也可以从 packages/* 等其他配置中收集。比较是列出 workspaces 的配置,它为每个工作区启动一个独立进程,并排运行。

项目指定从哪个目录发现评测文件,并保存推理执行器、矩阵等项目级配置。通过 defineEval 声明的评测项可以包含一个任务,describeTask 等 DSL 则会直接注册任务。运行器会组合每个评测项、每个推理执行器、每行运行矩阵和每行评测矩阵,为每组组合创建一个待调度任务。任务包含一个或多个用例;用例执行后会产生通过或失败的断言结果,也可以记录具名分数和自定义指标。每个任务有一个主分数,报告把它作为标题数值显示,并在旁边显示执行成功率,即得出结果的用例所占的比例。

Vieval 提供两种重复执行机制:尝试和重试。每次尝试都会执行任务中的全部用例;配置 autoAttempt 后,如果仍有符合条件的用例失败或超时,运行器会开始下一次尝试,并把各次结果都计入任务汇总。配置 autoRetry 后,重试只会在当前尝试中再次执行失败或超时的用例。

CLI 默认显示便于阅读的进度和摘要。--json 会把标准输出改为机器可读的结果。每次运行默认都会把分析和比较命令所需的报告文件写入配置文件旁边的 .vieval/reports;--report-out <directory> 修改报告根目录,--no-report 关闭报告。

概念职责常见范围
比较列出工作区,为每个工作区启动独立进程,最后输出排行榜同一评测基准的多种实现
工作区列出项目,在同一进程中调度它们,并提供环境变量一个仓库或 monorepo 根目录
项目设置评测文件的发现规则,并保存推理执行器和矩阵默认值同一目录中的一组评测文件
推理执行器项目可以注册多个推理执行器,运行器会分别针对每个执行器调度任务;它与运行矩阵中的模型选择是两个独立维度项目
任务定义要评测的行为;调度后会关联一个评测项、一个推理执行器,以及当前组合所采用的运行矩阵和评测矩阵取值一项被测行为的一组具体配置
用例执行一个输入或场景,并记录断言结果、分数和指标任务中的一次检查
运行矩阵展开模型、场景等执行侧变量项目、评测定义或任务定义
评测矩阵展开评分标准等评测侧变量项目、评测定义或任务定义
尝试执行任务中的全部用例;仍有用例失败或超时时,可按 autoAttempt 重新执行全部用例一个已调度任务
重试按 autoRetry 在同一次尝试中重新执行失败或超时的用例一次用例执行
报告目录保存运行摘要、事件与用例记录;除非使用 --no-report,否则都会写入一个项目的一次运行及其报告目录
分析与比较读取报告文件以检查结果,或比较多次运行和不同评测方案一组或多组报告目录

下一步学习如何编写任务、用例与输入。