文件与文档问答指南

Analytics Agent 不只可以基于结构化表进行数据问答，也可以将文件加入分析域，用于文档问答、口径解释和业务说明检索。

文件适合承载非结构化或半结构化说明材料，例如数据字典、业务规则、指标口径说明、产品手册、运营政策和部门制度。配置完成后，用户可以在分析域中用自然语言询问文件中的内容。

文件问答适合解决什么问题

场景	示例问题	文件的价值
解释业务术语	“文档里活跃账户是什么意思？”	从上传文件中检索解释文本，减少口径误解。
查询数据字典	“source 字段有哪些含义？”	帮助用户理解字段来源、取值和适用范围。
补充指标说明	“活跃率的计算口径是什么？”	将指标说明与结构化指标配置互相补充。
查询制度或说明文档	“退款规则有哪些限制？”	支持围绕业务文档进行问答。
辅助排查问答歧义	“为什么当前活动用户数等于活跃账户数？”	通过文档和知识解释同义词、口径和使用边界。

文件问答和结构化数据问答是互补关系。表、指标、答案构建器更适合计算结果；文件和知识更适合解释规则、术语和背景。

上传文件

进入分析域配置页：

打开目标分析域。
进入“数据”页。
切换到“文件”。
上传文件。
等待文件处理完成并出现在文件列表中。

实操中，“数据 > 文件”页面提示支持以下格式：

```
.xlsx
```
.xlsx
```
.txt
```
.txt
```
.pdf
```
.pdf

单文件大小限制为 10MiB。

上传后，文件会先进入导入或任务列表。处理完成后，文件才会出现在当前分析域文件列表中。只有已经加入分析域并处理完成的文件，才适合用于文档问答验证。

文件加入域后的表现

实操中，在分析域文件列表中可以看到已经加入的文件数量和文件名。例如测试域中曾显示“共2个文件”，包含：

```
analytics-agent-file-qa-test.txt
```
analytics-agent-file-qa-test.txt
```
data_dictionary.pdf
```
data_dictionary.pdf

如果文件已经加入分析域，不能重复加入。遇到文件已存在或无法重复添加时，应先检查当前域文件列表，而不是反复上传同一文件。

文件问答如何生效

文件加入分析域后，用户可以在该域的问答入口提问与文件内容相关的问题。

实操验证中，提问：

根据上传文件，文档活跃账户是什么意思？

系统回答时使用了文档检索能力。问答记录中可以看到：

```
search_document_knowledge
```
search_document_knowledge
来源文件包括
```
analytics-agent-file-qa-test.txt
```
analytics-agent-file-qa-test.txt
来源文件也可能包括同域中的其他文档，例如
```
data_dictionary.pdf
```
data_dictionary.pdf

这说明文件问答不是简单展示文件列表，而是在问答过程中检索当前分析域内的文件内容，并把相关片段作为回答依据。

文件和知识的关系

文件和知识都能帮助系统理解业务语义，但适用方式不同。

配置	适合内容	特点
文件	数据字典、制度文档、说明书、PDF、Excel、文本说明	内容可以较长，适合从文档中检索答案。
知识	关键术语、同义词、稳定口径、简短业务规则	更适合直接补充问答语义和指标口径。

实操中，关于“活跃账户”的问题同时命中了上传文件和知识配置。知识“测试知识_活跃用户口径_20260609”定义了活跃用户、当前活动用户数、活跃账户数按

active_subscription = TRUE

active_subscription = TRUE

理解；文件则提供了文档中的解释来源。

因此，推荐做法是：

稳定、短小、经常被问到的口径写入知识。
完整的数据字典、制度说明和长文档上传为文件。
对关键术语，文件和知识可以互相补充，但表述应保持一致。

文件内容编写建议

为了让文件更容易被检索和引用，建议文件内容具备清晰结构。

使用明确标题

使用业务常用词

如果用户常说“当前活动用户数”，文件里不要只写

active_subscription

active_subscription

。建议同时写技术字段和业务说法：

活跃账户、当前活动用户数、活跃用户数均指 active_subscription = TRUE 的账户。

避免多个口径混写

不要在同一个段落里混写多个相似但不同的指标口径。例如“活跃账户”“登录用户”“付费用户”应分开说明，否则问答时容易混淆。

保持文件和字段语义一致

文件中的字段解释应与表字段配置中的别名、描述、用途一致。否则用户提问时，文件说明和表字段语义可能互相冲突。

文件问答验证

文件加入分析域后，建议至少验证以下问题：

验证问题	检查点
文档中某个术语是什么意思？	是否引用了正确文件。
某个字段有哪些含义？	是否能从数据字典中检索到字段说明。
某个指标口径是什么？	是否与指标配置、知识配置一致。
问一个文件中不存在的问题	系统是否避免编造，或提示没有足够依据。
同义词提问	是否能把用户常用说法映射到文档术语。

验证时建议查看问答记录，确认是否命中了文档检索，以及来源文件是否正确。

常见问题

文件已经上传，为什么问答没有引用？

按以下顺序检查：

文件是否已经处理完成。
文件是否出现在当前分析域的文件列表中。
用户是否在正确的分析域中提问。
问题是否明确指向文件中的标题或术语。
文件内容是否使用了用户常用表达。
是否有知识或字段语义与文件内容冲突。

文件问答和指标计算有什么区别？

文件问答主要回答“是什么、怎么定义、规则是什么”。指标计算回答“有多少、趋势如何、按什么分组”。

例如：

问题	更适合的能力
“活跃账户是什么意思？”	文件或知识。
“活跃账户总数是多少？”	指标或答案构建器。
“按 plan 展示活跃账户数”	指标、答案构建器或结构化问答。

文件能否替代表字段配置？

不能。文件可以解释业务背景，但字段别名、字段描述、列类型、字段用途仍应在表字段配置中维护。字段配置直接影响系统选字段、生成过滤条件和构造 SQL。