> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据建模

<Tip>
  **PRO**

  此功能在**专业版**中支持。
</Tip>

## 背景介绍

在传统的数据分析平台中，数据建模始终是一项高门槛、强依赖人工经验的任务，往往需要数据工程师手动完成大量模型设计、维度配置、度量定义等操作，效率低下且容易出错。
为了提升建模效率、降低建模门槛，我们在 **XpertAI 智能体平台** 上打造了一套 **语义数据建模工具集（Semantic Model Tools）**，旨在通过智能体协助用户完成多维数据模型的构建与维护。

本工具集已与 **XpertAI 数据分析平台** 无缝集成，可与 ChatBI、智能问答、指标管理等模块协同使用，实现从模型构建、调试、预览到智能分析的一站式体验。

#### 🌟 功能价值

* ✅ **智能辅助建模**：结合大模型能力，用户只需描述业务场景，智能体即可推荐并生成初始建模结构（如维度、指标、层级关系等）
* ✅ **自助建模门户**：通过可视化或语义化操作构建 Cube，无需深度 SQL 能力即可定义分析模型
* ✅ **建模与分析联动**：支持即时预览模型结果，快速验证建模配置的正确性
* ✅ **降本增效**：减少 70% 以上重复建模工作量，让更多分析师具备“轻建模”能力
* ✅ **统一建模接口**：各工具功能模块化、服务化，可对接外部系统或编排工作流

#### 📌 应用场景

* 智能问答系统中，自动根据提问构建或修正数据模型（如补充缺失维度、添加计算指标）
* 新业务指标上线时，通过 ChatBI 自动创建多维分析模型
* 分析师通过自然语言描述业务逻辑，由智能体生成并部署模型
* 数据治理场景下，辅助维护模型的一致性、可追溯性

## 工具概览

### 1. 切换工作空间 switch\_model\_workspace

该工具用于在智能建模流程中**切换到指定的语义模型工作区**，或**新建一个工作区并初始化其状态**。这是建模流程的第一步，确保后续的表、Cube、维度等操作都在正确的模型上下文中进行。

它将调用后端服务初始化或加载模型工作区，并将模型当前状态同步至上下文，供后续操作引用。

通常在以下情况下使用：

* 开启新的建模任务时，创建一个全新的模型工作区；
* 切换到已有模型进行调整或扩展；
* 通过智能体提示用户指定模型或创建新模型。

### 2. 列出物理表 list\_tables

该工具用于**列出当前语义模型关联的数据源中的所有物理表（Tables）**。它适用于建模初期，帮助用户了解当前数据源中的可用表结构，并作为后续建模（如选择表建 Cube、定义维度等）的基础。

工具会根据语义模型中的 `modelId` 和 `catalog/schema` 信息，查询底层数据源（如数据库、数据湖）并返回表清单。

### 3. 列出数据表的字段结构 list\_table\_schema

该工具用于**查看指定数据表的字段（列）结构**，包括字段名、数据类型等信息，帮助用户了解表结构以进行建模（如建维度、度量）。

#### 🧾 输入参数

| 参数名         | 类型       | 说明       |
| ----------- | -------- | -------- |
| `tableName` | `string` | 要查看结构的表名 |

#### 📤 输出结果

返回所选表的字段结构信息（字段名、类型、注释等），包括：

* 可读的 JSON 格式内容（供智能体呈现）
* 原始结构数据（供 UI 使用）

### 4. 列出立方体 list\_cubes

该工具用于**列出语义模型工作区中所有定义的 Cube（立方体）**，帮助大语言模型了解当前建模上下文中的核心分析单元，以便后续调用其他建模相关工具（如读取 Cube、编辑维度、度量等）。

工具会从模型草稿（`draft.schema.cubes`）中提取所有已定义的立方体，返回它们的 `name`、`caption` 与 `description`。

#### 🧾 输入参数

| 参数名       | 类型       | 说明                                     |
| --------- | -------- | -------------------------------------- |
| `modelId` | `string` | 可选，指定要读取的语义模型工作区 ID。如果不传，将从上下文中提取当前模型。 |

#### 📤 输出结果

该工具返回两个部分（供语言模型使用）：

* `content`: 格式化 JSON 字符串，包含所有 Cube 的基本信息
* `artifact`: 结构化数据数组，可供上下游工具链使用

返回示例：

