大家好，我是 Ai 學(xué)習(xí)的老章

關(guān)于 Text-to-SQL，我之前寫過：

那篇介紹的是 Wren AI，它的核心思路是在數(shù)據(jù)庫上加一層"語義層"。今天要聊的QueryWeaver，走了另一條路——用圖數(shù)據(jù)庫來理解數(shù)據(jù)庫 Schema，思路完全不同，但同樣精彩。

先聊聊背景：FalkorDB 是誰？

在聊 QueryWeaver 之前，得先說說它背后的公司FalkorDB。

FalkorDB 是一家專注于圖數(shù)據(jù)庫的公司，官方定位是 **"Ultra-fast, Multi-tenant Graph Database Powering GenAI"**——超快的、多租戶的圖數(shù)據(jù)庫，專為 GenAI 而生。

它的核心產(chǎn)品是同名的 FalkorDB 圖數(shù)據(jù)庫，主要特點：

• 采用屬性圖模型（Property Graph Model），支持 OpenCypher 查詢語言

• 性能碾壓級別：官方 benchmark 顯示延遲比 Neo4j 快496 倍，內(nèi)存占用低6 倍

• 支持全文搜索、向量相似度搜索、范圍索引三種索引類型

• 內(nèi)置GraphRAG SDK，直接支持圖檢索增強生成

• 應(yīng)用場景覆蓋 GraphRAG、Agentic AI、Chatbot、欺詐檢測、安全圖譜等

簡單說，F(xiàn)alkorDB 的核心競爭力就是快、省內(nèi)存、多租戶。在圖數(shù)據(jù)庫賽道里，Neo4j 是老大哥沒錯，但 FalkorDB 在性能上的優(yōu)勢確實驚人。

所以你可以理解，當(dāng) FalkorDB 團隊做 Text-to-SQL 工具的時候，他們天然會想：能不能用圖來理解數(shù)據(jù)庫結(jié)構(gòu)？QueryWeaver 就這么來了。

簡介

QueryWeaver是 FalkorDB 推出的一個開源 Text-to-SQL 工具，核心定位很清晰：把自然語言問題轉(zhuǎn)換成 SQL 查詢，用圖數(shù)據(jù)庫來理解數(shù)據(jù)庫 Schema。

QueryWeaver 產(chǎn)品界面演示

和其他 Text-to-SQL 工具最大的不同在于——它的底層是圖驅(qū)動的 Schema 理解（graph-powered schema understanding）。

什么意思？傳統(tǒng) Text-to-SQL 工具是把表結(jié)構(gòu)塞進 prompt，讓 LLM 硬猜。QueryWeaver 是先把你的數(shù)據(jù)庫 Schema 解析成一個圖——表是節(jié)點，外鍵關(guān)系是邊——然后通過圖遍歷來理解表與表之間的關(guān)系。

這思路其實很聰明。數(shù)據(jù)庫本來就是關(guān)系模型，用圖來表示表之間的關(guān)系，比把 Schema 平鋪成文本給 LLM 要直觀得多。LLM 在理解多表 JOIN 時更不容易出錯。

核心功能與特點：

• Graph-powered Schema 理解：用 FalkorDB 圖數(shù)據(jù)庫存儲和理解數(shù)據(jù)庫 Schema 關(guān)系，自然語言查詢時通過圖遍歷定位相關(guān)表

• REST API + MCP 雙接口：既有傳統(tǒng)的 RESTful API，也支持 MCP（Model Context Protocol）協(xié)議，可以被 Claude、Cursor 等 AI 工具直接調(diào)用

• 多 LLM 支持：默認用 Azure OpenAI，也支持 OpenAI 直連。Embedding 用text-embedding-ada-002，Completion 用gpt-4.1

• 對話記憶：每個用戶的對話上下文存在 FalkorDB 中，支持多輪對話追問，不會"翻臉不認人"

• 流式響應(yīng)：Text-to-SQL 的生成過程是流式返回的，包含中間推理步驟，你能看到它"思考"的過程

• Google/GitHub OAuth 登錄：企業(yè)級的認證體系，不是玩具項目

既然都是 Text-to-SQL，免不了和我之前介紹的 Wren AI 做個對比：

對比維度

QueryWeaver

Wren AI

