【免费下载链接】openchatbi
OpenChatBI is an intelligent chat-based BI tool powered by large language models, designed to help users query, analyze, and visualize data through natural language conversations. It uses LangGraph and LangChain to build chat agent and workflows that support natural language to SQL conversion and data analysis.
OpenChatBI 是一款基于大语言模型的智能对话式 BI 工具，用 LangGraph 和 LangChain 构建聊天 Agent 与工作流，支持自然语言转 SQL、数据分析与可视化。对于新手来说，用一句中文提问就能查出数据，非常友好。但 LLM 生成的 SQL 偶尔会执行失败——此时 OpenChatBI 会自动把错误分类、判断"该不该重试"，并把失败信息喂回模型生成修正版 SQL，整个流程对用户几乎无感。本文从代码层面拆解这套 SQL 错误恢复机制：错误如何分类、自动重试策略如何路由、失败上下文如何注入提示词。
一图看懂：Text2SQL 子图中的自动重试环路
OpenChatBI 的 SQL 生成由一个 LangGraph 状态子图驱动，节点包括 information_extraction、generate_sql、execute_sql、regenerate_sql 等。执行 SQL 失败后，条件边会把流程路由回 regenerate_sql 重新生成，而不是直接结束——这就是自动重试的骨架：
对应源码在 openchatbi/text2sql/sql_graph.py，节点函数定义在 openchatbi/text2sql/generate_sql.py。
4 种恢复策略：错误分类的核心
所有结构化错误都继承自 Text2SQLError，每个子类预置了一个"恢复策略"。策略由 RecoveryStrategy 枚举 定义，共 4 种：
| 策略 | 含义 | 后续动作 |
|---|---|---|
RETRY | 值得重试 | 回到 regenerate_sql 重新生成 SQL |
RETRY_WITH_NEW_TABLE | 换一张表重试 | 空结果场景下重新选表再生成 |
SURFACE_TO_USER | 直接暴露给用户 | 终止流程，展示错误信息 |
ABORT | 立即中止 | 不重试，结束 |
具体错误与策略的映射关系定义在 openchatbi/text2sql/errors.py：
- SQLSyntaxError（语法错误）→
RETRY：SQL 拼写/解析问题通常能被模型自我修正，值得重试； - SQLSecurityError（安全校验失败）→
SURFACE_TO_USER：生成 SQL 未通过安全校验（如试图越权操作），重试无意义，直接告知用户； - InvalidDBConnectionError（连接无效）→
SURFACE_TO_USER：连接本身有问题，重试也解决不了； - DBTimeoutError（执行超时）→
ABORT：默认不重试，避免慢查询被反复执行拖垮数据库； - EmptyResultError（空结果，需显式开启）→
RETRY_WITH_NEW_TABLE：查不到数据可能是选错了表； - UnknownSQLError（兜底类）→
RETRY：未知错误默认可尝试一次自愈。
从原始异常到分类错误：classify_sql_exception
数据库抛出的原始异常五花八门，classify_sql_exception 负责把它们归入上表：
- 超时（
TimeoutError）→DBTimeoutError； - OperationalError → 先用关键词启发式判断消息内容，如出现
timeout、connection refused、server has gone away等标记词归为超时/连接类，出现syntax error、unexpected token、near等标记词归为语法类（见 _classify_operational_error）； - ProgrammingError → 视为
SQLSyntaxError； - 其余
DatabaseError或未知异常 → 兜底为UnknownSQLError。
分类结果会连同"人类可读的错误标签"（error_type，如 SQL syntax error）一起写入状态，供重试节点和 UI 使用。错误码常量统一维护在 openchatbi/constants.py。
自动重试路由：哪些错重、哪些错不重
执行 SQL 节点之后，条件边函数 _route_after_execute 决定下一步走向，规则优先级如下：
- 执行成功（
SQL_SUCCESS）→ 走向可视化； - 超时 → 仅当用户显式开启
retry_on_timeout且未超过重试上限时才重试，否则终止。超时错误默认策略是ABORT，这里特意留出"显式配置优先"的旁路，方便用户按库调优； - 策略驱动 → 读取最近一条错误的
recovery_strategy：SURFACE_TO_USER/ABORT→ 直接结束；RETRY/RETRY_WITH_NEW_TABLE→ 若sql_retry_count < max_retries则回到regenerate_sql，否则结束；
- 兜底 → 无结构化策略的旧状态按错误码走传统路由。
重试上限默认 3 次，由配置项 sql_max_retries 控制，retry_on_timeout 默认关闭，两者定义在 openchatbi/config_loader.py，默认值可参考 openchatbi/config.yaml.template。
重试不是"盲重"：把失败历史注入提示词
regenerate_sql_node 是自动重试的关键实现。它会把历次失败尝试逐条拼进提示词：每次的 SQL 原文、错误类型（如 SQL syntax error）和错误信息，然后要求模型"分析上述错误并生成修正后的 SQL"。同时递增 sql_retry_count 计数器；若模型这次连 SQL 都吐不出来（空输出），则直接记录失败并结束，避免死循环。
这种"错误反馈驱动"的设计意味着：模型不是重新掷一次骰子，而是拿着具体的报错去修正，重试成功率远高于简单重放。
小结
OpenChatBI 的 SQL 错误恢复机制可以概括为三步：分类（原始异常 → 6 种结构化错误）、决策（4 种恢复策略 + 重试上限，超时与安全错误默认不盲试）、反馈（失败 SQL 与错误信息注入提示词重新生成）。对新手用户而言，这套机制让"提问—查询—出图"的体验更顺滑；对开发者而言，扩展新的错误类型时只需在 errors.py 中新增子类并指定策略，路由逻辑会自动生效。更多模块说明可参考官方文档目录 docs/source/ 中的 text2sql 与 tools 章节。
【免费下载链接】openchatbi
OpenChatBI is an intelligent chat-based BI tool powered by large language models, designed to help users query, analyze, and visualize data through natural language conversations. It uses LangGraph and LangChain to build chat agent and workflows that support natural language to SQL conversion and data analysis.
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
