DB-GPT Chat Excel用自然语言对话分析 Excel 数据的实现原理与使用指南【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPTChat Excel 是 DB-GPT 内置的表格数据分析应用用户上传一份 Excel/CSV 文件后即可用自然语言直接提问系统会自动将文件导入 DuckDB、生成数据摘要与提问建议并通过LLM 生成 SQL 执行 可视化渲染的闭环返回分析结果。本文基于仓库中的官方使用文档与dbgpt-app场景源码完整梳理其使用步骤、底层处理流水线文件加载、Excel 学习、SQL 分析与可视化以及可配置项读完后可理解 Chat Excel 从一份表格文件到可对话的数据分析库的完整技术链路。Chat Excel 是什么按官方文档 chat_excel.md 的定义Chat Excel means that you can interpret and analyze Excel data through natural language dialogue.即通过自然语言对话来解读和分析 Excel 数据。它作为 DB-GPT 的内置场景注册在 scene/base.py 中ChatExcel Scene( codechat_excel, nameChat Excel, describeDialogue with your excel, use natural language., param_types[File Select], )注意param_types[File Select]与其他需要绑定数据库连接、知识库资源的场景不同Chat Excel 的参数不是预先绑定的数据源而是在会话中直接选择文件。这与前端实现一致——NativeApp.tsx 在配置应用时会判断chatScene ! chat_excel为 Chat Excel 隐藏参数绑定下拉框因为它的参数就是聊天窗口里上传的文件本身。使用步骤官方文档给出的使用流程分为三步选择 Chat Excel 应用 → 上传 Excel 文件 → 开始对话。下面逐步说明并补充源码中的实际行为。1. 选择Chat Excel应用在 Web 界面左侧的应用列表中进入Chat Excel。前端通过场景标识chat_excel控制专属交互chat-excel.tsx 中只有当scene chat_excel时聊天头部才会渲染文件上传/文件信息组件其余场景该组件直接返回null。2. 上传 Excel 文件进入会话后通过头部Select File Upload按钮上传文件。从 excel-upload.tsx 可以看到几个关键约束文件格式accept.csv,.xlsx,.xls且提交前有正则校验/\.(csv|xlsx|xls)$/其他格式会被拒绝上传接口调用postChatModeParamsFileLoad见 request.ts以doc_file字段携带文件同时附带convUid会话 ID、chatMode、模型及 temperature/max_new_tokens 参数请求超时被设置为 1 小时timeout: 1000 * 60 * 60因为上传后服务端还要完成文件解析与Excel 学习大文件耗时较长文件不可更换UI 上有明确的 Tooltip 提示File cannot be changed after upload上传完成后移除/更换按钮均被禁用。官方文档中有一条重要说明⚠️ the Excel file format is converted to.csvformat即上传的 Excel 在内部会被转换为 CSV 形式的表格数据来处理后文会看到实际的落地形态更进一步——最终物化为 DuckDB 表。上传成功后系统默认对内容做摘要并推荐若干提问策略这个摘要 提问建议不是静态文案而是由后文的ExcelLearning预执行阶段真实生成并写回数据库的表注释中。3. 开始对话此后即可基于上传的文件自由提问。前端整体交互示意如下源码解析从文件到可对话数据库的完整流水线Chat Excel 的实现位于 packages/dbgpt-app/src/dbgpt_app/scene/chat_data/chat_excel由三个核心部分构成excel_analyze对话分析主场景、excel_learning首次学习阶段、excel_reader文件与 DuckDB 访问层。场景类在 chat_factory.py 中被延迟导入注册。文件解析ExcelReader 与 DuckDB 导入excel_analyze/chat.py 中的ChatExcel.__init__是入口。它首先校验select_param即上传文件的路径未上传文件会直接抛出Please upload the Excel document you want to talk to然后为本次会话解析出数据文件路径file_pathDuckDB 数据库路径{DATA_DIR}/_chat_excel_tmp/_chat_excel_{file_name}.duckdb——每个 Excel 文件对应一个独立的 DuckDB 数据库文件作为会话级临时数据库固定表名data_analysis_table。随后创建ExcelReaderread_typedirect。excel_reader.py 的加载策略是多路降级read_direct先尝试让 DuckDB 按文件扩展名自动导入create table {table_name} as SELECT * FROM {file_path}失败则按扩展名显式选择加载函数.csv用read_csv、.xlsx用read_xlsxempty_as_varchartrue, ignore_errorstrue、.json用read_json_auto、.parquet用read_parquet.xls旧格式以及前两步全部失败时回退到read_from_df用 pandas 读入 DataFrame先经chardet探测编码空串替换为 NaN再对每一列做类型推断——可解析为日期的列统一格式化为%Y-%m-%d否则尝试转数值最后兜底为字符串列名统一做strip 空格替换为下划线最后CREATE TABLE ... AS SELECT *物化到 DuckDB。这一层解释了上传成功后内容被默认摘要的前提所有后续分析都建立在这张 DuckDB 表之上。Excel 学习阶段生成摘要与提问建议ChatExcel.prepare()会在首轮对话前插入一次学习调用构造chat_modeExcelLearning的ChatParam以[文件名] Analyze作为输入执行 excel_learning/chat.py 中的ExcelLearning它把data_example采样数据、table_summary通过 DuckDBSUMMARIZE {table}得到的统计摘要见ExcelReader.get_summary和table_schema注入提示词让 LLM 产出结构化的TransformedExcelResponse包含description表的自然语言描述、columns新旧列名映射与每列说明、plans推荐的提问策略随后do_action调用ExcelReader.transform_table把学习结果真正写回 DuckDB按映射重命名列保留原列类型、执行COMMENT ON TABLE ... IS {description}写入表注释、对每列执行COMMENT ON COLUMN ... IS {column_description}写入列注释。这就是官方文档中上传成功后内容会被默认摘要、并推荐一些提问策略的源码依据摘要成为表注释plans成为前端展示的推荐问题。对话分析LLM 生成 SQL 并可视化执行每轮对话的核心链路如下组装提示词输入ChatExcel.generate_input_values通过ExcelReader取到table_schemaget_create_table_sql重建的建表 DDL含列类型/可空性/注释和data_exampleSELECT * FROM {table} USING SAMPLE 5的 5 行采样连同展示方式列表display_type一起填入提示词模板提示词约束excel_analyze/prompt.py 将模型设定为数据分析专家明确要求基于 DuckDB 语法作答并内置了 DuckDBGROUP BY的关键注意事项非聚合列必须出现在 GROUP BY、多层 CTE 列引用一致性、可用ANY_VALUE()兜底、时间戳用to_timestamp()而非直接 CAST 等。输出必须转换为如下可被程序解析的格式api-call name[数据展示方式]/name argssql[正确的 duckdb 数据分析 sql]/sql/args /api-call模板中附带了按地区统计销售额与利润率和近 24 个月销售趋势两个 Few-shot 示例DATE_TRUNC(month, ...)、NULLIF防除零等写法且该场景注册温度为PROMPT_TEMPERATURE 0.3以换取更稳定的 SQL 输出执行与渲染ChatExcel.stream_plugin_call调用ApiCall.display_sql_llmvis把 LLM 输出中的 SQL 交给ExcelReader.get_df_by_sql_ex执行取回 DataFrame 后按name指定的展示方式渲染为图表中文列名兜底真实业务表格常含中文列名ExcelReader.run执行前会调用add_quotes_to_chinese_columns基于 sqlparse检测 SQL 中的中文标识符并自动加双引号避免 DuckDB 解析报错。另外hf_adapter.py 中的场景列表包含chat_excel当使用 HuggingFace 本地模型时该场景会走代码类对话的提示词风格源码注释中说明这是当前的临时区分方案。状态复用与文件存储为了让多轮对话不必重复解析文件ChatExcel做了两层缓存本地层DuckDB 文件落在{DATA_DIR}/_chat_excel_tmp/下ExcelReader.__init__检测数据库文件已存在时直接复用已有data_analysis_table跳过重新导入分布式层当文件来源是对象存储file_path.startswith(_SCHEMA)时_resolve_path会先把文件下载到本地并在首轮学习完成后把 DuckDB 数据库文件以file_id_{conv_uid}为键上传回dbgpt_app_filebucket后续请求发现该数据库文件已存在时直接下载复用见chat.py中prepare与_resolve_path的逻辑。可配置项Chat Excel 的应用级配置定义在 chat_data/chat_excel/config.py配置项默认值说明model/temperature/max_new_tokens由应用配置决定常规 LLM 参数前端 NativeApp 表单中可设置temperature 取值 0~1duckdb_extensions_dir空列表DuckDB 扩展.duckdb_extension/.duckdb_extension.gz所在目录列表。留空时 DuckDB 会自行从网络下载扩展配置本地目录可让离线环境直接使用。注意扩展具有平台/版本相关性force_installFalse为True时即使扩展已安装也会强制重装ExcelReader.install_extension中据此判断跳过或安装memoryBufferWindow 窗口keep_start_rounds0、keep_end_rounds10对话记忆配置控制提示词中保留的历史轮数在应用构建界面Construct → App中Chat Excel 的可选参数即模型、Prompt 模板、temperature 与 max_new_tokens其中参数绑定项对该场景不生效文件在会话内选择。适用场景与限制适用单文件维度的即席分析——销售明细、财务报表、调研数据等以.csv/.xlsx/.xls存在的表格支持中文列名与日期/数值混合列配合推荐问题业务人员无需写 SQL 即可完成分组聚合、趋势分析并直接获得图表。实现层面的限制均可在源码中确认文件在上传后不可更换需新开会话重新上传.xls旧格式与异常文件会走 pandas 降级解析路径类型推断基于日期 → 数值 → 字符串的固定顺序复杂混合列需留意类型是否符合预期分析能力受 DuckDB 单表能力与所选 LLM 的 SQL 生成质量约束提示词中的约束GROUP BY 规则、api-call格式、temperature 0.3正是为降低这类不稳定而设置学习阶段表注释/列注释/推荐问题仅在首轮执行源码中同样存在多轮对话下消息调整的多轮 TODO 注释说明该环节主要针对首轮场景优化。小结Chat Excel 的本质是一条文件 → DuckDB 表 → LLM 学习摘要/重命名/推荐问题→ 每轮生成 SQL → 执行 → 可视化对话循环的流水线。使用上只需三步选择应用、上传.csv/.xlsx/.xls文件、开始提问理解上掌握ChatExcel会话编排、ExcelLearning首轮学习、ExcelReader文件与 DuckDB 访问三个类的分工即可完整复现或扩展这一场景的行为例如替换 DuckDB 扩展目录以适配离线环境或基于api-call输出格式对接自己的可视化组件。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考