从语义准备到模型验收：HENGSHI SENSE Data Agent 的 RAG 与部署工程实践

摘要： 企业级数据问答的难点不在于把一句自然语言送进大模型，而在于让系统在既定的数据范围、业务口径和权限边界内给出可核验的结果。HENGSHI SENSE 的 Data Agent 将数据语义准备、向量检索、模型调用和数据查询组织成一条可运维链路。本文以当前公开的 6.2 手册为配置基线，结合公开发布说明中列出的 6.3.2 与 6.2.5 版本，说明向量服务如何交付和升级，RAG 在链路中解决什么问题，以及模型、提示词、权限和验收应如何一起落地。实际部署仍应以现场所用版本的发布说明、交付包和启动日志为准。

1 先把数据语义和责任边界准备好

1.1 Data Agent 先读懂业务对象，再处理用户问题

Data Agent 的问答质量从数据准备开始。数据集、字段和原子指标需要有清晰名称、类型和描述；业务术语、同义词、默认过滤条件和统计口径应写入数据集知识管理或相应的提示词。对于“财年”“小订单”“有效客户”这类组织内约定，管理员应明确其时间窗口、筛选条件和对应指标，而不应把解释留给模型猜测。无关字段可以隐藏，避免它们进入检索候选和提示词，降低歧义与上下文成本。

对需要复用的复杂口径，优先在数据侧沉淀为指标并维护变更记录。这样，模型面对的是可解释的业务语义，而不是在一次对话中临时拼接计算规则。Data Agent 也提供 Agent 核心指令、资源搜索指令、值集查询指令、HQL 执行指令和行业与私域指令等调优位置。提示词应当写清角色、术语和边界，并由熟悉业务的人审阅；提示词不是绕开数据治理的替代品。

把调优配置当成受控的业务规则来维护。管理员可以通过资源搜索指令约束优先查找的资源，通过值集查询指令说明地区、产品类别等可选值的别名，通过 HQL 执行指令补充默认行数或必需过滤条件。每项规则都应有适用范围、负责人和复核日期。规则互相冲突、描述过长或把临时例外写成永久约束，都会让检索与执行变得难以解释。

• 为常用指标写明定义、粒度、时间口径、单位和是否含退款、优惠、税费等条件。
• 在知识管理中维护业务别名与字段、指标的对应关系，避免相近名称被误选。
• 把已验证的问题与分析步骤沉淀为示例、看板或智能解读思路，并在数据或口径改变后复审。
• 对智能学习产出的内容执行人工检查、增删改，再用于后续问答。

1.2 RAG 缩小候选范围，不替代权限和事实核验

RAG 的作用是把问题与相关的数据集、字段、指标、函数说明或示例连接起来，再把有限的候选上下文提供给模型。HENGSHI SENSE 的向量搜索可与分词搜索及模型筛选配合使用；它帮助系统缩小候选范围，并不保证选中的候选、生成的查询或最终解释必然正确。相似度阈值、字段数量限制和示例数量等参数需要结合本组织的数据规模和验收结果调整，不能把某组默认值当成通用准确率承诺。

权限也不由向量相似度决定。用户可见的数据范围、角色和数据源选择应先限制检索和查询的边界；向量库用于保存和检索语义表示及相关检索材料，不能充当权限系统，也不能替代原始数据、元数据和配置的备份。知识变化后需要重新向量化并复验召回结果，不能因为旧向量仍可查询就假定它仍描述当前 schema 或指标口径。

2 向量服务：按交付脚本部署，按运行状态运维

2.1 交付包、运行目录与持久化状态分开管理

向量服务的交付包包含 deploy.sh、Compose 文件、发布版本清单和离线资源。官方配置说明要求通过 deploy.sh 管理，不直接执行 docker compose up。配置、模型和数据库数据应与部署包分离：默认运行目录包含配置文件和模型目录，PostgreSQL 数据保存在 Compose 项目的 Docker volume。升级交付包前，必须保留运行目录和 PostgreSQL volume；先执行检查，再执行升级，不能把删除运行状态当成常规升级步骤。

cd /opt/vector-server-release
./deploy.sh -m check
./deploy.sh -m start

