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

# 初始化组织本体助理与建模助理

> 准备组织共享工作空间，分别初始化本体助理和语义模型建模助理，并检查绑定和实际使用结果。

本教程面向平台管理员。完成后，当前组织会拥有可复用的本体助理和语义模型建模助理，成员无需各自重复初始化。

操作分为：**检查租户运行时 → 准备组织共享空间 → 初始化所需助理 → 核对绑定 → 用普通成员验证**。如果只需要 AI 协助建模，可直接完成建模助理部分；本体助理按需初始化。

| 助理 | 何时使用 | 向导步骤 |
| - | - | - |
| 组织本体助理 | 探索本体实体、关系、可用动作及其策略，例如查询采购订单关联的供应商 | 选择工作空间 → 创建环境 → 创建 MCP 工具集 → 导入 Xpert DSL |
| 组织语义模型建模助理 | 在语义模型工作台中查看结构、校验模型和修改草稿 | 选择工作空间 → 创建环境 → 导入 Xpert DSL |

业务助理的使用人群和资源配置另见[配置并发布业务助理](https://docs.xpertai.cn/zh-Hans/data/tutorial/semantic-analysis/configure-business-assistant.md)。完整的建模到问数流程见[从语义建模到业务助理问数](https://docs.xpertai.cn/zh-Hans/data/tutorial/semantic-analysis/modeling-to-business-assistant.md)。

## 1. 检查初始化条件

1. 使用 `SUPER_ADMIN` 登录，确认 Xpert 与 Data Xpert 当前选择的是同一组织。
2. 打开 Data Xpert 的 **系统管理 → 平台初始化 → 租户本体运行时**。
3. 确认运行凭据已初始化，且 **Data Xpert AI Tools** 插件就绪。
4. 确认当前组织已有可用的协同模型，稍后将在导入模板时选择。

租户本体运行时负责服务连接凭据及工具加载。它不是每个用户的独立沙箱，也不会授予业务数据权限。运行凭据与插件有各自的状态；凭据保存成功、插件仍待加载时，还不能继续视为全部就绪。

首次部署时，在运行时页选择或创建租户本体工作空间，点击 **初始化本体运行时**。如果插件提示“需要重启 Xpert”，由运维人员按部署流程重启 Xpert API 实例，再刷新状态。已就绪的环境无需因新增成员而重复初始化。

## 2. 准备组织共享工作空间

在 Xpert 中操作：

1. 打开工作空间名称旁的下拉菜单，创建或选择专用空间，例如“组织助理”。
2. 从同一下拉菜单进入 **设置 → 通用**。
3. 在 **工作空间访问** 中开启 **组织共享工作空间**。
4. 点击 **更新**，确认状态显示“组织共享”。

回到 Data Xpert 初始化页。可选空间必须属于当前组织、未归档、对初始化人可写，并且已启用组织共享。没有合适空间时，也可使用向导中的 **初始化默认工作空间**。两种组织助理可以共用一个空间。

> [!NOTE]
>
> 组织共享允许本组织成员查看和编辑空间资源；已发布 Assistant 的使用授权仍单独检查。请使用专用空间，不要为开放组织助理而共享存放私有业务配置的空间。助理能访问哪些模型和数据，仍取决于调用者对相应资源的权限。

如果页面提示“原绑定的空间不在可选列表中”，选择符合条件的新空间并完成整个初始化向导。仅修改下拉框不会更新生效绑定。

## 3. 初始化组织本体助理

打开 **系统管理 → 平台初始化 → 当前组织本体助理**。

### 3.1 选择工作空间

在 **目标工作空间** 中选择“组织助理”，点击 **下一步**。先核对左上角组织；工作空间、协同模型、助理及绑定必须属于同一组织。

### 3.2 创建环境

环境名称可使用“本体运行环境”或 `Ontology Runtime`。保留向导提供的环境变量定义：

```json theme={null}
[
  { "name": "oidc_token", "type": "secret", "value": "" },
  { "name": "business_assistant_id", "type": "secret", "value": "" }
]
```

这两个字段用于运行时传递调用身份和业务助理上下文。初始化时保持默认空值，不要填入管理员个人令牌供所有成员共用。密钥字段重新打开时可能不回显；不要仅凭界面空白判断实际请求是否带有身份。

确认环境名称和 JSON 后，点击 **下一步**。

### 3.3 创建 MCP 工具集

MCP 工具集用于连接 Data Xpert 的本体能力。

| 字段 | 填写方式 |
| - | - |
| 工具集名称 | 例如“本体 MCP 工具集”或 `Ontology MCP Toolset` |
| MCP 传输方式 | 使用部署提供的默认值；本例为 HTTP |
| 工具集描述 | 可选，说明该工具集的用途 |
| 工具名前缀 | 可选，按部署约定填写，例如 `ontology` |
| MCP 请求头 JSON | 保留下面的环境变量引用 |

```json theme={null}
{
  "x-uose-actor-token": "{{env.oidc_token}}",
  "x-business-assistant-id": "{{env.business_assistant_id}}"
}
```

双花括号内容是变量引用，不是要替换成固定密钥的示例。连接地址由部署配置提供；缺少地址或无法连接时，先让管理员检查服务地址和网络可达性。确认后点击 **下一步**。

### 3.4 导入并发布助理

在 **导入 Xpert DSL** 中完成以下配置：

| 字段 | 配置 |
| - | - |
| 启用助理绑定 | 开启，使本次初始化结果成为当前组织的生效绑定 |
| 协同模型 | 选择当前组织可用的模型，无须使用特定厂商或固定型号 |
| Xpert DSL 模板 | 选择“本体助理” |
| Xpert 名称 | 保留向导生成的名称，或填写不重复的名称 |
| 发布说明 | 例如“初始化组织本体助理 v1” |

核对页面底部的工作空间、环境、MCP 工具集及模型摘要，点击 **开始初始化**。

### 3.5 确认绑定成功

等待绿色成功提示，并检查：

* 状态为 **已配置**。
* **当前绑定** 已显示助理标识。
* **当前工作空间** 为刚选择的“组织助理”。
* **最近初始化时间** 对应本次操作。

如果关闭“启用助理绑定”，即使保留了配置记录，也不会把该助理作为当前组织的生效绑定。

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

切换到 **当前组织语义模型建模助理** 页签，分别完成：

1. **选择工作空间**：选择同一“组织助理”共享空间，点击 **下一步**。
2. **创建环境**：环境名称可使用“语义模型 Workbench”或 `Semantic Model Workbench`；保留前述两个默认密钥变量及空值，点击 **下一步**。
3. **导入 Xpert DSL**：开启绑定，选择当前组织可用的协同模型，模板选择 **语义模型建模助理**。
4. 确认名称、发布说明及摘要，点击 **开始初始化**。
5. 检查已配置状态、当前绑定、当前工作空间和最近初始化时间。

这个向导没有独立的“创建 MCP 工具集”步骤。按当前页显示的三步完成即可，不需要照搬本体助理的四步流程。

> [!NOTE]
>
> 部分界面版本在建模助理初始化完成后，仍显示“本体助理已完成初始化并更新绑定”的通用成功文字。请同时核对当前页签及绑定信息，确认完成的是语义模型建模助理。

## 5. 检查生成的资源

回到 Xpert，刷新并切换到“组织助理”工作空间。按所初始化的类型检查以下资源：

| 资源 | 核对内容 |
| - | - |
| 语义模型建模助理 | 已发布；配置中包含语义模型建模、模型工作台、指标管理或查询分析等模板工具 |
| 本体助理 | 已发布；模板显示名称可能是“统一本体语义执行专家” |
| 本体 MCP 工具集 | 本体助理的工具连接可用；图中可能显示为 `HttpUOSE` 节点 |

显示名称可能随模板或自定义配置变化。存在同名助理时，以初始化页的当前绑定和实际目标空间为准。

建模助理通过工具读取、校验或修改模型；本体助理通过 MCP 查询实体、关系及动作能力。工具出现在配置图中只代表已配置，实际调用仍需满足资源权限和运行条件。

## 6. 用普通成员完成使用验证

配置成功后，再选择有目标资源权限的普通成员进行验证：

1. 打开 Data Xpert 的目标语义模型工作台，展开建模助理。
2. 询问“请列出当前模型的 Cube、维度和度量，先不要修改”。确认返回的结构属于当前模型。
3. 如已初始化本体助理，在对应本体入口查询一条已知实体及其关系，核对结果。
4. 再用没有目标模型或实体权限的成员验证，该资源仍不能被读取或修改。

组织级初始化让组织复用助理配置，不会让成员获得他人的全部模型，也不会代替查询、编辑、发布或动作审批权限。绿色成功提示、已发布卡片和问候回复，都不能代替以上实际调用验证。

## 7. 常见问题

| 现象 | 检查方式 |
| - | - |
| 找不到目标工作空间 | 确认当前组织、组织共享开关、归档状态和初始化人的写权限；更新后刷新 |
| `Access denied to workspace` | 核对所选空间和当前账号权限，不要通过复用管理员令牌绕过 |
| 凭据已初始化，插件仍不可用 | 分别检查插件安装、API 地址、运行加载状态；需要重启时按部署流程处理 |
| 助理生成了，但工作台仍用旧助理 | 确认启用绑定并完成初始化，核对当前绑定和工作空间后重新打开工作台 |
| 缺少 `ChatKit client secret` | 检查当前组织绑定和会话创建请求的具体错误；这不是要求终端用户手填 API 密钥 |
| 能打开助理但工具调用失败 | 检查调用者资源权限、模型发布状态及服务连接；成功初始化不代表数据查询成功 |

下一步可[配置并发布业务助理](https://docs.xpertai.cn/zh-Hans/data/tutorial/semantic-analysis/configure-business-assistant.md)，将已发布模型提供给指定用户组使用。


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