lanerchenbuna/QueryForge

QueryForge 是一个本地优先、领域优先的 AI 数据分析平台，其构建围绕着一个核心理念： **生成的 SQL 应当像应用程序代码那样受到治理，而不是像普通文本那样被信任**。 用户首先创建或选择一个数据领域——例如零售、金融、产品，或者内置的 Anime Streaming（动漫流媒体）示例——然后接入该领域的数据，审查其语义契约，并在同一个治理边界内提出问题。 QueryForge 将该工作流与自然语言转 SQL、AST 级别的安全性、只读执行、多候选选择、修复预算以及完整的运行产物结合在一起。 ## 产品导览

## 为什么选择 QueryForge？ 大多数 NL2SQL 演示在模型输出查询后就停止了。QueryForge 则覆盖了完整的交付闭环： | 需求 | QueryForge 的方法 | | --- | --- | | 信任生成的 SQL | 使用 SQLGlot 解析并在执行前强制实施命名策略 | | 保持业务含义一致 | 在 YAML 中定义指标、维度、粒度和 Join Path | | 防止上下文泄露 | 将数据源、语义契约、策略和运行历史限制在选定的数据领域内 | | 从不完美的输出中恢复 | 在明确的预算内进行反思、修复和重试 | | 处理更复杂的问题 | 使用有边界的 schema 发现和并行 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。 ``` 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` 中设置一个 provider。已包含兼容 OpenAI 的、Claude、Gemini、Qwen、DeepSeek 和 GLM 的配置。 ``` LLM_PROVIDER=openai OPENAI_API_KEY=your-api-key OPENAI_MODEL=gpt-4.1-mini ``` Provider 默认值和环境变量映射位于 [`models.yml`](models.yml) 中。 ### 3. 运行内置示例 ``` queryforge --prepare-sample-data queryforge \ --database sample_data/anime_streaming/anime_streaming.sqlite \ --question "Which anime generated the most watch hours?" ``` 尝试一个多跳语义查询： ``` 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 "Compare watch completion and merchandise GMV by anime genre" ``` ### 探索 QueryForge Studio 该代码库包含一个完整的可视化工作区，用于创建和切换数据领域、接入领域拥有的数据、审查所需的语义层、提出受治理的问题、检查 SQL 和 Trust Trace（信任追踪）证据，以及审计领域范围内的运行历史。 ``` # 终端 1：QueryForge API python -m pip install -e ".[api]" queryforge --serve-api # 终端 2：QueryForge Studio make web-install make web-dev ``` 打开 。从 **Data Domains** 开始，选择内置的 Anime Streaming 示例或创建一个全新的领域，然后在该领域内添加数据。如果 Python API 处于离线状态，示例领域分析仍可通过确定性的演示响应进行探索。请参阅 [Studio 指南](docs/studio.md)。 ## 工作原理

