Skip to content

KNOWLEDGE_USAGE.md

Latest commit

 

History

History
120 lines (91 loc) · 8.33 KB

KNOWLEDGE_USAGE.md

File metadata and controls

120 lines (91 loc) · 8.33 KB

中文 | English

DataAgent 知识配置最佳实践指南

在 DataAgent 系统中，AI 的能力上限取决于它所掌握的“知识”质量。为了让智能体准确理解用户自然语言查询并转化为正确的 SQL 和分析报告，我们需要分层配置三类知识：语义模型、业务知识和智能体知识库。

一、 语义模型配置 (Semantic Model)

定位：这是 NL2SQL 的地基。它负责建立“人类语言”到“数据库物理表/字段”的硬映射。如果这里配置不准，SQL 一定会写错。

1. 核心字段配置技巧

配置重点在于消除数据库字段的歧义。语义模型不是要求你要把所有的表和所有列都要配置到这里，这么多表你也配不完，如果你发现数据列的description字段描述太少，LLM不能很好理解该数据列，或者某个很“专业”的业务名词是映射到某个列的而LLM理解不了，此时你可以尝试在这里配置。

  • 表名/数据库字段名：
    • 保持与数据库物理名称一致。
  • 业务名称 (Business Name)：
    • 最佳实践：使用业务人员口语中常用的标准名称。
    • 反例：csat_score -> "CSAT" (太技术化)
    • 正例：csat_score -> "客户满意度分数"
  • 同义词 (Synonyms) —— ⭐ 最重要配置：
    • 作用：解决用户问法多样性的问题。
    • 最佳实践：枚举所有可能的叫法，用逗号分隔。
    • 案例：
      • 字段 price2 (订单价格)：同义词填入 订单金额, 成交价, 销售额, 支付金额, amount
      • 字段 user_id：同义词填入 用户ID, 会员ID, 客户编号
  • 业务描述 (Description) —— 解决逻辑歧义：
    • 作用：告诉 LLM 这个字段的特殊取值逻辑或业务含义。
    • 最佳实践：如果是枚举值或状态码，必须解释每个值的含义。
    • 案例：对于 order_status 字段，描述应填：订单状态：0代表待支付，1代表已支付/已成交，2代表已取消，3代表退款中。计算GMV时通常只统计状态为1的订单。
  • 数据类型：
    • 确保准确（如 int, varchar），这决定了生成的 SQL 中是否给值加引号。

二、 业务知识配置 (Business Knowledge)

定位：这是 DataAgent 的业务逻辑字典。它解决“什么是...？”的问题，用于定义计算公式、专有名词和业务指标。注意，前面语义模型的业务名称侧重的是和表的映射，但是并不是所有的业务名词都会和表一一对应的。

1. 适用场景

当用户问“上个月的 GMV 是多少？”或者“高价值用户占比多少？”时，LLM 不知道 GMV 的公式，也不知道高价值用户的定义，这时需要业务知识召回（Recall）。

2. 配置最佳实践

  • 业务名称：填写指标或术语的标准名称。
    • 例：GMV、复购率、高潜客户。
  • 描述 (Description) —— 核心逻辑区：
    • 最佳实践：用自然语言清晰地描述计算公式、过滤条件或业务定义。
    • GMV 案例：GMV（商品交易总额）= 订单表中所有状态为'已支付'或'已发货'的订单金额总和，不扣除退款金额。
    • 复购率案例：复购率 = 在选定时间段内，购买次数大于等于2次的去重用户数 / 总去重购买用户数。
  • 同义词：
    • 例：GMV 的同义词：流水, 交易额, 全站销售额。
  • 是否召回：
    • 务必开启。开启后，当用户的提问涉及这些词汇时，系统会通过向量检索将这段“描述”作为上下文注入给 Prompt，指导 SQL 生成节点写出正确的公式。

三、 智能体知识库配置 (Agent Knowledge)

定位：这是 DataAgent 的外脑扩充（RAG）。支持非结构化文档上传，用于提供背景信息、行业知识、SOP 或历史案例。

1. 知识类型与用途

支持 文档、问答对(Q&A) 等。

