排查问答准确性问题

当 Analytics Agent 的回答不符合预期时，不应只看最终文字答案。正确的排查方式是沿着执行链路逐步确认：用户问题如何被理解、命中了哪些知识和配置、生成了什么 SQL、使用了哪些字段、过滤、分组和指标。

本指南基于实际配置和问答验证整理，适用于排查“答错数、用错字段、漏过滤、分组错误、未命中指标或答案构建器、解释口径不清”等问题。

排查顺序

建议按照以下顺序排查：

步骤	看什么	目的
1. 看最终答案	数值、解释、图表、表格	判断问题类型。
2. 看 SQL语句	表、字段、过滤、分组、聚合、JOIN	判断 SQL 是否符合业务口径。
3. 看记录	知识、指标、答案构建器、工具调用	判断系统是否命中正确配置。
4. 查字段语义	别名、描述、类型、用途、隐藏、虚拟列	判断字段是否被正确理解。
5. 查知识	业务词、口径、同义词	判断用户说法是否有解释依据。
6. 查指标和答案构建器	是否存在、启用、口径、参数	判断是否应固化计算逻辑。
7. 查表关系	自动关联、手工关系、JOIN 路径	判断多表查询是否正确。
8. 看健康度	异常和警告	找到影响问答准确性的配置缺口。

不要一开始就改 SQL 或改配置。先通过 SQL 和记录确认错误发生在哪一层。

常见问题类型

问题表现	典型原因
数字不对	用错字段、漏过滤、聚合函数不对、JOIN 膨胀、指标口径错误。
SQL 用错字段	字段别名/描述缺失，存在相似字段，字段用途不清。
没按用户要求过滤	过滤字段未配置，字段真实取值大小写不一致， `${filters}` ${filters} 未绑定。
没按用户要求分组	维度字段未配置， `${dims}` ${dims} 未绑定，字段不适合作为维度。
没命中知识	知识未配置、未启用，或没有包含用户常用说法。
没命中指标	指标未加入分析域、未启用、名称/别名不匹配。
没命中答案构建器	构建器名称、别名、描述不清，输出指标名不清，或参数未配置。
多表结果异常	表关系缺失、JOIN 错误、关联字段不唯一。
图表不符合预期	SQL 结果列不适合图表，维度或度量选择不合理。
解释口径不清	字段描述、知识、指标描述不足。

第一步：看最终答案

先判断最终答案错在哪里。

重点看：

数字是否符合预期。
是否使用了正确口径。
是否按用户要求过滤。
是否按用户要求分组。
表格和图表字段是否符合问题。
自然语言解释是否说明了口径。

例如，用户问：

只看 source 为 google 的账户健康概览，按 plan 展示活跃率和活跃席位

如果答案只返回总体活跃率，没有按

plan

plan

分组，说明可能是维度没有传入或未配置。如果答案按

plan

plan

分组了，但没有过滤

source = Google

source = Google

，说明可能是过滤条件没有生效。

第二步：看 SQL语句

点击答案下方的 SQL语句，检查实际执行的 SQL。

重点检查：

检查项	判断方法
表是否正确	SQL 中 FROM 的表是否是预期表。
字段是否正确	SELECT、WHERE、GROUP BY 中字段是否符合业务口径。
过滤是否正确	WHERE 是否包含用户要求的条件。
分组是否正确	GROUP BY 是否包含用户要求的维度。
聚合是否正确	COUNT、SUM、AVG、MAX、MIN 是否符合指标口径。
JOIN 是否正确	多表查询时 ON 条件是否正确，是否可能造成数据膨胀。
LIMIT / ORDER BY 是否合理	是否影响明细或 TopN 类问题。

实际验证中，答案构建器命中后，SQL 会显示模板已被替换。例如：

WHERE active_subscription = TRUE AND `plan` = 'Basic'

这说明用户说的 “Basic Plan” 已经被转成过滤条件。

如果 SQL 中没有出现用户要求的过滤条件或分组字段，应继续查看记录，确认系统是否传入了

filters

filters

或

dims

dims

。

第三步：看记录

点击答案下方的记录，查看完整执行链路。

记录是排查准确性的关键，因为它会显示：

是否搜索知识。
是否命中知识。
是否找到指标。
是否找到答案构建器。
是否执行指标计算。
是否回退到表结构和 SQL 查询。
是否先查询字段真实取值。
是否生成图表或表格。

记录中常见信号

