我们的智能分析架构

在Anthropic，我们通过构建智能数据架构来最大限度地减少三类常见错误：

  1. 实体歧义：通过数据基础和权威数据源，缩小可能实体的范围，确保只有一个受控答案。
  2. 数据陈旧：维护和验证流程保证数据随业务变化保持新鲜和准确。
  3. 检索失败：技能确保智能体能够可靠地找到并正确使用答案。

以下内容将详细介绍我们如何构建每一层。

智能分析架构

数据基础

确保分析智能体准确性的关键是坚实的数据基础，包括数据模型、转换、测试、数据仓库中的表以及描述它们的元数据。传统的数据工程和数据质量实践，如维度建模、提前测试、关键管道的新鲜度和完整性检查依然适用。

数据基础

不同的是，数据模型的最终用户不再是数据专家，而是代表用户的智能体，这些用户对数据专业知识和底层基础设施的理解程度不一。因此，结果不能依赖用户来验证其正确性。

数据基础层主要解决歧义问题：例如，“收入”对应唯一的受控数据集，而非多个候选集，这样问题在智能体搜索之前就大大减少了。同时，这里也是防止数据陈旧的第一道防线，因为定义规范模型的代码库自然成为保持模型最新的地方。

我们发现以下做法特别有效：

  • 创建权威数据集：最常见的问题是智能体无法将概念（如“产品X的收入”）映射到唯一正确的表、列和指标定义，通常是因为存在多个相似但细微不同的候选。解决方案是减少模型数量，严格管理，维护一小批权威且易用的数据集，积极废弃近似重复的版本。物理汇总和缓存仍然重要，但应从权威模型机械派生，而非作为替代品并存。目标是让智能体搜索时找到唯一受控答案。
  • 执行标准：只有通过工具（智能体结构上优先访问权威模型）、持续集成（绕过权威模型的更改会失败审核）和强制要求（下游团队必须基于受控层构建或说明原因），才能保证基础层的稳定。否则治理很快会退化为多个候选问题。
  • 共置工件：我们对抗数据模型和业务逻辑频繁变化的主要手段是共置。几乎所有数据代码（建模、语义层、参考文档、权威仪表盘定义）都存放在同一代码库，持续集成检查跨层完整性。如果建模改动破坏下游仪表盘或文档指标，CI会报警并要求在同一PR中修复。
  • 将元数据视为一等产品：代码库之所以表现良好部分原因是其可读性（README、类型签名、文档字符串等）。同样，数据仓库也能做到可读，但前提是列和表描述、权威指标定义、粒度文档、有效值范围、血缘、归属和模型分层都要像转换代码一样严格维护。良好的治理提供了关键上下文，帮助智能体选择正确数据集。

权威数据源

如果数据基础是数据仓库本身，权威数据源则是智能体用来导航仓库的参考层。它减少概念与实体的歧义，将“每周活跃用户”转化为数据模型中的具体受控实体。按信任度大致排序：

  • 语义层：编译后的指标和维度定义。如果问题能映射到定义好的指标，智能体调用函数得到唯一数字，与公司其他所有渠道一致。我们的智能体结构上必须优先使用语义层。我们尝试过让大语言模型自动从原始表和查询日志生成指标定义，但结果反而带入了歧义，效果不如人工策划的层。因此建议用Claude生成文档，但定义由人工维护。
  • 血缘和转换图：当语义层无法覆盖问题时，血缘和表排名帮助智能体推断上游模型、废弃模型和共享粒度的模型。这将“我不知道指标”转变为“我知道从哪个受控模型聚合”。这也是我们后文“在线验证”中新鲜度和溯源信号的基础。
  • 查询语料库：历史SQL查询来自仪表盘、笔记本和先前分析。理论上应很有价值，因为它记录了所有已正确回答的问题。但实际上，给智能体直接访问数千条查询对准确率提升不足1%。非结构化检索无法将新问题映射到正确先例。有效做法是将查询语料提炼成结构化的领域参考文档和可复用分析模式（见“技能”部分）。
  • 业务上下文：大多数团队忽视的层，也是我们最初低估的。不了解业务的智能体会回答用户问的问题，但不一定是用户真正想问的。它不会知道“第二季度发布”指特定产品，不知道两个团队对同一术语定义不同，也不知道问题背后是因为董事会会议。我们引入公司知识图谱，包括索引文档、路线图、决策日志和组织结构，帮助智能体解析上下文引用并提出更好的澄清问题。

