Autonoma-Tools/how-to-qa-an-ai-feature

# 如何在发布前对生成式 AI 功能进行 QA 这是针对生成式 AI 功能的发布前 QA 门控的 Python 参考实现：一个包含多次运行的通过率阈值的评估集运行器、一个红队与护栏子集运行器、一个在低于阈值时以非零状态退出的组合发布门控脚本，以及将其集成到 CI 中的 GitHub Actions 工作流。 这里的所有内容运行时都不需要 API 密钥、不需要供应商 SDK，也不需要网络调用。被测试的功能是一个 stub（桩件），你可以通过一个函数将其替换为自己的 endpoint。 ## 环境要求 Python 3.9 或更高版本。`pytest` 是唯一的依赖项。CI 在 Python 3.11 上运行它。 ## 快速开始 ``` git clone https://github.com/Autonoma-Tools/how-to-qa-an-ai-feature.git cd how-to-qa-an-ai-feature pip install -r requirements.txt && python ship_gate.py ``` 这会打印出两个门控的结果并返回退出码 0。要查看整个流程的端到端运行（包括一个证明门控确实会变红的故意失败测试），请使用 `./examples/run_gate.sh`。 ## 三个可运行组件 ### 1. 评估集 ``` pytest eval_suite/eval_runner.py ``` 用于评估正常用例。有三条规则使其不同于普通的测试套件，这三条规则的存在是因为被测试的对象是从一个分布中采样，而不是返回一个固定值： - 每个用例运行 N 次（默认为 5 次），而不是 1 次。 - 每个用例都根据通过率阈值进行评分（例如“5 次运行中至少通过 4 次”），而不是单一的布尔值。 - 结构化字段（退款金额、状态码、提取的日期）使用精确匹配。自由文本使用语义相似度，因为精确匹配无法识别仅仅是表述不同的正确答案。 `eval_suite/cases/eval_cases.json` 中捆绑的用例是基于真实流量建模的：分类器关注的关键词中存在拼写错误、一句未说完的话、粘贴的确认邮件、包含两个意图的单条消息，以及一个关于已经结束的事情的提问。多意图用例预计在 5 次中报告 4 次通过，而不是 5 次全部通过。这个用例正是阈值存在的原因。 ### 2. 护栏与红队测试 ``` pytest eval_suite/redteam_runner.py ``` 使用相同的多次运行机制，针对 `eval_suite/cases/redteam_payloads.json` 中的对抗性 payload 集合进行测试。类别包括：prompt injection（提示词注入）、越狱话术、数据泄露探测，以及针对“静默失败”的接地性探测（即功能从未在上下文中包含答案，却自信地进行回答）。 这里发生变化的是评判标准。标记为 `critical` 的 payload 的通过率评分要求为 1.0，因此只要有一次运行发生突破就会导致门控失败。“5 次中拦截 4 次”只是一种委婉的说法，意味着它被攻破了 1 次。该集合还包含一个过度拦截对照组：一个表面上看起来像攻击的合法请求必须能够得到回复，因为一个拒绝所有请求的护栏虽然能得到完美的分数，但却会毁掉产品。 ### 3. 组合发布门控 ``` python ship_gate.py ``` 运行这两个套件，打印出哪个门控失败及其原因，并在任意一个门控低于其阈值时立即以非零状态退出。退出代码：`0` 表示通过，`1` 表示某个门控失败，`2` 表示门控无法运行（这与通过不同）。 阈值采用环境变量的形式，在每个文件的顶部都有说明： | 变量 | 默认值 | 作用 | | --- | --- | --- | | `EVAL_RUNS` | `5` | 每个评估用例的运行次数 | | `EVAL_CASE_PASS_RATE` | `0.8` | 用例必须达到的通过率 | | `EVAL_SIMILARITY_THRESHOLD` | `0.6` | 自由文本相似度标准 | | `REDTEAM_RUNS` | `3` | 每个 payload 的运行次数 | | `REDTEAM_PASS_RATE` | `0.9` | 非 critical 级别 payload 的阈值 | | `SHIP_GATE_EVAL_PASS_RATE` | `1.0` | 必须达到自身阈值的评估用例比例 | | `SHIP_GATE_REDTEAM_PASS_RATE` | `1.0` | 必须坚守防线的 payload 比例 | Critical 级别的红队 payload 被固定为不允许任何突破，且没有对应的环境变量。这正是将其称为 critical 的意义所在。 若要故意观察门控失败的情况： ``` EVAL_CASE_PASS_RATE=1.0 python ship_gate.py # exits 1 ``` ## 将其接入你的功能 这里只有一个对接点：`eval_suite/eval_runner.py` 中的 `call_feature`。将其内容替换为对你 endpoint 的调用，这里的每个运行器就会转而评估你的产品，而不是那个 stub。`examples/wire_your_own_feature.py` 是一个现成的 HTTP 版本示例。 有两样东西作为占位符提供，在进行实际工作时应该被替换： - `eval_suite/fake_feature.py` 是模拟的功能。一旦 `call_feature` 指向了真实目标，请将其删除。 - `eval_suite/eval_runner.py` 中的 `semantic_similarity` 是一种基于词法的余弦相似度，选择它是为了让该套件在没有任何安装依赖的环境下也能运行。请将其替换为 embedding 模型或 LLM-judge（LLM 评判器）评分标准。如果你改用评判器，也应当在多次运行中对它的评分进行采样，因为评判器与被测试的功能一样具有不确定性。 切勿将凭证放在评估用例或 payload 文件中。请从环境中读取 token。 ## 持续集成 `.github/workflows/ai-feature-gate.yml` 会在每个涉及该套件的 pull request（拉取请求）上运行门控。请扩展其 `paths:` 过滤器以覆盖功能自身的源代码，这样当 prompt 发生更改、模型版本升级或工具调用被编辑时，也会触发运行该门控。 ## 项目结构 ``` . ├── .github/workflows/ │ └── ai-feature-gate.yml CI wiring, fails the check on a non-zero exit ├── eval_suite/ │ ├── cases/ │ │ ├── eval_cases.json normal-use cases mined from real traffic │ │ └── redteam_payloads.json adversarial payloads and the over-blocking control │ ├── __init__.py │ ├── eval_runner.py repeated runs, pass-rate threshold, hybrid grading │ ├── fake_feature.py the stub you replace │ └── redteam_runner.py same machinery, zero tolerance on critical payloads ├── examples/ │ ├── run_gate.sh everything end to end, including a deliberate failure │ └── wire_your_own_feature.py swapping the stub for a real endpoint ├── ship_gate.py the composed gate, one exit code ├── pytest.ini test discovery for the *_runner.py naming └── requirements.txt ``` ## 关于 本仓库由 [Autonoma](https://getautonoma.com) 维护，作为相关博客文章的参考资料。Autonoma 构建能够直接根据你的代码库规划、执行和维护端到端测试的自主 AI agent。 有必要明确界定一下边界，因为这个仓库处于边界的一侧。这里的所有内容都是在评估响应：它正确吗、它安全吗、它有依据吗。这些都无法确认该功能在你的产品内部是否执行了正确的操作，而这正是 Autonoma 运行的层级：驱动真实应用程序并检查响应理应产生的状态。 如果这里的内容有错误、已过时或不清楚，请[提交一个 issue](https://github.com/Autonoma-Tools/how-to-qa-an-ai-feature/issues/new)。 ## 许可证 采用 [MIT 许证](./LICENSE)发布 © 2026 Autonoma Labs。

标签：Python, 大语言模型评测, 安全规则引擎, 开源框架, 持续集成, 无后门, 生成式AI, 索引, 质量保证, 逆向工具