使用命令行工具管理语义模型的 AI 代理

Published: | Updated:
Picture of Kurt Buhler
创新负责人

Kurt Buhler 是 Tabular Editor 的 Head of Innovation，他在该职位上研究并传播语义模型和 BI 的未来发展——从技术最佳实践到智能代理式开发。Kurt 强调以用户为中心，帮助数据专业人士在纷繁复杂的信息中抓住重点，构建稳健且真正有价值的解决方案。

此内容由人工智能翻译，尚未经过人工编辑审核。图像和图表保持其原始语言。

关键要点

  • 本文为系列文章之一。 从第一部分开始，请点击这里。
  • AI 代理可以编写代码并使用命令行工具管理语义模型。 Tabular Editor 2 CLI 让代理能够修改和查询模型，并运行 Best Practice Analyzer，即最佳实践分析器。 Fabric CLI 让代理可以直接使用任何 Fabric API。
  • 编程接口的灵活性最高，适合脚本化、可确定的结果。 用这种方式，只要能用代码描述的事情，你都能做到。 一旦你有了可用的脚本或命令，就可以把它加入示例 repository 中，或把它转换成宏，方便在后续场景中复用。 这不仅有助于获得可确定的结果；同时，代理也会因为有这些示例可随时参考而持续改进并扩展能力。
  • 不过，这种方式复杂且成本高。 你需要投入大量精力来编写高质量的指令，并收集示例脚本，才能起步。 否则，代理会经常产生幻觉，浪费大量时间。 另外，脚本会消耗大量 token，而且在探索或检索模型方面通常不如其他方法高效。
  • 针对本地元数据文件使用 CLI，或针对启用 Git 集成的远程模型使用 CLI。 这样你就能跟踪并管理变更，并在代理出错时回滚。 我们建议将代理式开发隔离到独立于人工开发的 Workspace 中，因为它还不够成熟，而且错误很常见。

本摘要由作者撰写，并非由 AI 生成。

使用命令行工具修改语义模型

本系列将介绍使用 代理 让 AI 促进语义模型变更的不同方法。 语义模型代理有一些工具，让它能读取、查询，并把更改写回语义模型。 以这种方式使用代理称为 agentic development，在某些场景下，它可以作为传统开发工具和工作流的有效补充。

AI 可以通过多种方式对语义模型进行更改，包括修改元数据文件、使用 MCP 服务器，或编写代码。 每种方式各有利弊。如果你要用 AI 来更改语义模型，那么很可能三种都会用到。

K031 Figure 1 - AI-generated content may be incorrect

本文介绍如何使用 Tabular Editor 2 命令行界面 (CLI) 执行 C# Script，也就是 C# 脚本，来更改语义模型，以及如何使用 Fabric CLI 来管理它。

什么是命令行工具？

我们在 上一篇文章 中简要介绍过命令行工具。 简而言之，这些工具让你通过在终端中编写并执行命令，以另一种方式与软件交互。 这种命令行界面是图形用户界面 (GUI) 的替代方案，并且非常适合代理。

本文将讨论两种命令行工具——当然，Power BI 或 Fabric 还可以配合使用更多工具：

  • Tabular Editor 2 CLI，用于辅助开发和管理语义模型。 它随 Tabular Editor 2 一起提供；如果你有 TE2，就有它的 CLI。
  • Fabric CLI，用于在命令行中从 Fabric 获取信息或在 Fabric 中执行操作。 你需要用 Python 安装 ms-fabric-cli 组件。

下面是一个代理（Claude Code）使用 Tabular Editor 2 CLI 修改在 Power BI Desktop 中打开的语义模型的示例：

K031 Figure 2 - An example of a coding agent, Claude Code, making changes to a semantic model via C# scripts

这个示例来自本系列的第一篇文章，展示了编码代理如何处理在 Power BI Desktop 中打开的本地模型。 它重构了一个中等规模的模型，以使用某个 DAX 函数（错误语法源于 Power BI 的一个问题）。 后面我们还会展示更多示例，但先弄清楚这里发生了什么。

MCP 服务器与 CLI 工具有什么不同？

你可能会把“代理使用 MCP 服务器”和“代理使用 CLI 工具”这两种方式搞混。 例如，在语义模型的场景中，两者都可以通过 TOM 库以编程方式与语义模型交互。 不过，它们实现这一点的方式不同。 以下是主要功能差异：

  • MCP 服务器会提供信息（工具名称、描述、资源），并将其预先加载到上下文中。 CLI 工具则不会；智能体只能依靠其训练数据，或其他自定义提示词和指令文件，才知道要使用它们。
  • MCP 服务器通常会让 AI 使用工具去执行固定的代码模式。 当 AI 调用某个工具时，它无法修改或扩展这次工具调用。 相比之下，使用 CLI 工具的智能体通常更灵活。 它们可以把命令与其他命令组合起来(例如 Bash 中的“管道” pipe)。 这让智能体可以扩展或修改 CLI 的结果，或者更高效地生成输出。 我们稍后会举例说明。
  • MCP 服务器是一种用于扩展 LLM 能力的特定方案。 CLI 工具和其他软件一样设计出来，既可供智能体使用，也可供人类使用。 通过提供更清晰、更具描述性的输出与命令，CLI 工具也可以变得更适合智能体使用。

