Queryweaver

🚀 QueryWeaver

QueryWeaver 是一个开源的 Text2SQL 工具，它借助图驱动的模式理解技术，能够将普通的英文问题转化为 SQL 查询语句。该工具让你可以用自然语言向数据库提问，并返回相应的 SQL 语句和查询结果。

🚀 快速开始

Docker

💡 推荐用于评估目的（无需本地安装 Python 或 Node）

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

启动地址：http://localhost:5000

使用 .env 文件（推荐）

通过复制 .env.example 文件创建一个本地的 .env 文件，并将其传递给 Docker。这是提供所有必需配置的最简单方法：

cp .env.example .env
# 编辑 .env 文件以设置你的值，然后执行以下命令
docker run -p 5000:5000 --env-file .env falkordb/queryweaver

替代方法：逐个传递环境变量

如果你更喜欢在命令行中传递变量，可以使用 -e 标志（但对于多个变量来说不太方便）：

docker run -p 5000:5000 -it \
  -e APP_ENV=production \
  -e FASTAPI_SECRET_KEY=your_super_secret_key_here \
  -e GOOGLE_CLIENT_ID=your_google_client_id \
  -e GOOGLE_CLIENT_SECRET=your_google_client_secret \
  -e GITHUB_CLIENT_ID=your_github_client_id \
  -e GITHUB_CLIENT_SECRET=your_github_client_secret \
  -e AZURE_API_KEY=your_azure_api_key \
  falkordb/queryweaver

注意：若要直接使用 OpenAI 而非 Azure OpenAI，请在上述命令中用 OPENAI_API_KEY 替换 AZURE_API_KEY。

有关完整的配置选项列表，请参考 .env.example 文件。

✨ 主要特性

MCP 服务器：托管或连接（可选）

QueryWeaver 可选支持模型上下文协议（MCP）。你可以让 QueryWeaver 公开一个与 MCP 兼容的 HTTP 接口（以便其他服务可以将 QueryWeaver 作为 MCP 服务器调用），也可以将 QueryWeaver 配置为调用外部 MCP 服务器以获取模型/上下文服务。

QueryWeaver 提供以下功能：

• 该应用程序注册了专注于 Text2SQL 流程的 MCP 操作：
  • list_databases
  • connect_database
  • database_schema
  • query_database
• 若要禁用内置的 MCP 端点，请在 .env 文件或环境变量中设置 DISABLE_MCP=true（默认：启用 MCP）。
• 配置
  • DISABLE_MCP：禁用 QueryWeaver 内置的 MCP HTTP 接口。设置为 true 可禁用，默认值为 false（启用 MCP）。

示例

在使用 Docker 运行时禁用内置的 MCP：

docker run -p 5000:5000 -it --env DISABLE_MCP=true falkordb/queryweaver

调用内置的 MCP 端点（示例）

• MCP 接口以 HTTP 端点的形式公开。

服务器配置

以下是一个最小化的 mcp.json 客户端配置示例，该配置针对的是在 /mcp 路径公开 MCP HTTP 接口的本地 QueryWeaver 实例。

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

REST API

API 文档

• Swagger UI：https://app.queryweaver.ai/docs
• OpenAPI JSON：https://app.queryweaver.ai/openapi.json

概述

QueryWeaver 公开了一个小型的 REST API，用于管理图（数据库模式）和运行 Text2SQL 查询。所有修改或访问用户范围数据的端点都需要通过承载令牌进行身份验证。在浏览器中，应用程序使用会话 cookie 和 OAuth 流程；对于 CLI 和脚本，你可以使用 API 令牌（请参阅 tokens 路由或 Web UI 来创建一个）。

核心端点

• GET /graphs：列出经过身份验证的用户可用的图
• GET /graphs/{graph_id}/data：返回图的节点/链接（表、列、外键）
• POST /graphs：上传或创建一个图（JSON 有效负载或文件上传）
• POST /graphs/{graph_id}：针对指定的图运行基于聊天的 Text2SQL 查询（流式响应）

身份验证

• 添加一个 Authorization 头：Authorization: Bearer <API_TOKEN>

示例

1. 列出图（GET）

   curl 示例：

   curl -s -H "Authorization: Bearer $TOKEN" \
      https://app.queryweaver.ai/graphs
   

   Python 示例：

   import requests
   resp = requests.get('https://app.queryweaver.ai/graphs', headers={'Authorization': f'Bearer {TOKEN}'})
   print(resp.json())
   

