Forge

面向 Data Agent 的开源可信数据运行时：让 AI 辅助的数据查询可约束、可审核、可执行、可追溯。

Forge 位于上游 Agent 与数据库之间。它接收 Direct SQL 或受约束的 Forge JSON 候选，通过 Registry、确定性 SQL 编译、只读与权限校验、人工审核、Evidence 和 Audit 降低静默错误。它不是只把自然语言转成 SQL 的 wrapper，也不把“模型生成了 SQL”等同于“查询可信”。

English README · 贡献指南 · 文档索引

30 秒理解 Forge

当前已有的核心能力：

• Forge JSON 受约束中间表示与确定性 SQL 编译；
• Direct SQL / Forge JSON 统一候选、QueryRun 审核和执行链；
• Registry 结构与语义约束、关系和粒度校验；
• 只读 SQL、字段/表范围、审批 hash、超时和结果上限；
• SQLite、PostgreSQL、MySQL 的自动化兼容性检查；
• 可回放的准确率 Benchmark、Exact Result 比较和失败诊断。

项目状态：early-stage，actively iterating。 当前适合评估、贡献和带人工审核/只读账号的受控部署，不代表功能完备、开放世界准确或大规模高可用。最新完整 500-case BIRD 运行中，Forge EA 为 45.4%，Direct SQL 为 56.4%；历史 Spider2-Lite SQLite 子集 EA 仍为 9.2%。这些结果受数据集、模型、Provider、Prompt、Registry 与运行配置约束，不能外推为普遍能力。详见 当前项目状态 与 Benchmark 边界。

快速开始

# 1. 克隆 & 安装
git clone https://github.com/shisuidata/Forge
cd Forge
bash scripts/bootstrap-dev.sh

# 2. 配置（填入 LLM_API_KEY + EMBED_API_KEY）
cp .env.example .env

# 3. 一键启动 Demo（生成 200 表数仓 + 同步 Registry + 跑通测试）
bash scripts/demo-setup.sh

# 4. 启动服务
uvicorn main:app --host 0.0.0.0 --port 8000  # Web UI + API

Docker 开发方式（自带 PostgreSQL，热重载）：

docker compose up
# 访问 http://localhost:8000/admin

生产交付方式：

cp .env.production.example .env.production
docker compose -f docker-compose.prod.yml --env-file .env.production up -d --build
forge doctor --profile prod
bash scripts/production-smoke.sh

生产部署必须使用数据库只读账号，并确认 /health/readiness 无 fail 项。详见 生产交付部署说明。

接入自己的数据库：

# 修改 .env 中的 DATABASE_URL，然后同步 schema
forge sync --db postgresql://user:pass@host/db
# 或写入指定 Registry 路径
forge sync --db "$DATABASE_URL" --out registry/data/schema.registry.json

使用火山方舟 Ark（OpenAI 兼容接口）：

LLM_PROVIDER=openai
LLM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
LLM_MODEL=doubao-seed-2-1-pro-260628
LLM_API_KEY=你的火山方舟 API Key

运行测试：

# 编译器 + API 测试（本地，无需服务运行）
pytest tests/ -v

# Playwright E2E 测试（需服务运行）
pip install playwright && playwright install chromium
FORGE_BASE_URL=http://localhost:8000 pytest tests/test_e2e.py -v

工作原理

flowchart LR
    NL["自然语言"]

    subgraph forge["Forge 管道"]
        direction TB
        REG["Registry<br/>结构层 + 语义层"]
        RETRIEVER["SchemaRetriever<br/>向量检索 / BM25 降级"]
        LLM["LLM<br/>Structured Output"]
        JSON["Forge JSON<br/>有约束的中间表示"]
        COMPILER["确定性编译器"]
        SQL["SQL"]
    end

    DB["数据库"]
    RESULT["结果集"]

    NL --> RETRIEVER
    REG --> RETRIEVER
    RETRIEVER -->|"top-k 相关表"| LLM
    LLM --> JSON
    JSON --> COMPILER
    COMPILER --> SQL
    SQL --> DB
    DB --> RESULT

