DataSprite 是一个基于 NL2SQL 的智能问数系统。用户用自然语言提问(如"华北地区上季度 GMV 是多少"),系统自动完成关键词抽取 → 多路召回 → 上下文组装 → SQL 生成与校验 → 流式返回结果的全链路处理。
💡 基于 shopkeeper-agent 学习并二次开发
-
NL2SQL 全链路闭环:关键词抽取 → Qdrant 语义检索 + ES 全文检索 → 过滤合并 → LLM SQL 生成 → SQL 校验修正 → 执行 SQL 并返回可视化结果,17 个节点端到端自动化,用户只需说人话。
-
混合检索架构:MySQL 存结构化元数据 + Qdrant 做字段/指标语义向量召回 + ES 做字段取值全文匹配,三库协同解决"用户说的词对应哪个字段、哪个值"的核心问题,避免 LLM 裸写 SQL 的幻觉风险。
-
异步并发与高可用:三路数据源 SQLAlchemy async 并行召回,减少串行等待;Redis 缓存 Embedding 向量(7 天 TTL)与热点查询结果(1 小时 TTL),解耦 LLM 调用与结果消费,避免高峰期阻塞 —— 缓存全程 fail-open(Redis 故障自动跳过 + 30s 熔断,不影响主链路)。
-
三层兜底策略:意图兜底(模糊请求主动追问澄清)→ 执行兜底(SQL 修正重试 ≤3 次;摘要 LLM 故障时降级跳过,用户仍拿到原始表格数据)→ 全局兜底(管道超时熔断 + 全局异常 JSON 兜底),任何异常都有响应。
-
工程化交付:OmegaConf + YAML 配置外置,Docker Compose 一键启动全部基础服务,API 限流保护(令牌桶双层)+ SQL 只读限制与行数上限控制 + 全局异常兜底 + 健康检查端点,loguru + request_id 记录系统运行日志,出问题有据可查。
完整交互版(矢量,可浏览器缩放):langgraph-workflow.html
| 类别 | 技术 |
|---|---|
| 🧠 大模型 | qwen3.8-max-0902(通义千问) |
| 🔢 Embedding | BGE-large-zh-v1.5(1024维) |
| 🔍 向量检索 | Qdrant(HNSW 索引) |
| 📄 全文检索 | Elasticsearch(IK 中文分词) |
| 🗄️ 数据库 | MySQL 8.0(星型模型:1事实表 + 4维度表) |
| 🔗 工作流 | LangGraph(17节点编排) |
| 🌐 后端 | FastAPI + SSE 流式推送 |
| 🎨 前端 | React 19 + TypeScript + Tailwind CSS |
| 🐳 部署 | Docker Compose |
登录页(JWT 鉴权) · 首页(历史会话 / 示例问题 / 问数输入)
前端用 border-beam(纯 CSS conic-gradient 流光边框)做核心高光点亮,按「交互优先、装饰从轻」分层:
| 位置 | 强度 | 说明 |
|---|---|---|
| 输入框(聚焦) | 0.6 | 核心交互,最亮 |
| 流式骨架屏卡 | 0.55 | 问数进行中 |
| AI 摘要卡 | 0.5 | 完工高光 |
| 流程活跃节点 | 0.5 | 引导视线 |
| 登录按钮 | 0.45 | 门面,略收 |
| 结果表 / 图表卡 | 0.4 | 数据区,克制 |
| 数据来源卡 | 0.35 | 最静,不抢戏 |
⚠️ border-beam 1.3.0 会给每个实例内联<style>:在卡片 /div里藏得住看不到,但侧边栏menu > li列表会把 CSS 文本摊成可见内容,所以列表 / menu 上不要用它,只适合卡片类容器。
包管理统一用 uv(pyproject.toml + uv.lock,Python >= 3.14)。
- Python 3.14+(
uv包管理,见 uv) - Docker Desktop
- Node.js 20+ / pnpm
- 基础设施:MySQL + Qdrant + Elasticsearch(Python 依赖里还有 Embedding 服务)
uv synccd docker
docker compose up -d
# 启动 MySQL + Qdrant + Elasticsearch + Embedding 服务cp .env.example .env
# 编辑 .env,至少填入 LLM_API_KEY(DashScope API Key),其余可留默认uv run python app/scripts/build_meta_knowledge.py --config conf/meta_config.yaml
# 把 meta 库的表结构灌进 Qdrant + ES,没跑这步问数召回会全空uv run uvicorn main:app --reload --port 8000
# 访问 http://localhost:8000/docs 查看 API 文档
# /api/ask(同步 JSON)走 X-API-Key 头鉴权;/api/query(SSE 流式)走登录 JWTcd frontend
pnpm install && pnpm dev
# 访问 http://localhost:5173uv run python -m app.agent.graph # 直连各客户端,跑一次真实问数
uv run python app/scripts/run_evaluation.py # 问数评测,报告落 docs/evaluations/datasprite/
├── app/
│ ├── agent/ # LangGraph 工作流(17个节点 + 图编排)
│ ├── api/ # FastAPI 路由 + 依赖注入
│ ├── clients/ # MySQL/Qdrant/ES 客户端
│ ├── entities/ # 领域实体
│ ├── models/ # 数据模型
│ ├── repositories/ # 数据仓储层
│ ├── services/ # 业务服务层
│ └── scripts/ # 工具脚本
├── conf/ # 配置文件
├── docker/ # Docker Compose + SQL 初始化
├── frontend/ # React 前端
├── prompts/ # LLM 提示词模板
└── main.py # 应用入口
生产链路里每个"可能炸"的环节都有兜底——预设整体思路是:宁可给用户看未过滤结果,也不让下游饿死;宁可放行出错 SQL,也不让用户永远转圈。
| 环节 | 兜底机制 | 配置 |
|---|---|---|
| 🧠 LLM 单次调用 | 请求超时 + 客户端自动重试(指数退避)+ 主模型失败降级备用模型 | conf/app_config.yaml → llm: request_timeout: 60 / max_retries: 3 / fallback_model(默认 qwen-plus) |
| ⏱️ 整条问数管线 | asyncio.wait_for 整体超时,防 LLM 假死导致请求永久挂起(SSE 也一样有超时) |
llm.query_timeout: 120 |
| 🔄 SQL 校验 | validate_sql 用 EXPLAIN 校验 → 失败进 correct_sql 修正,最多 3 次;超限则直接执行(让错误暴露给用户,而不是静默) |
graph.py MAX_CORRECT_RETRIES = 3 |
| 🧩 召回 / 过滤节点 | LLM 输出格式异常时不过滤、保留全部候选(宁可漏选不可清空,防下游无表无指标可用) | _llm_guard 防御 |
| 🚦 限流 | Redis 令牌桶双层限流;Redis 挂掉 → fail-open 直接放行(限流器故障不影响主业务),加 30s 熔断防假死 | rate_limit 段;桶状态存 Redis |
| 💾 消息持久化 | 用户/助手消息保存失败仅记录日志,不阻塞查询结果返回 | query_service.py 各 try/except |
| 🚨 全局异常 | 中间件兜底,统一错误响应 + 带 request_id 落日志 |
main.py |
| 🧠 会话记忆 | 多轮上下文经 dream 节点压缩,防 context 溢出;recursion_limit 保护超长链路 |
dream 节点 |
日志统一用 loguru,且必须 from app.core.log import logger(loguru —— 该实例会注入 request_id,裸导入会因 extra 缺字段导致日志静默丢失)。
- 链路标识:每个请求注入
request_id(ContextVar,并发协程互不干扰);若上游带了X-Request-Id头则沿用(feishu-bridge → DataSprite 全链路贯通),否则 UUID 自动生成 - 输出位置:
- 控制台(
app_config.logging.console) - 文件:
logs/app.log(logging.file:rotation: 10 MB按大小轮转、retention: 7 days自动清理、UTF-8)
- 控制台(
- 日志格式:
时间 | 级别 | request_id | 模块:函数:行号 | 内容 - 配置:
conf/app_config.yaml→logging:段(开关 / 级别 / 路径 / 轮转 / 保留期) - 特殊日志:SQL 执行日志(SQLAlchemy event 输出,
/* select#N */前缀可对应到第几条)、LangGraph 检查点、节点进度事件(SSE 里的progresschunk) - 审计(#27):SQL 全链路审计落
audit_logs表(谁问了什么 → 生成什么 SQL → 耗时 → 结果行数),不可篡改,可从/api/audit/*查看
完整清单与进度(当前 31 / 37)见 TODO.md,此处只列要点,避免清单漂移。
- SQL 修正循环(correct → re-validate)
- 多轮对话上下文(conversation_id 透传 + 记忆压缩)
- 可视化图表(6 种图表自动检测,支持后端 PNG 生成)
- 结果导出 CSV/Excel
- 查询历史 + 收藏(会话列表)
- 全链路 Token 归集(一次问数 token 记账 + /api/ask 透传 token_usage)
- ⏰ 定时报告(定时 SQL + 飞书推送,#13)
- 📱 微信小程序版(Taro 复用 React 代码,#32)
- 📡 多端接入 Channel 抽象层(微信/钉钉,#23)
- 🔄 AgentScope 企业级外壳迁移(多租户 / 沙箱,v1.0 稳定后评估,#31)
- 前端 UI 持续重设计
MIT © 2026