2. 获取图模式（GET）

   curl 示例：

   curl -s -H "Authorization: Bearer $TOKEN" \
      https://app.queryweaver.ai/graphs/my_database/data
   

   Python 示例：

   resp = requests.get('https://app.queryweaver.ai/graphs/my_database/data', headers={'Authorization': f'Bearer {TOKEN}'})
   print(resp.json())
   

3. 加载图（POST）—— JSON 有效负载

   curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d '{"database": "my_database", "tables": [...]}' \
      https://app.queryweaver.ai/graphs
   

   或者上传文件（多部分/表单数据）：

   curl -H "Authorization: Bearer $TOKEN" -F "file=@schema.json" \
      https://app.queryweaver.ai/graphs
   

4. 查询图（POST）—— 运行基于聊天的 Text2SQL 请求 POST /graphs/{graph_id} 端点接受一个至少包含 chat 字段（消息数组）的 JSON 主体。该端点将处理步骤和最终的 SQL 作为服务器发送的消息块流式返回，这些消息块由前端使用的特殊边界分隔。对于简单的脚本编写，你可以调用该端点并从流式消息中读取最终的 JSON 对象。

示例有效负载

{
   "chat": ["How many users signed up last month?"],
   "result": [],
   "instructions": "Prefer PostgreSQL compatible SQL"
}

curl 示例（简单，收集整个响应）

curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
   -d '{"chat": ["Count orders last week"]}' \
   https://app.queryweaver.ai/graphs/my_database

Python 示例（支持流式处理）

import requests
import 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": ["Count orders last week"]}, stream=True) as r:
      # 服务器生成由消息边界字符串分隔的 JSON 对象
      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)
                  if not part.strip():
                        continue
                  obj = json.loads(part)
                  print('STREAM:', obj)

注意事项和提示

• 图 ID 是按用户进行命名空间划分的。直接调用 API 时，请使用普通的图 ID（服务器将按经过身份验证的用户进行命名空间划分）。对于上传的文件，database 字段决定了保存的图 ID。
• 流式响应包括中间推理步骤、后续问题（如果查询不明确或偏离主题）和最终的 SQL。前端期望消息之间使用边界字符串 |||FALKORDB_MESSAGE_BOUNDARY|||。
• 对于破坏性 SQL（INSERT/UPDATE/DELETE 等），服务将在流中包含一个确认步骤；前端会处理此流程。如果你要自动化执行破坏性操作，请确保正确处理确认（请参阅代码中的 ConfirmRequest 模型）。

📦 安装指南

开发环境安装

按照以下步骤从源代码运行和开发 QueryWeaver。

前提条件

• Python 3.12+
• pipenv
• 一个 FalkorDB 实例（本地或远程）
• Node.js 和 npm（用于 TypeScript 前端）

安装和配置

快速启动（推荐用于开发）：

# 克隆仓库
git clone https://github.com/FalkorDB/QueryWeaver.git
cd QueryWeaver

# 安装依赖项（后端 + 前端）并启动开发服务器
make install
make run-dev

如果你更喜欢手动设置或需要自定义环境，可以使用 Pipenv：

# 安装 Python（后端）和前端依赖项
pipenv sync --dev

# 创建本地环境文件
cp .env.example .env
# 编辑 .env 文件并填入你的值（在本地开发时设置 APP_ENV=development）

在本地运行应用程序

pipenv run uvicorn api.index:app --host 0.0.0.0 --port 5000 --reload

服务器将在 http://localhost:5000 上可用。

或者，仓库提供了 Make 目标来运行应用程序：

make run-dev   # 开发服务器（自动重新加载，便于调试）
make run-prod  # 生产模式（如有需要，确保前端已构建）

前端构建（必要时）

前端是一个位于 app/ 目录下的 TypeScript 应用程序。在生产运行之前或前端发生更改后进行构建：

make install       # 安装后端和前端依赖项
make build-prod    # 将前端构建到 app/public/js/app.js

# 或者手动操作
cd app
npm ci
npm run build

OAuth 配置

QueryWeaver 支持 Google 和 GitHub OAuth。为每个提供商创建 OAuth 凭证，并将客户端 ID/密钥粘贴到你的 .env 文件中。

• Google：设置授权来源和回调地址 http://localhost:5000/login/google/authorized
• GitHub：设置主页和回调地址 http://localhost:5000/login/github/authorized

特定环境的 OAuth 设置

对于生产/预发布部署，请在环境中设置 APP_ENV=production 或 APP_ENV=staging 以启用安全会话 cookie（仅支持 HTTPS）。这可以防止 OAuth CSRF 状态不匹配错误。

# 对于生产/预发布环境（启用仅支持 HTTPS 的会话 cookie）
APP_ENV=production

