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