启动脚本负责检查环境、初始化配置、准备镜像和模型、处理容器名及端口冲突、创建 vectorize 扩展，并输出实际连接信息。默认配置中可出现 3000 和 54321 这类示例端口，但它们不是每个环境的固定端口。脚本在发现冲突时会选择可用端口并把结果写回固定配置文件；HENGSHI SENSE 的 VECTOR_DB_URL 与 VECTOR_ENDPOINT 应填写启动日志和运行目录 .env 中的实际值，随后按当前部署方式重启服务以应用配置。

离线环境还需在交付包的 artifacts/ 中准备匹配的镜像与模型，并在执行检查和启动前设置离线模式。Kubernetes 部署同样要根据集群实际存储系统调整存储配置。无论采用哪种形态，部署包可替换，运行目录与 PostgreSQL volume 则应作为受保护的运行状态管理。

2.2 默认模型、连通性与向量生命周期

系统自带向量服务使用 intfloat/multilingual-e5-base 作为当前默认模型配置。它是部署基线，不能据此推断所有项目都固定使用同一模型。若计划替换模型，先确认向量服务是否支持该模型、运行环境是否可取得模型文件，以及新旧向量是否需要重建；不同嵌入模型生成的表示不能默认直接混用或直接比较。替换后应对同义词、易混淆字段、历史口径和权限范围分别做召回抽验。

排障时先区分“向量服务无法工作”和“问答结果不理想”。前者可按交付脚本的 check、status、logs 顺序确认环境、镜像、模型、容器和实际端口；再用嵌入接口确认服务端可返回向量，并在数据库中以 vectorize.transform_embeddings 验证扩展与模型链路。这里不应把实现泛称为某一种固定的向量索引或扩展组合，实际交付以安装包和现场状态为准。

select vectorize.transform_embeddings(
  input => '验收文本',
  model_name => 'intfloat/multilingual-e5-base'
)::text;

后者通常从数据资产开始处理：数据包发布、字段或指标描述修改、口径变更、同义词调整之后，重新执行数据向量化，并在任务管理的执行计划中查看进度。需要持续更新的资产可以安排计划任务，但每次重要变更都应保留变更记录和人工抽验。向量化产物是可重建的检索材料，原始数据和必要的元数据备份仍要按数据平台的备份策略单独管理。

3 模型接入：把“兼容”视为待验证的接口契约

3.1 逐项验证端点、认证、参数与运行能力

云端模型和自建模型都需要可访问的 HTTP 服务地址；云服务通常还需要由企业自行申请和保管的 API Key。平台列出多家模型供应商，也提供 OpenAI-API-Compatible 选项。接口兼容表示服务可按约定的请求与响应格式配置到平台中，并不表示任何服务都能免配置、免验收地接入。接入前应使用“测试模型连接”确认端点、认证信息、模型名和服务可用性，再用真实问题完成业务验收。

验收项	需要核对的内容	通过证据
请求与认证	端点路径、协议、鉴权方式、密钥权限、模型名称	测试连接与受控请求返回预期响应
请求参数	temperature、max_tokens 或 max_completion_tokens、JSON 返回、思考参数	分别启用与关闭相关配置并保存请求日志
能力协作	工具调用、流式返回、超时、重试和限流后的表现	覆盖成功、超时、限流、格式不支持等边界用例
数据边界	发送到外部服务的提示词、元数据和结果摘要范围	安全、采购与业务方完成确认并留存配置

自建模型可让模型服务和相关运行环境处在企业可控网络中；一旦配置外部大模型端点，发送给该端点的数据流仍由该供应商的服务、合同与地区设置约束。两类模式可以并存，但不能把“本地部署了某个组件”理解为外部模型调用也自动不出域。密钥不应写入前端脚本或日志，调用服务应具备最小权限、访问控制和审计能力。

3.2 Workflow 与 Agent 是不同运行服务，API 是接入方式

选择模型前先确定问答由谁持续推进。Workflow 模式由后端工作流服务处理一次问答的执行过程，适合希望由后端统一管理执行逻辑、权限边界和稳定交付的场景。Agent 模式则保留持续推进、状态变化、工具调用和逐步反馈的运行特征；在浏览器嵌入时由前端嵌入能力承接，后端侧如需保留 Agent 模式则需要相应的 Node.js Agent 服务。iframe、JS SDK 和 API 都是接入方式，不应与运行模式混为一谈。

运行模式	公开手册中的私有部署候选	选型与验收重点
Workflow	Qwen3.5-27B	结构化任务、指令遵循、超时与结果稳定性
Agent	Kimi-K2.5、MiniMax-M2.5、DeepSeek-V4-Flash、GLM-5	多步推理、工具调用、长会话、无进展中止与资源上限

