semantic-model

语义模型：设计、构建、刷新、审查

介绍如何在终端设计、构建、刷新和审查 Power BI / Analysis Services 表格模型。本指南将模型审查与建模最佳实践整合在一起，并将每项变更交由最精简且能胜任的工具处理。深入内容位于 references/；本文介绍操作流程和工具路由。

适用场景

• 设计或构建模型：星型架构、关系、度量值、计算组、角色、参数、存储模式、增量刷新
• 优化模型：大小 / VertiPaq、DAX 正确性、Direct Lake、刷新成本
• 根据质量、性能和最佳实践标准审查或审计模型
• 为 Copilot / AI 使用准备模型

不适用场景

• 编辑报表视觉对象、页面或格式：使用 pbir-cli 技能（reports 插件）
• 单独调优 DAX 查询性能：使用 dax 技能
• TMDL 文件语法机制：使用 tmdl 技能（本技能会在文件编辑回退方案中转交给它）
• te 命令本身的用法：te-cli 技能（tabular-editor 插件）是命令参考；本技能则是在此基础上提供建模判断

工具级联（核心操作规则）

按顺序选择最精简且能胜任的工具。大多数编辑都不会超出第 1 步。

1. 优先使用 te CLI。 每项操作使用一个动词，在内存中暂存更改，直到执行 --save；保存时会进行 DAX 和引用完整性检查。支持对度量值、列、关系（te add 中使用 Sales[K]->Dim[K] 简写）、角色 + RLS 筛选器、计算组 / 项添加、设置、删除和移动；支持 DAX 格式化（te set <path> --format Expression，或对整个模型使用 te script --inline "Model.AllMeasures.FormatDax();"）、te bpa、te vertipaq、te query。每次 Bash 调用都会启动一个全新的 shell，因此每条命令都要传入 --model <path>（远程模型则使用 -s/-d），或设置 TE_SESSION。属性通过 -p Name=Value 指定；先用 te get <obj> --properties 查看对象实际可设置的属性。所有变更在执行 --save 前都是试运行。完整命令参考请见 te-cli 技能。
2. 当 te 无法访问某个属性时，使用 TOM 或模型 MCP。 某些属性不在 te set -p 支持范围内（例如 alternateOf、securityFilteringBehavior、crossFilteringBehavior、KPI 子对象、语言架构内容、日历对象）。可通过 te script C# 处理流程（进程内 TOM）进行操作，或使用 connect-pbid 技能（通过 PowerShell + TOM/ADOMD 连接到运行中的本地 Desktop 实例；也是访问跟踪的唯一途径：EVALUATEANDLOG、聚合命中事件、存储 DMV）。如果倾向于使用 MCP，也可以使用 Power BI Modeling MCP 服务。本地 Desktop 代理无法访问 Direct Lake；此时请使用远程 XMLA 终结点。
3. 最后使用 fab + 直接编辑 TMDL，并遵循 tmdl 技能。 用于没有模型编辑动词的服务端和文件结构操作：为角色分配 Entra 主体（在工作区端，而非 .tmdl 中）、绑定报表与模型、Copilot 文件夹功能（AI 指令、AI 数据架构、已验证答案）、重塑 Direct Lake 背后的 Lakehouse / Delta，以及与其执行 N 次 te 调用相比、通过一次 TMDL 差异更简洁的大规模结构调整。若要以只读方式从 Fabric 获取 AI 指令 / 架构，请使用 scripts/get_semantic_model_ai_metadata.py。使用 tmdl 技能编写 TMDL，然后运行 te validate。

顺序检查：添加任何使用 RELATED() 或跨表 CALCULATE() 的度量值之前，先添加关系；否则保存检查会因 DAX0002（上下文中没有关系）而失败。

DAX 中的对象引用和元数据

列引用写作 'Table'[Column]：表名始终存在，并且始终用单引号括起。度量值引用写作 [Measure]，绝不加表名前缀。这适用于 DAX 或模型元数据中命名对象的所有位置：度量值、计算列和计算项表达式、RLS 筛选器、格式字符串表达式、DAX 查询（te query、pbir model -q），以及提及对象的说明或注释。

原因：度量值属于模型，而非其所在表，因此在表之间移动度量值时，任何使用它的表达式都不应发生变化；单独的 [Measure] 也能让读者一眼看出这是度量值，而不是列。未限定表名的列一旦有两个表共享列名就会产生歧义，而为每个表名加引号，无论名称是否需要引号，都能保持格式一致。

生命周期

设计

采用维度建模：星型模型（事实表加一致性维度）优于雪花模型和事实表之间的联接。在构建前决定存储模式和刷新策略；发布后，两者几乎都是不可逆的选择。请参阅 references/dimensional-modeling.md、references/storage-modes.md、references/composite-models.md 和 references/direct-lake.md。

构建

按照上述级联流程进行每项更改。一次性为度量值编写完整元数据（DisplayFolder、FormatString、Description）。每次变更后都进行验证（te validate），并通过 BPA 门禁检查（te bpa run --fail-on error）。重命名或移动任何对象都可能悄然破坏下游报表和模型；先运行血缘检查，然后使用 pbir-cli / fabric-cli 传播更改（请参阅 references/refactoring-renaming.md）。各领域的详细指南：references/relationships.md、references/time-intelligence.md、references/calculation-groups.md、references/parameters.md、references/security.md、references/dax-authoring.md。

刷新

