AI 推广数据产品的工程实践：从指标解释到稳定上线

AI 推广产品的难点不只是接入模型或画一张报表，而是让业务问题、数据口径、解释逻辑、交互反馈和上线监控保持一致。本文根据可公开的工程实践归纳方法；业务名称、内部系统、代码仓库和专有实现均不在文中展开。

从“做一个功能”转成可验证的问题

先写清用户要做什么决定，再讨论页面和接口。比如，用户需要理解某项指标为何变化、判断是否采取建议动作，还是定位一段时间内的异常。不同目标对应不同的输入数据、解释粒度和成功指标。

需求拆解时至少明确：

• 用户决策：看完结果后，用户要采取什么动作？
• 指标定义：分子、分母、统计窗口、时区、归因规则和延迟数据如何处理？
• 适用范围：哪些对象、日期区间和状态可以参与计算？
• 证据来源：结论依赖哪些指标或诊断信号，数据缺失时如何表达？
• 验收方式：通过哪些埋点、接口样本、边界用例和线上指标证明结果正确？

建立前后端共享的数据契约

数据产品常见故障不是页面崩溃，而是前端和后端对“同一个数字”理解不同。接口定义应给指标带上名称、单位、时间窗口、计算口径、更新时间和可用状态，而不只传一个裸数值。

后端应使用参数化查询和显式字段白名单，不把用户输入拼进 SQL；限制时间范围和分页大小；为重复请求、重试和异步计算设计幂等键。前端则根据契约展示加载、空数据、部分数据、失败和过期状态。

让 AI 输出可理解、可回退

AI 解释应该建立在可核验的数据之上。可以把结构化事实与自然语言分开返回：事实字段供界面和测试使用，文字负责解释；当数据不足时明确说明证据不足，而不是补造原因。建议类能力应说明适用对象、观察窗口和不确定性，并保留“不采取建议”的路径。

流式界面也要把协议状态设计完整。不能只把每个 token 直接拼到一段文字里，还要处理开始、增量内容、阶段状态、完成、错误、取消和未知消息类型。

type StreamEvent =
  | { type: "delta"; text: string }
  | { type: "stage"; name: string }
  | { type: "done"; requestId: string }
  | { type: "error"; message: string }
  | { type: string; payload?: unknown };

function describeUnknownEvent(event: StreamEvent) {
  if (event.type === "delta") return event.text;
  if (event.type === "stage") return `处理中：${event.name}`;
  if (event.type === "done") return "已完成";
  if (event.type === "error") return event.message;
  return "收到暂不支持的消息类型，当前结果仍可继续查看";
}

生产实现还需要校验 payload 结构、限制单条消息大小、清理订阅、支持取消，并避免把令牌或敏感输入写入日志。未知消息应可观测但不应让整个会话白屏。

消息触达与多类型交互

当页面承载文本、卡片、图片、诊断结果等多种消息时，渲染逻辑要按类型隔离。类型识别失败时展示安全的通用占位，并记录脱敏后的类型和请求上下文，避免对未知 payload 直接做深层字段访问。消息重放、重复上报和异步回调也要有去重与生命周期管理。

用灰度和数据校验闭环交付

发布前先在代表性样本上核对接口返回、指标计算、页面展示和埋点事件。灰度阶段同时观察功能错误率、接口耗时、数据完整性和用户行为；当解释内容异常时，应能通过配置开关关闭新能力，或回退到稳定的旧展示。

一次完整交付可以按这个顺序检查：

1. 从需求中定义用户决策与可量化验收条件。
2. 和产品、数据、后端一起确认指标口径与数据延迟。
3. 设计接口状态、错误码、分页、权限和未知类型的降级行为。
4. 编写前端加载/流式/取消/空态/错误态，并验证移动端布局。
5. 用固定样本校验解释和指标，覆盖边界时间、空值、重试和重复事件。
6. 灰度上线，检查埋点、日志和业务指标，再逐步扩大范围。
7. 记录变更、遗留问题和回滚方式，把线上问题转成回归用例。

复盘时关注什么

• 用户是否更快理解了指标，而不是只多看到一段 AI 文案？
• 前后端是否共享同一套计算口径和时间范围？
• 部分数据、未知消息和上游超时是否仍有可用的降级体验？
• 建议是否可解释、可忽略、可追踪，而不是看起来确定但无法验证？
• 埋点是否能回答功能有没有被使用、是否改善了用户决策？

把这些问题放进方案评审和上线清单，AI 能力就不再是孤立的模型调用，而是可观察、可验证、可回退的产品链路。

公开范围说明

本文只保留通用工程方法。具体企业、业务系统、内部仓库、内部依赖、域名、接口字段和数据样本均已省略或泛化；示例代码为独立编写的通用示意，不对应任何内部实现。