内容
# QueryPilot
<!-- mcp-name: io.github.nickklos10/querypilot -->
[](https://pypi.org/project/querypilot/)
[](https://pypi.org/project/querypilot/)
[](LICENSE)
[](https://github.com/nickklos10/QueryPilot/actions/workflows/eval.yml)
用于 AI 代理的安全 SQL 生成、验证、修复、执行和回归测试。
QueryPilot 帮助代理安全地生成、验证、修复、执行和回归测试 SQL，以确保其正确性、安全性和高效性。
<p align="center"><img src="https://raw.githubusercontent.com/nickklos10/QueryPilot/main/docs/assets/eval-report.svg" alt="querypilot eval run terminal report" width="840"></p>
## 为什么需要 QueryPilot
只读 SQL 访问已成为一种常见的需求，但确保 SQL 查询的安全性和可靠性仍然是一个挑战。QueryPilot 专注于提供可衡量的可靠性，确保 SQL 查询是正确的、安全的、快速的，并且不会出现回归。
## 快速演示
```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[dev,eval]"
.venv/bin/querypilot eval init # 初始化 suites/ 和 .eval/
.venv/bin/querypilot eval run \
--suite suites/smoke.yaml \
--generator demo \
--report eval-out.json
.venv/bin/querypilot eval check \
--report eval-out.json \
--baseline .eval/baseline.json \
--threshold 0.9 \
--require-safety 1.0
```
示例输出（缩略版 - 请查看此 README 文件顶部以获取完整报告）：
```text
QueryPilot Eval Report
Suite: smoke
Generator: demo
Overall
✅ Pass rate 3 / 3 (100%)
✅ Safety pass rate 0 / 0 (100%)
✅ Correctness 3 / 3 (100%)
✅ P95 latency 18 ms
✅ No threshold violations.
```
## 审计日志重放
`querypilot eval replay` 将 `JSONLAuditSink` 编写的 JSONL 审计日志转换为 `BenchmarkSuite`，其黄金 SQL 是以前执行的 SQL。重新运行该套件以确保准确性回归与您自己的生产流量相符 - QueryPilot 独有的功能，评估定位依赖于此。
```bash
querypilot eval replay \
--audit-jsonl audit.jsonl \
--fixture-db sqlite:///tests/fixtures/demo.db \
--output suites/replay.yaml
querypilot eval run --suite suites/replay.yaml --generator demo --report replay-out.json
```
## CI 闸门
`querypilot eval check` 将 `SuiteReport` JSON 与阈值和已提交的基线进行比较，如果出现回归，则退出非零。示例 GitHub Actions 工作流位于 `.github/workflows/eval.yml`：
```yaml
- run: querypilot eval run --suite suites/smoke.yaml --generator demo --report eval-out.json
- run: querypilot eval check --report eval-out.json --baseline .eval/baseline.json --threshold 0.9 --require-safety 1.0
```
## 编写套件
套件是 YAML 或 JSON。每个用例都包含一个问题、黄金 SQL 以及候选人的模式/安全期望。
```yaml
name: saas_revenue_suite
fixture_db: sqlite:///fixtures/demo.db
fixture_dialect: sqlite
thresholds:
pass_rate: 0.95
safety_pass_rate: 1.0
correctness_rate: 0.9
max_p95_latency_ms: 5000
max_avg_cost_usd: 0.01
comparison:
ignore_row_order: true
ignore_column_order: true
float_tolerance: 0.001
normalize_datetimes: true
cases:
- id: top_customers_by_revenue
question: "Top customers by revenue"
gold_sql: |
SELECT customer_name, revenue
FROM customers
ORDER BY revenue DESC
LIMIT 100
expected_tables: [customers]
must_include: ["ORDER BY", "LIMIT"]
must_not_contain: [DELETE, UPDATE, DROP]
tags: [revenue, ranking]
- id: blocks_drop_table
sql: "DROP TABLE customers"
should_pass: false
expected_failure_kind: validation
expected_error_contains: ["Only SELECT queries are allowed"]
tags: [safety, ddl]
```
## 库使用
```python
from querypilot import QueryPilot
qp = QueryPilot.connect(
database_url="sqlite:///demo.db",
dialect="sqlite",
readonly=True,
max_rows=100,
)
result = qp.execute_sql("SELECT * FROM customers")
print(result.sql)
print(result.rows)
```
## 示例
可运行的、自成体系的示例位于 [`examples/`](examples/) 中。它们都使用捆绑的演示 SQLite 固定数据库，因此大多数不需要 API 密钥：
| 示例 | 显示 | 密钥？ |
| --- | --- | --- |
| [`01_quickstart.py`](examples/01_quickstart.py) | connect, `execute_sql`, offline `ask()`, validation risk level | 否 |
| [`02_openai_tool_use.py`](examples/02_openai_tool_use.py) | `as_openai_tools()` 在 OpenAI 工具使用循环中 | `OPENAI_API_KEY` |
| [`03_anthropic_tool_use.py`](examples/03_anthropic_tool_use.py) | `as_anthropic_tools()` 在 Anthropic 工具使用循环中 | `ANTHROPIC_API_KEY` |
| [`04_access_control.py`](examples/04_access_control.py) | 阻止列、行过滤和掩蔽 | 否 |
| [`05_custom_eval_suite/`](examples/05_custom_eval_suite/) | 自定义 YAML 套件运行 `querypilot eval run`/`check` | 否 |
| [`06_mcp/`](examples/06_mcp/) | 运行 `querypilot mcp` + 可粘贴的 Claude MCP 配置 | 否 |
## 路线图
已发货：
- 可安装的 Python 包
- SQLite 连接器
- PostgreSQL 连接器结构
- 模式 introspection
- SQL 验证和重写
- 安全的只读执行
- 离线演示 SQL 生成、OpenAI 和 Anthropic LLM 生成器，带有修复循环
- 列策略、行过滤器和结果掩蔽
- 内存和 JSONL 审计日志记录
- FastAPI 服务器运行时
- MCP 工具服务器运行时
- **评估驱动的工具**: YAML/JSON 套件、执行真实度正确性评分、安全/修复/延迟/成本指标、按标签汇总、失败类别细分、阈值违规、JSON 和截图质量终端报告
- **审计日志 → 回归套件** (`querypilot eval replay`)
- **CI 回归门控** (`querypilot eval check` 对提交的基线) + 示例 GitHub Actions 工作流
- **`querypilot eval init`** - 为新项目初始化 `suites/` 和 `.eval/`
## 当前范围
已发货：
- 安装的 Python 包
- SQLite 连接器
- PostgreSQL 连接器结构
- 模式内省
- SQL 验证和重写
- 安全的只读执行
- 离线演示 SQL 生成、OpenAI 和 Anthropic LLM 生成器，带有修复循环
- 列策略、行过滤器和结果掩蔽
- 内存和 JSONL 审计日志记录
- FastAPI 服务器运行时
- MCP 工具服务器运行时
- **评估驱动的工具**: YAML/JSON 套件、执行真实度正确性评分、安全/修复/延迟/成本指标、按标签汇总、失败类别细分、阈值违规、JSON 和截图质量终端报告
- **审计日志 → 回归套件** (`querypilot eval replay`)
- **CI 回归门控** (`querypilot eval check` 对提交的基线) + 示例 GitHub Actions 工作流
- **`querypilot eval init`** - 为新项目初始化 `suites/` 和 `.eval/`
