企业官网建设流程全解析

简介：《2024 ChatBI+Agent实战手册》共134页，汇集平安人寿、滴滴、喜马拉雅、腾讯、快手、阿里巴巴、网易等八家知名企业的ChatBI与AI Agent真实落地案例，面向数据分析、AI研发及技术管理人员，聚焦大模型如何赋能智能BI，覆盖自然语言查数、SQL生成、报表智能解读、多轮对话分析以及Agent工具编排等应用场景。各案例完整展示了从项目背景、技术选型、架构设计、模型调优到效果评估与挑战应对的实操路径，并针对复杂指标查询、指标口径对齐、数据权限管理和可视化组装等问题，给出了可复用的解决思路，对理解ChatBI产品演进与Agent落地路径尤为直接。资源包内为单个PDF文档，共134页，大小9.33MB，适合按企业顺序通读，也可作为日常技术参考。目前已有四百三十三人学习，对正在规划或建设企业智能分析平台的数据团队具有较好的借鉴价值。

1. 2024 ChatBI+Agent 实战手册：为什么 ChatBI 的瓶颈不在 SQL 生成

2024 年做 ChatBI 的人，多半都撞上过同一堵墙：大模型生成 SQL 的能力早就够看，问答页面却上线两周就没人用。把这份 2024 ChatBI+Agent 实战手册（八大案例，共 134 页）当作技术路线重读后，我的反直觉结论是：ChatBI 的瓶颈不在 Text2SQL 准确率，而在把“一次翻译”当成了整个方案。Agent 化的本质，是把“问题 → SQL → 结果”这条直线，变成“理解 → 规划 → 执行 → 校验 → 解释”的决策循环。

134 页的八大案例指向同一个落点：当聊天主导权交还给模型，你得在它周围补上指标字典、记忆、沙盒和执行校验，否则智能体会在真实数仓里乱跑。下面按落地顺序讲：为什么非 Agent 不可、最小实现怎么做、案例怎么拆成套路、坑在哪，以及上线前必须做的验证。

2. 从 ChatBI 到 Agent：为什么多步决策比一次性生成 SQL 可靠

2.1 先承认一个事实：Text2SQL 不是 ChatBI 的全部

传统 ChatBI 的经典链路是：用户输入一句自然语言 → 把表结构和少量示例塞进提示词 → 模型生成 SQL → 执行 → 返回表格。这个链路在 demo 里非常能打，演示的时候都是“上个月华东区销售额多少”这种单表单指标问题。真实业务里，用户问的是“上个月毛利率为什么跌了两个点”，这句话至少包含四个问题：毛利率的口径是哪个、和什么周期比、跌两个点是怎么算出来的、需要拆到哪个维度去解释。一次性生成 SQL 的模型要么靠猜，要么抛出一个数字然后闭嘴。

我拆过的两个失败项目，问题都不在 SQL 生成上，而在三点：口径冲突没人管、多轮指代没人接、结果解释没人做。第一点最致命——同一家公司里，“毛利率”可能有三种定义，财务口径剔除内部调拨，运营口径只看线上渠道，管理层口径还要考虑未实现毛利。你把这些都塞给模型，它只能随机挑一个，然后领导问“这数哪来的”，项目就黄了。

所以 ChatBI 能不能用，先不取决于模型有多强，而取决于你有没有一套机制让它在开口之前先搞清楚“用户说的是哪个指标、在哪个权限范围、需要什么粒度”。这正是 Agent 能补上的部分。理解这一步，再谈上手才不跑偏。

2.2 Agent 化的本质：把“翻译”拆成“决策循环”

Agent 化之后，ChatBI 的内部结构从“一条直线”变成“一个可以停下来的循环”。我一般把它拆成五个节点：

• 规划：把用户问题拆成子目标，例如先找到指标定义，再确定时间范围，再决定是否做对比。
• 检索：从指标字典和 schema 里拿到与问题相关的表和口径，不是全量注入。
• 执行：调用 SQL 查询工具，这个工具被限制在只读账号里。
• 观察：拿到执行结果，判断是直接回答，还是结果为空需要改写，还是需要追加对比查询。
• 复盘与解释：把查询路径整理成结论，必要时把“为什么”写进答案。

传统 ChatBI 与 Agent 化 ChatBI 的对比：

这个表格是 2024 年做 ChatBI 落地时最常见的演进方向。你会发现每一步改动都不大，但合在一起，模型从“一次翻译器”变成了“一个能自查的数据分析实习生”。而 Agent 框架解决的就是这个循环的编排：哪些节点可以做、做几步、失败怎么跳转。这也是为什么这个方向不叫“Text2SQL 优化”，而叫“Agent 实战”。