记录信号	含义
`search_knowledge` search_knowledge 找到 0 条	没有可用知识解释用户业务词。
`get_knowledge_detail` get_knowledge_detail	系统已读取知识详情。
找到 N 个指标	当前分析域存在可用指标或答案构建器输出。
执行指标计算	系统尝试使用已配置指标或答案构建器。
指标计算失败，改用 SQL 查询	已配置对象可识别，但执行失败，系统回退 SQL。
查看表结构	系统需要依赖字段结构临时推断。
查询 DISTINCT 字段值	系统在确认枚举值大小写或真实取值。

答案构建器命中的记录特征

如果命中答案构建器，记录中通常会出现：

找到匹配指标或答案构建器。
```
metricType = SQL
```
metricType = SQL
。
```
metricId
```
metricId
指向答案构建器生成的 SQL 指标。
参数中出现
```
dims
```
dims
、
```
filters
```
filters
或
```
outputColumns
```
outputColumns
。

例如：

参数	含义
`dims = plan` dims = plan	按 Plan 分组。
`filters: source = Google` filters: source = Google	只看 Google 来源。
`outputColumns = active_account_rate, active_seats` outputColumns = active_account_rate, active_seats	只返回活跃率和活跃席位。

如果用户的问题适合答案构建器，但记录中没有命中构建器，通常需要检查构建器名称、别名、描述和输出指标名称。

排查字段语义

字段语义问题是问答错误最常见的原因之一。

典型问题

问题	处理方法
用户说“套餐”，SQL 没用 `plan` plan	给 `plan` plan 增加“套餐、计划、版本”等字段别名。
用户说“活跃账户”，SQL 没用 `active_subscription` active_subscription	补充字段描述，并配置知识说明活跃账户口径。
SQL 用了错误时间字段	区分 `created_at` created_at 、 `trial_ends_at` trial_ends_at 、 `canceled_at` canceled_at 的描述和用途。
按 ID、邮箱分组导致结果很碎	调整字段用途，避免高基数字段作为默认维度。
字段没有出现在 filters 或 dims	检查字段类型、字段用途、隐藏状态。

消除字段歧义

当一个表或多个表中存在相似字段时，应优先补字段语义。

例如账户表中同时有：

```
active_subscription
```
active_subscription
```
trial_converted
```
trial_converted
```
canceled_at
```
canceled_at
```
legacy_plan
```
legacy_plan

如果用户问“活跃账户”，应通过字段描述和知识明确：

活跃账户指

active_subscription = TRUE

active_subscription = TRUE

的账户，不等同于试用转化账户，也不等同于未取消账户。

这样可以减少模型误选字段。

排查知识配置

知识用于解释业务词、口径和同义词。

什么时候需要查知识

现象	说明
用户用了业务术语	需要知识解释术语。
同一个概念有多个叫法	需要知识维护同义词。
字段描述无法完整说明口径	需要知识补充跨字段或业务规则。
答案解释口径不清	需要知识支持自然语言解释。

排查方法

查看记录中是否出现：

```
search_knowledge
```
search_knowledge
```
get_knowledge_detail
```
get_knowledge_detail
命中的 Knowledge ID

如果没有命中知识：

检查知识是否加入当前分析域。
检查知识是否启用。
检查知识名称和描述是否包含用户常用说法。
检查是否需要把简称、别名、英文表达写入知识。

实际验证中，配置“活跃用户口径”知识后，用户问“活跃账户有多少个？”，记录中命中了该知识，并使用

active_subscription = TRUE

active_subscription = TRUE

解释口径。

排查指标配置

指标适合固化简单聚合口径。

常见问题

现象	可能原因	处理方法
系统没有使用指标	指标未加入分析域或别名不匹配	检查指标状态、名称、别名。
指标计算失败后回退 SQL	指标定义或执行参数有问题	查看记录和 SQL，修正指标定义。
指标口径不符合业务	自动生成指标未经人工确认	修改指标或改用答案构建器。
用户说法匹配不到指标	缺少指标别名	增加常用业务叫法。

实际操作中，自动生成指标只是候选建议，不等于最终业务口径。系统可能生成

COUNT(canceled_at)

COUNT(canceled_at)

、

MIN(created_at)

MIN(created_at)

、

SUM(seats)

SUM(seats)

等候选指标，用户应检查后再采纳。

排查答案构建器

答案构建器适合复杂 SQL、多指标、动态过滤和动态维度。

重点检查

