企业官网建设流程全解析

nao test是开源分析智能体 nao 内置的测试命令：把「自然语言问题 + 期望 SQL」写成一个个 YAML 测试用例，一键验证 AI 数据分析智能体的回答是否准确，并用通过率、Token 成本等指标建立可复现的评估基线。对于刚接触 nao 的新手来说，它是保障智能体「分析准确性」最实用的工具。

nao test 是什么：给数据分析智能体做「单元测试」

传统软件的单元测试验证函数返回值，而nao test验证的是 AI 智能体的分析结果。它的工作流程可以概括为三步：

1. 提问：把 YAML 里的自然语言 prompt 发给 nao 智能体（比如「所有订单的总收入是多少？」）；
2. 执行：智能体生成自己的 SQL 并查询数据库，同时框架用你写好的「期望 SQL」查询出标准答案；
3. 比对：逐行、逐列 diff 两份结果数据，一致才算通过（支持浮点容差，避免精度噪音）。

所有测试用例统一放在项目根目录的tests/文件夹中，一个文件一个用例。项目自带了一个最小示例：

• 示例用例：total_revenue.yml

它的完整内容只有 5 行：

name: total_revenue prompt: What is the total revenue from all orders? sql: | SELECT SUM(amount) as total_revenue FROM orders

name是测试名称，prompt是发给智能体的问题，sql是标准答案。就这么简单——这就是AI 智能体单元测试的全部骨架。

测试用例怎么写：两条核心编写规则

nao 官方在 create-context-tests/SKILL.md 中沉淀了一套编写测试的规范，核心是两条规则：

规则一：prompt 要像真实用户在聊天

问题要短、要口语化，不要泄露表名、列名或计算方法。测试的目的是验证智能体能从模糊的真实问题中得出正确答案，而不是「按提示抄作业」：

规则二：SQL 输出列名编码「格式/单位」而非来源

列名应该告诉读数据的人如何解释这个值，而不是暴露它是从哪张表算出来的：

完整的用例模板（含可选字段说明）见 templates/test.yaml。模板中几个值得留意的可选字段：

• database：配置了多个数据库时，指定本用例查询哪个库；
• category/difficulty：给用例打标签，方便分类统计；
• notes：记录这个用例为什么要存在、它捕捉哪类失败模式。

进阶：用 assertions 断言智能体的「中间行为」

只看最终数据还不够——有时你关心的是智能体过程是否符合预期。比如用户问「收入是多少」但没说哪个时间段，你期望智能体先追问，而不是直接给一个数字。这时可以用assertions字段断言智能体是否调用了特定工具：

name: ambiguous_revenue_period prompt: What was the revenue? assertions: - type: tool_call tool: clarification

这条断言要求智能体在运行过程中调用过clarification工具（即发起澄清追问）。它还可以：

• 通过args校验工具调用的参数子集（省略args则匹配任意调用）；
• 通过min_count要求工具至少被调用 N 次；
• 与 SQL 数据比对组合使用——所有检查全部通过，用例才算通过。

断言逻辑实现在 assertions.py，一个坏掉的 assertions 配置会直接让整个测试运行失败，而不是被静默跳过，保证评估结果可信。

多模型对比与 pass@k：量化评估准确率

nao test不只是跑一遍就完事，它内置了两个对 AI 评估特别有用的维度：

一次运行对比多个模型

通过-m参数可以同时测试多个模型，格式为provider:model_id：

nao test -m openai:gpt-4.1 -m anthropic:claude-sonnet-4-5

运行结束后会输出「测试 × 模型」通过率矩阵，一眼看出哪个模型在你的业务问题上更靠谱。

用 pass@k 衡量稳定性

LLM 输出有随机性，同一个问题跑 10 次可能 7 次对、3 次错。--k 5让每个用例重复跑 5 次，框架据此计算 summary.py 中定义的三个指标：

默认值可以在nao_config.yaml的test配置块中设置，命令行参数会覆盖配置。配置结构定义见 config/test/init.py。

test: models: - openai:gpt-4.1 - anthropic:claude-sonnet-4-5 threads: 4 # 并行线程数 k: 5 # 每个用例跑 5 次 comparison: # 数据比对容差 rtol: 0.00001 atol: 0.00000001 decimals: 2

其他常用参数（完整说明见 cli/README.md）：

• -s/--select：只跑指定用例，支持按名称、文件名或子文件夹筛选，如nao test -s contracts；
• -t/--threads：并行执行线程数，加速大规模评估；
• -u/--password：非交互环境下的登录凭据（也可用NAO_USERNAME/NAO_PASSWORD环境变量）。

结果怎么读：输出报告与可视化查看器

每次运行结束后，nao test会输出三张表：每个用例的明细（状态、Token 数、成本、耗时、工具调用次数）、按模型汇总的通过率表，以及测试 × 模型矩阵。所有原始结果以 JSON 形式保存到tests/outputs/目录，方便追溯和 diff。

如果失败用例较多，终端表格看不清楚，可以启动内置的结果查看器：

nao test server

它会在浏览器中打开一个本地 Web 服务（默认 8765 端口），展示通过/失败状态、Token 用量、成本，以及失败用例的实际数据 vs 期望数据的逐行 diff——排查「智能体到底哪里算错了」时非常直观。查看器实现在 test/server.py。

最佳实践：把测试纳入智能体的持续迭代

根据官方技能文档 create-context-tests/SKILL.md 的建议，推荐的迭代节奏是：

1. 建立基线：为RULES.md中每个核心指标至少写一个测试，再补充时间范围（「最近 30 天」）、多步查询、空值/边界情况、歧义表述等场景；
2. 跑基线：nao test -t 10，记录通过率、Token 成本与耗时作为基线；
3. 小步修复：每次只改一条上下文规则（RULES.md），重新跑测试，让每次改动的效果可归因；
4. 失败诊断：从tests/outputs/中读取失败用例的详细 diff，定位规则缺口再修复。

官方强调的一点：测试套件是回答「上下文工程到底有没有用」的唯一诚实答案——每修改一次RULES.md，都应让这套YAML 评估框架重新验收一次。

常见问题（FAQ）

问：跑测试前需要做什么准备？

答：在包含nao_config.yaml的项目目录下，确保 LLM 已配置好，并先后台启动nao chat &（测试运行器会复用聊天服务）。首次运行会提示登录凭据。

问：只想要文本答案、没有标准 SQL 的用例怎么测？

答：只写prompt+assertions即可，不写sql。此时框架通过断言中间行为（如是否调用了execute_sql工具）来判定通过与否。

问：浮点数比对总因为精度差 0.01 失败？

答：调整test.comparison容差配置，decimals控制比对前四舍五入的小数位数，rtol/atol控制相对/绝对误差，详见 runner.py 中的check_dataframe比对逻辑。

小结

nao test用最少的 YAML 配置，为数据分析智能体提供了接近工程化的单元测试能力：标准答案比对、中间行为断言、多模型横评、pass@k 稳定性指标、成本统计与可视化 diff。把它接入你的工作流后，每次改动上下文、换模型、升级版本，都能用同一个AI 智能体评估框架客观回答一个问题：智能体的分析准确性，到底变好了还是变差了？