这四层的共同失败模式是：文档不完善或陈旧。Claude非常适合弥补这一差距（起草列描述、根据查询模式建议指标文档、CI中标记无文档模型），但策划和归属必须由人负责。

接下来两节将讨论如何降低归属维护成本。

技能

如果权威数据源是智能体的声明性知识（指标含义），那么技能就是其过程性知识：按顺序访问哪些数据源，如何处理歧义，什么是完整分析。

在Claude Code中，技能是智能体按需读取的Markdown文件夹。在Anthropic，我们开发的技能极大提升了价值。没有技能时，Claude在评测中准确率仅21%；加入技能后，整体准确率稳定超过95%，某些领域甚至达到99%。附录中有我们大部分技能的模板。

一些最佳实践：

  • 创建成对技能：一个知识技能作为顶层路由，允许按需加载领域细节。它指示“先试语义层，若无覆盖，这里有约30个参考文件描述相关表、列、连接和注意事项”。这个路由器实际上解决了检索失败问题：避免智能体在百万字段仓库中搜索，而是先缩小到几十个策划文件。分析技能编码高级分析师的流程：澄清问题、查找数据源（通过知识技能）、执行查询、通过对抗性子智能体复核结果。它还包含多种可复用分析模式（留存曲线、率分解、漏斗分析），避免重复造轮子。
  • 创建适合LLM检索的参考文档：描述表（粒度、范围、排除）、注意事项（如排除免费邮箱域但保留公司邮箱）、明确路由触发条件（如“关于实验提升的问题不要用原始事件计数”），避免过时的具体操作指南。附录有参考文档模板。
# [领域] 表

## 快速参考
### 业务上下文 — [该领域的通俗含义]
### 实体粒度 — [一行代表什么]
### 标准过滤器 — [该领域所有查询默认应用的过滤]

## 维度
- [关键维度编码及同一概念在不同表中的命名差异]

## 关键表
### [表名]
- **粒度**: [...] · **范围/排除**: [...]
- **使用说明**: [何时用，何时不用，连接键，必需过滤]

## 注意事项
- [高级分析师会提醒的错误答案模式]

## 最佳实践 / 常用查询模式
- [默认选项，标准切片，复杂查询模式]

## 交叉引用
- [相邻领域文档]
  • 将技能维护视为一等公民：数据模型每天都在变，技能文档不维护几周就错。我们发现上线时准确率约95%，一个月后跌至65%，才意识到这是工程问题。解决方案是将技能Markdown文件与转换模型共置在同一代码库，修改模型的PR必须同时更新技能文档。代码审查钩子会标记未更新技能的模型变更。约90%的数据模型PR包含技能更新。随着模型改进，我们也定期清理技能脚手架。
  • 跨所有界面保持一致体验：同一技能必须在Slack、IDE、仪表盘工具和独立智能体会话中给出相同答案。我们通过确保唯一权威源（数据仓库代码库）和自动同步技能变更实现。合并后，技能同步到插件市场（IDE用户）、云存储（托管应用）并通过MCP直接提供资源。设计时避免硬编码路径和界面特定命名空间，保证可移植性。

验证

最后，验证帮助发现仍存在的失败模式。

离线评估

许多数据团队搭建复杂分析环境，却缺乏评估分析智能体准确性的流程。离线评估是简单的问答对，类似机器学习模型的离线测试，不能完全反映在线表现，但能发现关键缺陷。

Anthropic部署两类离线评估：

  • 仪表盘评估：由Claude自动生成并人工验证，覆盖最常见的利益相关者问题。
  • 长尾评估：输入业务上下文（路线图、表文档），让Claude生成领域内其他合理问题。我们还持续收集利益相关者纠正智能体的对话，作为评估样本。

其他最佳实践：

  • 固定基准，防止漂移：评估基于快照数据或稳定事实表，或评估查询而非结果数字。集成CI，相关依赖变更时自动重跑评估。
  • 像遥测一样存储结果：每次运行结果存入仓库表，记录技能版本、Git SHA、模型ID、断言通过情况、token数和耗时。方便查询变化趋势，捕捉缓慢回退。
  • 按领域设门槛：领域负责人只有在评估通过率达到阈值（如90%）后，才能向利益相关者发布智能体，促使先修复文档。
  • 合理数量的评估：数量取决于业务和数据模型复杂度。我们发现每主题几十个评估后收益递减，且新模型准确率上限下降。
  • 离线评估准确率应接近100%，正确答案应全部命中语义层（如有）。这保证无明显漏洞，但不代表系统不会偶尔出错。