核心思路

圖數(shù)據(jù)庫理解 Schema 關(guān)系

語義層（Semantic Layer）抽象

Schema 理解

自動構(gòu)建表關(guān)系圖，圖遍歷定位

需手動建模語義層

上手門檻

Docker 一行啟動，導(dǎo)入 Schema 即用

需要花時間建立語義模型

MCP 支持

? 原生支持

數(shù)據(jù)源

通過 Schema 導(dǎo)入，不直連數(shù)據(jù)庫

直連 PostgreSQL、MySQL、Snowflake 等

LLM

Azure OpenAI / OpenAI

支持多家（OpenAI、Gemini、Claude、Ollama）

SQL 驗證

流式返回含推理過程

內(nèi)置 SQL 執(zhí)行驗證

可視化

圖形化 Schema 展示

自動生成圖表和報告

GitHub Stars

336 ?

13.3k ?

兩者各有所長。QueryWeaver 的優(yōu)勢在于開箱即用和 MCP 原生支持——上傳 Schema 就能開始問問題，不需要花時間建模。而且 MCP 支持意味著你可以在 Claude、Cursor 等 AI IDE 中直接用它查數(shù)據(jù)庫，這個體驗是很超前的。

Wren AI 的優(yōu)勢在于成熟度和可配置性——語義層雖然建模麻煩，但一旦建好，可以帶來更精確的 SQL 生成，對企業(yè)級場景更友好。

安裝

QueryWeaver 的安裝非常簡單，Docker 一行搞定：

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

啟動完成后訪問 http://localhost:5000 就能看到界面了。

如果你想配置 API Key，推薦用.env文件：

cp .env.example .env
# 編輯 .env 設(shè)置你的配置
docker run -p 5000:5000 --env-file .env falkordb/queryweaver

也可以通過環(huán)境變量直接傳：

# 使用 OpenAI
docker run -p 5000:5000 -it \
  -e FASTAPI_SECRET_KEY=your_secret_key \
  -e OPENAI_API_KEY=your_openai_api_key \
  falkordb/queryweaver


 # 使用 Azure OpenAI
docker run -p 5000:5000 -it \
  -e FASTAPI_SECRET_KEY=your_secret_key \
  -e AZURE_API_KEY=your_azure_api_key \
  -e AZURE_API_BASE=https://your-resource.openai.azure.com/ \
  -e AZURE_API_VERSION=2024-12-01-preview \
  falkordb/queryweaver

這是 QueryWeaver 最讓我興奮的功能。它內(nèi)置了 MCP Server，提供了 4 個 Text-to-SQL 相關(guān)的操作：

• list_databases：列出可用數(shù)據(jù)庫

• connect_database：連接到指定數(shù)據(jù)庫

• database_schema：獲取數(shù)據(jù)庫 Schema

• query_database：執(zhí)行自然語言查詢

配置也很簡單，在你的 MCP 客戶端配置文件中加入：

{
  "servers": {
    "queryweaver": {
      "type": "http",
      "url": "http://127.0.0.1:5000/mcp",
      "headers": {
        "Authorization": "Bearer your_token_here"
      }
    }
  },
  "inputs": []
}

想象一下這個場景：你在 Claude Desktop 或 Cursor 里寫代碼，突然想查一下"上個月有多少新注冊用戶"，直接在 AI 對話里問就行，QueryWeaver 作為 MCP Server 在后臺幫你把自然語言翻譯成 SQL 并返回結(jié)果。

這才是 Text-to-SQL 的正確打開方式——不是一個單獨的 Web 界面，而是融入到你的工作流里。

REST API 使用

QueryWeaver 也提供了完整的 REST API，適合集成到自己的產(chǎn)品中：

import requests
import json

 # 列出可用的圖（Schema）
resp = requests.get(
    'https://app.queryweaver.ai/graphs',
    headers={'Authorization': f'Bearer {TOKEN}'}
)
print(resp.json())

 # 自然語言查詢（流式）
