Metadata-Version: 2.4
Name: AquaMind
Version: 0.0.4
Summary: LLM 应用功能与非功能一体化测试工具：并发负载下联动测量 TTFT/质量退化/成本，输出 SLO 双门禁报告
Author: hu-chenyu
License-Expression: MIT
Project-URL: Homepage, https://github.com/hu-chenyu/AquaMind
Project-URL: Repository, https://github.com/hu-chenyu/AquaMind
Keywords: llm,testing,evaluation,llm-testing,performance-testing,load-testing,quality-gate,slo,ttft,pytest,rag,agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.7
Requires-Dist: typer>=0.12
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == "openai"
Dynamic: license-file

# AquaMind

> **AquaMind——LLM 应用在并发阶梯负载下的质量退化测试工具。**
> 旗舰：并发阶梯实验 + 退化统计判定（S1-S4：bootstrap 置信区间/重复测量噪声基线/效应量/配对置换检验）+ 测量有效性校验（S5-S8：循环滞后（GIL 计时污染）自校准/协调遗漏/截尾分离/冷启动分离）——把"负载让质量掉多少"变成可统计判定、可复现、可门禁的结论；配套公开退化数据集。

[![CI](https://github.com/hu-chenyu/AquaMind/actions/workflows/ci.yml/badge.svg)](https://github.com/hu-chenyu/AquaMind/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

---

## 1. 一句话定位

**AquaMind 的旗舰是：并发阶梯负载下的质量退化统计判定 + S1-S8 统计/测量双重校验**——把"负载让质量掉多少"变成可统计判定、可复现、可门禁的结论；在此之上提供功能与非功能质量的一体化测试：

> **全项目方法论：约束下量化质量 → 门禁决策**——退化结论先过统计（S1-S4）与测量（S5-S8）双重校验，再由 SLO×质量双门禁裁定。

它在同一份测试资产上回答两类问题：

- **功能质量**：回答对不对？事实是否忠实？是否命中预期？——用精确匹配与 LLM-as-Judge 评分，批量跑分、进 CI 门禁；
- **非功能质量**：压力下还靠不靠谱？——并发阶梯上升时，同时量出 TTFT/ITL/百分位延迟/TPS/goodput、Judge 质量分退化曲线、token 成本变化，给出 SLO×质量双门禁报告。

**边界**：测的是 LLM **应用**（调用模型 API 或自部署端点的客服、RAG、智能体应用）的端到端体验，不做 GPU、KV Cache、推理框架层面的引擎调优。

```bash
pip install aquamind
```

---

## 2. 为什么不用现成工具：三者交叉的位置

| 工具类型 | 代表 | 流式延迟 | 并发负载 | 回答质量评分 | 负载下质量退化 |
|---|---|:---:|:---:|:---:|:---:|
| 推理引擎压测 | GuideLLM / NVIDIA AIPerf | ✅ TTFT/ITL/TPS | ✅ 并发阶梯、Pareto | ❌ 只测引擎不测内容 | ❌ |
| 通用压测 | Locust / JMeter / k6 | △ 需手写 SSE 解析 | ✅ | ❌ 无评分钩子 | ❌ |
| 功能评测框架 | Promptfoo / DeepEval / RAGAS | △ 可读 TTFT span | △ 仅并行加速跑分 | ✅ 指标/红队/报告 | ❌ 无退化实验设计 |
| **AquaMind** | — | ✅ | ✅ | ✅ | ✅ 同一并发阶梯下延迟、质量、成本三曲线联动 + 双门禁；**退化统计判定（S1-S4）+ 测量有效性（S5-S8）+ 公开退化数据集** |

补充事实：

- NVIDIA AIPerf 有 TPS/GPU 与 TPS/User 的 Pareto 分析，但对象是推理引擎，没有回答正确性维度；
- Promptfoo 2026 年加入了自适应限流与 trace 中的 TTFT 读取，但其并发只用于加速跑完评测，不做"并发升高 → 质量是否退化"的实验；
- 学术界对"压力下的质量退化"已有大规模验证：REST 压力测试框架覆盖主流开源与商用模型，发现压力条件下推理表现显著下降，且输出长度溢出并非退化的唯一原因（arXiv:2507.10541）；但尚无开源工具把它产品化成一份可复现、可统计判定的测试报告。
- AquaMind 的差异化不在"有没有并发"（DeepEval 已有 AsyncConfig、Promptfoo 已有限流 AIMD），而在把"负载下质量退化"做成可统计判定的实验：退化统计判定（S1-S4）+ 测量有效性（S5-S8），并配套公开退化数据集。

AquaMind 不声称发现了新现象，它做的是**把压测圈与评测圈两套分散指标第一次放进同一份报告**。

---

## 3. 六个功能模块

| # | 模块 | 核心能力 |
|---|---|---|
| 1 | **用例管理与批量执行** | YAML/JSON 用例（输入 + 预期/评分标准）；多模型适配层（OpenAI 兼容协议，DeepSeek/Qwen/GPT 等）；重试退避、超时降级、错误分类 |
| 2 | **评分器** | 精确匹配（正则/包含/关键词）+ LLM-as-Judge（0-1 分 + 理由）；附"同题多次运行分数波动区间"作为质量可信度提示 |
| 3 | **负载引擎与流式采集（旗舰）** | 并发阶梯、思考时间与 token 长度分布、ramp-up/down；逐 token SSE 计时（TTFT/ITL）；流式直方图、p50/p95/p99、TPS、goodput；429 退避与并发自整定；负载参数矩阵可追溯 |
| 4 | **性能-质量-成本联动（旗舰）** | 负载-质量相关性、质量退化曲线、尾延迟段请求质量分析、成本随负载变化、三曲线联动 |
| 5 | **SLO×质量双门禁报告** | SLO 阈值（延迟 + 错误率/超时率/限流率）× 质量阈值联合判定；CI 拦截；自包含 HTML（双曲线、内联 SVG、断网可开、可导出） |
| 6 | **轻量持久化** | SQLite 运行历史；两次运行版本对比；一条质量趋势线 |

**被测对象（SUT）层**：项目自带一个带检索增强的 demo 应用作为真实被测对象，并提供一个 mock SSE 服务器，用零成本方式稳定复现退化曲线（可控队列与超时）。报告中明确区分"受控实验（mock SUT）"与"真实端点观测"。

---

## 4. 路线图：六个里程碑

| 里程碑 | 主题 | 结束时可演示的产物 |
|---|---|---|
| **M1 底座** | 多模型适配层 + SSE 流式采集骨架 + 命令行 | 跑通一个模型，打印 TTFT/ITL 延迟数字 |
| **M2 功能基线** | 评分器 + 用例管理 + 批量执行 + 质量基线 | 跑 10 条用例，输出每条质量分 |
| **M3 负载引擎** | 负载模型 + 性能指标 + 限流自适应 + 参数矩阵 | 并发压测输出延迟百分位曲线 |
| **M4 联动分析** | 质量×性能联动 + 退化曲线 + 双门禁 + 报告升级 | 输出完整的"并发下质量退化"HTML 报告 |
| **M5 持久化与 SUT** | SQLite（FTS5）历史/对比 + 验证用 SUT（FTS5 检索）+ 真实端点观测（3 档×1） | 运行落库、版本对比、真实数据分区标注 |
| **M6 打磨交付** | 覆盖率 ≥80% + 中文文档 + ADR + 复盘文章 | 完整可交付项目 |

94 天核心开发期，之后按季度维护节奏推进；每个里程碑结束必须有可演示产物，新想法一律进 backlog，不动当前里程碑。

---

## 5. 非目标（明确不做）

- **推理引擎调优**：不做 GPU、KV Cache、vLLM/TensorRT 等底层性能分析与调度优化——那是研发与推理平台团队的职责；
- **平台化服务**：不做账号、权限、多人协作与集中式调度，库形态 + 命令行 + 可选 pytest 插件；
- **学术级裁判校准**：不做 κ/ECE/双标注/预注册（指裁判本身的人类对齐校准；退化判定的统计有效性 S1-S4 仍做，历史取舍见 ADR 与计划文档）；
- **红队/攻击语料库**：不做提示注入攻防产品化（该方向已有成熟工具）；
- **多模态**：本期只覆盖文本类 LLM 应用；
- **语义相似度评分**：不引入 embedding 重依赖，功能评分以精确匹配 + Judge 两种为限。

---

## 6. 项目状态

- 当前版本：**v0.0.3（占位包）** v1.0 计划已冻结，核心能力按 M1→M6 推进
- 源码：<https://github.com/hu-chenyu/AquaMind>
- 开发计划：[`docs/PROJECT-PLAN.md`](./docs/PROJECT-PLAN.md)（v1.0：定位、模块、里程碑、方法学与维护策略）
- 现阶段 v0.0.3 除版本号外暂无评测 API；命令行 `aquamind --help/version` 骨架可用，功能随里程碑交付

[MIT 许可证](./LICENSE) © 2026 hu-chenyu