自然语言经 Registry 语义注入后，由 LLM 生成结构化的 Forge JSON，再由确定性编译器翻译为 SQL。在 Provider 严格执行动态 JSON Schema 的字段上，非法候选可在生成阶段被阻止；表达式透传、兼容降级路径、业务口径和算法选择仍需校验、审核与测试。用户审核的 SQL 和执行的 SQL 是同一份。

从产品价值、核心原理到生产落地的系统讲解，见 Forge 完整架构教材；快速参考见 工作原理与 DSL 能力。

当前状态

不同数据集、模型、Provider、Prompt、Registry、重试策略和评价器的结果不可直接横向比较。详见 基准测试详情。

已落地功能

项目结构

forge/
  ├── schema.json          — Forge DSL 格式定义（JSON Schema）
  ├── compiler.py          — 确定性编译器：Forge JSON → SQL
  ├── retriever.py         — Schema 向量检索器（四层召回 + ACL 过滤）
  ├── executor.py          — SQL 执行器
  ├── lint.py              — 业务/字段/结果契约检查
  ├── cache.py             — 查询缓存（精确 + 模糊匹配）
  ├── chart.py             — 图表生成（ECharts）
  └── cli.py               — CLI 入口（compile / sync / doctor）

agent/
  ├── agent.py             — Agent 调度（查询 / 指标定义 / 缓存反馈）
  ├── llm.py               — LLM 客户端（RAG + ACL + 约定注入）
  ├── pipeline.py          — Pipeline 引擎（分析 / 可视化 / 报告）
  ├── db.py                — 数据库抽象层（SQLite / PostgreSQL）
  ├── tenant.py            — 多租户（org / team / user / ACL）
  ├── knowledge.py         — 五通道知识收集框架
  └── memory/
      ├── ems.py           — Episodic Memory Store（对话历史）
      ├── smp.py           — Semantic Memory Pool（业务知识）
      └── wmb.py           — Working Memory Buffer（当前上下文）

web/
  ├── router.py            — FastAPI 路由（Web UI + API + execute-raw）
  ├── auth.py              — HMAC-SHA256 Cookie + API Key 认证
  └── templates/           — Jinja2 模板（Chat + Dashboard + 11 个 Admin 页面）

registry/
  ├── sync.py              — forge sync：直连数据库生成结构层
  ├── staging_sync.py      — 用户确认规则合并入 Registry
  └── data/                — 生产 Registry 路径（schema / metrics / disambiguations / conventions）

scripts/
  └── seed_mock_data.py    — Mock 数据填充（团队/用户/审计/会话/知识）

tests/
  ├── conftest.py          — 共享 fixtures（app / client / auth_client）
  ├── test_compiler*.py    — 编译器单元测试（118 个用例）
  ├── test_api.py          — API 端点测试（26 个用例）
  ├── test_e2e.py          — Playwright E2E 测试（22 个用例）
  ├── test_docs_links.py   — 公开文档本地链接检查
  ├── accuracy/            — 自有 40 题基准（当前推荐 Method AI）
  └── spider2/             — Spider2-Lite SQLite 子集（123 题）

文档

开发日志

真实的建造记录，包括走错的路、自我怀疑的时刻，和偶尔出现的顿悟。

参与维护

贡献入口与复现要求见 CONTRIBUTING.md。shisuidata/Forge 是项目主仓库；仓库历史中出现的 rockythink 与 shisuidata 标识属于同一维护者/团队上下文。

License

Forge 使用 Apache License 2.0。

官网

website/ 是 Forge 的 Astro + Starlight 对外站点，用于承载快速开始、概念说明、基准测试和商业化 PoC 叙事：

cd website
npm install
npm run build