2.3 先分清框架和 harness：Agent 的“编法”和“跑法”不是一回事

热词里 harness 和 agent 的区别几乎每个 Agent 项目都会被问到。我的理解是：Agent 框架管“怎么决策”，harness 管“在什么环境里跑”。落到 ChatBI，框架决定规划节点怎么调工具、怎么回退；harness 决定 SQL 在哪个数据库账号上执行、超时多少、返回多少行、能不能连外网。很多人把 SQL 执行限制写进提示词，要求模型“只能 SELECT，不要 UPDATE”，这在框架层做等于没做——模型可能被提示注入绕过。正确做法是把限制写在 harness 里，也就是 SQL 执行器本身只接受白名单账号，数据库侧连 UPDATE 权限都不给。

Agent 安全的核心也在这个边界上：提示词约束是软的，执行环境的约束才是硬的。我在 ChatBI 里把 SQL 执行器做成独立服务，由它统一管理连接池、超时和行数限制，模型层只传 SQL 文本，拿回的是 JSON 数组。这样即使模型被恶意问题带偏，最坏结果也是一条查询失败，而不是数据被改或全表被拉爆。harness 这个概念在 Agent 开发里越来越重要，原因就在这里。至于 Agent 部署，很多团队把执行沙盒独立部署，和推理服务分开扩缩容，SQL 并发高的时候只加沙盒节点，LLM 节点保持稳定——这是后话，第 5 章会提到并发相关的坑。

2.4 先别急着上“多 Agent”：什么情况才值得拆

多 Agent 是 2024 年被问烂的词。ChatBI 里我看到不少方案把“规划 Agent”“SQL Agent”“图表 Agent”全拆开，每人一个 prompt，结果链路延迟翻倍、token 成本翻三倍，回答质量并没有变好。判断要不要拆，我一般看三个条件：

• 任务类型是否差异够大，比如 SQL 生成和归因解释的 prompt 风格完全不同；
• 是否需要一个独立的校验角色，审核 SQL 再放行；
• 单 Agent 的上下文是否容易被工具结果撑爆。

如果只是“问销售数据 → 出数 → 画图”，单 Agent 加三个工具就够。真正值得拆的是那种“除了查数，还要对比历史、找异动原因、生成结论”的完整分析场景：规划节点先定分析框架，SQL 节点专心写查询，复审节点卡一道安全闸，最后解释节点做归因。这时候每个角色上下文干净，排查也容易。记住一个原则：拆 Agent 是给复杂度买单，不是为了显得架构高级。

3. 搭一个最小可跑的 ChatBI+Agent：先写循环，再上框架

3.1 选型清单：LLM、编排与执行沙盒怎么配

聊到动手，很多人的第一反应是上 LangGraph 之类的 Agent 框架。我的建议反而不是：第一次做 ChatBI+Agent，先别用框架，用几十行代码把工具调用循环手写一遍。原因很实在——框架把编排逻辑包成了黑匣子，一旦回答不对，你不知道是模型决策错了还是框架状态恢复错了。手写循环时每一步 messages 都是自己 append 的，出问题直接打日志看，特别适合排错。等链路稳定、确实需要分支和状态机了，再迁移到框架，成本很低。

LLM 选型要注意的一点：不要光看榜单分数，要看它在你的历史 SQL 样本上工具调用稳不稳定。同一个模型，生成 SQL 准确率高不代表它调用工具的参数格式一直不跑偏。我会先挑 30 条历史问答，让模型走一遍工具调用，统计“工具名正确加参数合法 JSON”的比例，低于 90% 的直接换。

3.2 最小链路：一个工具调用循环把跑通

下面这段是我常用的最小实现骨架。它不依赖任何 Agent 框架，只假设你的 LLM 服务支持 OpenAI 兼容的 tools 协议（现在国内主流模型服务基本都兼容）。这段代码只做三件事：发消息、收 tool_calls、分发执行后把结果塞回对话。

