> ## 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.

# 从语义建模到业务助理问数

> 以采购查价为例，完成组织助理初始化、语义模型发布、业务助理授权与使用验收。

本教程以“采购查价助手”为例，带你完成：**准备运行条件 → 用助理完善语义模型 → 发布模型 → 配置业务助理 → 用普通成员账号验证访问和查询**。

示例使用“采购”业务域、“采购用户组”和 `ProcurementPrices` 语义模型。名称和业务字段仅用于演示，请替换为实际值。操作涉及 Xpert 和 Data Xpert 两个界面；先确认两边选择的是同一组织。

本文说明完整流程。需要逐项配置时，可阅读下面两份配套教程：

* [初始化组织本体助理与建模助理](https://docs.xpertai.cn/zh-Hans/data/tutorial/semantic-analysis/initialize-organization-assistants.md)：工作空间、环境变量、MCP 工具集、模板和绑定检查。
* [配置并发布业务助理](https://docs.xpertai.cn/zh-Hans/data/tutorial/semantic-analysis/configure-business-assistant.md)：新建与编辑、用户组、模型资源、发布及普通成员验收。

## 1. 先分清要配置的对象

| 对象 | 解决的问题 | 本教程中的用法 |
| - | - | - |
| 租户本体运行时 | 准备平台连接凭据、系统任务模板及 Data Xpert AI Tools 插件 | 由平台管理员检查一次，供后续初始化使用 |
| 组织语义模型建模助理 | 在模型工作台中理解模型、查询结构、校验和修改草稿 | 建模人员用它完善采购模型 |
| 组织本体助理 | 查看本体实体、关系、Action 及其可用性 | 需要跨对象探索或受控操作时使用 |
| 业务助理 | 面向特定业务任务，组合指令、工具、使用人群和资源范围 | 采购人员通过它查价格 |
| 工作空间 | 存放和维护模型、助理、环境、工具等创作资源 | 决定谁能进入并维护这些配置 |
| 业务域 | 划分资源归属和数据访问范围 | 将采购模型和采购助手归入“采购”域 |
| 用户组 | 管理一组使用者 | 指定“采购用户组”可以使用助手 |
| 可访问资源 | 限定某个业务助理可调用的资源 | 只绑定采购模型，不自动绑定同域其他模型 |

**能使用助理、能编辑助理、能查询数据，是三种不同的权限。** 发布到某个工作空间不代表全组织都能使用；分享助理也不会自动授予它所涉及的全部数据权限。

只做采购价格查询时，不必先建成本体实体和关系，也不必为了业务助手单独初始化组织本体助理。若希望由 AI 协助建模，初始化组织语义模型建模助理即可；已有可用模型时可以直接进入业务助理配置。

## 2. 准备运行条件

### 2.1 检查租户本体运行时

由 `SUPER_ADMIN` 打开 Data Xpert 的 **系统管理 → 平台初始化 → 租户本体运行时**。

1. 选择现有的租户本体工作空间；没有合适空间时，先在本页创建。
2. 点击 **初始化本体运行时**，等待处理完成。
3. 分别检查运行凭据状态和 **Data Xpert AI Tools** 插件状态。
4. 如果提示“需要重启 Xpert”，由运维人员按部署方式重启 Xpert API 实例，再刷新状态，直到插件显示就绪。

运行凭据已保存，只说明凭据这一部分完成；插件仍处于不可用、待加载或需要重启状态时，初始化还没有全部完成。

这里的“运行时”负责 Data Xpert 与 Xpert 之间的服务连接及工具加载，不等于为每个人新建 Python 或 Shell 沙箱，也不授予业务数据访问权。业务助理还会检查自身所在工作空间的运行凭据；创建页面的准备状态若提示缺项，按提示进入对应工作空间补齐。

### 2.2 准备组织助理的共享工作空间

组织内置助理应放在**当前组织中、初始化人可写的组织共享工作空间**。

1. 在 Xpert 打开工作空间下拉菜单，创建或选择专用空间，例如“组织助理”。
2. 打开 **设置 → 通用 → 工作空间访问**。
3. 开启 **组织共享工作空间**，点击 **更新**。
4. 回到 Data Xpert 初始化向导，在目标工作空间中选择该空间。

也可以在初始化向导中点击 **初始化默认工作空间**。两种组织助理可以使用同一个组织共享空间。

> [!NOTE]
>
> 组织共享允许本组织成员查看和编辑该空间中的资源，已发布 Assistant 的使用授权仍单独检查。建议为组织助理使用专用共享空间；不要为了让采购员聊天，就把存有其他私有资源的业务工作空间改成组织共享。

### 2.3 初始化组织语义模型建模助理

仍由 `SUPER_ADMIN` 打开 **当前组织语义模型建模助理** 页签：

1. **选择工作空间**：选择上一步的组织共享空间，点击 **下一步**。
2. **创建环境**：确认环境名称，例如“语义模型 Workbench”。保留向导提供的变量定义；不要把管理员个人令牌填成所有人共用的固定值。
3. **导入 Xpert DSL**：开启 **启用助理绑定**，选择当前组织可用的协同模型，模板选择 **语义模型建模助理**。
4. 确认 Xpert 名称和发布说明，点击 **开始初始化**。
5. 等待成功提示，检查状态为“已配置”，当前工作空间与所选空间一致。

初始化会创建或更新助理并更新当前组织的绑定。若旧绑定使用的空间不在可选列表中，选择符合条件的共享空间重新初始化；仅切换下拉框不会使新绑定生效。

### 2.4 需要本体助理时再初始化

打开 **当前组织本体助理**，选择同一共享空间，依次完成 **创建环境 → 创建 MCP 工具集 → 导入 Xpert DSL**。使用本体助理模板，选择可用模型，开启绑定后开始初始化。

MCP 工具集负责连接 Data Xpert 的本体能力。沿用部署提供的连接参数；若缺少 MCP 地址，应由管理员修正服务配置后重试。

例如：在资源详情或本体工作台中询问“这张采购订单关联哪些供应商？”或“当前资源有哪些可用 Action？”时，使用组织本体助理。涉及执行动作时，还要满足该动作的权限、策略和审批条件。编辑本体定义草稿另有管理权限要求，能打开助理不代表能修改本体。

**本节完成标志：** 所需插件就绪、组织助理绑定启用，且模型工作台能够打开对应助理。无需每个成员重新初始化一套组织助理。

## 3. 配置业务域、用户组和人员权限

先确定“谁维护”和“谁使用”，再授权。

1. 在 Xpert 的 **设置 → 用户组** 中创建“采购用户组”，加入需要查价的成员。用户组是人员集合，不要求与公司部门一一对应。
2. 在 Data Xpert 的 **治理 → 业务域** 中选择“采购”域，在 **成员与权限** 中给该组授予消费者 `consumer`。没有目标域时，由具备业务域管理权限的人员创建。
3. 为建模人员授予模型所在工作空间的创作权限，以及采购域的发布者 `publisher`；管理本域授权的人员使用域管理员 `domain_admin`。
4. 检查成员的平台功能权限。业务域角色不会自动授予查询、建模等产品功能，也不会代替数据源绑定和凭据检查。

| 业务域角色 | 可以做什么 | 不会自动获得什么 |
| - | - | - |
| 消费者 `consumer` | 消费本域已发布资源 | 创作工作空间成员身份、模型编辑权 |
| 发布者 `publisher` | 消费资源，并在具备创作权限时发布 | 本域授权管理能力 |
| 域管理员 `domain_admin` | 管理本域授权，并具备本域发布能力 | 修改组织用户组、平台角色或业务域结构的权限 |

`BUSINESS_AREA_MANAGE` 是平台级业务域管理权限，不应作为“让采购员查价”的常规授权方式。业务域父子关系用于分类，父域授权不会自动继承给子域。个人授权、用户组授权和平台权限可能同时生效，撤销一条授权后还应检查其他来源。

> [!NOTE]
>
> 授予“采购域消费者”，意味着可以消费该域内符合条件的已发布资源，并不只限于本教程的一个模型。如果同域模型包含不同敏感级别的数据，应先合理拆分业务域。后面的助理资源列表只限制这个助理，不会收回用户通过其他入口已有的数据权限。

## 4. 完善并发布语义模型

### 4.1 准备可查询模型

在 Data Xpert 进入目标 **AI 工作空间 → 数据智能 → 语义模型**。没有现成模型时，先按[数据分析快速开始](https://docs.xpertai.cn/zh-Hans/data/analytics/quick-start.md)完成数据源绑定、模型创建、维度和度量配置。

本例需要一个可按物料或图号查价的模型。至少明确查询键、价格字段、币种、价格是否含税，以及同一物料出现多条价格时的筛选口径。不要把单价简单求和当作查价结果。

### 4.2 在模型工作台中使用建模助理

1. 打开 `ProcurementPrices`，等待草稿显示“已同步”。
2. 打开右侧助理面板，选中相关数据立方体、维度或度量。
3. 先检查结构，再要求修改。可输入：

> 请先检查当前模型的物料维度、价格度量和关联关系，列出影响查价的问题。先不要修改或发布。

确认方案后，再输入：

> 按刚才确认的方案修改当前模型草稿，说明改动的对象和校验结果。不要发布。

4. 检查变更内容和质量提示，等待草稿重新同步。
5. 运行模型校验，并用已知物料做查询核对。

工作台助理依据当前模型上下文工作；它不会因为自己放在共享空间，就获得其他用户所有模型的编辑权限。SQL 模型与 XMLA 模型的可编辑范围不同，远程 XMLA 技术绑定应通过元数据刷新和源系统配置处理。

### 4.3 发布到正确的业务域

将模型归属到“采购”业务域，校验通过后执行 **发布**，确认存在已发布版本。业务消费使用已发布模型；草稿修改需要再次发布才会成为新的消费版本。

在查询实验室验证一个已知结果。编辑区中的 `SELECT 1 AS value` 之类示例只用于演示，不代表系统已为你的业务模型生成了查询。可以手写、使用模板，或请助理协助生成适合当前模型的 SQL / MDX，再运行并核对结果。

**本节完成标志：** 模型已发布到采购域，已知物料的价格、币种和筛选条件与业务记录一致。

## 5. 创建采购查价业务助理

进入 Data Xpert 的 **AI 工作空间 → 目标工作空间 → 助理智能体**。这个空间用于维护业务助理，不必与组织建模助理所在的共享空间相同。

操作账号需要具备业务助理管理权限、目标工作空间的写权限，以及目标业务域的发布权限。

点击 **创建业务助理**，选择 **业务模板**。若修改现有助手，在列表中点击该行的 **… → 编辑**。本教程使用业务模板流程；“平台新建”和“绑定已有”是其他创建方式。

### 5.1 填写基本信息

| 字段 | 示例或操作 |
| - | - |
| 名称 | 采购查价助手 |
| 智能体编码 | `procurement_price_assistant`，与现有编码区分 |
| 业务范围 | 选择“团队” |
| 业务区域 | 选择模型所在的“采购”域 |
| 在菜单中显示 | 开启，让授权用户有菜单入口 |
| 描述 | 按物料查询采购价格，返回币种、含税口径和适用条件 |

“团队”决定助理的业务展示范围，不等于向全组织开放。实际使用人群在“资源与权限”中配置。关闭菜单显示也不等于撤销使用权限。

### 5.2 配置能力

1. 打开 **能力配置**。
2. 选择插件提供的 **Business assistant with data-xpert tools** 模板。
3. 选择当前工作空间中为该助理准备的可用环境。环境名称可能是 `Ontology Runtime`、“语义模型 Workbench”或自定义名称，以实际配置为准；名称本身不代表数据权限。
4. **MCP 实例**选择 **自动创建默认 MCP 工具集**，或选择管理员已准备的兼容实例。
5. 在可编辑的业务指令中明确查价范围和口径，例如：

> 使用已授权的采购模型按物料查价，返回价格、币种、含税口径和有效条件。匹配多条记录时先说明差异并让用户补充条件，不要合计单价。找不到授权数据时说明原因，不编造价格。

模板提供工具能力，业务指令定义如何回答，真正的数据访问仍由资源和调用者权限控制。

### 5.3 选择使用人群和资源

打开 **资源与权限**：

1. 在 **可访问用户组** 中选中“采购用户组”。确认按钮处于选中状态，不要把“列出了候选组”误认为已经授权。
2. 在 **可访问资源** 中勾选 `ProcurementPrices` 对应资源。部分列表显示 `datax-semantic-model-<模型 ID>`，应核对模型 ID 后选择。
3. 确认已选资源数量与计划一致，只勾选助手完成任务所需的资源。

业务助理与绑定的语义模型必须属于同一业务域。只选择业务域不会自动把该域所有模型绑定给助手。

选定用户组后，这类 Data Xpert 托管业务助理的使用人群会受到该组限制，成员仍需满足业务域和资源访问条件。不要留空用户组来表达“无人可用”；未指定组时可能按已有业务域或分享规则开放。

### 5.4 检查并发布

1. 点击 **保存草稿** 保存配置；草稿保存不等于发布。
2. 点击 **检查并发布**，查看准备状态、模板、扩展能力和资源检查结果。
3. 有失败项时先修复，再 **重新检查**。
4. 确认业务范围、资源数量和发布说明，点击发布按钮；修改已有助手时按钮为 **发布修改**。
5. 等待“业务助理和助理智能体已创建并发布”等成功提示，确认列表中发布状态为“已发布”、菜单状态为“已启用”。

## 6. 用普通成员账号验收

请使用测试账号和已知样例数据，分别验证“允许”和“拒绝”。管理员看到入口或助手回复一句“你好”，都不能证明普通成员已经具备正确的查询权限。

| 验证场景 | 预期结果 |
| - | - |
| 采购用户组成员，具备采购域消费和查询所需权限 | 能打开助手，查询已绑定的已发布模型 |
| 同组织成员不在任何已选用户组中 | 不应获得此助手的使用入口；复制助手直链也不能绕过组限制 |
| 在已选组中，但缺少所需业务域或数据访问条件 | 不能成功查询受限数据 |
| 用户可查模型 A 和 B，助手只绑定 A | 此助手只使用 A；用户其他入口已有的 B 权限不受影响 |
| 从所有已选组移除测试成员后重新发起请求 | 不能继续通过该组授权使用助手 |
| 用户可以聊天，但没有创作工作空间权限 | 不因此获得助理或模型的编辑权 |

授权成员从菜单打开“采购查价助手”，可先问：

> 请查询物料 123456 的采购价格，并说明币种、是否含税和适用条件。如果有多条记录，请先列出差异。

确认返回数据来自预期模型，并与已知业务记录一致。若只返回能力介绍，继续执行一次真实查询再判定成功。用户组、模型归属或资源列表调整后，应重新验证相关场景。

## 7. 常见问题

| 现象 | 处理方式 |
| - | - |
| 初始化提示 `Access denied to workspace` | 核对当前组织、空间是否归属该组织、是否未归档、初始化人是否可写；组织内置助理还要求组织共享空间 |
| 凭据已初始化，插件仍不可用 | 按插件卡片检查安装和运行加载状态；若提示 API 地址错误，使用 Xpert API 服务可访问的 Data Xpert API 地址配置，再重试 |
| 插件提示需要重启 | 由运维人员重启 Xpert API 实例，刷新至插件就绪；无需让每个用户重新初始化 |
| 模型助理提示缺少 `ChatKit client secret` | 先确认当前组织助理绑定已启用、工作空间可用；再检查聊天会话创建请求的具体错误，不要让用户填写管理员密钥 |
| 看不到业务助理 | 核对组织、已发布状态、菜单开关、已选用户组成员资格和业务域访问 |
| 能聊天但查询失败 | 检查绑定资源、模型发布版本、模型与助手业务域是否一致，以及调用者查询权限、数据源绑定和连接状态 |
| 退组后仍能查采购数据 | 区分“还能用此助手”和“能从其他入口查数据”；检查其他组、个人授权和平台管理权限 |
| 更新后仍使用旧配置 | 确认已经发布修改；组织助理还需检查当前绑定。不要只凭镜像更新或草稿保存判断配置生效 |

完成后，继续阅读[语义模型工作台](https://docs.xpertai.cn/zh-Hans/data/analytics/semantic-model/semantic-modeling-workspace.md)、[语义模型助手](https://docs.xpertai.cn/zh-Hans/data/analytics/semantic-model/ai-assistant.md)、[查询实验室](https://docs.xpertai.cn/zh-Hans/data/analytics/semantic-model/query-lab.md)或[本体工作室](https://docs.xpertai.cn/zh-Hans/data/ontology/ontology-studio.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.