```json theme={null}
[
  {
    "name": "Sales",
    "caption": "Sales Cube",
    "description": "Cube for sales analysis"
  },
  {
    "name": "Inventory",
    "caption": "Inventory Cube",
    "description": "Cube for stock tracking"
  }
]
```

### 5. 读取立方体 read\_cube

该工具用于**读取指定名称的 Cube 定义**，包括其维度、度量、层级等建模结构，帮助大语言模型深入理解当前语义模型中的某个分析主题。

工具在当前工作区的模型草稿中查找目标 Cube，返回完整结构信息，并触发一个用于仪表盘展示的 Cube 消息事件。

#### 🧾 输入参数

| 参数名         | 类型       | 说明           |
| ----------- | -------- | ------------ |
| `cube_name` | `string` | 要读取的 Cube 名称 |

#### 📤 输出结果

结构化返回目标 Cube 的完整定义（JSON 字符串 + 原始对象），供模型进一步推理建模意图或推荐编辑操作。

### 6. 编辑共享维度 edit\_dimension

该工具用于**在语义模型中创建或更新一个共享维度（Shared Dimension）**。当维度名称相同时，将对其进行更新；否则视为新建。

它支持大模型在建模过程中，通过结构化参数定义维度的属性（如名称、类型、描述、层级等），并自动校验维度定义的完整性和正确性，确保其可以安全纳入模型草稿中。

操作完成后会更新当前模型草稿，并生成可用于 UI 展示的维度跳转链接。

#### ✅ 功能特性

* 自动校验维度结构合法性（如缺失属性、冲突层级等）
* 可更新已有维度（通过名称匹配）
* 可视化链接用于跳转至维度管理界面

### 7. 编辑层次结构 edit\_hierarchy

用于在指定共享维度下**创建或更新层级结构**，通过名称判断是新增还是修改。工具自动校验层级定义的合法性，确保语义模型一致性。

完成操作后更新模型状态，并生成可跳转到层级详情的链接及提示信息。

### 输入参数

* `dimension_name`：所属维度名称
* `hierarchy`：层级对象定义

### 8. 编辑立方体 edit\_cube

用于在语义模型中创建或更新一个立方体，通过名称判断是新增还是修改。工具会校验立方体的合法性，确保模型结构正确。

完成后会重置立方体的向量嵌入，并触发更新事件，刷新模型状态并返回操作成功提示。

#### 输入参数

* 立方体完整定义（符合 `CubeSchema` 结构）

### 9. 编辑度量 edit\_measure

`EDIT_MEASURE` 工具用于在指定的立方体（cube）中创建或更新一个度量（measure）。

它会先加载当前语义模型草稿，插入或更新度量定义，然后进行校验，确保度量配置合法。

操作完成后，会触发事件通知，并返回更新后的模型状态和成功消息。

**输入参数**：

* `cube_name`：目标立方体名称
* `measure`：度量详细信息

**功能**：管理立方体内的度量定义，实现灵活的度量维护。

### 10. 编辑计算成员 edit\_calculated\_member

`EDIT_CALCULATED_MEMBER` 工具用于在指定立方体（cube）中批量创建或更新计算成员（Calculated Members），即基于公式和查询定义的动态度量。

主要流程包括：

* 逐个处理输入的计算成员，修正公式，验证公式有效性；
* 通过执行测试查询确认计算成员的正确性；
* 将计算成员写入语义模型草稿并校验合法性；
* 最终更新模型状态并发送操作成功的消息通知。

**输入参数**：

* `cube_name`：目标立方体名称
* `calculated_members`：计算成员数组，每个成员包含名称、公式、验证用的查询等信息

**功能**：方便用户灵活定义和维护基于公式的计算度量，提升模型的表达能力和分析深度。

### 11. 编辑计算度量 edit\_calculation

`EDIT_CALCULATION` 工具用于创建或编辑指定立方体（cube）中的计算属性（Calculation）。

核心功能：

* 在语义模型中新增或更新某个立方体的计算定义；
* 对计算属性进行校验，确保其符合规范且合法；
* 更新模型状态并发送操作成功的消息通知。

输入参数包括：

* `cube_name`：目标立方体名称
* `calculation`：包含计算属性详细信息的对象

该工具便于管理立方体中的计算逻辑，支持灵活定义复杂的业务计算，提升数据模型的分析能力和扩展性。

### 12. 编辑参数 edit\_parameter