url = 'https://app.queryweaver.ai/graphs/my_database'
headers = {
    'Authorization': f'Bearer {TOKEN}',
    'Content-Type': 'application/json'
}
with requests.post(
    url,
    headers=headers,
    json={"chat": ["上個月有多少新注冊用戶？"]},
    stream=True
) as r:
    boundary = '|||FALKORDB_MESSAGE_BOUNDARY|||'
    buffer = ''
    for chunk in r.iter_content(decode_unicode=True, chunk_size=1024):
        buffer += chunk
        while boundary in buffer:
            part, buffer = buffer.split(boundary, 1)
            ifnot part.strip():
                continue
            obj = json.loads(part)
            print('STREAM:', obj)

流式響應(yīng)會包含中間推理步驟和最終 SQL，前端可以很好地展示"AI 正在思考"的過程。

源碼開發(fā)

如果你想從源碼運行或參與開發(fā)：

# 克隆倉庫
git clone https://github.com/FalkorDB/QueryWeaver.git
cd QueryWeaver


 # 一鍵安裝和啟動
make install
make run-dev

前置條件：Python 3.12+、pipenv、Node.js（前端是 React + Vite）、以及一個 FalkorDB 實例。

項目結(jié)構(gòu)很清晰：

• api/— FastAPI 后端

• app/— React + Vite 前端

• tests/— 單元測試和 E2E 測試

QueryWeaver 有個貼心的設(shè)計：對話記憶。每個用戶的會話上下文都存在 FalkorDB 中，默認永久保存。如果你擔(dān)心占用空間，可以設(shè)置 TTL 自動清理：

# 1 周無活動后自動清理記憶
MEMORY_TTL_SECONDS=604800

只要用戶還在互動，TTL 就會刷新。這樣活躍用戶不受影響，休眠用戶的數(shù)據(jù)自動回收。

它適合誰？

• 數(shù)據(jù)分析師：上傳 Schema 就能自然語言問數(shù)據(jù)，不用手寫 SQL

• AI 應(yīng)用開發(fā)者：通過 REST API 或 MCP 協(xié)議把 Text-to-SQL 能力集成到自己的產(chǎn)品

• Claude/Cursor 用戶：通過 MCP 直接在 AI IDE 中查數(shù)據(jù)庫

• 技術(shù)團隊：需要一個開源可控的 Text-to-SQL 方案（AGPL 協(xié)議）

當(dāng)然也不是完美的：

1. LLM 選擇有限：目前只支持 Azure OpenAI 和 OpenAI 直連，不像 Wren AI 那樣支持 Ollama 本地模型，對數(shù)據(jù)安全要求高的團隊不太友好

2. 不直連數(shù)據(jù)庫：需要手動上傳 Schema（JSON 或文件），不能像 Wren AI 那樣直接對接 PostgreSQL/MySQL

3. 社區(qū)規(guī)模較小：336 Star，相比 Wren AI 的 13.3k Star，生態(tài)還在早期

4. 缺少可視化報表：只返回 SQL 和查詢結(jié)果，沒有自動生成圖表的功能

QueryWeaver 給 Text-to-SQL 賽道帶來了一個有意思的思路：用圖數(shù)據(jù)庫來理解數(shù)據(jù)庫 Schema。這和 Wren AI 的"語義層"路線形成了有趣的互補——前者自動化程度高、開箱即用，后者精度更高、可定制性更強。

最讓我看好的是它的MCP 原生支持。Text-to-SQL 工具不應(yīng)該是一個獨立的 Web 應(yīng)用，而應(yīng)該融入到開發(fā)者的工作流中。QueryWeaver 做到了這一點。

FalkorDB 作為背后的圖數(shù)據(jù)庫公司，在技術(shù)底蘊上是沒問題的。如果后續(xù)能支持更多 LLM、直連更多數(shù)據(jù)源，這個項目還是很有潛力的。

官方鏈接匯總：

• GitHub：https://github.com/FalkorDB/QueryWeaver

• 在線體驗：https://app.queryweaver.ai

• FalkorDB 文檔：https://docs.falkordb.com/

• FalkorDB 官網(wǎng)：https://falkordb.com

• Swagger API 文檔：https://app.queryweaver.ai/docs

• Discord 社區(qū)：https://discord.gg/b32KEzMzce

制作不易，如果這篇文章覺得對你有用，可否點個關(guān)注。給我個三連擊：點贊、轉(zhuǎn)發(fā)和在看。若可以再給我加個，謝謝你看我的文章，我們下篇再見！