OpenChatBI：用自然语言对话数据库的智能 BI 助手

当 BI 系统开始「听懂人话」

想象这样一个场景：业务部门的产品经理想看「过去三个月华北区域按周维度的转化率趋势」，传统流程是需要找数据工程师写 SQL，等排期，看结果，不满意再改，一来一回可能耗费半天。而在 OpenChatBI 中，只需要输入一句话，系统自动理解意图、生成 SQL、连接数据仓库、执行查询、返回带图表的可视化结果——整个过程不到 30 秒。

这就是 OpenChatBI 的核心价值：用自然语言驱动数据分析，让不懂 SQL 的人也能自助完成数据探索。

---

项目背景：从 text2sql 到端到端 BI Agent

OpenChatBI 由独立开发者 zhongyu09（Yu Zhong） 开发，项目于 2024 年创建，目标是将大语言模型的自然语言理解能力与数据分析工作流深度结合。

在 OpenChatBI 之前，text2sql（文本转 SQL）领域已有多个成熟方案。但这些方案大多止步于「生成一条 SQL」，无法处理数据分析的完整链路：理解问题 → 选择数据源 → 生成查询 → 执行验证 → 可视化展示 → 追问深挖。

zhongyu09 的思路是做完整的对话式 BI Agent：以 LangGraph 为核心编排引擎，将 text2sql、时间序列预测、异常检测、根因下钻、Python 代码执行等多种能力串联为一个协作网络，用户通过自然语言就能驱动整个分析流程。

---

核心功能：不止于 SQL 生成

1. 自然语言转 SQL（text2sql）

OpenChatBI 的 text2sql 模块基于 LangChain + OpenAI/Claude API 实现，包含以下关键步骤：

• Schema Linking：根据用户问题，自动从数据目录中检索相关表和字段，避免生成指向不存在表的 SQL
• Prompt Engineering：精心设计的系统提示词，引导 LLM 生成符合目标数据库方言的 SQL
• 置信度评估：对生成的 SQL 进行置信度打分，低置信度时主动向用户确认
• 可视化渲染：查询结果通过 Plotly 直接渲染为交互图表

2. 数据目录管理（Data Catalog）

• 表结构自动发现：连接数据仓库后，自动扫描并注册所有表和字段
• 元数据存储后端：支持向量检索（Chroma）和 BM25 两种模式，灵活适配不同规模
• 业务语义标注：用户可以为表和字段添加中文注释，优化检索质量
• 检索增强：结合目录知识库和外部知识库（MCP 工具），处理跨数据库的复杂问题

3. 数据分析 Agent

这是 OpenChatBI 最具深度的部分——一个专门处理复杂分析任务的子 Agent，基于 deepagents 框架构建，可调度多种分析工具：

• 时间序列预测：内置预测模型，处理趋势分析和预测
• 异常检测：自动识别数据中的异常波动点
• 根因下钻（Adtributor）：当发现异常时，系统自动进行多维度下钻分析，精确定位异常来源
• Python 执行：在沙箱中运行用户提交的 Python 代码，完成自定义数据处理
• 多指标关联分析：跨指标相关性分析，发现业务关联规律

4. 对话式记忆管理

基于 LangGraph Checkpointing 实现对话历史持久化和用户特征记忆，支持跨会话继续分析，长分析任务可任意节点中断恢复。

5. MCP 工具集成

OpenChatBI 支持通过 MCP（Model Context Protocol）接入外部工具，扩展能力边界：接入外部知识库回答需要领域知识的复杂问题，通过配置文件注册任意 MCP 兼容工具。

---

技术架构：LangGraph 驱动的多 Agent 协作网络

OpenChatBI 采用单主 Agent + 多工具子模块的架构，主 Agent 基于 LangGraph 实现有状态的工作流编排。

核心技术栈

组件	技术选型	职责
Agent 框架	LangGraph 1.x + LangChain 1.x	工作流编排、状态管理
LLM 接入	LangChain OpenAI/Anthropic	GPT-4 / Claude 3 接口封装
向量检索	Chroma (langchain-chroma)	数据目录语义检索
数据库连接	SQLAlchemy + PyHive	Presto/PostgreSQL/MySQL 多方言
Web UI	Streamlit + Gradio	两个示例界面
记忆存储	SQLite + langgraph-checkpoint	对话状态持久化
代码沙箱	RestrictedPython + Docker	Python 代码安全执行
图表渲染	Plotly	交互式数据可视化
中文分词	jieba（Python 3.12+ 回退标点切分）	Schema 检索

目录检索实现

openchatbi/catalog/ 下实现了两种检索模式：

• 向量检索（schema_retrival.py）：通过嵌入模型将表名、字段名、注释转为向量，语义匹配用户问题
• BM25 检索（retrival_helper.py）：传统关键词检索，作为无嵌入模型时的降级方案

text2sql 工作流

text2sql 模块（openchatbi/text2sql/）采用多步骤流水线：

1. extraction.py：从用户问题中抽取实体、聚合维度、时间范围
2. schema_linking.py：基于检索结果，选取最相关的表和字段
3. generate_sql.py：调用 LLM 生成 SQL，带置信度评分
4. confidence.py：二次校验 SQL 语法和逻辑
5. visualization.py：执行结果后，调用 Plotly 生成图表

