QueryForge

<div align="center"> <img src="docs/assets/queryforge-hero.svg" width="100%" alt="QueryForge — 受管控的 AI 数据分析，从自然语言到可信的 SQL"> # QueryForge ### 受管控的 AI 数据分析，从自然语言到可审计的 SQL 将业务问题转化为安全、可追溯的 SQLite 查询 — 通过语义层、策略执行、有限恢复和生产环境友好的交付接口。 [简体中文](README.zh-CN.md) · [快速开始](#快速开始) · [架构](#工作原理) · [文档](#文档)      </div> --- QueryForge 是一个本地优先的 AI 数据分析平台，围绕一个原则构建： **生成的 SQL 应该像应用程序代码一样受到管控，而不是像散文一样被信任**。 它将自然语言转换为 SQL 与语义合约、AST 级安全、只读执行、多候选选择、修复预算和完整的运行工件相结合。结果是一个可用的、可检查的和难以滥用的 AI 数据系统参考实现。 > QueryForge 目前针对 SQLite 和受控环境。它是一个投资级的参考架构，而不是多租户分析服务。 ## 产品游览 <div align="center"> <img src="docs/assets/queryforge-studio-overview.png" width="100%" alt="QueryForge Studio 概览，具有语义健康、业务指标和参与度趋势"> _{工作区概览 — 实时语义健康、受管控的指标和 anime 平台活动。} </div> <br> <div align="center"> <img src="docs/assets/queryforge-studio-semantic.png" width="49%" alt="QueryForge 语义工作室实体关系图和合约编辑器"> <img src="docs/assets/queryforge-studio-analysis.png" width="49%" alt="QueryForge 受管控的分析结果，包含生成的 SQL 和信任轨迹"> <br> _{语义工作室 · 受管控的分析，包含可审计的 SQL 和信任轨迹} </div> ## 为什么选择 QueryForge？ 大多数 NL2SQL 演示在模型发出查询后停止。QueryForge 涵盖了整个交付循环： | 需求 | QueryForge 方法 | | --- | --- | | 信任生成的 SQL | 使用 SQLGlot 解析并在执行前强制执行命名策略 | | 保持业务含义一致 | 在 YAML 中定义指标、维度、粒度级别和连接路径 | | 从不完美的输出中恢复 | 在明确的预算内反射、修复和重试 | | 处理更难的问题 | 使用有限的模式发现和并行 SQL 候选项 | | 跟踪发生了什么 | 保留运行状态、策略决策、质量证据和工件 | | 与其他工具集成 | 通过 CLI、REST/SSE、MCP、网关、JSON、图表和 HTML 报告公开 | | 从原始数据开始 | 从 CSV、Parquet 和分页 JSON API 构建受管控的 SQLite 资产 | ## 亮点 - **深度防御** — 在执行前检查候选项，并在数据库边界重新验证。 - **语义合约** — YAML 模型描述业务指标、实体、关系、基数、所有权、SLA、敏感性和质量规则。 - **自适应工作流** — 简单问题保持快速；复杂问题可以激活有限的工具循环和并发候选选择。 - **默认只读** — 正常分析以只读模式打开 SQLite 数据库，并拒绝写入或管理 SQL。 - **多个交付界面** — 通过 CLI、REST/SSE、MCP 或 webhook 网关使用相同的应用程序服务。 - **可复制的评估** — 仓库包括离线验收检查和 120 个案例的 NL2SQL 金标准。 ## 快速开始 ### 1. 安装 要求：**Python 3.11 或 3.12** 和 SQLite。 ```bash python3.11 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -e . cp .env.example .env ``` ### 2. 配置模型 在 `.env` 中设置一个提供商。包含 OpenAI 兼容、Claude、Gemini、Qwen、DeepSeek 和 GLM 配置。 ```dotenv LLM_PROVIDER=openai OPENAI_API_KEY=您的 API 密钥 OPENAI_MODEL=gpt-4.1-mini ``` 提供商默认值和环境变量映射位于 [`models.yml`](models.yml) 中。 ### 3. 运行捆绑示例 ```bash queryforge --prepare-sample-data queryforge \ --database sample_data/anime_streaming/anime_streaming.sqlite \ --question "哪些动漫产生了最多的观看小时？" ``` 尝试多跳语义查询： ```bash queryforge \ --database sample_data/anime_streaming/anime_streaming.sqlite \ --semantic-model sample_data/anime_streaming/semantic_model.yml \ --sql-policy sample_data/anime_streaming/sql_policy.yml \ --question "比较观看完成度和动漫类型的商品 GMV" ``` ### 探索 QueryForge 工作室 仓库现在包含一个完整的可视化工作区，用于数据上线、审查所需的语义层、提出受管控的问题、检查 SQL 和信任轨迹证据以及审计运行历史。 ```bash # 终端 1：QueryForge API python -m pip install -e ".[api]" queryforge --serve-api # 终端 2：QueryForge 工作室 make web-install make web-dev ``` 打开 <http://localhost:3000>。如果 Python API 离线，界面会自动使用确定性演示响应，以便每个屏幕仍然可探索。参见 [工作室指南](docs/studio.md)。 ## 工作原理 <div align="center"> <img src="docs/assets/queryforge-flow.svg" width="100%" alt="QueryForge 运行时架构动画"> </div> 公共生命周期故意保持较小： ```text 分析 → 候选项 → 执行 → 完成 → 交付 ``` 角色特定的代理在这些阶段内运行。确定性路由器选择路径；模型不控制安全边界。 ## SQL 管控 每个生成的查询都通过可审计的管道： ```text SQL 候选项 → SQLite AST 解析 → 单个只读语句 → 表和列范围 → 危险函数检查 → 递归 CTE 和交叉连接检查 → 表、连接和 LIMIT 预算 → 受管控的预览 → 执行边界重新验证 ``` 策略可以小到： ```yaml version: 1 name: anime_streaming allowed_tables: - fact_watch_session - dim_anime require_limit: true max_limit: 500 max_tables: 2 max_joins: 1 allow_cross_join: false ``` 策略拒绝返回结构化的 `SQL_SECURITY_ERROR`，在 SQLite 执行前。 ## 语义层 QueryForge 的 YAML 语义模型为生成的 SQL 提供业务上下文，而原始模式无法提供： ```yaml metrics: - name: watch_hours description: 有效观看时间（小时）。 entity: watch_session aggregation: sum expression: SUM(fact_watch_session.watch_seconds) / 3600.0 default_filters: - fact_watch_session.is_valid = 1 owner: audience-analytics sensitivity: internal ``` 模型可以声明实体、维度、指标、粒度级别、关系、连接路径、扇出约束、操作元数据和物理质量规则。QueryForge 默认要求验证模型；它会自动发现数据库旁边的模型，除非调用者明确选择诊断逃生舱。 构建或增量刷新一个： ```bash python scripts/build_semantic_model.py \ --database warehouse.sqlite \ --output warehouse.semantic.yml \ --owner data-platform ``` 生成的报告将高置信度的物理证据与需要业务审查的定义分开。参见 [语义层创作](docs/semantic_authoring.md) 和 [语义合约](docs/semantic_contracts.md)。 仓库还包含一个周一早上的 [语义漂移工作流](.github/workflows/semantic-weekly.yml)，该工作流检查模式、指标、关系、连接路径和数据质量合约是否符合审查的基线。 ### 动漫平台展示 捆绑的数据集是专门为 QueryForge 构建的，是完全合成的：**370,762 行**、**15 张表**、**30 个声明的关系**、**7 个受管控的连接路径** 和 **11 个业务指标**，涵盖内容、参与度、订阅、广告、社区和商品。 ```mermaid flowchart LR Studio[工作室] --> Anime[动漫] Genre[类型] --- Bridge[动漫-类型桥] --- Anime Anime --> Episode[剧集] --> Watch[观看会话] User[用户] --> Watch User --> Rating[评分] --> Anime User --> Subscription[订阅] Watch --> Ad[广告印象] User --> Order[商品订单] --> Item[订单商品] Product[商品] --> Item Anime --> Product User --> Follow[用户关注] --> User classDef dimension fill:#111827,stroke:#7c3aed,color:#f9fafb; classDef fact fill:#172554,stroke:#22d3ee,color:#f9fafb; class Anime,Studio,Genre,Episode,User,Product,Bridge dimension; class Watch,Rating,Subscription,Ad,Order,Item,Follow fact; ``` 参见 [数据集合约](sample_data/anime_streaming/README.md)，检查 [语义模型](sample_data/anime_streaming/semantic_model.yml)，或使用 `python sample/generate_anime_streaming.py` 重新生成数据库和可选的 CSV 导出。 ## 常见工作流 ### 预览计划而不执行 SQL ```bash queryforge \ --plan-mode \ --question "比较按订阅层划分的每月观看小时数" ``` ### 启用复杂执行配置文件 ```bash queryforge \ --complexity-mode complex \ --parallel-candidates 3 \ --question "按类型、设备和会员层解释完成率变化" ``` ### 流式传输进度或创建报告 ```bash queryforge --stream --question "列出观看小时数最高的十部动漫" queryforge --report --question "为按类型的每月参与度生成报告" ``` ### 构建受管控的数据资产 ```bash python -m pip install -e ".[assets]" python scripts/scaffold_data_asset.py \ --source events.csv \ --output events.assets.yml \ --owner engagement-analytics # 审查语义草稿并设置 semantic_model.reviewed：true。 python scripts/build_data_assets.py \ --config sample_data/data_assets/assets.yml \ --publish-database .queryforge/demo/analytics.sqlite ``` 每个上传的资产都必须携带实体语义。数据和语义同时发布，因此失败的指标、关系、粒度级别或质量合约会回滚整个上传。 ### 启动 REST API ```bash python -m pip install -e ".[api]" queryforge --serve-api --api-host 127.0.0.1 --api-port 8000 ``` ```bash curl -X POST http://127.0.0.1:8000/ask \ -H 'content-type: application/json' \ -d '{ "question": "列出完成率最高的十部动漫", "database": "sample_data/anime_streaming/anime_streaming.sqlite" }' ``` ### 启动 MCP 服务器 ```bash python -m pip install -e ".[mcp]" python -m queryforge.interfaces.mcp.server --transport stdio ``` ## 接口 | 界面 | 入口点 | 最适合 | | --- | --- | --- | | 工作室 | `make web-dev` | 可视化上线、语义创作和受管控的分析 | | CLI | `queryforge --question "..."` | 本地探索和工程工作流 | | REST | `POST /ask` 和 `POST /plan` | 应用程序集成 | | SSE | `POST /ask/stream` | 进度感知客户端 | | MCP | `queryforge.interfaces.mcp.server` | IDE 和 MCP 兼容的助手 | | 网关 | `POST /gateway/webhook` | 稳定的用户/通道会话适配器 | | 工件 | JSON、Vega-Lite、SVG、HTML | 审查、共享和审计 | ## 项目结构 ```text queryforge/ ├── cli.py # 已安装的 CLI 实现 ├── application/ # 传输中立的服务外壳和资源 ├── core/ # 配置、模式和可观察性 ├── data_assets/ # 摄取、质量、血统和发布 ├── domain/ # SQL 策略、语义、合约和技能 ├── infrastructure/ # SQLite、模型提供者、存储和工具 ├── interfaces/ # CLI 邻近 API、MCP 和网关适配器 ├── orchestration/ # 路由器、角色代理、生命周期和状态 └── workflow/ # NL2SQL 节点、选择、修复和报告 evaluation/gold/ # 多领域 NL2SQL 评估案例 sample_data/ # 即用型 SQLite 数据集和语义模型 web/ # QueryForge 工作室和托管持久性适配器 scripts/ # 构建、基准测试、评估和验收工具 tests/ # 单元、集成、边界和验收测试 docs/ # 架构和功能文档 .github/ # CI、语义漂移审计和贡献模板 ``` 依赖关系从接口和应用程序代码流入领域、基础设施和核心合约。 ## 质量和评估 运行完整的离线质量门控： ```bash python scripts/run_acceptance.py --full ``` 或直接运行测试套件： ```bash python -m unittest discover -s tests -q ``` 实时模型评估报告执行成功率、语义等价性、策略精度/召回率、延迟、估计成本和候选选择提升： ```bash python scripts/evaluate_sql.py \ --cases evaluation/gold/nl2sql_multidomain.jsonl \ --model-provider openai \ --output .queryforge/evaluations/openai.json ``` CI 在 Python 3.11 和 3.12 上运行离线验收门控。 ## 文档 | 主题 | 指南 | | --- | --- | | 架构 | [代理团队架构](docs/agent_team_architecture.md) | | 配置 | [配置参考](docs/configuration.md) | | 工作室 | [可视化工作区和语义上线](docs/studio.md) | | REST API | [API 参考](docs/api_reference.md) | | MCP | [MCP 服务器](docs/mcp_server.md) | | 语义层 | [语义合约](docs/semantic_contracts.md) | | 语义创作 | [构建、审查和要求语义模型](docs/semantic_authoring.md) | | 数据资产 | [数据资产构建](docs/data_assets.md) | | 评估 | [NL2SQL 评估](docs/nl2sql_evaluation.md) | | 报告 | [报告工件](docs/report_artifact.md) | | 主题范围 | [主题树](docs/subject_tree.md) | | 验证 | [最终验收](docs/phase2_final_acceptance.md) | | GitHub 发布 | [首次发布检查清单](docs/github_release.md) | | 文档索引 | [所有指南](docs/README.md) | ## 贡献和安全 - [贡献指南](CONTRIBUTING.md) - [安全策略](SECURITY.md) - [行为准则](CODE_OF_CONDUCT.md) - [变更日志](CHANGELOG.md) 源代码树已准备好进行 GitHub 审查和 CI。仓库所有者仍需要在公共发布前选择并添加 `LICENSE`；在其代表下未假设任何许可。 ## 范围和安全 QueryForge 的保证适用于其配置的 SQLite 执行边界。该项目当前不包括： - 生产身份验证、授权、租户隔离或速率限制； - 持久分布式工作流恢复或令牌级取消； - PostgreSQL、MySQL、数据仓库、湖仓或流系统适配器； - 提供者归一化计费或训练模型生命周期。 在受控环境中保留 REST 和 MCP 传输。不要提交提供者密钥、生成的运行状态或包含敏感数据的本地数据库。 ## 路线图 - 超出 SQLite 的数据库适配器 - 一流身份验证和租户策略边界 - 持久工作流执行和取消 - 仓库目录集成 - 提供者独立的使用和成本核算 在选择存储库许可证后，欢迎贡献和设计讨论。