QueryWeaver：图谱驱动的自然语言转 SQL 开源工具

GitHub: https://github.com/FalkorDB/QueryWeaver | 许可: AGPL-3.0 | 语言: Python / TypeScript | Stars: 1032 | 分支: staging

---

一、项目起源与行业背景

数据库是现代应用的神经中枢，但 SQL 语言的门槛将绝大多数业务人员挡在门外。Text2SQL（自然语言转 SQL）赛道已经拥挤多年，从早期的规则映射到 GPT-3 的 few-shot 提示，再到 Claude/GPT-4 的强推理能力，经历了多次范式跃迁。然而大多数 Text2SQL 工具存在一个共同缺陷：它们只看到表结构，看不到表与表之间的语义关系——外键在哪里、哪些列代表同一种实体、聚合查询应该选哪个维度表，这些"隐性知识"在 ER 图里存在，在 CREATE TABLE 语句里却消失了。

QueryWeaver 的出现正是为了填补这个空白。它由 FalkorDB 团队开发——FalkorDB 本身就是一个基于 Redis 的图数据库项目，在图数据领域积累深厚。团队将图数据库的推理能力引入 Text2SQL 流程：用 FalkorDB 作为"数据库的数据库"，先把目标数据库的 schema（表结构、列类型、外键关系、样本值）整体抽取出来存入图谱，再在查询时利用图谱进行多跳推理，精确锁定最相关的表和列，而不是靠 LLM 盲目猜测。

---

二、核心功能与使用场景

2.1 图谱增强的 Schema 理解

QueryWeaver 的独特之处在于两层 schema 表示：

• 原始层：目标数据库（PostgreSQL / MySQL / Snowflake）的实际表结构
• 图谱层：将原始 schema 抽取后存入 FalkorDB，构建表-列节点图，外键关系建模为图边

这个图谱在首次连接数据库时自动构建，之后每次查询都在图谱上做相关性检索。当用户问"显示上个月销量超过 10 万的客户"时，图谱能准确识别 orders 表的 amount 列、customers 表的 created_at 和 name 列，以及两者之间的 JOIN 路径——而不是把整个数据库里所有表都扔给 LLM，让它自己去猜。

2.2 多 Agent 协作管道

QueryWeaver 的查询管道由多个专业化 Agent 组成，每个 Agent 各司其职：

Agent	职责	输入	输出
RelevancyAgent	判断问题是否与数据库相关	用户问题 + schema 描述	On-topic / Off-topic + 原因
AnalysisAgent	生成 SQL 查询	用户问题 + 相关表 + schema	SQL 语句 + 置信度 + 缺失信息
HealerAgent	SQL 执行失败后自愈	错误信息 + schema + 原始问题	修正后的 SQL + 执行结果
FollowUpAgent	信息不足时追问	缺失信息描述	追问话术
ResponseFormatterAgent	格式化结果	SQL 结果 + AI 响应	用户友好的自然语言回复

这套多 Agent 架构的价值在于容错分离：Relevancy 检查避免了无效查询浪费 LLM token，Healer 的自愈机制将 SQL 错误恢复率大幅提升，Analysis 和 Response 是核心生成步骤。

2.3 多 LLM 提供商支持（LiteLLM）

通过 litellm 库，QueryWeaver 支持 OpenAI、Anthropic Claude、Google Gemini、Azure OpenAI、Ollama、Cohere 等多种 LLM 后端。配置文件 .env.example 中有详细的环境变量说明，用户只需设置对应的 API Key 即可切换模型，无需修改代码。

2.4 MCP（Model Context Protocol）支持

QueryWeaver 原生支持 MCP，可以通过 HTTP 端点（/mcp）暴露 Text2SQL 操作，供其他 MCP 兼容客户端（如 Claude Desktop）调用。这意味着 QueryWeaver 可以作为 AI 助手的"数据库工具"，在对话中实时查询数据库——这比直接让 LLM 连接数据库更安全、更可控。

2.5 对话记忆（可选）

通过 graphiti-core（Graphiti）实现对话记忆功能。QueryWeaver 会在 FalkorDB 中记录每次查询的意图、使用的表/列、成功或失败的模式，下次查询类似问题时可以利用历史上下文，减少 LLM 的幻觉概率。

---

三、技术架构深度解析

3.1 目录结构

queryweaver/         # Python SDK 核心包（可 pip install）
  __init__.py        # 包入口，导出 QueryWeaver 类
  client.py          # SDK 主类，封装 query/connect_database/get_schema 等方法
  connection.py      # FalkorDB 连接管理（连接池、URL 解析）
  models.py          # 数据模型（QueryResult、SchemaResult 等）

api/                 # FastAPI 服务端（不在 pip 包中，通过 Docker 或源码运行）
  core/
    text2sql.py      # 核心异步管道 run_query()，驱动整个 Text2SQL 流程
    pipeline.py      # 管道辅助函数（SQL 消毒、破坏性操作检测、内存保存）
    schema_loader.py # 数据库 schema 抽取（postgres/mysql/snowflake各有专属 loader）
    result_models.py # 查询结果模型（QueryResult、QueryMetadata、QueryAnalysis）
  agents/
    analysis_agent.py      # 核心分析 Agent，prompt 约 400 行，Claude 深度参与
    healer_agent.py        # SQL 自愈 Agent，接收错误信息 + schema 生成修正 SQL
    relevancy_agent.py     # 问题相关性判断
    follow_up_agent.py    # 追问生成
    response_formatter_agent.py  # 结果格式化
  loaders/
    base_loader.py         # 抽象基类，定义接口
    postgres_loader.py     # PostgreSQL 专属 schema 抽取（约 23KB）
    mysql_loader.py        # MySQL 专属 schema 抽取（约 19KB）
    snowflake_loader.py    # Snowflake 专属（约 26KB）
    graph_loader.py       # FalkorDB 图谱管理
  graph.py          # 图谱操作（find 相关表、get_db_description 等）
  config.py         # LLM 提供商自动检测 + prompt 模板