公共生命周期被刻意保持得很小： ``` analysis → candidate → execution → completion → delivery ``` 特定角色的 agent 在这些阶段内运行。确定性的路由器负责选择路径；模型不控制安全边界。 ## SQL 治理 每个生成的查询都会经过一个可审计的 pipeline： ``` SQL candidate → SQLite AST parse → single read-only statement → table and column scope → dangerous-function checks → recursive CTE and cross-join checks → table, join, and LIMIT budgets → governed preview → execution-boundary revalidation ``` 一个策略可以很简单，比如： ``` 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 ``` 策略拒绝会在 SQLite 执行前返回一个结构化的 `SQL_SECURITY_ERROR`。 ## 语义层 QueryForge 的 YAML 语义模型为生成的 SQL 提供了原始 schema 无法提供的业务上下文： ``` metrics: - name: watch_hours description: Total valid viewing time in hours. 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 ``` 模型可以声明实体、维度、指标、粒度、关系、Join Path、扇出约束、操作元数据以及物理质量规则。 默认情况下，QueryForge 要求经过验证的模型；它会自动发现数据库旁边的模型，并拒绝仅基于 schema 的分析，除非调用者明确选择诊断逃生舱。 在 Studio 中，语义构建是领域优先且受控的： ``` Create/select domain → upload domain-owned sources → profile physical schema → confirm entity identity and grain → define dimensions, measures, metrics, and time → review relationships, cardinality, and Join Paths → classify sensitivity, ownership, policy, and quality → validate 100% of blocking checks → publish data + semantics atomically ``` 技术名称被视为证据，而非业务事实。新领域初始为空，绝不会继承 Anime 示例的实体或指标。 构建或增量刷新一个模型： ``` 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)，它会根据已审查的基线检查 schema、指标、关系、Join Path 和数据质量契约。 ### 内置示例领域：Anime Streaming Anime Streaming 是一个可直接运行的示例数据领域，而不是覆盖全产品的 schema。该数据集是专为 QueryForge 构建且完全合成的：**370,762 行**、**15 张表**、**30 个声明的关系**、**7 个受治理的 Join Path**，以及跨越内容、参与度、订阅、广告、社区和商品销售的 **11 项业务指标**。 ``` flowchart LR Studio[Studio] --> Anime[Anime] Genre[Genre] --- Bridge[Anime–Genre Bridge] --- Anime Anime --> Episode[Episode] --> Watch[Watch Session] User[User] --> Watch User --> Rating[Rating] --> Anime User --> Subscription[Subscription] Watch --> Ad[Ad Impression] User --> Order[Merch Order] --> Item[Order Item] Product[Merch Product] --> Item Anime --> Product User --> Follow[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 的情况下预览计划 ``` queryforge \ --plan-mode \ --question "Compare monthly watch hours by subscription tier" ``` ### 启用复杂执行配置文件 ``` queryforge \ --complexity-mode complex \ --parallel-candidates 3 \ --question "Explain completion-rate changes by genre, device, and membership tier" ``` ### 流式传输进度或创建报告 ``` queryforge --stream --question "List the top ten anime by watch hours" queryforge --report --question "Build a report for monthly engagement by genre" ``` ### 构建受治理的数据资产 ``` python -m pip install -e ".[assets]" python scripts/scaffold_data_asset.py \ --source events.csv \ --output events.assets.yml \ --owner engagement-analytics # 审查 semantic draft 并将 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 ``` python -m pip install -e ".[api]" queryforge --serve-api --api-host 127.0.0.1 --api-port 8000 ``` ``` curl -X POST http://127.0.0.1:8000/ask \ -H 'content-type: application/json' \ -d '{ "question": "List the ten anime with the highest completion rate", "database": "sample_data/anime_streaming/anime_streaming.sqlite" }' ``` ### 启动 MCP server ``` python -m pip install -e ".[mcp]" python -m queryforge.interfaces.mcp.server --transport stdio ``` ## 接口 | 入口 | 接入点 | 最适用于 | | --- | --- | --- | | Studio | `make web-dev` | 数据领域管理、可视化接入、语义编写和受治理的分析 | | CLI | `queryforge --question "..."` | 本地探索和工程工作流 | | REST | `POST /ask` 和 `POST /plan` | 应用程序集成 | | SSE | `POST /ask/stream` | 需要感知进度的客户端 | | MCP | `queryforge.interfaces.mcp.server` | IDE 和兼容 MCP 的助手 | | Gateway | `POST /gateway/webhook` | 稳定的用户/频道会话适配器 | | Artifacts | JSON, Vega-Lite, SVG, HTML | 审查、共享和审计 | ## 项目结构 ``` queryforge/ ├── cli.py # Installed CLI implementation ├── application/ # Transport-neutral service facade and resources ├── core/ # Configuration, schemas, and observability ├── data_assets/ # Ingestion, quality, lineage, and publication ├── domain/ # SQL policy, semantics, contracts, and skills ├── infrastructure/ # SQLite, model providers, storage, and tools ├── interfaces/ # CLI-adjacent API, MCP, and gateway adapters ├── orchestration/ # Router, role agents, lifecycle, and state └── workflow/ # NL2SQL nodes, selection, repair, and reporting evaluation/gold/ # Multi-domain NL2SQL evaluation cases sample_data/ # Ready-to-run SQLite datasets and semantic models web/ # QueryForge Studio and hosted persistence adapters scripts/ # Build, benchmark, evaluation, and acceptance tools tests/ # Unit, integration, boundary, and acceptance tests docs/ # Architecture and feature documentation .github/ # CI, semantic drift audit, and contribution templates ``` 依赖关系从接口和应用程序代码向内流向领域、基础设施和核心契约。 ## 质量与评估 运行完整的离线质量门禁： ``` python scripts/run_acceptance.py --full ``` 或者直接运行测试套件： ``` python -m unittest discover -s tests -q ``` 实时模型评估会报告执行成功率、语义等价性、策略精确率/召回率、延迟、预估成本以及候选方案选择带来的提升： ``` 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 上运行离线验收门禁。 ## 文档 | 主题 | 指南 | | --- | --- | | 架构 | [Agent 团队架构](docs/agent_team_architecture.md) | | 配置 | [配置参考](docs/configuration.md) | | Studio | [可视化工作区与语义接入](docs/studio.md) | | REST API | [API 参考](docs/api_reference.md) | | MCP | [MCP server](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) | | GitHub 发布 | [首次发布清单](docs/github_release.md) | | 文档索引 | [所有指南](docs/README.md) | ## 贡献与安全 源代码树已准备好进行 GitHub 审查和 CI。在公开发布之前，代码库所有者仍需选择并添加一个 `LICENSE`；我们不会代替他们假定任何许可证。 ## 范围与安全 QueryForge 的保证适用于其配置的 SQLite 执行边界。该项目目前**不**包含： - 生产级身份验证、授权、租户隔离或速率限制； - 持久化的分布式工作流恢复或 token 级别的取消； - PostgreSQL、MySQL、数据仓库、湖仓或流处理系统适配器； - Provider 归一化的计费或经过训练的模型生命周期。 请将 REST 和 MCP 传输保留在受控环境中。切勿提交 provider 密钥、生成的运行状态或包含敏感数据的本地数据库。 ## 路线图 - 超越 SQLite 的数据库适配器 - 一流的身份验证和租户策略边界 - 持久的工作流执行和取消 - 数据仓库目录集成 - 与 Provider 无关的使用量和成本核算 在选择代码库许可证后，欢迎贡献和设计讨论。

标签：DLL 劫持, Python, SQLite, Text-to-SQL, 代码示例, 大语言模型, 数据分析, 数据治理, 无后门, 逆向工具