`EDIT_PARAMETER` 工具用于创建或编辑指定立方体（cube）中的参数（Parameter）。

* 支持批量新增或更新立方体内的多个参数；
* 对每个参数进行严格校验，确保参数定义规范且有效；
* 在模型草稿中更新参数定义，并同步最新模型状态；
* 发送操作成功的消息通知，方便前端展示和跟踪。

#### 输入参数：

* `cube_name`：目标立方体名称；
* `parameters`：参数数组，每个参数符合基础参数结构（BaseParameterSchema），包含名称、类型、默认值、描述等信息。

适用于在语义模型中动态调整或扩展立方体的参数配置，从而满足不同分析场景的灵活计算和过滤需求。

该工具为数据建模提供了便捷的参数管理接口，增强了模型的灵活性和可维护性。

### 13. 编辑虚拟立方体 edit\_virtual\_cube

`EDIT_VIRTUAL_CUBE` 工具用于创建或编辑一个虚拟立方体（Virtual Cube），通过在语义模型中增删改虚拟立方体定义，实现对多维数据模型的灵活扩展和管理。

* **创建或更新虚拟立方体**：支持向模型中添加新的虚拟立方体，或根据名称编辑已存在的虚拟立方体；
* **自动校验虚拟立方体定义**：通过 `VirtualCubeValidator` 对虚拟立方体进行完整性和规范性检查，保证模型数据质量；
* **同步更新模型状态**：修改完成后，自动更新最新的语义模型状态，并广播操作消息供前端展示；
* **重置虚拟立方体的Embedding缓存**，确保数据的一致性和新定义生效；
* **等待数据源确认虚拟立方体存在**，保证数据查询的有效性和稳定性。

#### 输入参数：

* `VirtualCube` 对象，包含虚拟立方体的名称、维度、度量、来源等详细定义，结构符合 `VirtualCubeSchema`。

适合需要基于已有物理立方体组合构建新的虚拟分析视图的场景，比如数据集市、报表定制、多源融合分析等，提升模型复用和扩展能力。

### 14. 维度成员检索器 model\_dimension\_member\_retriever

`DIMENSION_MEMBER_RETRIEVER` 工具用于在指定的多维数据模型中，查询维度成员（dimension member）的关键信息，支持通过维度、层级和级别等过滤条件精确检索，用于数据过滤和分析时提供基础维度数据支持。

#### 主要功能：

* **检索指定模型和立方体（cube）中的维度成员信息**，根据成员名称或通配符`*`进行查询；
* 支持按**维度（dimension）**、\*\*层级（hierarchy）**和**级别（level）\*\*筛选，自动验证属性是否存在于模型中，保证查询合法性；
* **动态触发维度成员的Embedding操作**，如当前模型中未缓存对应embedding，或强制重新embedding，保证检索数据准确完整；
* 调用后台维度成员服务（DimensionMemberService）进行数据拉取，并将结果格式化为字符串输出，方便展示和后续使用。

#### 输入参数：

* `modelId`：数据模型ID，指定在哪个语义模型中查找；
* `cube`：立方体名称，指定数据集合范围；
* `member`：需要检索的成员名称，支持精确或通配符`*`；
* `dimension`（可选）：维度名称，格式如`[dimensionName]`，用于限定查询范围；
* `hierarchy`（可选）：层级名称，格式如`[hierarchyName]`，支持细粒度过滤；
* `level`（可选）：级别名称，格式如`[hierarchyName].[levelName]`，进一步定位层次；
* `topK`（可选）：限制返回的最大条数；
* `re_embedding`（可选，默认false）：是否强制重新生成embedding，更新维度成员的向量表示。

#### 使用场景：

* 需要根据维度成员进行数据过滤、条件筛选的报表和分析场景；
* 多维模型动态查询维度成员，支持交互式下钻和数据探索；
* 保证维度成员信息与模型一致，自动维护embedding，提高查询准确度。

### 15. 获取立方体运行时上下文 get\_cube\_runtime\_context

`GET_CUBE_RUNTIME_CONTEXT` 工具用于获取指定立方体（cube）的运行时上下文信息，主要包括该立方体的维度、度量、层级等结构化数据。

### 16. 预览立方体 preview\_cube

`PREVIEW_CUBE` 工具用于预览指定立方体（cube）的数据内容，帮助用户快速验证立方体的结构和数据是否符合预期。

## 版本控制与更新日志（Changelog）

* v3.4 初始版本。