从终端配置增量刷新（te incremental-refresh）；对于 Direct Lake，刷新就是构建框架。请参阅 references/incremental-refresh.md，以及 refresh-semantic-model 技能中的监控和故障排除内容。

审查

根据以下类别进行审计，并提供按优先级排列且标明文件位置的发现。先使用 scripts/get_model_info.py 收集上下文（存储模式、大小、已连接报表、认可状态、数据源、刷新计划）。完整检查清单见 references/review-checklist.md；性能方法见 references/performance.md。

审查类别（按严重程度排列）

• 严重：双向关系歧义、循环依赖、缺少数据类型、孤立表、故障时默认放行的 RLS、会静默丢弃行的有限关系
• 内存和大小：高基数词典、自动属性层次结构（隐藏列或高基数列上的 isAvailableInMDX）、未拆分的 DateTime、自动日期/时间表、错误的数据类型、应改为度量值的计算列、未使用的对象
• 数据缩减：未筛选的事实历史数据（无增量刷新）、不必要的列、报表无需使用的明细粒度、适合上游处理的逻辑
• DAX 正确性：在 CALCULATE 中筛选表而非列、未防护的除法、不考虑上下文的计算列、变量时间偏移错误（references/dax-authoring.md；查询调优请使用 dax 技能）
• 度量值规范：隐式度量值、应放在模型中的报表范围度量值、含义模糊的重复项
• 文档和 AI：缺少说明（Copilot 会在 200 个字符后截断）、缺少显示文件夹、缺少同义词、命名不一致（使用 organize-semantic-model）
• 设计：违反星型模式、日期表标记错误、没有桥接表的多对多关系、无效的非活动关系
• Direct Lake：一侧键不唯一（查询在运行时失败）、回退到 DirectQuery、不同 Direct Lake 类型对计算列的支持情况、违反 Delta 防护限制

相关技能

• tmdl：TMDL 文件编写（级联流程的第 3 步备用方案）
• dax：DAX 查询性能优化
• connect-pbid：通过 PowerShell 使用 TOM / ADOMD 连接正在运行的 Desktop 实例；跟踪；TOM / MCP 层
• te-cli：te 命令参考
• c-sharp-scripting：TOM C# 脚本和宏（te script），用于操作 te 无法访问的属性
• organize-semantic-model：组织和命名整改
• refresh-semantic-model：刷新监控和故障排除
• lineage-analysis：项目沿袭分析（跨工作区使用此模型的下游报表和模型）；区别于模型内部对象依赖关系
• bpa-rules（tabular-editor）：编写 BPA 规则；fabric-cli：服务 / 工作区操作

参考索引

references/dimensional-modeling.md:    star schema, SCD2, junk / degenerate dimensions, header-detail, bridges
references/relationships.md:           cardinality, limited relationships, ambiguity, active / inactive, USERELATIONSHIP
references/time-intelligence.md:       classic vs calendar TI, mark-as-date traps, week-based / 4-4-5
references/calculation-groups.md:      precedence, sideways recursion, selection expressions, the variant trap
references/parameters.md:              field parameters, what-if parameters, dynamic titles
references/security.md:                RLS validation + defensive filters, bidirectional + RLS, OLS restrictions
references/query-semantic-model.md:    querying a model with DAX, INFO functions, output formats, probing
references/storage-modes.md:           Import / DirectQuery / Dual / Hybrid decision matrix
references/composite-models.md:        source groups, regular vs limited, Direct-Lake-plus-Import
references/aggregations.md:            user-defined aggregations, grain, te-script AlternateOf
references/direct-lake.md:             OneLake vs SQL, framing, DirectQuery fallback, guardrails
references/incremental-refresh.md:     IR policy, detect data changes, hybrid / real-time, refresh strategy
references/vertipaq-optimization.md:   VPA metrics, value vs hash encoding, splitting high-cardinality keys
references/dax-authoring.md:           variable semantics, DIVIDE, measure vs calc column (gaps vs the dax skill)
references/ai-copilot-readiness.md:    the Copilot grounding contract, synonyms / linguistic schema, descriptions, Q&A retirement
references/metadata-and-organization.md: descriptions, display folders, naming, measure tables, perspectives
references/hierarchies-cultures.md:    user hierarchies, parent-child, KPIs, perspectives, cultures / translations
references/documentation-and-bpa.md:    data dictionary, BPA documentation gate, metadata diffs, intra-model impact analysis (artifact lineage = the lineage-analysis skill)
references/refactoring-renaming.md:    safe rename workflow (lineage check first, then propagate via pbir-cli / fabric-cli)
references/review-checklist.md:        full audit checklist with remediation
references/performance.md:             performance testing, unused-column detection, memory analysis
scripts/get_model_info.py:             model metadata overview (mode, size, reports, endorsement, sources, refresh)
scripts/manage-ai-metadata.csx:        read/write AI instructions and AI schema through TOM culture linguistic metadata
scripts/get_semantic_model_ai_metadata.py: Fabric CLI service-definition readback for AI instructions and AI schema

本技能特意不涉及的内容

• GUI 工具的操作指南，以及旧版审查技能中“使用任何可用工具”的表述：现已由 te-cli 优先的级联流程取代
• 手动编写的问答措辞：问答功能正在淘汰，Copilot 不会读取这些措辞；应着重完善同义词和说明
• 被当作安全措施的透视和显示文件夹：任何有权访问模型的人都可以查询二者；请使用 RLS / OLS
• PBIT 格式：不在范围内