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

# 配置 Xpert AI 助手

在 Xpert 中，配置 AI 助手，本质上就是把一个**已经准备好的数字专家**绑定到某个助手入口。

配置完成后，用户从对应入口打开助手时，实际使用的就是你绑定的这个数字专家。

如果这个数字专家本身是通过 YAML DSL 创建或导入的，那么这个 AI 助手的能力也就来自这份 DSL 配置。

## 当前支持的三种助手

根据当前系统实现，Xpert 的系统级 AI 助手分为三类：

* **通用助手（Common Assistant）**：用于通用聊天页中的内嵌助手入口；
* **ChatBI 助手（ChatBI Assistant）**：用于 ChatBI 页面中的数据分析助手入口；
* **工作空间助手（Workspace Assistant）**：用于工作空间和 Studio 外壳中的共享助手入口。

这三种助手都通过“设置 / 助手”页面进行配置，但它们面向的使用场景不同。

## 前置配置

在开始配置之前，请先确认以下内容：

* 已按 [配置 AI 提供商](./configure-ai-provider/) 完成模型供应商配置；
* 已创建一个可以作为助手使用的数字专家；
* 该数字专家已经**发布**；
* 如果你希望工作空间助手帮助你创建或修改数字专家，建议额外准备一个专门的“创作助理”数字专家；
* 如果配置租户级默认助手，需要具备租户管理员权限；
* 如果配置组织级助手，需要先切换到目标组织，并具备相应管理权限。

> 在“设置 / 助手”页面中，通常只有当前作用域内可访问且**已经发布**的数字专家才能被选中。

## 如何配置 Xpert AI 助手

进入“**设置 / 助手**”页面后，按照下面步骤进行配置。

### 1. 选择要配置的助手类型

在列表中找到你要配置的助手项。

* **通用助手**
* **ChatBI 助手**
* **工作空间助手**

每一项都会单独保存配置，互不影响。

### 2. 选择配置层级

助手支持两层配置方式：

* **租户默认**：为整个租户设置默认助手，组织会默认继承这份配置；
* **组织覆盖**：为当前组织单独配置助手，配置后会优先于租户默认生效。

如果组织级没有单独配置，系统会继续使用租户默认配置。

### 3. 启用或停用当前助手

在对应助手项中，打开或关闭“**启用**”开关。

* 启用后，该入口会使用你绑定的数字专家；
* 关闭后，即使存在绑定关系，该入口也不会按启用状态对外提供该助手。

### 4. 绑定数字专家

在“**Assistant ID / Xpert ID**”选择框中，选择你要绑定的数字专家。

你可以按名称或 ID 搜索当前作用域内可访问的数字专家。保存前请确认当前助手已经启用。

点击“**保存**”后，该助手入口就会开始使用你选择的数字专家。

## 三种助手分别适合什么场景

### 通用助手

通用助手对应通用聊天页中的默认助手入口，适合以下场景：

* 提供一个统一的通用问答入口；
* 面向知识问答、流程咨询、业务助手等通用对话场景；
* 作为租户或组织级默认聊天助手使用。

如果你希望用户进入通用聊天页后，直接获得一个统一的默认 AI 助手，通常应该配置这里。

### ChatBI 助手

ChatBI 助手对应 ChatBI 页面中的内嵌助手，适合以下场景：

* 在 ChatBI 页面中回答分析问题；
* 围绕指标、模型、维度、口径解释等场景进行多轮问答；
* 提供固定的数据分析助手入口。

如果你的目标是让用户在 ChatBI 页面里直接进行对话式分析，这里应绑定一个偏数据分析或业务问答的数字专家。

### 工作空间助手

工作空间助手对应工作空间和 Studio 中的共享助手，适合以下场景：

* 在工作空间里通过聊天创建新的数字专家；
* 在 Studio 中继续修改当前数字专家草稿；
* 帮助补充知识库、工具集、提示词或工作流结构。

如果你的目标是“配置一个能帮你编排数字专家的 AI 助手”，这里通常应该绑定一个专门的“创作助理”数字专家。

## 如何准备“创作助理”数字专家

如果你希望工作空间助手帮助你创建或修改数字专家，建议单独准备一个“创作助理”数字专家，而不是直接复用业务专家。

常见做法是：

* 使用平台提供的“创作助理”模板创建一个新的数字专家；
* 或者基于同类 YAML DSL 模板创建一个专门用于“数字专家创作”的数字专家；
* 配置完成后先发布，再到“设置 / 助手”中把它绑定给工作空间助手。

## 租户默认与组织覆盖

### 租户默认

适合作为全租户统一使用的默认助手配置。

例如：