# 对于开发环境（允许使用 HTTP 会话 cookie）
APP_ENV=development

重要提示：如果你在预发布/生产环境中遇到 "mismatching_state: CSRF Warning!" 错误，请确保将 APP_ENV 设置为 production 或 staging 以启用安全会话处理。

AI/LLM 配置

QueryWeaver 使用 AI 模型进行 Text2SQL 转换，支持直接使用 Azure OpenAI 和 OpenAI。

默认：Azure OpenAI

默认情况下，QueryWeaver 配置为使用 Azure OpenAI。你需要设置所有三个 Azure 凭证：

AZURE_API_KEY=your_azure_api_key
AZURE_API_BASE=https://your-resource.openai.azure.com/
AZURE_API_VERSION=2024-12-01-preview

替代方案：直接使用 OpenAI

若要直接使用 OpenAI 而不是 Azure，只需设置 OPENAI_API_KEY 环境变量：

OPENAI_API_KEY=your_openai_api_key

当提供 OPENAI_API_KEY 时，QueryWeaver 会自动切换到使用 OpenAI 的模型：

• 嵌入模型：openai/text-embedding-ada-002
• 完成模型：openai/gpt-4.1

此配置在 api/config.py 中自动处理，你只需提供相应的 API 密钥即可。

带有 AI 配置的 Docker 示例

使用 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

直接使用 OpenAI：

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

💻 使用示例

基础用法

以下是使用 QueryWeaver REST API 列出图的 Python 示例：

import requests
resp = requests.get('https://app.queryweaver.ai/graphs', headers={'Authorization': f'Bearer {TOKEN}'})
print(resp.json())

高级用法

以下是使用 QueryWeaver REST API 运行基于聊天的 Text2SQL 请求的 Python 示例（支持流式处理）：

import requests
import 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": ["Count orders last week"]}, stream=True) as r:
      # 服务器生成由消息边界字符串分隔的 JSON 对象
      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)
                  if not part.strip():
                        continue
                  obj = json.loads(part)
                  print('STREAM:', obj)

📚 详细文档

测试

快速提示：许多测试需要 FalkorDB 可用。如有需要，请使用包含的辅助工具在 Docker 中运行测试数据库。

前提条件

• 安装开发依赖项：pipenv sync --dev
• 启动 FalkorDB（请参阅 make docker-falkordb）
• 安装 Playwright 浏览器：pipenv run playwright install

快速命令

推荐使用 Make 辅助工具准备开发/测试环境（安装依赖项和 Playwright 浏览器）：

# 准备开发/测试环境（安装依赖项和 Playwright 浏览器）
make setup-dev

或者，你可以运行特定于端到端（E2E）测试的设置脚本，然后手动运行测试：

# 准备 E2E 测试环境（安装浏览器和其他设置）
./setup_e2e_tests.sh

# 运行所有测试
make test

# 仅运行单元测试（速度更快）
make test-unit

# 运行 E2E 测试（无头模式）
make test-e2e

# 运行 E2E 测试并显示浏览器以进行调试
make test-e2e-headed

测试类型

• 单元测试：专注于单个模块和实用程序。使用 make test-unit 或 pipenv run pytest tests/ -k "not e2e" 运行。
• 端到端（E2E）测试：通过 Playwright 运行，测试 UI 流程、OAuth、文件上传、模式处理、聊天查询和 API 端点。使用 make test-e2e。

请参阅 tests/e2e/README.md 以获取完整的 E2E 测试说明。

CI/CD

GitHub Actions 在推送和拉取请求时运行单元和 E2E 测试。测试失败时会捕获屏幕截图和工件以便调试。

故障排除

• FalkorDB 连接问题：启动数据库辅助工具 make docker-falkordb 或检查网络/主机设置。
• Playwright/浏览器故障：使用 pipenv run playwright install 安装浏览器，并确保系统依赖项已安装。
• 缺少环境变量：复制 .env.example 文件并填写所需的值。
• OAuth "mismatching_state: CSRF Warning!" 错误：对于 HTTPS 部署，请在环境中设置 APP_ENV=production（或 staging）；对于 HTTP 开发环境，请设置 APP_ENV=development。这可以确保会话 cookie 针对你的部署类型进行正确配置。

项目布局（高层级）

• api/：FastAPI 后端
• app/：TypeScript 前端
• tests/：单元和 E2E 测试

📄 许可证

本项目采用 GNU Affero 通用公共许可证（AGPL）。有关详细信息，请参阅 LICENSE。

版权所有 FalkorDB Ltd. 2025