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

## 1. 概述（Overview）

**XpertAI 指标管理工具集**是为大语言模型设计的一组智能体工具，旨在实现**语义驱动的指标管理自动化**。通过集成该工具集，智能体可以理解用户的自然语言指令，并在数据分析平台中完成指标的创建、编辑、检索等操作。

### 🌐 应用背景

在传统 BI 或数据平台中，指标管理操作繁琐，用户需手动配置、跨界沟通。借助该工具集，智能体可在语义模型的支持下自动执行指标操作，显著降低操作门槛并提升效率。

### 💡 核心能力

* **项目切换**：自动切换工作空间或业务域
* **指标发现**：通过语义理解列出相关指标
* **指标创建**：根据描述生成基础或派生指标
* **指标维护**：支持指标的编辑、删除操作
* **上下文感知**：联动数据立方体与维度信息，辅助指标构建

该工具集可无缝集成现有数据系统，赋能智能体具备数据治理能力，实现指标操作的智能化、规范化和低门槛使用。

***

## 2. 快速开始（Quick Start）

### ✅ 前置条件：选择 BI 项目

在使用指标管理工具集之前，需为智能体配置一个[**BI 项目**](/docs/stories/project/)，用于统一指标命名、维度结构与业务上下文的语言理解。BI 项目应符合以下条件：

* 已注册至平台的项目（如：某业务域的数据项目）。
* 关联了具有度量、维度的数据立方体等语义模型信息。
* 可供大模型解析并作为推理上下文。

实现此功能大模型所用工具为

* **`SWITCH_PROJECT`** 切换当前工作空间或项目

***

## 3. 管理指标功能

> 每个工具子项独立展开，包含用途、参数、返回结构、使用示例

* `LIST_INDICATORS`：列出项目下所有指标
* `CREATE_DERIVE_INDICATOR`：创建派生指标
* `CREATE_BASIC_INDICATOR`：创建基础指标
* `EDIT_INDICATOR`：编辑现有指标
* `DELETE_INDICATOR`：删除指定指标

以下是指标管理工具集中的核心操作工具，每种工具均可被智能体调用以实现相应的指标操作功能：

### 🔍 `LIST_INDICATORS` — 列出所有指标

用于获取当前项目下的全部指标列表，可按条件筛选（如类型、命名空间、标签等）。
**典型用途：**

* 浏览已有指标
* 辅助用户选择目标指标
* 提供智能体后续操作的候选项

> 🧠 示例任务：
> “我们目前有哪些关于用户行为的指标？”

### ➕ `CREATE_BASIC_INDICATOR` — 创建基础指标

用于创建直接来源于原始数据的**基础指标**，例如字段聚合（如求和、计数、最大值等），以及某些条件限制下的基础度量。

**典型用途：**

* 定义业务原子指标，如「订单数」「访问量」
* 建立统一指标规范入口

> 🧠 示例任务：
> “创建一个基础指标，用于统计下单量”
> “创建一个基础指标，用于统计 XX产品 的下单量”

### ➕ `CREATE_DERIVE_INDICATOR` — 创建派生指标

用于基于现有指标构建**派生指标**，支持自定义计算逻辑、条件、分母分子等表达式。

**典型用途：**

* 构建复合指标，如转化率、同比增长率
* 支持语义建模中更高阶的指标表达能力

> 🧠 示例任务：
> “创建一个指标，计算本月活跃用户占比”

### ✏️ `EDIT_INDICATOR` — 编辑现有指标

用于修改已存在的指标属性（根据编码），如名称、表达式、所属业务域、业务口径等。

**典型用途：**

* 更新指标定义
* 修复错误或调整业务含义

> 🧠 示例任务：
> “把用户留存率的定义改成以注册日为基准”

### ❌ `DELETE_INDICATOR` — 删除指定指标

用于从当前项目中删除指定的指标。支持通过编码进行定位。

**典型用途：**

* 清理不再使用或定义错误的指标
* 保持指标系统整洁

> 🧠 示例任务：
> “删除编码为‘临时指标1’的指标”

***

## 4. 使用指标功能

* `INDICATOR_RETRIEVER`：根据名称/ID 检索指标详情
* `SHOW_INDICATORS`：结构化展示某类指标
* `GET_CUBE_CONTEXT`：获取与指标相关的数据立方体上下文
* `DIMENSION_MEMBER_RETRIEVER`：获取维度成员信息（如枚举维度的取值）

### 📄 `INDICATOR_RETRIEVER` — 检索指标详情

用于根据指标的名称或 ID 获取其完整定义信息，包括指标表达式、依赖字段、所属立方体、创建人等元数据。
**典型用途：**

* 查询单个指标的详细信息
* 为智能体生成解释、验证指标定义
* 支持进一步的编辑或衍生操作

> 🧠 示例任务：
> “告诉我‘活跃用户占比’的定义是什么？”

### 🧾 `SHOW_INDICATORS` — 结构化展示指标

用于将指标列表以结构化方式展示给用户，支持按类别、标签、所属模型、用途等方式分组展示。
**典型用途：**

* 高可读性地浏览指标体系
* 为用户呈现面板式指标信息
* 支持智能体生成视觉化结构/摘要说明

> 🧠 示例任务：
> “请帮我展示所有用户增长相关的指标”

### 🧠 `GET_CUBE_CONTEXT` — 获取指标数据立方体上下文

用于获取指标所属的数据立方体及其结构信息，如可用维度、度量、粒度等。
**典型用途：**

* 为指标创建提供上下文信息
* 判断指标是否可按某维度分析
* 生成指标表达式的语义支持信息

> 🧠 示例任务：
> “这个指标能不能按地区和时间维度来分析？”

### 🧩 `DIMENSION_MEMBER_RETRIEVER` — 获取维度成员信息

用于获取某个维度下的全部成员（取值），常用于枚举类维度，如地区、渠道、用户类型等。
**典型用途：**

* 支持创建有条件的指标表达式
* 辅助智能体为用户生成选择项
* 实现语义增强的筛选和分类

> 🧠 示例任务：
> “帮我列出所有的用户类型有哪些？”

***

## 5. 智能体调用指南（Agent Usage Guide）

* [工具如何注册进智能体](/docs/ai/xpert/#如何使用工具)
* 如何通过 Prompt 或 Action 触发工具
* 使用 LLM 生成结构化调用

## 7. 错误处理与调试（Error Handling & Debugging）

* 常见错误码及其含义
* 调用失败时的建议处理策略
* 日志追踪与问题排查建议

## 8. 常见问题（FAQ）

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

* v3.4 初始版本。