查询编织器

Name: 查询编织器
Author: FalkorDB

作者：FalkorDB245 星标更新：2025-11-24

安装使用来源：spider==github.com

项目介绍

<div align="center"> <h1>QueryWeaver</h1>

REST API · MCP · 基于图的

QueryWeaver 是一个开源的 Text2SQL 工具，它使用基于图的模式理解将普通英语问题转换为 SQL。它帮助您用自然语言向数据库提问，并返回 SQL 和结果。

连接并提问：

</div>

queryweaver-demo-video-ui

开始使用

Docker

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

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

启动：http://localhost:5000

使用 .env 文件（推荐）

创建一个本地 .env 文件，通过复制 .env.example 并将其传递给 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，请在上述命令中将 AZURE_API_KEY 替换为 OPENAI_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 客户端配置示例，该示例针对本地 QueryWeaver 实例，在 /mcp 处暴露 MCP HTTP 表面。

{
   "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: Bearer <API_TOKEN>

示例

列出图形（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())

获取图形模式（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())

加载图形（POST） — JSON 负载

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

或者上传文件（multipart/form-data）：

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

查询图形（POST） — 运行基于聊天的 Text2SQL 请求

POST /graphs/{graph_id} 端点接受至少包含 chat 字段（消息数组）的 JSON 身体。该端点流式传输处理步骤和最终 SQL，前端使用特殊的边界字符串分隔这些消息。对于简单的脚本，您可以调用它并从流式传输的消息中读取最终的 JSON 对象。

示例负载：

{
   "chat": ["上个月有多少用户注册？"],
   "result": [],
   "instructions": "偏好 PostgreSQL 兼容的 SQL"
}

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

curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
   -d '{"chat": ["上周有多少订单？"]}' \
   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": ["上周有多少订单？"]}, 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 前端）

### 安装和配置

快速开始（推荐用于开发）：

```bash
# 克隆仓库
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 2000:2000 -it \
  -e FASTAPI_SECRET_KEY=your_secret_key \
  -e OPENAI_API_KEY=your_openai_api_key \
  falkordb/queryweaver

测试

快速提示：许多测试需要 FalkorDB 可用。如有需要，使用提供的辅助工具在 Docker 中运行测试 DB。

前提条件

安装开发依赖项：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 连接问题：启动 DB 辅助程序 make docker-falkordb 或检查网络/主机设置。
Playwright/浏览器故障：使用 pipenv run playwright install 安装浏览器并确保系统依赖项存在。
缺失环境变量：复制 .env.example 并填写所需值。
OAuth “mismatching_state: CSRF Warning!” 错误：在您的环境中设置 APP_ENV=production（或 staging）以启用 HTTPS 部署，或 APP_ENV=development 以启用 HTTP 开发环境。这确保会话 cookie 根据您的部署类型正确配置。

项目布局（高层次）

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

许可证

根据 GNU Affero 通用公共许可证（AGPL）许可。参见 LICENSE。