DataAgent 项目适配评估 Checklist
本文用于在正式启动 DataAgent 项目前，判断当前客户环境、模型能力、数据质量和实施条件是否具备落地基础。
建议在售前验证、PoC 启动前、生产部署前各评估一次。凡是标记为“必须”的检查项未通过，都不建议直接进入正式实施或生产上线。
评估结论
判定规则
- 适合启动：所有“必须”项通过，且已准备好一批可验收的业务问题和标准答案。
- 整改后启动：存在少量可修复问题，例如模型 Tool Call 不稳定、部分核心表缺少主键、数据库网络未打通。
- 暂不建议启动：核心数据无法按实体/事件建模，指标口径无法确认，主模型不支持 Tool Call，或无法提供可用的数据源访问方式。
一、目标场景检查
- 已明确 DataAgent 首批要解决的业务场景。
- 已明确首批使用人群和使用入口，例如 Web、飞书、钉钉、企业微信、API。
- 已整理 20 到 50 个真实业务问题作为验收集。
- 每个验收问题都有标准答案、SQL、报表或业务口径作为对照。
- 已明确哪些问题属于首期范围，哪些问题不在首期范围。
二、部署环境检查
- 必须：服务器或容器平台可运行 DataAgent，支持 Docker Compose 或 Kubernetes。
- 必须：部署人员具备服务器
sudo权限或等价的容器平台操作权限。 - 必须：测试环境至少满足 4 核 CPU、8GB 内存、30GB SSD 硬盘。
- 必须：生产环境已按用户规模评估资源，建议至少 16 核 CPU、32GB 内存、60GB SSD 硬盘起步。
- 必须：PostgreSQL 版本满足 17 大版本，并已安装
pgvector扩展。 - 必须：Redis 版本满足 8，或在单进程测试环境中明确不使用 Redis。
- 必须：多进程、集群或 Kubernetes 部署时，缓存必须配置为 Redis，不能依赖进程内内存缓存。
- 必须：应用存储、PostgreSQL 数据目录已配置持久化卷或外部存储。
- 必须：已规划数据库备份、文件备份、恢复演练和升级回滚方案。
- 已确认反向代理、负载均衡、域名、证书、超时时间等生产访问配置。
- 已确认 SSE 流式响应在网关、Ingress 或代理层不会被提前中断。
三、网络与访问检查
- 必须：用户浏览器或业务系统可以访问 DataAgent 服务地址。
- 必须：DataAgent 容器或 Pod 可以访问主模型 API。
- 必须：DataAgent 容器或 Pod 可以访问 Embedding 模型 API。
- 必须：DataAgent 容器或 Pod 可以访问目标业务数据库。
- 必须：模型网关、数据库、代理服务器的证书、鉴权和白名单策略已配置完成。
- 如业务数据库不能直连，已准备 SSH 隧道、跳板机、专线或其他网络连通方案。
- 如部署在内网，已确认镜像包、离线安装包、模型服务和许可证获取方式。
四、大模型检查
- 必须：主模型为 Chat Completion 模型，且支持 Tool Call 或 Function Calling。
- 必须：主模型不是只适合推理输出的模型，工具调用场景下能稳定输出结构化结果。
- 必须：主模型参数量不低于 32B，并且实际通过 Tool Call 测试。
- 推荐：主模型参数量达到 235B 以上，优先用于生产问答、深度代理和 AI 建模。
- 必须：主模型能稳定返回可解析的工具参数，不能出现字段名随机变化、JSON 不完整、自然语言混入参数等问题。
- 必须：主模型中文理解正常，能把模糊问题改写为更明确的问题，且不改变业务含义。
- 必须：主模型响应速度在目标业务场景下可接受。
- 必须：Embedding 模型能稳定返回固定维度向量。
- 必须：Embedding 模型对相近中文词语的相似度排序明显高于无关词语。
五、数据源接入检查
- 必须：目标数据源属于标准支持数据库。
- 必须：DataAgent 使用的数据库账号具备查询目标表、视图和必要元数据的权限。
- 必须：生产接入优先使用只读账号，避免问答链路具备写入业务库的权限。
- 必须：已确认跨库查询边界。如果事件表与实体表位于不同数据库，需要先保证关联实体在事件表所在数据库中可访问。
- 已明确敏感字段、脱敏规则、行权限、角色权限和空间隔离规则。
六、数据要求检查
本节只列必须遵守的数据要求，不包含数据清洗、概念归一、建模便利性等最佳实践建议。
- 必须：核心业务数据能够被表达为实体表和事件表。
- 必须：实体表必须有稳定主键，用于唯一标识客户、产品、门店、员工等业务对象。
- 必须：事件表必须有明确时间字段，用于表示订单、支付、退货、出库等业务行为发生的时间。
- 必须：用于问答聚合的指标应具备可加性，按各维度加总后的结果应等于全体加总。
- 必须：同一指标表中不能混放会破坏加总口径的不同粒度汇总行。例如月目标和年目标同时存在，且月目标加总不等于年目标时，需要先拆分或重建口径。
- 必须：比率、均值、占比、转化率等不可直接加总的指标，不能只保留最终结果值；如需按任意维度分析，必须保留分子和分母，或保留可还原分子分母的明细数据。
- 必须：指标字段不能把维度写进字段名。例如“主渠道收入”“副渠道收入”“总收入”应改造为“渠道”维度加“收入”指标，而不是三个并列指标字段。
- 必须：需要被筛选、分组、对比的业务属性必须以维度字段或实体属性存在，不能只存在于指标名称、报表标题或人工说明中。
- 必须：业务口径存在特殊过滤条件时，需要能在数据层或语义模型中明确表达。例如销售额是否排除退货、是否排除取消订单。
七、业务口径与建模检查
- 必须：首批核心指标已有明确业务定义、计算公式和过滤条件。
- 必须：首批核心维度已有明确含义、取值范围和层级关系。
- 必须：已明确默认时间口径，例如下单时间、支付时间、发货时间或财务确认时间。
- 必须：已明确权限口径，例如不同部门、区域、角色可查看的数据范围。
- 必须：业务负责人可以参与建模评审，并确认系统回答是否符合业务口径。
- 已识别同名不同义、同义不同名、简称、别名和业务黑话。
- 已识别需要通过自定义指标、业务逻辑配置或脚本处理的特殊规则。
八、实施团队检查
- 必须：实施人员熟悉 SQL，能够排查查询结果和业务口径差异。
- 必须：实施人员理解三范式、雪花模型、维度建模和宽表拆分的基本方法。
- 必须：实施人员了解大模型 API、Embedding API、
baseURL、apiKey、模型名称等基本配置。 - 必须：部署人员能够操作 Docker Compose 或 Kubernetes。
- 必须：客户侧有业务负责人、数据负责人和系统负责人配合验收。
- 推荐：实施人员具备基础 JavaScript 能力，用于处理高级业务逻辑配置。
九、PoC 验收检查
- 必须：DataAgent 环境已部署成功，可以正常登录。
- 必须：主模型和 Embedding 模型已配置成功。
- 必须：至少一个真实业务数据源已连接成功。
- 必须：已完成首批核心表的语义建模。
- 必须：已完成 Schema 学习，Embedding 阶段正常完成。
- 必须：Nora 能正常调用 Data Query（Alisa）等工具，而不是只返回自然语言解释。
- 必须：验收问题集中，核心问题回答正确率达到项目约定标准。
- 必须：错误答案可以定位到具体原因，例如数据问题、建模问题、模型问题或权限问题。
- 必须：并发、响应时间和错误率满足首批用户试用要求。
- 必须：敏感数据、权限边界和访问日志满足客户安全要求。