import json # 只读查询工具，真正的防护在数据库账号侧 def query_runner(sql: str, row_limit: int = 50): """执行 SELECT，只返回行记录和列名。""" assert sql.lstrip().lower().startswith("select"), "只允许 SELECT" # 这里替换成你的数据库客户端，连接串只用只读账号 # rows = db_client.query(sql + f" LIMIT {row_limit}") # return {"columns": rows.columns, "rows": rows.to_dict("records")} return {"columns": [], "rows": [], "truncated": False} TOOLS = [{ "type": "function", "function": { "name": "query_runner", "description": "在只读数据仓库上执行 SQL，用于回答数据问题", "parameters": { "type": "object", "properties": { "sql": {"type": "string", "description": "完整的 SELECT 语句"}, "row_limit": {"type": "integer", "description": "返回行数上限，默认 50"} }, "required": ["sql"] } } }] def run_agent(user_query: str, max_steps: int = 6): messages = [{"role": "system", "content": "你是数据分析助手…"}, {"role": "user", "content": user_query}] for step in range(max_steps): resp = llm.chat(messages=messages, tools=TOOLS, temperature=0.1) msg = resp.choices[0].message messages.append(msg) if not msg.tool_calls: return msg.content # 模型不再调工具，直接回答 for call in msg.tool_calls: args = json.loads(call.function.arguments) result = query_runner(**args) messages.append({ "role": "tool", "tool_call_id": call.id, "content": json.dumps(result, ensure_ascii=False) }) raise RuntimeError(f"超过 {max_steps} 步仍未收敛，需要改写提示词或限制工具数量")

逻辑说明：这个循环的精髓在最后把 tool 结果 append 回 messages。模型看到工具返回后才能决定是“基于结果直接回答”还是“发现结果不对再查一次”。为什么先手写框架？因为上面每一步都是可打印、可回放的，第 6 章做评测时我会直接复用这段代码把轨迹存成 JSON，出错时按步骤回放定位是哪一步决策错了。

参数说明：temperature 我压到 0.1，避免同样的 SQL 换个措辞就生成不同答案；max_steps 设 6，正常查询 2 到 3 步就收敛，超过 6 步基本是模型在瞎绕，宁可报错也不要烧 token。row_limit 默认 50，就是为了防止一句“把所有订单拉出来”把内存打爆，聚合查询模型自己会处理，不聚合时这个值就是保险丝。这里的 llm.chat 是占位写法，接具体模型 SDK 时换成对应客户端即可。

3.3 五个必调参数和它们背后的“玄学”

工具调用循环跑通后，调参才是血泪经验开始的地方。我按影响程度排五个：

• temperature：SQL 生成场景压到 0 到 0.1，归因解释可以放到 0.3 到 0.5。别用同一个 temperature 跑全链路，规划节点和执行节点的偏好不一样。
• max_steps：4 到 8 之间。设太小，模型还没纠错就断了；设太大，死循环烧钱。我默认 6，外加每秒 token 预算。
• 工具超时：单条 SQL 执行 10 秒必须断。数据分析师能等，在线问答等不了 30 秒。
• 行数上限：500 行以内。需要全量明细时引导用户走导出通道，而不是让 Agent 硬扛。
• 并发上限：LLM 服务与 SQL 沙盒分别设线程池。SQL 沙盒可以按连接池大小动态扩，LLM 调用做请求级并发，会话状态按 session_id 隔离后基本能扛住日常几十路并发。别把“Agent 怎么扛并发”想成玄学，瓶颈一定在慢 SQL 和模型响应时间，两个都控制了，剩下的就是普通的服务扩容。

注意：max_steps 不是越大越好。模型在 4 步内解决不了的问题，8 步大概率也解决不了，只会把错误 SQL 换个说法再跑一遍。排查时先看轨迹，而不是加步数。

4. 八大案例背后的通用套路：指标字典、记忆与复审节点

4.1 八大案例的三种形态：问答型、报表型、洞察型

134 页的篇幅容纳八个案例，平均下来每个案例只有十几页，所以这本事手册的价值不在让你逐字照抄，而在给你一套“案例到模块”的映射。我按自己做过的项目把这八类拆成三种形态，你会发现它们对 Agent 的要求完全不同：

问答型：用户问“华东区上个月销售额”，要求低延迟、高确定性，本质是带权限的查数工具。Agent 设计上尽量少规划，让指标字典直接命中，一次工具调用就回答。

报表型：用户要“上季度各渠道月度营收对比”，涉及多表 join 和格式排版。Agent 需要组合多个工具，但决策路径仍然固定，适合把流程固化成工作流而不是自由决策。

洞察型：用户问“华东区毛利为什么跌”，这是最难的一种，模型要先定位指标、再找对比周期、再拆维度、最后生成归因。它需要规划、检索、执行、解释四个步骤全部走完，而且答案允许有不确定性。

八大案例无论怎么排列，最后都会落到这三类上。你先把自己的场景归好类，再决定要不要多 Agent——洞察型才需要完整决策循环，纯问答型用 Agent 反而会把简单问题变慢。