检查项	说明
SQL 是否包含 `${filters}` ${filters}	缺少时可能无法配置动态过滤，校验会报错。
SQL 是否包含 `${dims}` ${dims}	需要动态分组时必须配置。
是否绑定过滤字段	影响用户说“只看某条件”时能否生效。
是否绑定维度字段	影响用户说“按某字段展示”时能否生效。
输出字段是否命名清晰	影响问答是否能选择正确输出列。
描述是否清楚	影响系统能否选中该构建器。

典型命中案例

用户问：

按 plan 展示账户健康概览，包括账户数、活跃账户数、活跃率、总席位和活跃席位

记录显示：

找到答案构建器“账户健康概览”。
传入
```
dims = plan
```
dims = plan
。
返回多个输出指标。
自动生成表格和组合图。

用户继续问：

只看 source 为 google 的账户健康概览，按 plan 展示活跃率和活跃席位

记录显示：

先查询
```
source
```
source
真实值，确认是
```
Google
```
Google
。
传入
```
filters: source = Google
```
filters: source = Google
。
传入
```
dims = plan
```
dims = plan
。
传入
```
outputColumns = active_account_rate, active_seats
```
outputColumns = active_account_rate, active_seats
。

这说明答案构建器不仅能固定 SQL，还能动态响应用户的过滤、分组和输出列要求。

排查表关系

多表问答错误通常来自 JOIN 关系。

需要关注的情况

用户问题跨多张表。
SQL 中出现 JOIN。
结果明显放大或重复。
表关系未配置或自动关联无结果。
多张表中存在同名字段。

实际操作中，单表时自动关联不可用；加入多张表后可以点击自动关联，系统会打开确认关联窗口。自动关联可能返回“暂无表关联”，这时不能假设多表问答一定可靠。

建议：

人工确认事实表和维表关系。
检查 JOIN 字段是否唯一。
避免只凭字段名相同确认关联。
用典型多表问题验证 SQL 中的 JOIN。

使用健康度扫描

分析域健康度会扫描影响问答正确性的配置项。

实际操作中，健康度可能提示：

表字段缺少描述信息。
域内不存在指标。
表关系异常。
字段存在大量空值。

健康度不是形式检查。它提示的字段描述缺失、无指标、错误 Join 等问题，都可能直接影响问答准确性。

建议在上线前：

点击重新扫描。
处理异常项。
对暂时不处理的问题明确原因。
处理后用典型问题复测。

症状与处理方法

症状	优先检查	处理建议
数字明显不对	SQL、指标、答案构建器	检查聚合函数、过滤条件和口径。
用错字段	字段语义	补别名、描述、字段用途，必要时隐藏干扰字段。
漏过滤	SQL、记录、字段用途	检查是否传入 filters，字段是否可过滤。
漏分组	SQL、记录、维度配置	检查是否传入 dims，字段是否可作为维度。
没命中知识	记录、知识配置	补充知识同义词和业务口径。
没命中指标	指标状态、名称、别名	加入分析域，启用指标，补别名。
没命中答案构建器	构建器名称、描述、输出指标	补业务化名称、别名、描述。
多表结果放大	表关系、JOIN	检查关联字段和基数。
图表不合理	SQL 输出列	调整维度和度量字段。
解释不清	知识、字段描述、指标描述	补充业务口径说明。

验证目标	示例问题
字段映射	按套餐展示账户数。
过滤条件	只看 Google 来源的活跃账户数。
业务口径	当前活跃账户数是多少？
动态维度	按 plan 展示账户健康概览。
动态输出列	按 plan 展示活跃率和活跃席位。
知识命中	活跃用户有多少个？
答案构建器命中	按 plan 展示账户健康概览，包括账户数、活跃账户数、活跃率、总席位和活跃席位。
多表关系	按类目统计订单金额。

上线前检查清单

核心字段是否有别名和描述。
核心业务词是否配置知识。
常用指标是否创建并加入分析域。
复杂口径是否使用答案构建器固化。
答案构建器是否配置
```
${filters}
```
${filters}
和
```
${dims}
```
${dims}
。
输出指标是否有业务化名称、别名和描述。
表关系是否确认。
健康度异常是否处理。
是否通过典型问题验证。
是否查看 SQL 和记录确认命中路径。

问答准确性排查的核心原则是：不要只看答案，要看 SQL 和记录；不要只修单次问题，要回到字段语义、知识、指标、答案构建器和表关系这些可复用配置上修正。