Queryweaver

快速开始

Docker

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

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

访问：http://localhost:5000

---

使用 .env 文件（推荐）

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

cp .env.example .env
# edit .env to set your values, then:
docker run -p 5000:5000 --env-file .env falkordb/queryweaver

替代方式：传递单个环境变量

如果你更倾向于在命令行传递变量，请使用 -e 标志（变量较多时不太方便）：

docker run -p 5000:5000 -it \
  -e APP_ENV=development \
  -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

APP_ENV=development 用于让此命令提供的纯 HTTP http://localhost:5000 登录正常工作。通过 HTTPS 部署 QueryWeaver 时，请移除该设置（或改为其他值），以便将会话 Cookie 标记为 Secure。参见应用环境。

注意：QueryWeaver 支持多个 AI 提供商。你可以使用 OPENAI_API_KEY、GEMINI_API_KEY、ANTHROPIC_API_KEY 或 AZURE_API_KEY。详情请参见 AI/LLM 配置一节。

如需查看完整的配置选项列表，请参阅 .env.example。

内存 TTL（可选）

QueryWeaver 在 FalkorDB 中存储每位用户的对话记忆。默认情况下，这些图会永久保留。设置 MEMORY_TTL_SECONDS 可应用 Redis TTL（以秒为单位），自动清理闲置的记忆图。

# Expire memory graphs after 1 week of inactivity
MEMORY_TTL_SECONDS=604800

每次用户交互都会刷新 TTL，因此活跃用户的记忆会继续保留。

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 查询。所有会修改或访问用户范围数据的端点都需要身份验证。在浏览器中，应用会使用通过 OAuth 或电子邮件/密码建立的签名会话 Cookie；对于 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>

三种彼此独立的凭据

QueryWeaver 将三种“登录”凭据彼此独立管理，因此一种凭据失效时，绝不会表现为另一种凭据失效：

凭据	证明什么	存储位置	是否依赖 FalkorDB？
浏览器登录	谁在使用应用	签名会话 Cookie，通过 OAuth 或密码建立一次	否，只要进程正在运行
API 令牌	脚本可代表某个用户执行操作	Organizations 图中的 Token 节点，通过 Authorization: Bearer … 发送	是
数据源连接	对你自己的数据库的访问权限	每次请求提供，绝不存储	否（这是你自己的数据库）

由于浏览器登录使用签名 Cookie，保持登录状态无需往返数据库；在已运行的进程中，即使 FalkorDB 中断，登录状态也不会丢失——你仍可保留会话，只有确实需要访问图的操作才会失败。 显式提供 API 令牌的请求始终会经过数据库验证；如果数据库无法访问，服务会返回 503（而非 401），以便客户端重试，而不是重新进行身份验证。

请注意适用范围：这里说的是保持登录状态，而不是启动过程。QueryWeaver 仍会在启动时连接 FalkorDB，没有 FalkorDB 就无法启动，因此中断期间重启不在此范围内。

浏览器登录默认有效期为 24 小时；设置 BROWSER_SESSION_TTL_HOURS 可更改此时长。退出登录会清除会话 Cookie。浏览器不会获得 API 令牌，因此也没有可撤销的令牌——令牌需通过 tokens API 显式创建，并在那里撤销。（退出登录时，也会清除并撤销旧版本遗留的 api_token Cookie。）

电子邮件注册需先验证，之后才会创建账户

使用电子邮件地址和密码注册不会立即创建账户。提交的信息会暂存起来，系统会向该地址发送一个六位数验证码；只有将验证码填回注册表单后，账户和会话才会创建。因此，注册者无法控制的地址绝不会成为账户，也不会产生需要系统其他部分处理的半成品用户。