稍后我们还会通过更多示例帮助你进一步理解这一点。

场景示意图

下图简要展示了如何借助命令行工具，促进语义模型的智能体式开发：

K031 Figure 3 - The diagram depicts a flow for how you can use command line tools with a coding agent to facilitate development of a semantic model. The two command line tools you use are the Tabular Editor 2 CLI and the Fabric CLI

这种方式与你使用 MCP 服务器时非常相似。 下面是具体流程：

  1. 用户整理上下文，尤其是关于智能体应如何使用命令行工具的说明，以及命令和 C# Script 示例。 这一点非常重要。
  2. 用户为编码智能体提供指令和提示词，让其开始工作。
  3. 编码智能体可以处理 Power BI Desktop 中的本地模型、本地模型元数据，或通过 XMLA endpoint 在 PPU 或 Fabric Workspace 中操作远程模型。 它通过 TE2 CLI 进行更改，并通过 Fabric CLI 在 Fabric 中执行操作。
  4. 用户在 Power BI Desktop 或 Tabular Editor 中验证更改。
  5. 最好确保已经配置了源代码管理，这样需要时就能跟踪、管理并回滚更改。 使用本地元数据文件时最容易做到这一点，但在 Power BI Desktop 或远程模型上操作时也同样可行。

演示：实际效果是什么样的

这种方式最适合与“驻留在命令行里”的智能体配合使用，例如 GitHub Copilot CLI、Claude Code 或 Gemini CLI。 我们会用 Claude Code 来展示示例，因为我们主要使用它来测试这套方法。

Claude Code 示例

下面是一些智能体使用 Tabular Editor 2 CLI 的例子。

首先是一个简单示例：整理日期表，将列放入显示文件夹，并正确设置它们的 SortByColumn 属性。

当然，这还只是你能做的事情的一小部分。 例如，这个示例展示了智能体为模型配置增量刷新：

K031 Figure 4 - AI-generated content may be incorrect

即使是人类，在界面里配置增量刷新也很麻烦。 让智能体来做，可能会更省事、更快，同时也让这个多步骤流程更清晰。 当你遇到自定义混合表格或自定义分区等复杂场景时，这一点尤其明显。 不过，这对智能体来说也可能很复杂。 在我们的测试中，智能体一旦看到与增量刷新相关的示例或上下文，往往就会搞混，导致表现变差，并且常常会实施会把模型“弄坏”的刷新策略：

实际上，更快、更便宜也更可靠的做法通常是：让智能体用 TE2 CLI 在沙盒里测试脚本，然后给你一个可复用的宏，供你在 TE2 或 TE3 GUI 中使用。 下面你可以看到：用增量刷新宏在更短的时间内跑完同样的流程；对你来说也更容易理解并照着操作：

提示

我们想再次强调这一点：仅仅因为你能用智能体做某件事，并不代表你就应该这么做。 你并不一定能省时间，甚至也不一定能更方便地得到好结果。 在可行的情况下优先选择确定性的方法，并寻找让 AI 帮你把可重复的模式脚本化的方式，这样结果会更可靠。

如何开始

