smevals 轻量评测框架：目录即评测 · 干货攻略

• 链接: https://simonwillison.net/2026/Jul/31/smevals
• 分类: x-tips
• 来源: X @simonw
• 作者: Jay
• 更新: 2026-08-02
• 仓库: prime-radiant-inc/smevals

这是什么

smevals（全称 "small evals"）是 Prime Radiant 实验室推出的开源 Python CLI 评测框架，主打轻量、可复制、以目录为评测单元的设计理念。MIT 许可证，由 Simon Willison 主导开发，定位是帮助开发者在小模型与高性价比方案中做出选择——而不必总是跑最贵的 frontier 模型。

核心理念来自官方博客原文：

We've been building a new system for running evals against different models, prompts, and harnesses, with the goal of being able to identify the most appropriate small and inexpensive models for different categories of task.

核心哲学：把评测变成一个本地可复制的目录，而不是一个需要部署的复杂平台。

为什么值得关注

解决什么问题

当前主流评测工具（如 EleutherAI Harness、LightEval、DeepEval）往往要求较高的工程复杂度：需要写 Python 代码、配置专用 harness、或依赖云服务。smevals 的切入点是：

• 让非工程师也能快速搭建评测：目录 + YAML + 可执行脚本，无需写代码
• 让模型自己帮你写评测：README 设计为"AI 可读"，可以直接 uvx smevals docs 获取文档后让 Codex/Claude Code 等 coding agent 从零构建评测
• 聚焦小型/高性价比模型：官方定位就是帮你在 GPT-5.5 / Claude Fable 5 和 Gemini 3.5 Flash-Lite 之间找到"够用就好"的平衡点

核心概念体系（官方定义）

smevals 用一套清晰的分层抽象描述整个评测生命周期（来源：GitHub README）：

差异化定位

对比主流评测框架（来源：交叉检索 Tavily 搜索结果及官方 README）：

• EleutherAI Harness：更偏学术，支持大规模标准评测；smevals 更偏向本地快速迭代
• DeepEval：pytest 原生，强调 CI 集成；smevals 用 YAML + 目录，强调无代码化
• LightEval：HuggingFace 生态；smevals 无特定生态依赖
• smevals 独有：目录即评测、无需编程、Agent 可自主构建评测、可脱离云端本地运行

核验过程

官方来源

1. GitHub README（prime-radiant-inc/smevals）：https://github.com/prime-radiant-inc/smevals - 确认安装方式：uv tool install smevals / pip install smevals / uvx smevals --help - 确认许可证：MIT - 确认内置 Checker：contains、xml-valid - 确认目录结构规范（eval.yaml + tasks/ + configs/ + graders/ + checkers/ + run-llm + runs/） - 确认环境变量约定：SMEVALS_MODEL、SMEVALS_TASK、SMEVALS_PROMPT、SMEVALS_RUN_DIR、SMEVALS_TASK_ - 确认命令：smevals run、smevals grade、smevals report、smevals serve、smevals build、smevals docs

2. Prime Radiant 官方博客（2026-07-31）：https://primeradiant.com/blog/2026/smevals.html - 确认动机：帮开发者在小模型中找到够用方案 - 确认 AI 协作工作流：uvx smevals docs → Agent 读取后构建评测 - 确认实际运行示例：gpt-4.1-mini 在 pelican/otters-in-love 评测中 pass - 确认可用 smevals build 导出静态 HTML

3. Simon Willison 个人博客（2026-07-31）：https://simonwillison.net/2026/Jul/31/smevals - 确认与 Prime Radiant 联合开发背景 - 交叉确认 CLI 命令行接口与博客描述一致

交叉验证结论

• MIT 许可证：✅ README badge 确认
• Python CLI 工具：✅ PyPI badge + README 确认
• 目录结构规范：✅ README 逐文件描述，与博客实例完全吻合
• 环境变量接口：✅ README 完整列出，博客中 run-llm 脚本示例正确使用
• 多模型支持（-m）：✅ README CLI 部分确认
• -g 自动评分、-n 多次运行：✅ README 确认
• Agent 可读文档设计：✅ 博客详细演示，README 开篇明确说明

上手步骤

1. 安装（任选一种）

# 推荐：用 uv 工具安装
uv tool install smevals

# 或 pip
pip install smevals

# 或直接运行（无需安装）
uvx smevals --help

2. 让 AI agent 帮你从零构建评测

# 获取文档
uvx smevals docs

# 把文档丢给 Claude Code / Codex / Pi，然后：
Now build an eval that tests how well models can write haikus,
with two tasks - a haiku about a pelican and a haiku about two otters in love