A. 文档 (File Upload: PDF, DOCX, MD)

  • 用途：
    1. 数据库Schema说明书：如果表结构极其复杂，语义模型写不下，可以上传一份详细的数据库设计文档。
    2. 业务流程SOP：帮助 Planner (规划节点) 理解业务流程，甚至更好地按你想要的步骤进行数据分析。例如你觉得Agent做的“销量预测“老是做不好，你们公司有自己的销量预测流程，第一步如何做，第二步如何....等等固定流程，此时你完全可以在文档写上 "如何进行销量预测的步骤”，直接指定销量预测的流程。 强烈建议使用这个功能。当然你也可以放到Q&A问答对里面，或者把多个问答对塞到一个文档里面再上传。
    3. 行业报告：帮助 Report Generator (报告生成节点) 在生成最终 HTML 报告时，增加行业洞察和背景知识，而不只是单纯罗列数据。

B. 问答对/常见问题 (Q&A / FAQ) —— ⭐ 调优神器

这是修正 Agent 错误行为最高效的方式（Few-Shot Learning）。

  • 用途：当发现 Agent 对某类问题 SQL 生成总是错误时，不要反复改 Prompt，直接加一个 Q&A。
  • 最佳实践配置：
    • 问题 (Q)：模拟用户的提问。例如：统计上个月的销售额。
    • 答案 (A)：提供标准的 SQL 写法，或者思维链（CoT）。
    • 案例：
      • Q: 查询去年的活跃用户数
      • A: 活跃用户的定义是登录次数>3次。SQL逻辑应该是：SELECT count(distinct user_id) FROM login_logs WHERE login_time >= '2023-01-01' AND login_time <= '2023-12-31' GROUP BY user_id HAVING count(*) > 3。

四、 知识联动工作流 (Workflow Integration)

在 DataAgent 的一次完整运行中，这三层知识是如何协作的？

场景：用户提问 “请分析上个月华东地区的 GMV 趋势，并生成报告。”

  • 证据召回阶段 (EvidenceNode)：

    • 系统检索 “业务知识”，找到了 GMV 的定义（已支付订单总额）。
    • 系统检索 “智能体知识库”，可能找到了一份关于“区域划分标准”的文档，知道“华东”包含哪些省份。

  • 查询增强阶段（QueryEnhanceNode）：

    • 用于根据evidence信息把业务翻译，把用户的查询进行改写。

  • SchemaRecallNode &TableRelationNode：

    • 用上面重写后的查询召回表和列
    • TableRelationNode中用大模型精选出与问题相关的表，以及通过外键找到缺失的表，最终得到与问题相关的数据表和列（schema）
    • TableRelationNode根据这些表召回对应的语义模型。

  • PlannerNode：

    • 结合上面的证据，以及数据库的schema和语义模型，LLM拿到了全面的业务信息和数据库信息了，可以做出比较完善和正确的计划。

  • SQL 生成阶段 (SQLGenerateNode)：

    • 利用 “语义模型”，将“订单”映射到 orders 表，“金额”映射到 price2 字段，“地区”映射到 region 字段。
    • 结合 GMV 的定义，生成 WHERE status = 1 的过滤条件。
    • 生成 SQL：SELECT date, SUM(price2) FROM orders WHERE region IN ('上海','江苏'...) AND status=1 ...

  • 报告生成阶段 (Report Generator Node)：

    • LLM 拿到 SQL 执行的数据结果。
    • LLM 结合 “智能体知识库” 中的行业背景知识，对 GMV 趋势进行解读（例如：结合知识库中的“淡旺季说明”，分析为什么数据会涨跌）。
    • 最终输出 HTML 报告/MD格式报告。

五、 避坑指南 (Checklist)

  1. 不要在语义模型里写复杂的计算逻辑：语义模型只负责字段映射。复杂的公式（如 A/B*C）请在“业务知识”里定义。
  2. 同义词不要泛滥：不要把不相关的词填进去，否则容易造成错误的知识召回。
  3. Q&A 是救火队：如果 Agent 怎么教都学不会某个 SQL 写法，上传一个包含该 SQL 示例的 Q&A 是最快的解决办法。
  4. 描述要“讲人话”：在填写“业务描述”时，要把 LLM 当作一个新来的实习生，用最直白的语言解释字段含义，避免使用内部黑话（除非你在业务知识里定义了黑话）。