数据建模
此功能在专业版中支持。
背景介绍
在传统的数据分析平台中，数据建模始终是一项高门槛、强依赖人工经验的任务，往往需要数据工程师手动完成大量模型设计、维度配置、度量定义等操作，效率低下且容易出错。 为了提升建模效率、降低建模门槛，我们在 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: 结构化数据数组，可供上下游工具链使用
返回示例：
[
{
"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 初始版本。