app/                # React 前端（TypeScript + Vite + TailwindCSS）
  src/
    components/     # UI 组件
    pages/          # 页面路由
    services/       # API 调用封装

3.2 Text2SQL 管道核心流程（api/core/text2sql.py）

run_query() 是整个项目的核心——一个 async generator，yield 阶段性事件，最终返回 QueryResult：

1. Relevancy 检查：RelevancyAgent 判断问题是否与数据库相关（off-topic 直接返回）
2. 表发现（并发）：在 FalkorDB 图谱中检索与问题最相关的表
3. 分析生成：AnalysisAgent 结合相关表 + schema + 历史对话 + 可选记忆 → 生成 SQL + 置信度
4. 自引用标识符自动加引号：数据库标识符含特殊字符时自动修复
5. 破坏性操作检测：UPDATE/DELETE/DROP 需二次确认（演示图谱禁止破坏性操作）
6. SQL 执行：通过 loader 执行，支持失败后 HealerAgent 自愈
7. Schema 变更检测：执行后检测 schema 变更，自动刷新图谱
8. 响应格式化：ResponseFormatterAgent 将 SQL 执行结果转为自然语言

3.3 Schema 加载策略

每个数据库类型有专属 loader（postgres_loader / mysql_loader / snowflake_loader），核心职责是：

• 抽取所有表和列（名称、类型、注释）
• 抽取样本值（每列随机取 3 条）用于 AI 理解列的实际含义
• 抽取外键关系
• 将上述信息存入 FalkorDB 图谱

3.4 Dockerfile 多阶段构建

Dockerfile 使用了精妙的多阶段设计：

• python-base：提供 Python 3.12 环境
• falkordb/falkordb:latest：主镜像，包含 FalkorDB 图数据库
• 复制 python 运行时、安装 uv 包管理器、Node.js 22
• 构建 React 前端（npm --prefix ./app run build）
• 最终镜像暴露 5000（FastAPI）、6379（FalkorDB）、3000（前端）

---

四、部署体验

4.1 Docker 一键启动（推荐）

docker run -p 5000:5000 -it falkordb/queryweaver

然后访问 http://localhost:5000 即可使用 Web UI。API 文档：http://localhost:5000/docs。

4.2 本地开发模式

cp .env.example .env
# 编辑 .env 填入数据库连接和 LLM API Key
docker compose -f docker-compose.test.yml up -d  # 启动 PostgreSQL + MySQL 测试服务
make install && make run

4.3 Python SDK 独立使用

QueryWeaver 也可以作为 Python 库直接使用，不需要启动 Web 服务：

from queryweaver import QueryWeaver

async def main():
    qw = QueryWeaver(falkordb_url="redis://localhost/mydb")
    await qw.connect_database("postgresql://user:pass@localhost/dbname")
    result = await qw.query("dbname", "显示所有客户的订单总额")
    print(result.sql_query, result.results)

---

五、争议与局限性

5.1 强依赖 FalkorDB

整个系统的图谱推理能力建立在 FalkorDB 之上。如果不想引入 FalkorDB（一个基于 Redis 的图数据库），就无法使用 QueryWeaver 的核心优势。目前没有看到对 Neo4j、Memgraph 等其他图数据库的支持计划。

5.2 LLM 成本与延迟

每次查询至少涉及 2-3 次 LLM 调用（Relevancy + Analysis + 可选的 FollowUp），加上 Healer 的重试机制，实际 LLM token 消耗可能相当可观。对于高频查询场景，成本需要评估。

5.3 Schema 变更同步

当目标数据库 schema 变更（如新增列、新建表）后，QueryWeaver 依赖"执行时检测到 schema 变更"来触发图谱刷新。如果从未执行过包含该表的查询，该表会一直不在图谱中。

5.4 AGPL-3.0 许可

项目采用 AGPL-3.0 许可，代码修改后必须开源发布。如果企业在内部使用而不分发代码，通常不受影响，但商业闭源项目集成需要仔细评估许可合规性。

---

六、行业意义与趋势

QueryWeaver 代表的趋势是 "图谱增强的 RAG for Database"。传统的 Text2SQL 只做 schema + prompt 匹配，而 QueryWeaver 引入的图谱层让数据库的"元知识"可以被索引和检索。这与 RAG（检索增强生成）在 LLM 应用中的思路一脉相承，只是检索对象从文档变成了数据库结构。

从项目活跃度来看（2025-07 创建，持续更新至 2026-06，131 forks，73 open issues），QueryWeaver 处于积极维护状态，FalkorDB 团队在持续投入。其 MCP 支持表明项目正在向"AI Agent 工具"方向演进——让 AI 助手在对话中直接操作数据库，是 LLM 应用落地的重要方向之一。

---

报告生成时间：2026-06-15 | 数据来源：GitHub API + 源码分析