4.2 Agent 记忆：多轮对话不要做成全文重放

Agent 记忆是让问答从“单轮”走向“会话”的关键。最常见的翻车是：把最近 20 轮对话原样拼进提示词，上下文一长，模型既记不住重点，又把早期信息当成最新事实。我一般分三层做：

• 短时窗口：保留最近 2 到 3 轮原文，用于处理“那这个呢”“同比呢”这类指代。
• 会话摘要：每 5 轮把之前的对话压缩成 200 字以内的摘要，替换原文进上下文。
• 长期偏好：把用户常用的指标、默认时间粒度、默认对比基准存成 KV。用户第一次说“毛利率”按财务口径回答，第二次他就会期待同样口径。

记忆的存储按 session_id 隔离，这一点和并发直接相关——Agent 开发时如果图省事把 memory 做成全局对象，两个用户同时问就会互相污染，我们第 5 章会看到这个坑。我自己的习惯是，每条记忆都带一个“业务时间戳”，用户上一轮说“本月”，下一轮说“改成上季度”，模型要能判断指的是哪一段，而不是机械地把时间词拼进去。

4.3 指标字典：ChatBI 的灵魂，一个不能省的静态工具

没有指标字典的 ChatBI+Agent 就是裸奔。模型每猜一次指标口径，都是在抽一位用户信任度的签。指标字典的每条记录通常包含这些字段：指标名、口径描述、可对比维度、默认时间粒度、SQL 模板或表字段来源、权限分组。结构可以简单，但必须能在规划节点被检索到，并在提示词里原始呈现。

指标字典条目示例：

规划节点拿到“毛利率”后，先查字典，把命中条目的口径和来源表注入给 SQL 生成节点，而不是让模型从零猜。这一步做完，SQL 生成的列名幻觉会少一大半，指标冲突也能在事前暴露——同一个指标出现两条口径相近的字典记录时，应该在上线前人工合并，而不是交给模型仲裁。这个模块属于“134 页案例里反复出现的幕后功臣”，它不性感，但每个靠谱案例都有它。

4.4 复审节点：执行 SQL 前的最后一道闸

最后一个通用模块是复审节点，相当于给 Agent 加一个“质检员”。流程是：SQL 生成节点产出 SQL → 复审节点做规则校验 → 校验通过才交给沙盒执行，失败则带着原因返回规划节点重写。规则我一般写五条：

• 只允许单条 SELECT，不允许分号拼接。
• 表名和列名必须出现在注入的 schema 清单里，没见过的直接拦。
• 必须带上行级权限过滤条件，比如“AND dept_id = 当前用户部门”，这个条件由工具层注入而不是让模型自觉。
• 行数超过上限时自动加 LIMIT，聚合查询检查是否缺少必要的分组。
• 所有执行记录写审计日志，用户、session、SQL、返回行数一个不少。

这个节点的价值在 Agent 安全，也在成本。多跑一步校验，模型可能需要重写一次，看起来慢了，但它能拦住“模型被提示注入后试图 select * from 全表”“表名幻觉导致查出来的数完全是错的”这类事故。我见过不止一次，上线后唯一一次数据事故就是没加复审节点，一个用户问“有没有竞争对手数据”，模型从一张不存在的表里编出了答案。复审节点拦住的不只是 SQL，还有对模型的信任透支。

5. ChatBI+Agent 上线踩坑与排查：五个让方案失效的细节

5.1 并发一下会话就串味：全局记忆是最隐蔽的坑

现象：压测时并发到 20 路，用户 A 问华南区、用户 B 问华东区，A 的答案里出现了 B 的口径偏好或查询条件。

原因：session 状态没隔离。memory 对象或 messages 列表被设计成了模块级单例，多个请求共享同一份上下文，后到的请求覆盖了先到的。

解决：所有会话状态（messages、记忆 KV、指标偏好）一律按 session_id 存取，SQL 沙盒也要按 session 传递用户身份，不能复用同一个数据库连接而不带用户标识。排查时有个笨办法很有效：在轨迹日志里打印 session_id 和 memory 版本号，压测时一旦串味，立刻能定位是哪个共享对象出了问题。压测脚本里至少要模拟 50 个不同 session 同时提问，只看总 QPS 是测不出这个问题的。

5.2 表名幻觉：模型一本正经地查一张不存在的表

现象：回答流畅、格式完整，但 SQL 里的表名在数仓里不存在。追问时模型还坚持“这张表本周刚上线，可能是权限没刷”。

原因：schema 检索没做或全量注入被截断。上下文塞不下所有表结构时，模型只在截断后的片段里找线索，找不到就编。

