# data-agent

**Repository Path**: wuhaitang/data-agent

## Basic Information

- **Project Name**: data-agent
- **Description**: 从模糊提问到可信报告的数据分析 Agent：LangGraph 多节点链路 + 反问澄清 + 报告生成 v2 + 双 Tier 评测
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-06
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DataAgent-LangGraph

![Python](https://img.shields.io/badge/Python-3.12-3776AB?logo=python&logoColor=white)
![LangGraph](https://img.shields.io/badge/LangGraph-1.x-1C3C3C?logo=langchain&logoColor=white)
![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688?logo=fastapi&logoColor=white)
![Nuxt](https://img.shields.io/badge/Nuxt-4-00DC82?logo=nuxt&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green)

一个基于 LangGraph 的数据分析 Agent：用户以自然语言提问，系统自动完成知识检索、Schema 召回、SQL 生成与执行、Python 深度统计与可视化报告；当问题存在口径歧义时，系统通过结构化反问与用户确认口径后继续执行。

系统兼容 [Spring AI Alibaba DataAgent](https://github.com/alibaba/spring-ai-alibaba)（Java）的 SSE 协议与节点语义，前端零适配复用。

## 演示

![DataAgent 演示](docs/images/demo.gif)

*提问"各商品的销售额Top3"：系统检测到"商品"维度歧义，生成结构化反问；用户确认口径后同会话续跑，最终输出含图表的分析报告。*

## 系统架构

![系统总架构](docs/images/diagram-system.png)

一次请求的路径：**用户** → Caddy（口令门禁 / TLS / SSE 直通）→ **Nuxt 前端**（时间线、澄清卡片、流式渲染）→ **兼容层 FastAPI**（SSE 协议映射、SQLite 会话存储）→ **LangGraph 分析链路**（11 节点状态机）→ PostgreSQL（业务数据）、Qdrant（知识库）、豆包 Ark LLM、Docker 沙盒。

## 分析管线

![分析管线](docs/images/diagram-pipeline.png)

主链路：意图识别 → 证据召回与查询增强 → 可行性评估 → 执行规划 → SQL 生成与语义校验 → SQL 执行 →（可选 Python 沙盒）→ 报告生成。其中可行性评估在检出口径歧义时触发 `interrupt`，前端渲染结构化问题卡片，用户作答后经 `Command(resume)` 同会话续跑。

## 核心特性

| 能力 | 说明 |
|------|------|
| 混合检索 | Qdrant 向量检索 + BM25 关键词检索 + RRF 融合；知识条目按 7 类分型管理 |
| 两层表访问模型 | 连接器白名单物理隔离原始表；任务级动态注入处理表 |
| 反问澄清 | 确定性歧义护栏与 LLM 可行性评估相结合；interrupt/resume 同会话续跑 |
| 执行规划 | LLM 生成 JSON 多步计划（SQL / Python 编排），语义不一致自动重生成 |
| 沙盒深度分析 | Docker 容器隔离执行 Python；无 Docker 环境自动降级 subprocess |
| 报告生成 | 多图 pass、流式输出、口径声明、反幻觉规则 |
| 双 Tier 评测 | Tier1 SQL 执行对比 + Tier2 报告质量评分，见下文[评测体系](#评测结果) |

## 设计决策

### 两层表访问模型

模型对数据库的可见范围由两层机制共同约束：

1. **连接器白名单（物理层）**：仅 `sales_clean`、`promotion_clean`、`std_spu` 等处理表可被访问，原始表与竞品数据在连接器层面不可见，而非依赖提示词约束。
2. **任务级动态注入（逻辑层）**：默认仅注入 `sales_clean` 与 `promotion_clean` 的 Schema；`std_spu` 仅在表路由判定问题涉及商品属性时加入。Schema 注入量直接影响 SQL 生成质量，按需裁剪可降低噪声。

配套的知识库同样基于治理过程构建：知识条目按 7 类分型（字段注释、术语、指标口径、业务规则、边界陷阱、表元信息、平台），由脚本从数据治理过程中生成，检索命中后作为证据注入规划与 SQL 生成阶段。

### 混合检索

单一检索通道存在结构性盲区：向量检索擅长语义相似，但对 `paid_amount` 这类精确标识符的区分度不足；BM25 能精确命中标识符，但无法容忍同义改写。

实现为双通道并行、RRF（Reciprocal Rank Fusion）融合排序：Qdrant 承担语义召回，本地 SQLite BM25 承担词面召回，融合后取 Top-K 作为证据注入。检索前先经 LLM 查询重写（消解多轮指代，如"那上个月呢"改写为独立问题）。检索失败时降级为空证据，不阻塞主链路。

### 反问澄清：确定性 × LLM 的混合决策

可行性评估节点设计为三出口（可执行 / 需澄清 / 闲聊），由 LLM 完成分类；分类结果之后由**确定性护栏强制覆写**：

- 歧义词护栏：命中双解词（商品、销量、转化率、投放占比等）时强制进入澄清，豁免词仅依据用户原始输入判断（防止查询规范化文本引入豁免词导致漏拦）；
- 数据信号词覆写：含强数据信号词的输入不会被分类为闲聊；
- 总量查询抑制：无分组诉求的聚合查询不触发维度反问。

触发澄清后，LangGraph `interrupt` 挂起执行，SSE 发出 `CLARIFY_REQUIRED` 事件，前端渲染结构化问题卡片（选项与自由输入）；用户答案经 `Command(resume)` 注入并续跑，同时并入多轮上下文，作为本轮口径的事实来源。

### 报告生成：上下文注入与流式呈现

![报告生成管线](docs/images/diagram-report-v2.png)

报告质量的上限由注入的上下文决定。上下文包的构成为：规范化问题、澄清确认口径、计划描述，以及每步执行包（分析意图、SQL、TopN 结果行）。其中 SQL 是聚合意图的编码——主维度、排序优先级与口径都体现在 SQL 结构中，其信息量高于裸结果行。

两个关键设计：

1. **图表 pass 职责分离**：LLM 仅决定"选什么图、回答什么"（1–3 张，绑定步骤与字段）；图表数据由代码从对应步骤的真实结果行构建 ECharts option。选图的智能与数据的保真解耦，图表数据不存在编造空间。
2. **反幻觉规则**：执行结果是唯一事实来源；禁止补写未查询的同比、占比、趋势与因果；"数据完整/无异常"类结论必须有专门的质量查询支撑；空结果不生成图表。

报告正文经 LangGraph custom stream 逐段流出，以 SSE 增量帧到达前端，前端分块累积渲染，图表代码块在围栏闭合后即时渲染。

### 评测体系

![双 Tier 评测体系](docs/images/diagram-eval-tiers.png)

| 层 | 对象 | 方法 |
|----|------|------|
| Tier1 | SQL 执行结果 | 46 条 golden（8 类场景 + hidden 双解分支）；结果对比列名/行序无关、相对容差 0.5%、TopN 超集允许；3 次执行取多数决 |
| Tier2 | 报告质量 | 快照缓存上游产物，直调报告节点重跑；确定性硬检查（数字溯源、图表数据保真、结构完整）占 60%，LLM 软评（洞察、表达）占 40% |

两层的一致性标准不同：SQL 有标准答案，对比从严（相对容差 0.5%）；报告没有标准答案，否决仅针对**量级级编造**（报告数值与全部真实结果偏离超过 25%），量级正确的近似表述属于业务可接受范围。

评测还承担系统探针职能：报告层的数值异常可用于归因上游 SQL 或数据质量问题（如查询"各产品均值中位数"返回了单产品全零数据，会被报告层的数字溯源检查发现）。

## 评测结果

| 评测 | 结果 | 说明 |
|------|------|------|
| Tier1 SQL 执行 | 46/46 | 46 条 golden，3 次执行多数决，并发 10 |
| Tier2 报告质量 | 99.7 / 100 | 44 条报告，含 1 例量级级编造否决 |
| 反问触发 | 7/7 | 7 条双解 golden 全部触发结构化反问并收敛 |

评测结论的局限：SQL 生成与报告撰写依赖 LLM，存在单轮波动；多数决与确定性护栏用于约束该波动。评测脚本与 golden 定义见 [`backend/eval/`](backend/eval/) 与 [`backend/scripts/`](backend/scripts/)。

## 快速开始

环境要求：Python 3.12、Node.js 22、PostgreSQL、Qdrant，以及一个 OpenAI 兼容的 LLM API。

```bash
# 1. 后端依赖
cd backend && uv venv && uv pip install -e .

# 2. 配置（LLM / PG / Qdrant 凭据）
cp .env.example .env

# 3. 构建知识库（写入 Qdrant 集合）
python scripts/build_knowledge.py

# 4. 启动后端（SSE :8000）
uvicorn app.main:app --host 0.0.0.0 --port 8000

# 5. 启动前端（:3000）
cd ../frontend && pnpm install && pnpm dev
```

业务数据库需包含 `sales_clean` / `promotion_clean` / `std_spu` 三张表（电商销售明细结构，字段见 `scripts/import_excel_to_pg.py`）。可参考 `scripts/build_demo_data.py` 的映射方式准备演示数据。

**运行评测**：

```bash
python scripts/run_eval.py --concurrency 10                    # Tier1 全量
python scripts/run_report_eval.py --collect                    # Tier2 采集快照
python scripts/run_report_eval.py --judge --reuse <快照目录>    # Tier2 评分
```

**部署**（口令保护对外实例）：`deploy/` 目录含 Dockerfile 与 compose 配置；业务数据通过独立 schema（`search_path` 切换）与真实数据隔离。

## 项目结构

```
├── backend/
│   ├── app/
│   │   ├── graph/            # LangGraph 链路（节点 / 状态 / 构建器）
│   │   ├── api/              # 兼容层（SSE 协议映射 + SQLite 会话）
│   │   ├── services/         # LLM / 检索 / 沙盒 / 可观测
│   │   ├── connectors/       # PG 连接器（白名单 + 两层访问）
│   │   └── prompts/          # 提示词（意图 / 规划 / SQL / 报告 / 评审）
│   ├── eval/                 # golden set 定义
│   ├── scripts/              # 评测执行器 / 报告 judge / 知识库构建 / demo 数据
│   ├── tests/                # 确定性测试（Mock LLM）
│   └── docker/               # 沙盒执行器
├── frontend/                 # Nuxt 4（时间线 / 澄清卡片 / ECharts 渲染）
├── docs/diagrams/            # 交互式架构图（archify 生成，浏览器直接打开）
├── docs/images/              # 架构图 PNG / 演示 GIF
└── deploy/                   # Dockerfile / docker-compose / Caddy 配置参考
```

交互式架构图位于 `docs/diagrams/`，下载后用浏览器打开，支持视图聚焦、路径追踪与演示模式。

## 路线图

- [x] 核心闭环：意图 → 检索 → 规划 → SQL → 报告（SSE 流式）
- [x] 反问澄清全链路（interrupt/resume + 前端结构化卡片）
- [x] 报告生成 v2（多图 pass / 上下文注入 / 反幻觉 / 流式）
- [x] 双 Tier 评测体系与快照解耦
- [x] 口令保护部署（Caddy + demo schema 隔离）
- [ ] 多会话并发压测
- [ ] 报告导出 API
- [ ] 评测 judge 模型对比

## 致谢

- [Spring AI Alibaba DataAgent](https://github.com/alibaba/spring-ai-alibaba)：系统设计蓝本，SSE 协议与节点语义的兼容来源
- [LangGraph](https://github.com/langchain-ai/langgraph)：interrupt/resume 状态机基座
- [Archify](https://github.com/Cocoon-AI/architecture-diagram-generator)：架构图生成工具

## License

[MIT](LICENSE)