表中的名称是当前手册给出的候选，不构成通用最优排名，也不替代模型厂商对硬件、量化、许可和服务框架的要求。模型输出速度和效果会受到硬件、模型规模、输入输出长度、优化技术与系统环境共同影响。应先在受控数据集上对照业务问题、工具调用和并发边界验收，再决定生产配置。

4 把问答链路拆开验收：语义、检索、HQL、结果各自留证

4.1 从自然语言到数据结果的可核验路径

一条数据问答请求通常经过范围与权限约束、资源与示例检索、上下文组装、模型规划、查询表达式生成、数据执行和结果呈现等环节。RAG 只服务于其中的候选检索和上下文准备。对于衡石的数据问答，应把 HQL 理解为产品语义层中的查询语言或查询表达式，而不是把它等同于可直接对任意物理数据库下发的通用 SQL。数据源连接、语义模型和执行引擎如何处理实际查询，取决于平台与数据源配置；验收应检查语义、执行结果和权限是否一致，而不是只检查模型是否生成了看似合理的文本。

在实际项目中，模型可以先选择字段、指标、相关函数和示例，再形成 HQL 相关的查询意图或表达式；物理数据源最终看到的执行方式仍取决于连接器和查询引擎。因而排查“结果不对”时，要分别确认模型选了什么、HQL 表达了什么、平台对该表达式如何执行、数据源返回了什么。把这四层日志混在一起，会掩盖真正的故障点。

• 先用同义词、业务别名、日期口径和指标口径题验证语义准备与检索候选。
• 再用跨数据集、空结果、超出可见范围和字段被隐藏的题目验证范围与权限。
• 用人工已知答案核对 HQL 所表达的维度、过滤、聚合和时间窗口，并核对返回数据。
• 最后检查图表、表格与总结是否忠实反映查询结果；智能解读用于基于既有和历史数据的查询、汇总与描述，不应用于预测未来结果。

可将验收题和预期结果保存在一个小型回归集。例如“按已定义的财年比较两个区域的已发布指标”，就能同时检查财年解释、区域筛选、指标选择和结果核对，帮助团队把验收标准落实到具体业务任务。每次升级模型、调整提示词、替换向量模型或更新重要数据资产后，都应重新运行这组题，并记录差异、接受标准和处理结论。

4.2 按失败层排障，并保存执行日志与边界条件

失败层	优先检查	应保留的证据
数据语义	字段、指标、知识管理、提示词与向量化任务是否已更新	变更单、向量化任务状态、人工召回抽样
向量服务	交付脚本状态、实际端口、镜像、模型、扩展和连接信息	check/status/logs 输出与连通性结果
模型调用	端点、密钥、模型名、参数、超时、流式与工具支持	测试连接、脱敏请求响应、供应商错误码
查询与权限	当前用户角色、提问范围、HQL 语义、数据源执行错误	执行日志、角色与范围、可复现问题
呈现与总结	返回数据、图表渲染、总结环节和浏览器网络请求	执行日志、Fetch/XHR 响应、系统调试导出

Data Agent 与 ChatBI 的对话卡片可复制完整执行日志。复现问题时，还可保留浏览器开发者工具中的 Fetch/XHR 响应，并在系统调试中开启实时调试后导出日志。提交问题时应附上问题文本、用户角色、指定数据范围、发生时间、部署版本、实际端点状态和预期与实际差异；密钥、令牌和敏感原始数据需要脱敏。这样的记录能将“回答不对”拆成可定位的工程问题。

公开发布说明显示，2026 年 9 月 23 日发布的 6.3.2 包含 ChatBI 动态主题域指标问数未返回结果的修复；同日的 6.2.5 维护版本也修复了多轮问答数据源继承、问答不收敛、总结与图表数据不一致等问题。实施前应核对实际运行 build 的发布说明，6.2 手册页面可作为配置参考，但不应被表述为所有环境的“最新版本”。

5 结语

可靠的数据问答来自一组可检查的工程约束：先治理数据语义，再让 RAG 缩小候选；以权限决定可见范围；通过交付脚本保存向量服务的运行状态；把每一种模型接入当作接口和能力验收；把 HQL、数据执行与结果解释分别核对。做到这些，模型可替换、数据可更新、问题可复现，团队也能在版本演进中持续判断每项配置是否仍适合自身环境。