OpenChatBI 对话式智能BI分析助手
基于大语言模型的开源对话式BI工具，让用户用自然语言即可完成数据查询、分析与可视化，无需手写SQL。
最小权限：SQL结果默认限行、fail-closed SQL守卫可选、建议只读账号，处理较充分，扣1分因守卫是正则且默认fail-open。用户确认：HITL置信门（批准/拒绝/编辑）存在但默认关闭，扣分。数据流透明：架构图、目录库与数仓配置分离的说明清晰。敏感数据：审计日志默认对SQL字面量脱敏，但仓库凭据写入config.yaml的处理未充分说明。依赖安全：版本范围合理但未提供lock审计/依赖扫描证据。外部影响：代码执行提供local/RestrictedPython/Docker三档，但默认执行模式及其隔离强度未在证据中确认，扣分明显。回滚：无迁移回退或状态回滚说明。来源归属：作者与LICENSE明确（Yu Zhong, MIT），但发布者未经验证，且无外部引用声明，扣分。
自洽：README与pyproject（1.0.0b1、LangGraph v1要求、jieba/Py3.12不兼容）一致，但README出现'sample_ui streamlit_ui.py'拼写错误。依赖可用性：明确版本下限与可选extras、BM25回退降级路径，处理充分。失败消息：SQL错误分类恢复策略、jinja式重试预算有描述，但具体错误文案与用户可见信息未在证据中直接展示，扣1分。
受众与场景：开发者/分析师/终端用户分类器、多LLM多方言、CLI/API/两种UI，覆盖充分给满。能力边界：路线图明确标注'initial version, toward production readiness'，扣分因分析子代理的边界主要靠自我声明。触发精度：agent graph与text2sql graph的路由/中断逻辑有图示，但未见触发词或工具选择精度的测试证据。环境适配：Python 3.11+、多平台安装指引、jieba降级处理充分，Docker为可选。
信息架构：项目结构树详细到文件级，给满。安装说明：uv/pip/开发三种方式、可选SQLite编译指引、extras说明完备。命名稳定性：1.0.0b1为beta，API尚在变动（LangGraph v1升级要求降级到v0.2.2），扣分。示例与FAQ：demo配置、melted数据示例测试、evals流程，但无FAQ章节。已知限制：jieba不兼容3.12+、SQL守卫可能误拒方言SQL、路线图坦诚，给满。许可证：MIT全文在库。版本变更日志：无CHANGELOG文件证据，仅靠版本号，扣分明显。维护责任：单人维护（Yu Zhong），无治理/贡献者协议证据，未验证发布者，扣分。
输出可用性：plotly可视化、show_schema、save_report工具与流式UI，描述充分。边际价值：相比直接用LangChain自建，目录管理、置信门、golden SQL、Adtributor等组合有差异化，但多数为可选开关且成熟度自评为beta。成本效益：token/成本核算指标、专用analysis_llm可分离成本，多executor可选，合理；无实测成本数据，扣分。
声明可追溯：README声明大多能对应到文件路径（analysis/README、evals/judge/README、migrate.py），结构树可核对。交叉印证：pyproject的依赖、版本、extras与README一致，测试文件印证Adtributor与agent graph构建声明；但审计/置信门/golden SQL等核心安全声明无对应测试在证据中。事实与推断分离：路线图明确区分'initial version'与'toward production readiness'，诚实标注未完成项，给满。
- SQL守卫默认fail-open且为正则实现，可能漏检或误拒方言SQL；务必用只读非超级用户账号连接数仓。
- 代码执行的默认模式未在证据中确认，生产环境应显式配置Docker executor而非本地执行。
- HITL置信门、审计日志、golden SQL等安全与质量特性默认关闭，部署前需在config.yaml中显式启用。
- 数仓凭据写入config.yaml的处理文档不足，注意凭据泄露风险。
- 项目为单人维护的beta版本（1.0.0b1），无变更日志，升级LangGraph v1等破坏性变更需自行评估；本评估为静态审查，未做任何执行验证。
这个 Agent 能做什么，适合哪些场景？
OpenChatBI 是一个开源的对话式商业智能工具，核心是基于 LangGraph v1 和 LangChain 构建的 Agent 图与工作流。它将自然语言问题通过多阶段 Text2SQL 流水线（信息抽取、表选择、Schema Linking、SQL 生成、执行、评分与置信度门控）转换为 SQL 并执行，再用 Plotly 生成可视化结果。除 Text2SQL 外，它还内置一个基于 deepagents 的数据分析子 Agent，可编排时间序列预测、异常检测和 Adtributor 多维下钻根因分析，并支持沙箱化的 Python 代码执行。系统配备数据目录管理（文件系统或 SQLAlchemy 数据库后端，支持向量或 BM25 检索）、持久化会话记忆、MCP 工具集成，以及 Streamlit/Gradio 示例界面和 FastAPI 异步 API。可选的 Agent Harness 特性提供审计日志、Langfuse 追踪、HITL 置信度门控、SQL 错误恢复、学习式 SQL 记忆和评估工具链，但默认关闭。项目采用 MIT 许可证，需要 Python 3.11+、一个 LLM 提供商 API 密钥和数据仓库连接凭据。
OpenChatBI 接收用户的自然语言问题，通过 get_default_graph() 返回的 LangGraph 图进行处理：llm_node 节点调度 text2sql、data_analysis、run_python_code、search_knowledge、show_schema、memory_tools、mcp_tools 等工具，并在信息不足时通过 AskHuman 工具主动追问。Text2SQL 图依次执行信息抽取（information_extraction）、表选择（table_selection）、SQL 生成（generate_sql）、执行（execute_sql）、评分（score_sql）和可视化（generate_visualization），可选置信度门控会拦截低分 SQL 让用户审批。数据目录自动发现并索引数仓表结构，为 Schema Linking 提供表/列业务语义和派生指标定义；数据分析子 Agent 编排 text2sql、时间序列预测（独立预测服务）、异常检测、Adtributor 下钻和 Python 执行。输出包括系统生成的 SQL、查询结果和 Plotly 图表，可通过 Streamlit/Gradio 界面、CLI（run_cli.py）或 FastAPI 异步 API 使用。
- 数据分析师希望用中文或英文自然语言直接查询 Presto/PostgreSQL/MySQL 数仓并获得 SQL、结果表和图表，而不必手写查询。
- 业务运营人员需要监控指标趋势，当出现异常时利用 Adtributor 下钻自动定位根因维度。
- 数据团队希望建设带数据目录的 Text2SQL 平台，通过维护表/列的业务描述、SQL 规则和派生指标来持续提升生成质量。
- 工程团队需要将对话式 BI 能力嵌入自有 Web 应用，可复用 Streamlit/Gradio 示例或 sample_api/async_api.py 的 FastAPI 接口。
- 需要严格安全控制的部署可以启用 fail-closed SQL 守卫、Docker 沙箱代码执行、审计日志和 HITL 置信度门控。
- 拥有已批准 SQL 沉淀的团队可开启学习式 SQL 记忆与 Golden SQL，让高质量查询示例自动进入 few-shot 检索。
这个 Agent 有哪些优点和局限？
- Text2SQL 采用多阶段工作流（信息抽取、表选择、Schema Linking、生成、执行、评分），配合可维护的数据目录（表/列语义、SQL 规则、派生指标）和 few-shot 检索，而非单次提示生成。
- 内置差异化分析能力：基于 deepagents 的数据分析子 Agent 编排时间序列预测、异常检测和 Adtributor 多维下钻根因分析，超越简单的问数场景。
- 工程化程度高：提供 HITL 置信度门控、fail-closed SQL 守卫、Docker 沙箱代码执行、审计日志、Langfuse 追踪、RunLedger 确定性回放评估和 LLM-as-Judge 评估链路。
- 模型与后端高度可插拔：基于 LangChain 支持多家 LLM 提供商，检索在向量与 BM25 之间自动回退，目录存储支持文件系统与 SQLAlchemy 数据库并附迁移脚本。
- 运行要求较多：需要 Python 3.11+、LLM API 密钥、数据仓库凭据，时间序列预测还需单独部署一个 Docker 服务。
- jieba 中文分词在 Python 3.12+ 不可用，会退化为按标点分词，可能影响中文文本检索质量。
- 异常检测、根因分析和数据分析 Agent 均为初始版本，Roadmap 明确表示仍在向生产可用打磨。
- 可选高级特性（置信度门控、学习式记忆、Golden SQL、可观测性）默认全部关闭，需要自行在 config.yaml 中逐项启用；SQL 守卫基于正则，属于过渡方案，官方建议始终使用只读非超级用户账号连接数仓。
如何安装或部署这个 Agent？
环境要求：Python 3.11+（注意 jieba 在 3.12+ 不可用，会自动退化为按标点分词）、LLM 提供商 API 密钥、数据仓库凭据；可选 Docker 和 embedding 模型（缺失时自动改用 BM25 检索）。安装方式：
- 使用 uv（推荐）：
git clone [email protected]:zhongyu09/openchatbi
uv sync- 使用 pip：
pip install openchatbi- 开发模式：
uv sync --group dev若不依赖 LangGraph v1，请使用 v0.2.2 或更早版本。数据库驱动按需安装：pip install openchatbi[mysql] 或 openchatbi[postgresql]、openchatbi[azure-openai]、openchatbi[google-vertex-ai]、openchatbi[bedrock]、openchatbi[huggingface]、openchatbi[deepseek]、openchatbi[ollama]。
如何使用这个 Agent？
- 复制配置模板：cp openchatbi/config.yaml.template openchatbi/config.yaml，或直接用示例：cp example/config.yaml openchatbi/config.yaml，然后填入 API 密钥（sed -i 's/YOUR_API_KEY_HERE/[YOUR OPENAI API KEY]/g' openchatbi/config.yaml）。
- 在 config.yaml 中配置 default_llm、llm_providers（如 langchain_openai.ChatOpenAI）、可选的 embedding_model 和 text2sql_llm，以及数据仓库连接 data_warehouse_config（uri、include_tables、database_name）。
- 运行示例 Demo（使用 spider 数据集）：python run_streamlit_ui.py。
- 以代码方式调用：
export CONFIG_FILE=YOUR_CONFIG_FILE_PATH
from openchatbi import get_default_graph
graph = get_default_graph()
graph.invoke({"messages": [{"role": "user", "content": "Show me ctr trends for the past 7 days"}]}, config={"configurable": {"thread_id": "1"}})- 也可运行 CLI（python run_cli.py）、Streamlit UI（streamlit run sample_ui/streamlit_ui.py）或 Gradio UI（python sample_ui/streaming_ui.py）。时间序列预测需另行构建并启动 timeseries_forecasting 服务（./build_and_run.sh），并在配置中设置 timeseries_forecasting_service_url。