之所以使用验证码而非通过电子邮件发送链接，是因为验证码必须返回到提交表单的那个会话中。任何收到链接的人都可以打开它：陌生人可能用自己选定的密码提交你的地址，而你只需点一下，就会创建一个对方知道密码的账户。在这里，任何人都无法替别人注册，因为只有填写表单的人才能同时持有这两部分信息。 该代码仅可使用一次，15 分钟后过期，并且只能输错少数几次，超过后待处理的注册信息就会被丢弃——只有在尝试次数很少时，短代码才是安全的。该代码也只能在提交表单的浏览器中兑换：每次提交都会生成一张票据，并保存在该浏览器的会话中；如果没有票据就提交代码，系统会拒绝。输入代码后，浏览器会直接登录：密码是几分钟前刚设置的，再次要求输入密码毫无意义。可以在同一页面重新发送代码，但受每个地址的速率限制；发送次数配额按待处理的注册信息计算，因此待处理的注册信息过期后配额会重置，之后该地址始终可以再次注册。输入已过期的代码不算输错，也不会导致任何信息被丢弃——待处理的注册信息会保持原样，因此可以在同一页面发送新代码。

在开发环境中，如果没有配置邮件服务器，邮件内容会写入应用日志，而不是实际发送，因此可以从日志中复制代码来完成流程。这需要设置 APP_ENV=development——在其他环境中，未配置邮件服务器的进程会拒绝发送，而不会记录代码并报告成功。设置 MAIL_SERVER（以及 MAIL_PORT、MAIL_USERNAME、MAIL_PASSWORD、MAIL_DEFAULT_SENDER）即可实际发送；任何提供 SMTP 端点的服务商都适用。可通过 EMAIL_VERIFICATION_TTL_MINUTES、EMAIL_VERIFICATION_MAX_ATTEMPTS、EMAIL_VERIFICATION_RESEND_SECONDS 和 EMAIL_VERIFICATION_MAX_SENDS 调整有效期和限制。完整列表请参阅 .env.example。

签名会话 Cookie 的权衡之处在于，在过期前无法从服务器端撤销它：TTL 限定了风险窗口，轮换 FASTAPI_SECRET_KEY 则会立即使所有浏览器登录失效。API 令牌保留在服务器端，因此仍可单独立即撤销。如果需要更短的风险窗口，请缩短 BROWSER_SESSION_TTL_HOURS。

示例

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

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

curl -H "Authorization: Bearer $TOKEN" -F "[email protected]" \
   https://app.queryweaver.ai/graphs

4. 查询图（POST）— 执行基于聊天的 Text2SQL 请求

POST /graphs/{graph_id} 端点接受一个 JSON 请求体，其中至少包含 chat 字段（消息数组）。该端点会流式返回处理步骤和最终 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:
      # The server yields JSON objects delimited by a message boundary string
      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 模型）。

Python SDK

QueryWeaver Python SDK 让你可以在 Python 应用中直接使用 Text2SQL 功能，无需运行 Web 服务器。

安装

# SDK only (minimal dependencies)
pip install queryweaver

# With server dependencies (FastAPI, etc.)
pip install queryweaver[server]

# Development (includes testing tools)
pip install queryweaver[dev]

快速入门

import asyncio
from queryweaver import QueryWeaver

async def main():
    # Initialize with FalkorDB connection
    qw = QueryWeaver(falkordb_url="redis://localhost:6379")

    # Connect a PostgreSQL or MySQL database
    conn = await qw.connect_database("postgresql://user:pass@host:5432/mydb")
    print(f"Connected: {conn.database_id}")  # "mydb"

    # Convert natural language to SQL and execute — pass the database_id
    # returned by connect_database (un-prefixed; namespacing is internal).
    result = await qw.query(conn.database_id, "Show me all customers from NYC")
    print(result.sql_query)    # SELECT * FROM customers WHERE city = 'NYC'
    print(result.results)       # [{"id": 1, "name": "Alice", "city": "NYC"}, ...]
    print(result.ai_response)   # "Found 42 customers from NYC..."

    await qw.close()

asyncio.run(main())

上下文管理器

async with QueryWeaver(falkordb_url="redis://localhost:6379") as qw:
    conn = await qw.connect_database("postgresql://user:pass@host/mydb")
    result = await qw.query(conn.database_id, "Count orders by status")
# close() runs automatically, awaiting any in-flight background memory writes.

