配置知识

知识用于帮助 Analytics Agent 理解业务词汇、指标口径、专有概念和用户自然语言中的隐含规则。它解决的是“用户说的词是什么意思”的问题，而不是直接替代表、指标或答案构建器。

当用户经常使用业务简称、行业术语、公司内部口径或容易歧义的词时，应优先考虑配置知识。

知识配置的价值

自然语言问答不只需要表结构，还需要业务上下文。例如，用户说“活跃账户数”，系统需要知道：

“活跃账户”指什么？
是否等同于“当前活动用户数”？
应该使用哪个字段判断？
是否需要排除取消、试用、历史套餐等情况？

如果没有知识，系统可能只能从字段名、指标名和表结构中推断，容易出现口径不稳定。

实际验证中，当分析域没有配置知识时，问答记录里会出现知识搜索 0 条；配置知识后，系统会先通过

search_knowledge

search_knowledge

命中知识，再通过

get_knowledge_detail

get_knowledge_detail

获取口径详情，然后继续选择指标、答案构建器或生成 SQL。

适用场景

场景	为什么适合配置知识	示例
业务词和字段名不一致	帮助系统把用户说法映射到底层字段。	“活跃账户”对应 `active_subscription = TRUE` active_subscription = TRUE 。
同一概念有多个叫法	帮助系统理解同义词。	活跃账户、活跃用户、当前活动用户数、有效订阅账户。
指标口径需要解释	避免系统临时猜测计算规则。	“转化率 = 转化订单数 / 访问人数”。
字段容易歧义	告诉系统哪个字段才是正确口径。	`trial_converted` trial_converted 不等同于当前活跃账户。
企业内部术语	让系统理解公司内部简称。	“KA 客户”“有效商机”“沉默用户”。
问答解释需要业务背景	让答案能说明为什么这样算。	“活跃账户基于当前有活跃订阅的账户统计”。

知识尤其适合补充“字段语义无法完整表达”的业务规则。

知识、字段、指标和答案构建器的关系

知识不是孤立配置，应和字段语义、指标、答案构建器一起使用。

配置	解决的问题	示例
字段语义	这个字段是什么，适合怎么用	`active_subscription` active_subscription 是当前订阅是否有效。
知识	用户说的业务词是什么意思	“活跃账户”指 `active_subscription = TRUE` active_subscription = TRUE 的账户。
指标	简单聚合口径如何稳定计算	活跃账户总数。
答案构建器	复杂 SQL 或多指标组合如何稳定执行	账户健康概览。

实际问答链路通常是：

先搜索知识，理解业务词。
再查找可用指标、答案构建器和表。
如果命中指标或答案构建器，优先调用已配置逻辑。
如果无法直接执行，则回退到表结构和 SQL 生成。

因此，知识的作用是“解释语义和口径”，指标和答案构建器的作用是“执行计算”。

配置入口

在分析域中配置知识的一般路径：

进入管理 -> 分析域管理。
打开目标分析域。
进入数据页签。
点击知识。
点击 添加知识。

添加知识时，页面提供三种入口：

入口	说明
导入知识	通过 Excel 模板批量导入知识，适合已有知识表或术语表。
新建知识	手工创建单条知识，适合补充关键口径或测试验证。
选择已有知识	将已经创建的知识加入当前分析域。

导入知识支持 Excel 文件，页面提供模板下载。手工新建知识时，需要填写名称、关联分析域、描述方式和描述内容。

文本知识和字典知识

新建知识时，页面提供描述方式：

描述方式	适用场景
文本	解释一个概念、口径或规则。
字典	维护术语、枚举值、映射关系等结构化解释。

如果只是解释“活跃账户是什么”，使用文本即可。

如果需要维护多组术语映射，例如多个业务简称、状态码含义、品类编码说明，可以考虑字典或批量导入。

信息	说明	示例
业务词	用户会怎么说	活跃账户、活跃用户、当前活动用户数
计算或判断口径	应该使用什么字段或规则	`v_gpt_accounts.active_subscription = TRUE` v_gpt_accounts.active_subscription = TRUE
使用边界	不应该混淆什么	不等同于试用转化，不等同于未取消账户

实操验证案例

实际验证中，创建了一条知识：

配置项	内容
名称	测试知识_活跃用户口径_20260609
描述方式	文本
描述	在本分析域中，活跃用户、当前活动用户数、活跃账户数都指 `v_gpt_accounts` v_gpt_accounts 表中 `active_subscription = TRUE` active_subscription = TRUE 的账户数量。回答这类问题时应优先按该字段过滤后计数。
状态	已启用

配置前，问“当前活动用户数是多少？”时，记录显示知识库搜索 0 条，系统主要依靠指标和表结构推断。

配置后，问“活跃账户有多少个？”时，记录显示：

```
search_knowledge
```
search_knowledge
命中 1 条知识。
```
get_knowledge_detail
```
get_knowledge_detail
获取知识详情。
系统明确使用
```
active_subscription = TRUE
```
active_subscription = TRUE
作为活跃账户口径。
最终返回活跃账户数。

这说明知识会进入问答执行链路，而不仅仅是静态说明文本。

知识如何影响问答

知识对问答的影响主要体现在三个阶段：

阶段	作用
问题理解	把用户自然语言中的业务词解释成系统可理解的概念。
SQL 生成或指标选择	帮助系统选择正确字段、指标或答案构建器。
答案解释	让最终回答能说明计算口径，而不是只给数字。

例如在测试环境中配置知识后，答案中可以自然解释：

当前活跃账户数为 464 个。计算口径为

v_gpt_accounts

v_gpt_accounts

表中

active_subscription = TRUE

active_subscription = TRUE

的账户数量。

这种解释能力对业务用户很重要，因为用户不仅关心结果，还关心“这个结果按什么口径算”。

命名建议

知识名称应便于系统和管理员理解。

什么时候不用知识

以下场景不一定需要知识：

场景	更合适的配置
单字段别名问题	字段别名
单个简单聚合指标	指标
复杂 SQL 计算	答案构建器
文件内容问答	文件或文档知识
表字段本身描述不清	字段描述

如果一个问题可以通过字段别名和字段描述解决，不必把所有字段说明都写成知识。知识更适合表达跨字段、跨指标或业务口径层面的规则。

常见问题

问题	可能原因	处理建议
配了知识但问答没命中	知识名称或描述没有包含用户常用说法	在知识中补充同义词和常见表达。
命中了知识但 SQL 仍然错	只有知识，没有字段语义或指标支撑	同时配置字段别名、字段描述、指标或答案构建器。
知识太多导致匹配混乱	多条知识口径重叠或相互矛盾	合并重复知识，明确适用范围。
业务口径变化后答案仍按旧口径	知识未更新	修改知识并重新验证典型问题。
用户说简称系统不理解	知识没有包含简称	在知识描述中写入简称、全称和对应关系。

上线前检查清单

核心业务词是否都配置了知识。
同一业务概念的不同叫法是否写在同一条知识中。
知识是否明确字段、表或计算规则。
知识是否说明不应混淆的相似概念。
知识是否关联到正确分析域。
知识状态是否已启用。
是否用典型自然语言问题验证知识命中。
是否查看记录确认
```
search_knowledge
```
search_knowledge
和
```
get_knowledge_detail
```
get_knowledge_detail
生效。
业务口径变更后是否同步更新知识。

知识配置的目标，是让 Analytics Agent 用业务语言理解问题，用正确口径执行分析，并能向用户解释答案依据。