这种方式最灵活，但配置起来也最复杂。 要使用这种方式，你需要安装 Tabular Editor 2 和 Fabric CLI，以及它们各自的前置条件。 你需要的完整清单如下：

  • Tabular Editor 2 和 Fabric CLI，以及它们的依赖项。
  • 你的模型可以是以下三种格式之一：
    • 在 Power BI Desktop 中打开。
    • 以 PBIP 格式保存，或其定义保存在 model.bim、TMDL 或 database.json 中。
    • 发布到采用 PPU 或 Fabric capacity 许可模式的工作区中。
  • 一个具备 Bash 或 Powershell 工具、可以执行命令的编码智能体。
  • Tabular Editor 2 (包括 C# 脚本) 和 Fabric CLI (包括你想使用的命令和 API 端点) 的上下文文件与示例。
  • 最好也有办法来跟踪并管理对模型的更改。

与其他方式的差异

与其他方法相比，这种方式有几个关键不同之处。 在某些方面，它和 MCP 服务器很相似，因为它让你可以以编程方式与语义模型交互。 但不同之处在于，这里的代码是任意的，由 LLM 编写并执行，或作为脚本编写并执行，而不是预先定义在一份固定的工具清单中。 这个 agent 是否能“用好”CLI，完全取决于你提供的指令和示例——尤其是当 CLI 在训练数据中出现得不多时（例如较新的工具）。

优势

这种方式的关键优势如下：

  • 灵活性：采用这种方式，agent 几乎不受限制，只要能用代码表达，它就能进行任何改动。 这会带来更多可能性，即使是非常小众、不常见的场景也能覆盖。 不过要注意，它并不会“开箱即用”地知道怎么做，仍然需要依赖你的指令和示例……而且这种灵活性也会带来一定风险（见下方挑战）。
  • 可扩展性：最有意思的一点是，随着时间推移，你可以不断改进并扩展 agent 的能力。 Agent 产出的脚本越多，未来可作为示例引用的素材就越多。 你甚至可以让 agent 把 C# Script 转换成宏，然后将其添加到 Tabular Editor 用户界面中使用（TE2 和 TE3）。
  • 变更安全性：和 MCP 服务器一样，你不太容易因为变更而“弄坏”模型，因为不允许的变更会触发错误并拒绝写入操作。 这些错误也能为 LLM 提供反馈，帮助它改进刚写出的脚本。
  • 适合搜索大型复杂模型：能访问这些 CLI 工具的编码型 agent，可以更轻松地定位语义模型中的某些对象或属性，而无需读取整个文件或完整定义。 长期来看，这样能显著减少 token 消耗。

挑战

这种方式也有一些独特的挑战：

  • 缺少上下文时可靠性更低：你会发现，这种方式在一开始最“别扭”，错误和问题也最多。 但随着你不断补充上下文和示例，结果会明显变好。 来自他人的上下文，以及未来对 CLI 的改进，让它更“agent 友好”，在这里也可能会有所帮助。 但也要注意：如果示例质量差，或对某些模式过度强调，上下文反而可能带来 更差 的结果。
  • 配置复杂：这种方式需要更多时间和精力来搭建。 你需要包含一些如何使用 CLI 的示例和有用命令，否则它可能会胡编乱造。
  • 难以回滚变更：这一点和 MCP 服务器方式的注意事项相同。 你无法轻松查看或撤销变更。 因此，我们建议你在已配置 Git 集成的隔离 Workspace 中，对模型元数据或远程模型使用 CLI 工具。
  • 安全风险：允许 agent 编写并执行任意代码，可能会带来问题。 例如，当它在编写 C# Script 时，理论上可以利用这些脚本调用外部 API，或修改本地文件与系统。 为避免这种情况，你需要严格管理 agent 的权限，并只允许它在充分的人类监督下运行。

什么时候适合用这种方式

这种方式主要适用于两类场景：

  • 当你需要灵活性时：一个典型例子是，你想实现某个具体但复杂的变更，例如增量刷新。
  • 当你希望以确定性结果运行脚本和宏时：例如，为模型添加日期表或参数表，或引入常见的 DAX 模式。 这就是 C# Script 脚本和宏在 Tabular Editor GUI 中同样有帮助的地方。

何时可能不使用这种方法

在以下几种情况下，这种方法并不理想：

  • 有更简单的选项： 保持简单。 如果你可以通过可靠的 MCP 服务器工具，或直接修改模型元数据来完成任务，那就优先选那种方式。
  • 你不喜欢复杂度或命令行：如果你觉得这种方式的配置太折腾、不够舒适，或者你不喜欢使用命令行，那它可能不适合你。
  • 你在 Mac 或 Linux 上（仅 TE2 CLI）：目前，Tabular Editor CLI 只支持 Windows。 不过，Fabric CLI 在 Mac 或 Linux 上与 agent 的配合效果非常好。 这意味着，在 Linux 或 Mac 机器上对语义模型进行任何 agent 式开发，都将被限制为只能修改元数据文件。

总之，这种方式给你最大的灵活性，但代价是：要把它调教到符合你预期的工作方式，需要更高的复杂度。 当你有其他方式无法满足的特定需求，并且愿意深入研究把它落地时，这种方式往往最合适。 尤其是考虑到 agent 脚本可以保存并复用，从而让它的能力随时间不断扩展和改进。

结论

如果你能把指令写清楚，agent 就可以通过 C# Script 使用 Tabular Editor 2 CLI 来修改模型，并通过 Fabric CLI 管理模型。 采用这种方式，agent 几乎可以对语义模型执行任何变更或操作。 它尤其适合那些结果可预测、可重复的变更和模式——就像 Tabular Editor GUI 里的脚本和宏一样有用。 不过，除非你给它清晰的指令和高质量的示例，否则它做不到这一点。

到这里，我们关于语义模型的 Agentic 开发现状的系列文章就告一段落了。 这三种方法——基于元数据的代理、MCP 服务器或 CLI 工具——各有优缺点，但可以相互补充。 这些方法都是增强传统开发工作流的一种实用且有意思的方式。随着技术走向成熟，它们很可能会持续改进。

Related articles