多个实例

多个 QueryWeaver 实例可以在同一进程中并行运行。 每个实例都持有自己的 FalkorDB 连接，并在每次调用时显式传递该连接，因此不会发生共享全局状态冲突。

async with QueryWeaver(falkordb_url="redis://host-a:6379", user_id="tenant_a") as a, \
           QueryWeaver(falkordb_url="redis://host-b:6379", user_id="tenant_b") as b:
    sales = await a.connect_database("postgresql://user:pass@host-a/sales")
    ops = await b.connect_database("postgresql://user:pass@host-b/ops")
    await a.query(sales.database_id, "Show top customers")
    await b.query(ops.database_id, "Count open tickets")

可用方法

方法	描述
connect_database(db_url)	连接 PostgreSQL/MySQL 并加载架构
query(database, question)	将自然语言转换为 SQL 并执行
get_schema(database)	获取数据库架构（表和关系）
list_databases()	列出所有已连接的数据库
delete_database(database)	从 FalkorDB 中移除数据库
refresh_schema(database)	在数据库变更后重新同步架构
execute_confirmed(database, sql)	执行已确认的破坏性操作

高级查询选项

对于多轮对话、自定义指令或按请求覆盖 LLM 设置：

from queryweaver import QueryWeaver, QueryRequest

request = QueryRequest(
    question="Show their recent orders",
    chat_history=["Show all customers from NYC"],
    result_history=["Found 42 customers..."],
    instructions="Use created_at for date filtering",
    # Optional per-request LLM overrides — bypass env-based config
    custom_api_key="sk-...",
    custom_model="openai/gpt-4.1",
)

result = await qw.query("mydb", request)

处理破坏性操作

INSERT、UPDATE、DELETE 操作需要确认：

result = await qw.query("mydb", "Delete inactive users")

if result.requires_confirmation:
    print(f"Destructive SQL: {result.sql_query}")
    # Execute after user confirms
    confirmed = await qw.execute_confirmed("mydb", result.sql_query)

要求

• Python 3.12+
• FalkorDB 实例（本地或远程）
• OpenAI 或 Azure OpenAI API 密钥（用于 LLM）
• 目标 SQL 数据库（PostgreSQL 或 MySQL）

开发

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

先决条件

• Python 3.12+
• uv（Python 包管理器）
• FalkorDB 实例（本地或远程）
• Node.js 和 npm（用于 React 前端）

安装和配置

快速入门（推荐用于开发）：

# Clone the repo
git clone https://github.com/FalkorDB/QueryWeaver.git
cd QueryWeaver

# Install dependencies (backend + frontend) and start the dev server
make install
make run-dev

如果你更倾向于手动设置或需要自定义环境，请使用 uv：

# Install Python (backend) and frontend dependencies
uv sync

# Create a local environment file
cp .env.example .env
# Edit .env with your values (set APP_ENV=development for local development)

在本地运行应用

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

服务将在 http://localhost:5000 上运行

或者，仓库提供了用于运行应用的 Make 目标：

make run-dev   # development server (reload, debug-friendly)
make run-prod  # production mode (ensure frontend build if needed)

前端构建（需要时）

前端是位于 app/ 中的现代 React + Vite 应用。在生产环境运行前或修改前端后，请先构建：

make install       # installs backend and frontend deps
make build-prod    # builds the frontend into app/dist/

# or manually
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 设置

在生产/预发布部署中，默认情况下会将会话 Cookie 设为仅限 HTTPS。只有去除首尾空白并转换为小写后值为 development 的 APP_ENV 才会关闭此设置，因此即使部署时忘记设置该变量，Cookie 仍然安全。对于使用纯 HTTP 的本地运行，请设置 APP_ENV=development，否则浏览器会丢弃 Cookie，并导致 OAuth CSRF 状态不匹配错误。

经过签名的会话 Cookie 是浏览器唯一的凭据。api_token 绝不会写入浏览器 Cookie——Cookie 中的承载令牌会在其整个有效期内以明文形式存储在磁盘上——因此，程序化客户端应改为从令牌 API 获取令牌。在此变更之前签发的会话仍可使用：系统仍接受旧版 api_token Cookie，只是不再发放该 Cookie。