3. 手动构建最小评测目录

目录结构：

my-eval/
├── eval.yaml          # Eval 元数据
├── tasks/             # 一个 Task 一个 YAML
│   └── pelican.yaml
├── configs/           # 一个 Config 一个 YAML
│   └── default.yaml
├── graders/          # 一个 Grader 一个 YAML
│   └── default.yaml
├── checkers/         # 自定义 Checker 脚本
│   └── three-lines
├── run-llm           # Runner 可执行脚本
└── runs/             # smevals run 自动创建，不要手动编辑

eval.yaml：

name: haiku
description: >-
  Can the model write a haiku on demand? Graded on structure:
  the reply must be exactly three lines.

tasks/pelican.yaml：

name: pelicans
prompt: Write a haiku about pelicans. Reply with only the haiku, three lines.

configs/default.yaml（Runner 路径相对于本文件）：

name: default
runner: ../run-llm
model: gpt-4.1-mini

run-llm（Runner 示例，使用 llm CLI）：

#!/usr/bin/env bash
set -euo pipefail
llm -m "$SMEVALS_MODEL" "$SMEVALS_PROMPT"
llm logs -c --json > log.json

记得 chmod +x run-llm。

graders/default.yaml：

name: default
checks:
  - checker: ../checkers/three-lines
    required: true
scoring:
  pass_threshold: 1.0

checkers/three-lines（自定义 Checker）：

#!/usr/bin/env python3
import json, os, pathlib, sys

raw = pathlib.Path(os.environ["SMEVALS_RUN_DIR"], "output.txt").read_text()
lines = [line for line in raw.strip().splitlines() if line.strip()]
passed = len(lines) == 3
print(json.dumps({
    "score": 1.0 if passed else 0.0,
    "metrics": {"line_count": len(lines)},
    "notes": f"{len(lines)} non-empty line(s); expected exactly 3",
}))
sys.exit(0 if passed else 1)

chmod +x checkers/three-lines。

4. 运行评测

# 基础运行
smevals run my-eval -g

# 多模型对比
smevals run my-eval -g -m gpt-4.1-mini -m gpt-5.5 -m gemini-2.5-flash

# 同一 Task 跑 5 次（应对随机性）
smevals run my-eval -g -n 5

5. 查看结果

# 终端输出
smevals report my-eval

# 本地 Web UI
smevals serve my-eval    # 监听 http://127.0.0.1:7001

# 导出静态 HTML（可托管）
smevals build

坑与适用边界

✅ 适用场景

• 小团队/个人快速构建评测：不需要写一行 Python，只需 YAML + shell 脚本
• 模型选型对比：同一评测集跑多个模型，直观对比 pass rate
• CICD 集成：退出码非零表示失败，可直接接入 CI
• AI Agent 协作评测构建：smevals docs 直接丢给 agent，省去文档阅读成本
• 静态报告导出：可离线部署评测结果，无需服务

⚠️ 已知限制

• Runner 需自行实现：smevals 只定义 Runner 接口（环境变量约定），不提供默认 LLM 调用；需要自己写脚本对接 llm CLI、openai SDK 或 agent harness
• 不处理数据标注：适合自动评分场景，不适合需要人工标注的评测
• Grader 变更无需重跑 Run：这是设计亮点，但意味着你需要保留 runs/ 目录，磁盘占用随评测次数增长
• 多语言/复杂场景支持有限：当前文档以英文为主，内置 Checker 较少（仅 contains、xml-valid），复杂评测依赖自定义 Checker
• 生态尚在早期：对比 DeepEval、Promptfoo 等成熟框架，插件生态和社区积累较少

🔧 常见坑

1. Runner 路径错误：runner 在 configs/*.yaml 中是相对于该 YAML 文件的路径，不是相对于工作目录
2. output.txt 编码问题：Runner 标准输出被捕获为 output.txt，确保脚本输出 UTF-8
3. 多模型 -m 与 -n 的叠加：smevals run -n 5 -m A -m B 会把每个 Task × 每个模型跑 5 次，总 Run 数 = Tasks × Models × N
4. Failed Run 不计入 -n：Runner 非零退出的 Run 被标记为失败，不参与 -n 计数，实际跑出的 Run 可能少于预期

一句话结论

smevals 是一个以"目录即评测"为核心理念的轻量评测框架，特别适合小团队快速构建可复制的模型选型评测，并支持让 AI coding agent 从文档直接生成评测代码——但复杂评分逻辑仍需手写自定义 Checker。