消融实验

所有技能结构决策（如暴露哪些数据源、子智能体是否值得延迟、合并技能等）都基于固定离线评估集，通过单变量对比通过率。每次运行约一小时，方法论比单次结果更重要：

  • 设计接受无效结果：最有价值的消融是负面结果。我们让智能体直接全文检索数千个SQL文件，确认其确实读取了文件，但准确率提升不足1%。80%错误问题的答案确实存在语料中，但“答案存在”并不预测“答对”。说明瓶颈不是访问，而是结构化映射问题，指导了后续路线。
  • 在PR粒度消融：每次重要技能改动都跑前后评估，结果写入PR描述，保证改动真实有效，避免好心办坏事。
  • 记录失败案例：如文档反复精炼超过三轮反而变长不精简，或用更廉价模型替代对抗复核导致准确率大幅下降但无明显加速。负面结果便于后续避免重复试验。

在线验证

确保在线系统尽可能准确，我们采取：

  • 对抗性复核：用Claude技能严格挑战答案假设，评测准确率提升6%，但代价是token数增加32%，延迟提升72%。
  • 溯源页脚：每个回答附带来源层级（语义层›策划参考›原始表）、数据新鲜度和模型归属信息。虽不直接提升正确率，但帮助用户判断可信度。标注“原始表，未知新鲜度”提示需核实，缓解无声失败风险。
  • 数据质量检查：确保引用字段最新、完整且无异常，防止数据本身错误。
  • 被动监控：持续跟踪通过语义层解析的查询比例和带纠正语言的回答比例，周报仪表盘监控趋势。
  • 主动纠正收集：定时扫描利益相关者渠道，识别纠正语言，自动草拟一行修正并发起PR，标记领域负责人。流程简单，减少维护负担。纠正也反馈到离线评估集。

唯一难以完全捕捉的是无声失败：答案错误但看似合理且未被质疑。缓解措施包括溯源页脚、领导层答复需人工签核、每日对关键指标进行评估比对权威仪表盘，但尚无完美方案。

入门指南

从零开始时，准备少量权威数据集、几十个离线评估和一个基础知识技能即可覆盖大部分收益；本文其余内容是基于此基础的扩展。

我们分享了许多最佳实践，但并非所有都适合每个团队。建议结合组织实际，考虑：

  • 当前与未来准确性哪个更重要？ AI模型快速进步，很多基础设施为当前模型不足做准备，未来可能多余。了解模型短板，等待模型改进，成本更低，但风险容忍度不同。
  • 业务复杂度如何变化？ 如果数据量小、用户少、模型简单，部分流程可能过度。
  • 目标用户技术水平？ 面向数据科学家容错更高，面向非专业用户则需更严谨。
  • 愿意为准确性投入多少？ 对抗性验证等提升准确率但成本和延迟较高。
  • 数据访问和隐私控制要求？ 智能体上下文越多性能越好，但广泛访问可能违背治理策略，决定单一智能体还是多个分域智能体。

无论路径如何，最大收益来自解决三大失败模式：将歧义压缩为唯一受控答案，使答案易于发现，并及时标记陈旧。

本文作者：陈畅、Clement Peng、Justin Leder、Johanne Jiao、Josh Cherry（数据科学与数据工程团队）。感谢Michael Segner贡献。

附录

技能文件模板

以下为我们主要仓库技能的骨架结构，真实文件中具体内容用[方括号占位]替代。此模板非照搬，而是展示值得记录的章节类型。

---
name: [warehouse-skill]
version: [x.y.z]
description: "如果用户请求查询[公司]数据仓库中任何[业务领域列表]相关问题，调用此技能。不要用于[相邻工程任务]或无数据仓库成分的问题。"
---

# [仓库]技能说明

## 描述
数据查询的唯一权威路径。
被其他技能引用以指导查询执行。

扮演数据分析师角色，提供战略洞察和数据驱动建议，执行中寻求指导。

**不负责决策**：如[产品领域等] → 仅展示数据，声明“决策由[负责团队]负责”，不参与代码修复。

