项目架构分析：LangChain ChatBI

项目架构分析：LangChain ChatBI

执行摘要

LangChain ChatBI 是一个基于 LangChain 和 LangGraph 的智能商业智能（BI）系统，使用自然语言处理技术让用户通过中文/英文查询数据库并自动生成可视化图表。系统采用多 Agent 协作架构，通过 LangGraph 实现状态驱动的工作流编排，将自然语言问题转换为 SQL 查询、执行查询、生成图表配置并提取数据洞察。

核心价值

• 自然语言查询数据库：用户无需掌握 SQL 语法
• 自动可视化：基于查询结果自动生成 ECharts 图表配置
• 智能数据洞察：自动提取关键发现和趋势
• 字典值转换：支持业务友好名称到数据库 ID 的自动转换

---

业务功能

1. 自然语言到 SQL 转换

用户可以用自然语言（如"显示销售额前5的产品"）提问，系统自动生成对应的 SQL 查询语句。

2. 智能表结构选择

根据用户问题，从数据库的多个表中选择相关的表结构进行查询。

3. SQL 错误自动纠正

SQL 执行失败时，系统会自动分析错误信息并修正 SQL 语句，最多重试 3 次。

4. 可视化图表生成

根据查询结果自动选择合适的图表类型（柱状图、折线图、饼图、散点图、表格），生成 ECharts 配置。

5. 数据洞察分析

自动分析查询结果，提取关键发现、趋势和异常，提供业务洞察。

6. 字典值转换

将用户友好的业务名称（如"云总机"）自动转换为数据库中的 ID 值（如"1001"），支持同义词识别。

7. 多语言支持

支持中文和英文问答，自动适应不同语言环境。

8. Web 监控界面

提供实时监控面板，显示各 Agent 的执行状态和中间结果。

---

技术栈

表示层

技术	版本	用途
Flask	3.0+	Web 框架，提供 REST API
Server-Sent Events (SSE)	-	实时推送执行状态
HTML/JavaScript	-	前端监控面板

应用层（工作流引擎）

技术	版本	用途
LangGraph	1.0+	状态图工作流编排
LangChain	1.2+	LLM 调用封装
LangChain OpenAI	1.1+	OpenAI 集成
LangChain Core	1.2+	核心抽象和工具

领域层（Agent）

技术	版本	用途
Python	3.9+	核心语言，支持 async/await
Pydantic	2.5+	数据验证和结构化输出

数据层

技术	版本	用途
MySQL	8.0+	主数据库
PyMySQL	1.1+	MySQL 驱动
YAML	-	字典和同义词配置

基础设施层

技术	版本	用途
OpenAI API	-	GPT-3.5/4 语言模型
httpx	0.25+	异步 HTTP 客户端
aiohttp	3.9+	异步 HTTP 支持

可观测性

技术	版本	用途
Loguru	0.7+	结构化日志
pytest	7.4+	单元测试
pytest-asyncio	0.21+	异步测试

安全层

技术	版本	用途
python-dotenv	1.0+	环境变量和密钥管理

---

技术-问题映射

技术	类别	解决的业务问题	解决的技术问题	替代方案
LangGraph	工作流引擎	实现复杂的多步骤查询处理流程	状态驱动的节点编排、条件路由、并行执行	手写状态机、Airflow DAG
LangChain	LLM 框架	统一的 LLM 调用接口	提示词管理、结构化输出、回调机制	直接调用 OpenAI API
Flask	Web 框架	提供 Web 界面和 API	轻量级 REST API、SSE 实时推送	FastAPI、Django
Pydantic	数据验证	确保 LLM 输出格式正确	结构化输出、类型安全、数据验证	手动 JSON 解析
PyMySQL	数据库驱动	执行 SQL 查询获取业务数据	MySQL 连接管理、游标管理	MySQL Connector、SQLAlchemy
OpenAI API	LLM 服务	理解自然语言并生成 SQL	自然语言理解、SQL 生成、数据洞察	Claude、本地模型
Loguru	日志	调试和问题排查	结构化日志、异常追踪	标准库 logging
YAML	配置	字典和同义词配置	易读的配置文件格式	JSON、数据库存储

---

架构概述

系统架构模式

LangChain ChatBI 采用 状态驱动的多 Agent 协作架构，具有以下特点：

1. 工作流编排：使用 LangGraph 的 StateGraph 定义节点和边
2. 状态流转：ChatBIState 在节点间流转，累积中间结果
3. 条件路由：根据意图分类和 SQL 执行结果动态路由
4. 并行执行：图表生成和数据洞察并行执行
5. 会话记忆：MemorySaver 提供跨请求的会话状态

数据流

用户问题 (自然语言)
    ↓
[Preprocessing 节点] → 字典值转换 (业务名称 → ID)
    ↓
[Intent 节点] → 意图分类 (query/greeting/help)
    ↓ (query)
[Schema 节点] → 选择相关表结构
    ↓
[Reasoning 节点] → 生成查询推理计划
    ↓
[SQL 节点] → 生成 SQL 查询
    ↓
[DbType 节点] → 判断数据库类型
    ↓
[Execution 节点] → 执行 SQL (失败则重试)
    ↓
[并行分支]
    ├─→ [Chart 节点] → 生成图表配置 ─┐
    └─→ [Diagnosis 节点] → 数据洞察 ─┤
                                        ↓
                              [Answer 节点] → 自然语言答案
                                        ↓
                                    输出结果