# For production/staging (HTTPS-only session cookies - also the default)
APP_ENV=production

# For development (allows HTTP session cookies)
APP_ENV=development

重要提示：如果你在纯 HTTP 环境中遇到 “mismatching_state: CSRF Warning!” 错误，请确保已将 APP_ENV 设置为 development。

AI/大模型配置

QueryWeaver 支持多个 AI 提供商。设置一个 API 密钥，QueryWeaver 会自动检测要使用的提供商。

优先级顺序： Ollama > OpenAI > Gemini > Anthropic > Cohere > Azure（默认）

提供商	API 密钥	默认模型
Ollama	OLLAMA_MODEL	ollama/<your-model>，ollama/nomic-embed-text
OpenAI	OPENAI_API_KEY	openai/gpt-4.1，openai/text-embedding-ada-002
Google Gemini	GEMINI_API_KEY	gemini/gemini-3-pro-preview，gemini/gemini-embedding-001
Anthropic	ANTHROPIC_API_KEY	anthropic/claude-sonnet-4-5-20250929，voyage/voyage-3*
Cohere	COHERE_API_KEY	cohere/command-a-03-2025，cohere/embed-v4.0
Azure OpenAI	AZURE_API_KEY	azure/gpt-4.1，azure/text-embedding-ada-002

* Anthropic 不提供原生嵌入模型。你必须设置 VOYAGE_API_KEY 或 EMBEDDING_MODEL 来使用嵌入模型，否则启动时会报错。

可选：覆盖默认模型

COMPLETION_MODEL=gemini/gemini-3-pro-preview
EMBEDDING_MODEL=gemini/gemini-embedding-001

两者必须与 API 密钥对应的提供商匹配。

配置 AI 的 Docker 示例

使用 OpenAI：

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

使用 Google Gemini：

docker run -p 5000:5000 -it \
  -e FASTAPI_SECRET_KEY=your_secret_key \
  -e GEMINI_API_KEY=your_gemini_api_key \
  falkordb/queryweaver

使用 Anthropic：

docker run -p 5000:5000 -it \
  -e FASTAPI_SECRET_KEY=your_secret_key \
  -e ANTHROPIC_API_KEY=your_anthropic_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=2025-03-01-preview \
  falkordb/queryweaver

测试

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

前置条件

• 安装开发依赖：uv sync
• 启动 FalkorDB（参见 make docker-falkordb）
• 安装 Playwright 浏览器：uv run playwright install

快速命令

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

# Prepare development/test environment (installs deps and Playwright browsers)
make setup-dev

或者，你可以运行 E2E 专用设置脚本，然后手动运行测试：

# Prepare E2E test environment (installs browsers and other setup)
./setup_e2e_tests.sh

# Run all tests
make test

# Run unit tests only (faster)
make test-unit

# Run E2E tests (headless)
make test-e2e

# Run E2E tests with a visible browser for debugging
make test-e2e-headed

测试类型

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

完整的 E2E 测试说明请参见 tests/e2e/README.md。

CI/CD

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

故障排除

• FalkorDB 连接问题：启动数据库辅助工具 make docker-falkordb，或检查网络/主机设置。
• Playwright/浏览器故障：使用 uv run playwright install 安装浏览器，并确保系统依赖已就绪。
• 缺少环境变量：复制 .env.example 并填写必需的值。
• OAuth “mismatching_state: CSRF Warning!” 错误：除非 APP_ENV 去除首尾空格并转换为小写后为 development，否则会话 Cookie 仅限 HTTPS。对于纯 HTTP 环境，请设置 APP_ENV=development；对于 HTTPS 部署，请使用 production 或 staging（也可以完全不设置该变量）。

项目结构（概览）

• api/ – FastAPI 后端
• app/ – React + Vite 前端
• tests/ – 单元测试和 E2E 测试

许可证

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

版权所有 FalkorDB Ltd. 2025