## 查询执行优先级
1. **[托管连接]**（如可用）：[查询工具]/[模式工具]
2. **[CLI回退]**（如安装）：[默认项目，回退项目]
3. **无连接** — 请求用户认证后停止

---

# 语义层（必经第一步）

受控语义层是所有数据问题的默认路径——与[BI工具]数字一致，连接/粒度/过滤内置。仅当语义层无覆盖或编译失败时，才回退到原始SQL（见下文参考文档）。

## 必须流程
1. **加载** — [各运行时加载方式及回退]
2. **发现** — 关键词搜索指标/维度；**始终检查分段**（命名的标准过滤器，手写WHERE是主要错误源）
3. **编译并执行** — 构建规范→编译SQL→执行
4. **回退** — 仅当无相关指标或编译失败，使用`references/*.md`中的原始SQL

> **不要提前放弃。** 不要因以下理由回退：
> - “[自定义日期过滤/分群]” → [时间维度规范覆盖]
> - “[需要连接]” → [指标层已封装连接]
> - 其他3-4条常见借口

### 日期窗口与时区
- **基准日期与过去N天**：各自约定
- **“上周/上月”**：指完整日历周/月，不是过去7/30天
- **默认时区**：[TZ]；[特定汇总例外]
- **新鲜度延迟**：[部分]表数据延迟，基于最大日期锚定

---

# 第1部分：必须知晓（每次请求首读）

## 🚀 快速启动流程
1. **先检查红旗**：限制/敏感请求、高风险问题需额外验证
2. **超出范围则升级，不要猜测**：访问请求、管道故障、陈旧仪表盘、根因分析、产品定价建议等转给负责团队
3. **澄清请求**：时间段、分段、业务决策背景
4. **查找现有仪表盘**：[按领域仪表盘目录]
5. **确定数据源**：[导航图，优先受控/聚合表]
6. **执行分析**：[必需过滤+对抗性复核]
7. **传递洞察**：展示方法论，区分观察与解读

## 🏢 业务上下文

### 实体消歧（必须澄清）
- **“[术语A]”可能指**：[实体1]或[实体2]，必须明确
- **“[术语B]”可能指**：[实体1]→[实体2]→[实体3]（一对多链）
- **“用户”**：哪个标识准确计数，哪个会膨胀

### 业务术语
- [当前产品名与旧别名，旧别名仍在数据层冻结值中，文档用新名，过滤用旧名]
- [关键内部缩写]
- **[核心指标]计算**：月度/默认窗口/领先指标
- **不熟悉术语** — 查[内部文档]，不要猜

### 数据完整性要求 ⚠️
- **绝不**：编造数据/列；超出数据范围做推测
- **始终**：使用安全除法；区分观察（“数据表明X”）与解读（“这意味着Y”）；标注局限

---

# 第2部分：执行指南

## 🔧 技术执行指南
- [托管连接工具和CLI调用细节]
- **敏感信息保护**：限制数据仅返回SQL供用户自行执行，不返回结果

## 📊 分析最佳实践
1. 查询前澄清需求
2. 展示过程（过滤、包含/排除、新鲜度）
3. 澄清分母
4. 考虑样本偏差
5. 关联业务影响
6. **对抗性SQL复核（必需）** — 每次查询前调用[sql-reviewer]子智能体，阻断性问题必须修复重审，禁止自我认证
7. **带溯源报告** — 每个答案附带页脚：
   > **来源：** [语义层 | 受控表 | 原始探索] ·
   > **置信度：** [层级] · **复核：** [复核者✓，轮次N] ·
   > **新鲜度：** [数据最大日期] · **归属：** [负责团队]

---

# 第3部分：数据参考与资源

## 📚 知识库导航
### [领域A] → `references/[domain_a].md`
- **适用问题**：[问题类型]
- **关键表**：...
- **仪表盘**：`references/[domain_a]_dashboards.json`

### [领域B] → `references/[domain_b].md`
- **适用问题**：...

[每个业务领域一条，共数十条]

## ⚠️ 故障排查指南

### 信息缺失时
- [缺表/无权限/文档过时/未知枚举值 → 处理方法]

### 字段命名陷阱
- 使用`[field_x_v2]`而非`[field_x]`
- [同名表不同粒度指标选择]
- [两个候选中哪个是权威指标]
- [...更多经验总结]