语义层建好了，Agent 还是给错数：共享口径与任务口径之间的五道缺口

语义层建好了Agent 还是给错数共享口径与任务口径之间的五道缺口摘要很多团队把指标定义统一进语义层Agent 上线后照样答错。问题不在定义不准而在共享口径与任务口径之间隔着五道缺口子集、时间基准、权威源、适用性、留痕。本文给出五道缺口的判据与修法、指标从文档条目升级为受治实体的四类属性、一页纸任务口径卡模板以及一套三周可完成的改造顺序与验收指标。前言上个月帮一家制造企业看他们的问数 Agent。语义层做得很像样三百多个指标有唯一定义收入、毛利、活跃客户都写清楚了表达式和粒度BI 报表和自助取数都接在同一套定义上。然后业务提了一个问题“这季度有哪些客户到期不续约”Agent 给了一份名单。业务看了一眼就退回来了——名单里有三十多家是一次性采购根本没有合同可续。问题不在活跃客户这个定义。那个定义是对的过去 90 天有付费订单的账户。问题在于共享口径回答的是这个词在公司里是什么意思任务口径回答的是这次判断里哪些记录算数。前者语义层能覆盖后者语义层管不到而 Agent 恰恰是在后者上翻车。2026 年 9 月底到 10 月初一周之内三家数据平台同时往这个方向使劲Snowflake 把 Semantic Studio 正式放出来9-30DataHub 的 Metrics Catalog 把业务指标做成受治实体而不是散落在各工具里的定义10-1Databricks 用 Genie Ontology 标注哪些表是权威表、哪些业务规则适用、谁是可信任的专家10-5。同期还有一家厂商把数据目录直接接到 MCP 上给 Agent 当上下文源产品负责人的一句话我记下了目录最大的风险是变成一个逐渐过期、没人使用的形式登记以上均为厂商公开产品信息按公告口径引用。三家的动作说明一件事行业已经从统一指标定义走到给 Agent 交付受治上下文中间这一层才是现在真正缺的东西。一、先分清共享口径与任务口径不是一回事把两个概念摆在一起对比缺口就清楚了。维度共享口径语义层任务口径本次判断回答的问题这个指标是什么这次算哪些记录覆盖范围全公司通用单个任务、单个决策时间基准标准日历、默认窗口本次决策用的日历与截止时点权威源认证过的表/视图本次允许读哪几张、禁止读哪几张例外全公司通用规则某个团队、某条流程特有的例外质量要求有质量分即可本任务能否容忍当前的缺陷率生命周期长期演进随任务结束归档一句更直白的话语义层保证同一句话大家算得一样任务口径保证这句话用在这次判断上是对的。这也是为什么很多团队把语义层做得越完整Agent 的错反而越隐蔽——定义越统一Agent 越自信地按统一逻辑去算一个本来就不该统一的场景。二、五道缺口现象、判据、修法下面五道缺口按出现频率排序。每道给三样东西怎么发现、怎么修、落到哪个元数据字段。2.1 缺口一子集与例外最高频现象定义正确名单错误。上面那个续约的例子就是。同类还有统计活跃门店时把已闭店未销号的算进去算有效合同时把框架协议当正式合同统计在岗人数时没排除借调与实习。判据拿同一指标问三个不同任务的业务方让他们各自列出这次不算的如果三个人给出的排除项不一样说明例外没有落在元数据里只落在人脑里。修法在指标定义之外单独维护一层任务子集。子集不是过滤条件的堆叠而是三件事metric:active_customershared_definition:过去 90 天内存在已支付订单的账户task_subset:task_id:T-RENEW-2026Q4scope:存在有效服务合同且合同到期日落在 2026-10-01 ~ 2026-12-31 的账户exclude:-仅有一次付费记录且无合同主体的账户# 一次性采购-合同已终止但账户未销号的-内部关联方账户按关联方清单排除owner:客户成功部-张Xreviewed_at:2026-10-08元数据字段task_scope、task_exclude[]、scope_owner。这三个字段不放进共享指标定义单独挂在任务对象上——放进去就变成全局污染。2.2 缺口二时间基准现象财年与自然年混用“上季度按自然季度算但公司财年是 4 月开始数据截止到 T1Agent 按当天日期算本月累计”跨境业务时区错位美西 10 月 31 日的订单被算进 11 月。判据问 Agent “上季度收入是多少”再拿同一问题去问 BI 报表。两个数不一致先查日历不要查 SQL。修法把日历做成显式对象而不是在 SQL 里写死日期。字段说明示例calendar_id日历标识fiscal_cn_2026fiscal_start_month财年起始月4period_type周期类型季度data_cutoff数据截止时点2026-10-19T02:00:0008:00timezone业务时区Asia/Shanghailag_rule延迟规则T1月末 T3一条硬规则Agent 生成的时间表达式必须带calendar_id和data_cutoff两个字段缺失时拒绝出数。宁可让它说当前数据只到 10 月 18 日也不要它给一个看起来精确的错数。2.3 缺口三权威源指向现象语义层只定义了指标表达式没定义从哪张表算。于是 Agent 自己挑表——挑了数据集市里一份三个月没刷新的自助取数副本或者挑了某个部门自己拉的宽表。判据把 Agent 的执行日志拉出来看它实际扫了哪些表。如果出现tmp_、bak_、dwd_xxx_copy、个人 schema 下的表这一项就不合格。修法给每个业务概念标注权威表、候选表、禁用表三档。concept:revenueauthoritative:table:dwd.fin_revenue_digrain:日 × 产品线 × 区域certified_at:2026-09-30owner:财务数据组candidate:-table:ads.fin_revenue_monthnote:月度汇总仅用于报表核对不可用于明细追溯forbidden:-pattern:tmp_.*|.*_bak|.*_copy.*|ods_.*reason:临时表/备份表/个人副本不具备权威性元数据字段is_authoritative、grain、certified_at、forbidden_patterns[]。这一项比多数人想的更重要。厂商侧有一个判断说得很直白Agent 不会停下来质疑它拿到的数据。人看到同一个客户名三种拼法会犹豫一下Agent 不会它会以机器速度把错误传播到下游每个系统。2.4 缺口四适用性数据够不够用于这个任务现象语义层告诉 Agent 这个指标怎么算但没告诉它这批数据当前的质量状况。某个字段空值率 12%Agent 照样按它做分层某张表昨天同步失败Agent 按旧快照出了今日的数。判据做一次注入测试——把某张源表故意延迟一天看 Agent 是照常出数还是提示异常。照常出数说明适用性没有落到上下文里。修法给每个资产挂一个轻量的可用性画像四项就够项内容阈值示例新鲜度最近成功更新时间核心表 24h 告警完整性关键字段空值率 5% 需提示一致性与上游对账差异率 0.5% 需提示已知缺陷当前未修复的问题清单有则必须随结果返回这四项不必做成实时大屏做成 Agent 调用前的一次查询即可。关键是随结果返回而不是只在监控平台里躺着。业务看到的每一份 Agent 输出都应该带一行小字“本结果基于 10-19 02:00 快照客户等级字段空值率 3.2%。”2.5 缺口五留痕用了哪版定义、哪张表、哪次快照现象三个月后业务质疑一个数团队复现不出来。因为当时用的指标定义已经被改过两版源表也重构建过。判据随机抽 10 条历史回答要求团队在不问原作者的前提下复现出同一个数。复现率低于 80%这一项不合格。修法每条 Agent 输出绑定一个执行指纹。{answer_id:A-20261019-00417,task_id:T-RENEW-2026Q4,metrics:[{name:active_customer,definition_version:v7,effective_at:2026-09-01,source_table:dwd.crm_account_dim,snapshot:2026-10-19T02:00:0008:00}],calendar_id:fiscal_cn_2026,data_cutoff:2026-10-19T02:00:0008:00,prompt_version:qa-agent-2.3.1,model:内部部署模型-A,evidence_links:[doc://policy/customer-status#3.2]}这份指纹的价值不在合规在于它能让你在指标定义变更时批量找出受影响的 Agent 任务。没有它改一个指标定义就是一次盲改。2.6 把五道缺口串起来一个完整推演还是回到开头那个续约问题把五道缺口逐一放进去看错在哪一步就一目了然。第一次回答只有共享口径。业务问这季度有哪些客户到期不续约“Agent 拿到active_customer的定义——过去 90 天有付费订单——然后去找到期”。语义层里没有合同到期这个受治指标Agent 就从表名里挑了一个看起来最像的crm_contract_info按end_date在当季范围内筛。结果三十多家一次性采购进了名单两家已终止合作的也进了名单还有五家合同到期日字段是空的被直接漏掉。业务退回来一句话“这玩意没法用。”逐层看五道缺口全踩了子集没有排除无合同主体的一次性采购也没有排除已终止未销号时间基准Agent 用的是自然季度而客户成功部的考核按财年4 月起两边差一个季度权威源crm_contract_info是业务系统同步表真正的权威源是dwd.contract_fact做过合并与状态校准Agent 挑错了适用性end_date空值率 8%Agent 不知道这个缺陷直接把空值当未到期处理留痕回答里没有任何版本与快照信息业务追问你按哪个口径算的没人答得上来。改造后加了任务口径卡与权威源标注Agent 第一步不是查数而是读这张卡任务 T-RENEW-2026Q4决策对象是有有效服务合同的账户是否续约子集条件是合同到期日落在 2026-10-01~12-31时间基准fiscal_cn_2026权威源dwd.contract_fact已知缺陷客户等级空值 3.2%。于是它先去查权威源发现end_date空值 8% 的记录集中在一个历史迁移批次里这些账户被单独列成一栏到期日缺失需人工确认而不是被静默丢弃。名单输出时带三样东西判定依据为什么算进/排除、数据快照时间、缺失项清单。业务这次的反应是“名单能用但缺日期的那批我要去找 CRM 补。”——这就是从没法用到能用但有边界的差别。一个诚实的 92%比一个自信的 100% 有价值得多。这里有个容易被忽略的收益空值不再被当成未到期而是被显式暴露出来顺带推动了 CRM 那边的一次数据修复。任务口径卡不只是给 Agent 用的它同时是一份数据缺陷的发现清单。三、指标要从文档条目变成受治实体上面五道缺口要能修前提是指标本身是个有身份的对象而不是知识库里的一段说明文字。四类属性缺一不可。属性类具体内容缺失后果定义表达式、粒度、过滤条件、单位、正负向Agent 各算各的权威源认证表、粒度、认证时间、责任人挑到副本或临时表责任与审批owner、审批记录、变更历史改口径没人拦质量与适用性质量分、新鲜度、已知缺陷、适用场景拿脏数据当干净数据用再加一条容易被忽略的变更策略。指标定义要有版本号、生效日、弃用日并且允许双版本并行一段时间——新旧口径同时可算报表标注差异等业务确认后再切换。直接覆盖式修改是口径事故的头号来源。一个可以直接用的指标实体字段表metric_id:M-FIN-0021name:revenuealias:[营业收入,营收,收入]definition:expression:sum(pay_amount) where order_status in (paid,settled)grain:日 × 产品线 × 区域unit:CNYpolarity:positiveexclusion:[内部关联交易,测试订单]authority:table:dwd.fin_revenue_dicertified_at:2026-09-30owner:财务数据组governance:owner:财务BP-李Xapprover:数据委员会version:v3effective_from:2026-10-01deprecated_from:nullquality:freshness_sla:24hcompleteness:0.998known_issues:[华东区经销商返利尚未回冲]usage:allowed_scenarios:[经营分析,客户分层,预算达成]restricted_scenarios:[对外披露,审计口径]usage这一段是很多团队没想到的。同一个指标用于经营分析和用于对外披露要求完全不同。语义层如果不写清哪些场景能用Agent 就会把内部分析口径的答案直接拿去回答审计问题。四、一页纸任务口径卡五道缺口修完之后还需要一个载体把它们串起来。我一般让团队给每个 Agent 任务做一张卡一页纸不超过 15 行。字段填写要求示例任务名与 ID唯一可追溯季度续约风险识别 / T-RENEW-2026Q4决策对象判断的是什么哪些账户本季到期且不续约涉及指标只列本任务用到的active_customer、contract_end_date、renew_status子集条件谁算、谁不算有有效服务合同的账户排除一次性采购、已终止未销号、关联方时间窗与日历明确到日2026-10-01~12-31财年日历 fiscal_cn_2026数据截止 T1权威源表名 粒度dwd.crm_account_dim账户粒度例外谁批准的例外华东区经销商延后 15 天计入客户成功部 10-08 批准数据可用性已知缺陷客户等级空值 3.2%按行业均值补输出要求格式与必带信息名单 判定依据 数据快照时间责任人业务 数据各一业务客户成功部数据CRM 数据组复核节奏多久回看一次每季度末复核子集条件填这张卡的过程本身就有价值。大部分Agent 答错的争议在填卡阶段就会暴露——业务说不清排除项说明这个判断本来就没有成文规则。五、三周改造顺序与验收指标不要一上来就重做语义层。按下面的顺序三周能出可见效果。周动作产出判断标准第 1 周选 3 个高频任务填任务口径卡3 张卡业务方签字确认排除项第 2 周补齐权威源三档标注 可用性画像概念-表映射表Agent 日志中临时表/副本表出现次数为 0第 3 周加执行指纹 变更影响扫描指纹字段、影响清单抽 10 条历史回答复现率 ≥ 90%验收不要只看准确率准确率会被样本选择掩盖。建议看四个过程指标指标定义目标口径命中率回答中引用的定义版本 当前有效版本的比例≥ 98%可回链率答案能定位到定义版本、源表、快照时间的比例≥ 95%跨任务冲突率同一指标在不同任务中口径不一致且未标注的比例≤ 2%上下文开销单次任务注入的元数据 token 占比有基线并下降最后一项容易被忽略。有的团队为了信息充分把几百张表的 schema 全塞进 Prompttoken 成本翻倍、准确率反而下降。用语义检索先裁掉无关表只注入命中概念及其血缘相邻节点是更划算的做法。有厂商公开的基准显示在 278 张表与 264 张表两套 schema 上加了图结构语义层后 token 用量下降 45%~81%厂商基准环境依赖强标【待人工核验】不建议直接当采购依据。六、五个踩过的坑坑一把语义层当文档库。只写本指标反映公司营业收入不写表达式和粒度。这种语义层对 Agent 毫无用处因为它没有可执行内容。坑二指标爆炸。每个部门都能提指标一年涨到八百个其中三百个是同一个东西的不同叫法。治理动作不是继续加而是合并别名、设停用名单。坑三只做正向定义不做排除条件。“有效合同只写已签署且在执行中”不写不含框架协议、不含补充协议。Agent 一定会把框架协议算进去因为它按字面理解。坑四语义层与 BI 两套定义。BI 报表还留着旧的 SQL 口径两边数字长期不一致。这会直接摧毁业务对语义层的信任——而信任一旦没了后面所有治理动作都推不动。坑五指望 Prompt 解决口径问题。在提示词里写请注意使用最新版本定义实测基本无效。版本裁决必须是检索后的重排逻辑或查询时的强制条件不能是叮嘱。总结语义层解决的是同一个词大家理解一致Agent 需要的是这次判断该用哪个子集、哪张表、哪份快照。两者之间那一段过去靠人补现在必须被工程化。三件事可以立刻做给本周在跑的 Agent 任务各填一张任务口径卡业务签字的排除项比任何提示词都管用。把权威表、候选表、禁用表三档标出来先禁掉tmp_、*_bak、*_copy这类命名。给每条输出加执行指纹定义版本 源表 快照时间三项必须有否则这条答案不算可交付。你们的语义层上线后Agent 出错最多的是子集问题还是时间基准问题欢迎评论区说说具体场景。标签语义层,元数据,Data Agent,指标治理,数据治理