解决：schema 检索做成独立工具，先用 embedding 召回最相关的 5 到 10 张表，再连同指标字典一起注入提示词；执行器侧做一次硬校验，表名列名不在白名单里直接拒绝，并把错误返回给模型重写。同时把语法校验错误当成正常的工具结果反喂给模型，让它自己纠偏，这比用户看到报错体面得多。上线前把“存在的表”清单和“模型最爱编的表”清单各列一份，分别做白名单和黑名单，能压掉大部分幻觉。

5.3 权限漏洞：行级过滤不能在提示词里“拜托”模型

现象：低权限用户问“全公司各区域利润”，系统返回了所有区域的数据，而该用户只被授权看自己的区域。

原因：权限过滤写在应用层，SQL 生成节点虽然收到了“只能看自己区域”的提示，但模型漏加 where 条件，应用层发现不了。

解决：行级过滤条件由执行沙盒根据用户身份强制注入。用户身份在请求进入时解析，沙盒在 SQL 上追加 dept_id/region 条件后再执行，而不是信任模型生成的 SQL。这也呼应第二章说的“提示词约束是软的，环境约束才是硬的”。Agent 安全这件事，别指望靠模型自觉，数据库账号侧最小权限加上工具层强制注入，双保险缺一不可。

5.4 同一问题时好时坏：模型波动比你想的频繁

现象：同一个问题上午的回答正确，下午换了模型版本或调整了系统提示词后，SQL 生成了不同的 join 方式，结果数对不上。

原因：没有评测集。prompt 或模型一改，没人知道哪些历史回答被悄悄破坏了。

解决：建一个 50 到 200 条的回归评测集，覆盖三类典型案例加权限边界用例，每次改动前先跑基线，改动后 diff 通过率。这一步应该写进 Agent 评测的流程里，不是上线前做一次，而是每次改动都做。看 diff 报告时重点看三列：通过率变化、哪些 case 从过变挂、token 消耗变化。模型厂商升级版本这件事，尤其要跑完整评测，不要听 release note 说“提升推理能力”就放心。

5.5 Agent 死循环：max_steps 成了唯一的后悔药

现象：模型反复调用同一个查询工具，参数只有细微差别，token 消耗直线上升，接口迟迟不返回。

原因：工具返回的结果模型不满意，但它没有改变策略的能力，只会换个条件再查一遍。常见于“结果为空”时，模型不反思是口径错了，而是反复缩小时间窗口。

解决：除了 max_steps 兜底，还要在工具结果里带上“空结果原因提示”，例如把最近一个月的分区情况返回给模型，帮它判断是没数据还是查错表。死循环的轨迹要保留下来，它是判断提示词哪里没说清的最好素材。等你有几十条这类轨迹，就能总结出模型在哪些问题类型上特别容易钻牛角尖，再针对性补规划节点的约束。

6. 用评测集和轨迹回放，证明你的 ChatBI+Agent 不是玩具

任何 ChatBI+Agent 上线前，都要回答一个尴尬问题：你怎么证明它不只是“看起来能答”？我的答案是两件套：评测集加轨迹回放。前者管住模型波动，后者管住黑匣子。

评测集别贪大，50 到 200 条足够。三类各占一部分：固定口径问答（如“华东区上月销售额”）、探索式分析（如“各区毛利率为什么普遍下降”）、权限边界（如“查无权访问的维度”）。每条除了问题，还要带期望结论、涉及的表、最大步数上限。跑完后统计 SQL 执行成功率、结果正确率（和标准 SQL 结果做 diff）、端到端满意度、p95 延迟和每次请求 token 成本。改动 prompt、换模型版本、新增数据表，都先跑一遍基线再上线。

轨迹回放是我最依赖的排错手段。跑评测时给每条问答保留完整轨迹：每一步的 messages、工具调用参数、工具返回结果。回答错了，按步回放，两步就能定位是规划节点拆错了目标、SQL 节点写错了口径，还是解释节点归因跑偏。这和传统 ChatBI 最大的差别：以前只能看到输入输出，现在你能打开决策过程本身。

我之前有个项目上线后回答质量一直不稳定，后来养成一个习惯：每次改系统提示词，先跑 200 条评测基线，再对比 diff，绝不靠肉眼试几条就发版。这个习惯帮我挡下了至少三次模型侧的隐性回归。如果你正在做这个方向，建议从手写循环和 50 条评测集开始——先证明它能扛住回归，再谈框架和规模。希望帮到你。

本文还有配套的精品资源，点击获取