* 全公司默认都使用同一个通用助手；
* 所有组织默认都使用同一个 ChatBI 助手；
* 所有组织默认都使用同一个工作空间助手。

### 组织覆盖

适合某个组织有单独需求时使用，例如不同组织使用不同的通用助手、ChatBI 助手或工作空间助手。

当组织级配置存在时，系统会优先使用组织级配置；如果组织没有单独配置，则回退到租户默认配置。

如果你希望恢复继承租户默认，可以删除当前组织的覆盖配置，改回使用租户默认。

## 配置完成后可以做什么

### 在通用聊天页中提供统一入口

如果通用助手已经绑定好数字专家，用户进入通用聊天页后，就可以直接使用该助手进行问答、咨询或日常协作。

### 在 ChatBI 页面中进行对话式分析

如果 ChatBI 助手已经绑定好数字专家，用户就可以在 ChatBI 页面中围绕数据模型、指标和分析问题进行多轮对话。

### 在工作空间中新增或修改数字专家

如果工作空间助手绑定的是“创作助理”数字专家，用户就可以直接在聊天中描述需求，例如：

* `帮我创建一个售后客服专家`
* `帮我创建一个合同审查专家`

助手会根据描述创建新的数字专家草稿，并引导你继续到 Studio 调整。

如果你已经打开某个数字专家的 Studio，助手还可以继续协助你修改当前草稿，例如：

* 补充知识库；
* 调整提示词；
* 增加工具集；
* 修改工作流结构。

这类修改通常作用于**当前草稿**，不是直接替换已发布版本，所以修改完成后仍建议你检查并重新发布。

## 使用时需要注意

* 如果当前数字专家还只是草稿，没有发布，通常不能直接在助手设置中选中它。
* 租户级配置通常需要租户管理员权限；组织级配置需要先进入目标组织。
* 三种助手分别独立配置，给其中一个助手绑定数字专家，不会自动同步到其他助手。
* 如果组织级没有配置，系统会继续继承租户默认配置。
* 如果你希望工作空间助手专门负责“创建和修改数字专家”，最好给它单独准备一个创作助理，而不是直接复用业务专家。
* 如果入口打开后仍提示未配置，请检查是否已经启用、是否已选中数字专家，以及当前组织是否命中了正确的配置层级。

## 常见问题

### 为什么我的数字专家没有出现在助手可选列表里？

常见原因包括：

* 还没有发布；
* 当前不在正确的租户或组织作用域；
* 当前作用域下无权访问这个数字专家。

### 为什么我已经保存了组织配置，但实际还是租户默认？

建议检查：

* 当前是否真的已经切换到目标组织；
* 当前组织配置是否已经保存成功；
* 当前助手项是否已经启用；
* 是否误配置到了另一种助手类型。

### 为什么我已经绑定了助手，但工作空间里还是显示助手未配置？

工作空间里使用的是**工作空间助手**这一项，而不是通用助手或 ChatBI 助手。因此即使你已经绑定了别的助手类型，工作空间里仍然可能显示“助手未配置”。

常见原因包括：

* 你绑定的是**通用助手**或 **ChatBI 助手**，但没有配置**工作空间助手**；
* 你已经绑定了数字专家，但**没有启用**工作空间助手；
* 你把配置保存到了某个组织下，但当前所在的并不是这个组织；
* 当前组织没有命中组织覆盖配置，同时租户默认里也没有配置工作空间助手；
* 当前工作空间助手配置没有真正保存成功，或者保存后又被切回了“继承租户默认”；
* 工作空间助手对应的数字专家没有按当前作用域生效，导致当前组织下没有拿到有效配置。

遇到这种情况，建议优先检查：

* 在“设置 / 助手”中确认你配置的是**工作空间助手**；
* 确认当前所在组织与保存配置时的组织一致；
* 确认工作空间助手已经**启用**，并且已经绑定数字专家；
* 如果当前组织未单独配置，继续检查租户默认是否已经配置工作空间助手。

如果以上配置都没问题，但助手仍然无法正常打开，也建议继续检查 **ChatKit** 服务相关配置是否正常，例如：

* ChatKit 服务访问地址是否已正确配置；
* ChatKit 服务当前是否可访问、是否正常运行。

### 为什么工作空间助手改完数字专家后没有立即对外生效？

因为大多数这类修改先落到**草稿**上。若要让最终使用者看到更新后的版本，仍然需要你手动确认并发布。

## 相关文档

* [🤖 AI 智能助理](./ai-assitant/)
* [配置 AI 提供商](./configure-ai-provider/)
* [数字专家](../agent/)
* [专家配置](../expert-configuration/)