---

部署与上手

安装要求

• Python：3.11+（注意 jieba 不兼容 Python 3.12+，需回退到标点切分）
• LLM：OpenAI GPT-4 或 Anthropic Claude（需要 API Key）
• 数据源：Presto / PostgreSQL / MySQL 等主流数据仓库
• Docker：仅在使用沙箱 Python 执行器时需要
• 嵌入模型：可选，用于向量检索；不安装则自动降级为 BM25

快速启动

# 源码安装
git clone git@github.com:zhongyu09/openchatbi.git
cd openchatbi
uv sync

# 配置 API Key（复制模板）
cp openchatbi/config.yaml.template openchatbi/config.yaml
# 编辑 config.yaml 填入 LLM API Key 和数据仓库连接信息

# 启动 Streamlit 界面
python run_streamlit_ui.py

Web UI 启动后访问 http://localhost:8501（Streamlit）或 http://localhost:7860（Gradio）。

Docker 部署（python-executor 模式）

项目提供 Dockerfile.python-executor 用于构建安全的 Python 代码执行沙箱：

docker build -f Dockerfile.python-executor -t openchatbi-executor .

主服务仍需通过 pip 或源码启动，Docker 仅用于隔离用户提交的 Python 代码执行环境。

---

局限性与挑战

1. SQL 生成质量依赖 LLM

text2sql 的效果直接受制于底层 LLM 的能力。对于复杂的多表 JOIN、嵌套子查询、特定数据库方言的语法差异，GPT-4 偶尔会生成不正确或非最优的 SQL。建议在高风险场景（涉及财务/运营指标）下，始终由数据工程师复核生成的 SQL。

2. 数据安全

当前版本通过配置文件明文存储数据仓库连接凭证（用户名、密码）。在生产环境中，建议使用环境变量或密钥管理服务注入凭证，避免凭证泄露。

3. Python 执行器的安全边界

RestrictedPython 提供了一定的沙箱限制，但并非完全不可渗透的隔离。生产部署建议配合 Docker 容器网络隔离，确保恶意代码无法访问内网资源。

4. 仍处于 Beta 阶段

项目版本号 1.0.0b1，README 中明确标注异常检测和根因下钻算法仍处于「向生产就绪迭代」阶段，实际使用中可能遇到边界 case 处理不够完善的情况。

5. 部署复杂度不低

虽然提供了 Streamlit UI，但完整的 OpenChatBI 部署涉及：配置 LLM API、连接数据仓库、配置目录检索、部署 Docker 沙箱（可选）——对于非技术用户来说，门槛仍然较高，与「零配置」的理想状态仍有距离。

---

行业意义：LLM 重塑数据分析范式

从「找工程师」到「自己来」

传统 BI 系统的核心矛盾是需求与供给的错配：业务人员有分析需求，但需要通过数据工程师作为中介，排队等待。OpenChatBI 代表了一种新兴趋势——用 LLM 消除这个中介层，让业务人员用自然语言直接驱动数据探索。

类似的探索还包括：微软的 Microsoft Fabric Copilot、Tableau 的 Pulse、SQLGlot 的 NL2SQL 功能等。OpenChatBI 的差异化在于它的端到端性：不只生成 SQL，而是覆盖从问题理解、数据定位、查询执行、可视化到追问深挖的完整链路。

LangGraph 作为 Agent 编排的成熟案例

LangGraph 1.x 以其状态机模型和检查点机制，为 OpenChatBI 的多轮对话和长任务可恢复性提供了可靠基础设施。相比直接基于 LangChain 的 Agent，LangGraph 的图结构更适合表达复杂的条件分支和工具调度逻辑，zhongyu09 的实践为社区提供了有价值的参考。

开源生态的价值

作为一个 MIT 许可证的开源项目，OpenChatBI 的透明性让企业可以自行部署、数据不外流，同时允许社区贡献算法改进（如更准确的异常检测算法、更全面的 SQL 方言支持）。这对担心数据安全的金融、医疗行业用户尤为重要。

---

总结：谁应该关注 OpenChatBI？

强烈推荐：

• 有数据仓库（Presto/PostgreSQL/MySQL）并希望业务人员自助分析的团队
• 对 LangGraph Agent 架构感兴趣，想参考实际生产代码的开发者
• 需要快速搭建内部「对话式 BI」能力的数据平台团队

观望考虑：

• 数据安全要求极高、无法将凭证交给第三方 LLM 的场景
• 已有成熟 BI 系统（如 Tableau、Power BI）且用户满意度高的团队
• 非技术用户为主、无法完成 Python 环境配置和数据仓库连接配置的场景

一句话推荐：OpenChatBI 是 text2sql 领域一个有诚意的端到端开源方案，用 LangGraph 串联起从自然语言到数据洞察的完整链条——对于想搭建内部对话式 BI 能力的团队，值得在测试环境跑一跑 demo 看看效果。

---

项目仓库：https://github.com/zhongyu09/openchatbi | 许可证：MIT | 作者：zhongyu09