组件交互

1. Web 层：Flask 应用接收 HTTP 请求，通过 SSE 推送执行状态
2. 工作流层：LangGraph 编译的工作流协调整个流程
3. Agent 层：7 个专用 Agent 各司其职，调用 LLM 完成任务
4. 服务层：字典服务提供值转换，LLM 服务提供模型调用
5. 数据层：MySQL 连接执行 SQL，YAML 配置提供字典映射

---

架构图

高层架构图

参见 docs/high_level_architecture.puml

详细组件图

参见 docs/detailed_component.puml

技术栈图

参见 docs/technology_stack.puml

关键技术决策

1. 为什么选择 LangGraph 而非手动状态机？

决策理由：

• LangGraph 提供声明式的工作流定义
• 内置状态管理和条件路由
• 支持并行节点执行
• 提供可视化和调试工具

权衡：

• 学习曲线较陡
• 依赖 LangChain 生态系统

2. 为什么使用 7 个独立的 Agent？

决策理由：

• 单一职责：每个 Agent 专注于一个任务
• 易于测试：可以独立测试每个 Agent
• 可扩展性：可以单独升级或替换某个 Agent
• 并行执行：图表生成和洞察分析可以并行

权衡：

• 更多的 LLM 调用（成本增加）
• 状态管理复杂度提高

3. 为什么字典服务支持混合数据源？

决策理由：

• 静态配置：适合稳定的映射关系（如产品名称）
• 动态数据库：适合频繁变化的映射（如用户 ID）
• 缓存机制：减少数据库查询，提高性能

技术实现：

• 支持静态 YAML 配置
• 支持数据库表查询
• TTL 缓存自动刷新
• 同义词优先匹配

4. 为什么使用 Flask 而非 FastAPI？

决策理由：

• 简单易用，学习曲线低
• SSE 实现简单
• 项目规模较小，不需要 FastAPI 的自动文档等功能

权衡：

• 没有 async/await 原生支持（需要使用线程）
• 没有自动 API 文档

5. 为什么选择 Pydantic v2？

决策理由：

• LangChain 结构化输出依赖 Pydantic
• 提供运行时类型检查
• 自动 JSON 序列化/反序列化
• 更好的性能（v2 比 v1 快 5-50 倍）

---

目录结构

langchain_chatbi/
├── agents/                    # Agent 实现
│   ├── base.py               # 基类 LangChainAgentBase
│   ├── intent_agent.py       # 意图分类 Agent
│   ├── schema_agent.py       # 表结构选择 Agent
│   ├── sql_agent.py          # SQL 生成 Agent
│   ├── reasoning_agent.py    # 查询推理 Agent
│   ├── chart_agent.py        # 图表生成 Agent
│   ├── diagnosis_agent.py    # 数据洞察 Agent
│   └── answer_agent.py       # 答案生成 Agent
├── graph/                     # LangGraph 工作流
│   ├── state.py              # ChatBIState 状态定义
│   ├── nodes.py              # 节点函数
│   ├── edges.py              # 条件路由
│   └── workflow.py           # 工作流编译
├── models/                    # Pydantic 数据模型
│   └── response_models.py    # 响应模型定义
├── llm/                       # LLM 集成
│   └── langchain_llm.py      # LangChain LLM 封装
├── db/                        # 数据库访问
│   ├── mysql_db.py           # MySQL 连接
│   └── db_factory.py         # 数据库工厂
├── dictionary/                # 字典服务
│   ├── dictionary_service.py # 字典转换服务
│   └── models.py             # 字典模型
├── web/                       # Web 应用
│   └── app.py                # Flask 应用
├── config/                    # 配置文件
│   ├── dictionary_config.yaml # 字典配置
│   └── synonym_config.yaml    # 同义词配置
├── tests/                     # 测试
│   ├── conftest.py           # Pytest 配置
│   └── test_*.py             # 单元测试
├── demos/                     # 演示脚本
├── prompts/                   # 提示词模板
├── observability/             # 可观测性
├── utils/                     # 工具函数
├── requirements.txt           # Python 依赖
├── pyproject.toml            # 项目配置
└── docs/                     # 文档
    ├── high_level_architecture.puml
    ├── detailed_component.puml
    ├── technology_stack.puml
    └── architecture_analysis.md

---

建议

技术债务

1. LLM 调用优化：考虑使用本地缓存减少重复调用
2. 异步迁移：将 Flask 升级到 FastAPI 以获得更好的异步支持
3. 配置管理：考虑使用配置中心（如 Consul）替代 YAML 文件

改进机会

1. 数据库抽象：支持更多数据库类型（PostgreSQL、SQLite）
2. Agent 性能优化：并行化更多节点（如 schema + reasoning）
3. 监控增强：添加 Langfuse 等可观测性平台集成
4. 错误处理：更细粒度的错误分类和恢复策略

扩展方向

1. 多租户支持：隔离不同用户的数据库和配置
2. 权限控制：基于角色的数据访问控制
3. 导出功能：支持导出为 Excel、PDF 等格式
4. 自然语言反馈：支持用户对结果进行追问和修正

---

参考资源

• LangChain 文档
• LangGraph 文档
• OpenAI API 文档
• Pydantic v2 文档
• Flask 文档

---

生成日期: 2026-01-31 版本: 1.0.0 项目: langchain-chatbi