# https://github.com/evidentlyai/evidently 项目说明书
生成时间：2026-05-16 20:09:11 UTC
## 目录
- [项目介绍与安装](#page-1)
- [系统架构设计](#page-2)
- [指标系统 (Metrics)](#page-3)
- [预设评估 (Presets)](#page-4)
- [描述符系统 (Descriptors)](#page-5)
- [报告与测试套件](#page-6)
- [LLM集成与评判器](#page-7)
- [Guardrails安全护栏](#page-8)
- [数据管理与存储](#page-9)
- [前端UI组件库](#page-10)
## 项目介绍与安装
### 相关页面
相关主题：[系统架构设计](#page-2)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/evidentlyai/evidently/blob/main/README.md)
- [api-reference/README.md](https://github.com/evidentlyai/evidently/blob/main/api-reference/README.md)
- [src/evidently/sdk/configs.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)
- [src/evidently/sdk/adapters.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/adapters.py)
- [src/evidently/ui/workspace.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/workspace.py)
- [src/evidently/ui/utils.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/utils.py)
# 项目介绍与安装
## 项目概述
Evidently 是一个开源 Python 框架，专门用于评估、测试和监控机器学习（ML）以及基于大语言模型（LLM）的系统。该项目旨在为数据科学家和 ML 工程师提供全面的模型性能评估工具，支持从离线评估到在线监控的完整生命周期管理。
项目具有以下核心特性：
- **开源免费**：采用开源许可证，可自由使用和修改
- **多场景支持**：支持分类、回归、自然语言处理等多种模型评估场景
- **丰富的可视化**：提供直观的仪表板和报告展示评估结果
- **易于集成**：可通过 Python API 或 Web UI 进行集成
- **云端协作**：提供 Evidently Cloud 服务支持团队协作
资料来源：[README.md](https://github.com/evidentlyai/evidently/blob/main/README.md)
## 系统架构
Evidently 采用模块化的系统架构，主要包含以下核心组件：
```mermaid
graph TD
A[Evidently Core] --> B[Metrics 模块]
A --> C[Dashboard 模块]
A --> D[SDK 模块]
B --> E[数据漂移检测]
B --> F[模型性能评估]
B --> G[统计测试]
C --> H[Web UI]
C --> I[报告生成]
D --> J[Cloud API]
D --> K[Workspace]
```
### 核心模块说明
| 模块名称 | 功能描述 | 主要类/文件 |
|---------|---------|------------|
| Metrics | 核心指标计算 | `evidently.metrics` |
| Dashboard | 可视化报告 | `ui/packages/evidently-ui-lib` |
| SDK | 编程接口 | `src/evidently/sdk/` |
| Workspace | 项目工作区管理 | `src/evidently/ui/workspace.py` |
| Guardrails | LLM 输出验证 | `evidently.guardrails` |
资料来源：[src/evidently/sdk/configs.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)
## 安装方式
### 基础安装
使用 pip 安装稳定版本：
```bash
pip install evidently
```
### 开发版本安装
从源码安装最新开发版本：
```bash
pip install git+https://github.com/evidentlyai/evidently.git
```
### 扩展模块安装
根据需要安装额外的依赖模块：
```bash
# 基础模块
pip install evidently
# 扩展指标模块
pip install evidently.metrics
# LLM Guardrails 模块
pip install evidently.guardrails
```
资料来源：[api-reference/README.md](https://github.com/evidentlyai/evidently/blob/main/api-reference/README.md)
## SDK 配置与使用
### 配置元数据
Evidently SDK 提供了完整的配置管理功能，通过 `ConfigMetadata` 类管理配置元信息：
```python
ConfigMetadata(
created_at=datetime, # 创建时间
updated_at=datetime, # 更新时间
author=str, # 作者
description=str # 配置描述
)
```
资料来源：[src/evidently/sdk/configs.py:1-20](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)
### 工作区管理
Workspace 模块负责管理项目和实验配置：
```mermaid
classDiagram
class Workspace {
+create_project(name, description, org_id)
+add_project(project)
+get_project(project_id)
+delete_project(project_id)
+list_projects(org_id)
}
class ProjectModel {
+name: str
+description: str
+org_id: Optional[OrgID]
}
Workspace --> ProjectModel
```
关键方法说明：
| 方法 | 参数 | 返回值 | 功能 |
|-----|------|-------|------|
| `create_project` | name, description, org_id | Project | 创建新项目 |
| `add_project` | project: ProjectModel | Project | 添加项目 |
| `get_project` | project_id | Optional[Project] | 获取项目 |
| `delete_project` | project_id | None | 删除项目 |
| `list_projects` | org_id | Sequence[Project] | 列出项目 |
资料来源：[src/evidently/ui/workspace.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/workspace.py)
### 描述符配置
Descriptor Config 用于存储和版本化管理描述符配置：
```python
def save_descriptor(
project_id: STR_UUID,
name: str,
descriptor: Descriptor
) -> ConfigVersion
def get_descriptor(
project_id: STR_UUID,
name: str,
version: VersionOrLatest = "latest"
) -> Descriptor
```
资料来源：[src/evidently/sdk/configs.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)
## 依赖要求
### 最小依赖
Evidently 的核心功能需要以下最小依赖集：
- Python >= 3.8
- pandas
- numpy
- scikit-learn
### 完整依赖
完整安装包含所有可选依赖，适用于完整的模型评估和监控场景。
资料来源：[requirements.min.txt](https://github.com/evidentlyai/evidently/blob/main/requirements.min.txt)
## Web UI 组件
### 前端组件架构
Evidently UI 采用 React 和 Material-UI 构建，提供现代化的用户界面：
```mermaid
graph LR
A[用户界面] --> B[Dashboard 组件]
A --> C[Prompts 组件]
A --> D[Traces 组件]
A --> E[Descriptors 组件]
B --> F[Widget]
C --> G[Forms]
D --> H[Table]
E --> I[Features]
```
### 核心 UI 组件
| 组件名称 | 功能 | 文件路径 |
|---------|------|---------|
| NameAndDescriptionForm | 名称描述表单 | `ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx` |
| PromptsTable | 提示词表格 | `ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx` |
| TracesTable | 追踪记录表格 | `ui/packages/evidently-ui-lib/src/components/Traces/TracesTable.tsx` |
| DashboardDateFilter | 日期过滤器 | `ui/packages/evidently-ui-lib/src/components/Dashboard/DashboardDateFilter.tsx` |
资料来源：[ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx)
## 快速开始
### 步骤一：安装 Evidently
```bash
pip install evidently
```
### 步骤二：创建评估报告
```python
from evidently.dashboard import Dashboard
from evidently.tabs import DataDriftTab, CatTargetDriftTab
# 创建仪表板
dashboard = Dashboard(tabs=[DataDriftTab(), CatTargetDriftTab()])
# 运行评估
dashboard.calculate(reference_data, current_data)
```
### 步骤三：导出报告
```python
dashboard.save_html("report.html")
```
## 进一步资源
| 资源 | 链接 |
|-----|------|
| 官方文档 | https://docs.evidentlyai.com |
| API 参考 | https://evidentlyai.github.io/evidently/api-reference |
| Discord 社区 | https://discord.gg/xZjKRaNp8b |
| Evidently Cloud | https://www.evidentlyai.com/register |
---
## 系统架构设计
### 相关页面
相关主题：[项目介绍与安装](#page-1), [指标系统 (Metrics)](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [src/evidently/ui/utils.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/utils.py)
- [src/evidently/sdk/configs.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)
- [src/evidently/ui/workspace.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/workspace.py)
- [src/evidently/sdk/adapters.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/adapters.py)
- [README.md](https://github.com/evidentlyai/evidently/blob/main/README.md)
- [api-reference/README.md](https://github.com/evidentlyai/evidently/blob/main/api-reference/README.md)
# 系统架构设计
## 1. 概述
Evidently 是一个开源的机器学习与 LLM 驱动系统的评估、测试和监控框架。该项目采用模块化设计，将核心评估逻辑与用户界面分离，同时提供 SDK 和 Web UI 两种交互方式。
**核心设计目标：**
- 提供可复用的评估指标和报告生成能力
- 支持本地运行和云端服务两种部署模式
- 实现配置版本化管理
- 支持多项目组织和团队协作
资料来源：[README.md:1-10]()
## 2. 整体架构
```mermaid
graph TD
subgraph "前端层 UI Layer"
WEB[Web UI - React]
API_REF[API Reference Docs]
end
subgraph "业务逻辑层 Business Logic"
SDK[Evidently SDK]
METRICS[Metrics & Evaluators]
GUARDRAILS[Guardrails]
end
subgraph "数据模型层 Data Models"
CORE[Core Module]
BASE_TYPES[Base Types]
LEGACY[Legacy Module]
end
subgraph "服务层 Services"
WORKSPACE[Workspace Service]
CONFIGS[Config API]
ADAPTERS[Adapters]
end
WEB --> SDK
SDK --> METRICS
SDK --> GUARDRAILS
SDK --> CORE
CORE --> BASE_TYPES
SDK --> WORKSPACE
SDK --> CONFIGS
SDK --> ADAPTERS
```
## 3. 核心模块架构
### 3.1 SDK 模块结构
Evidently SDK 是系统的核心，提供了评估、报告生成和配置管理的功能。
```mermaid
graph LR
subgraph "SDK Module"
CONFIGS[Configs]
ADAPTERS[Adapters]
REPORT[Report]
METRICS[Metrics]
end
CONFIGS --> ADAPTERS
REPORT --> METRICS
```
**主要组件：**
| 模块 | 文件路径 | 功能说明 |
|------|----------|----------|
| ConfigAPI | `src/evidently/sdk/configs.py` | 提供配置的增删改查和版本管理 |
| Adapters | `src/evidently/sdk/adapters.py` | 配置与 API 之间的适配器 |
| Report | `src/evidently/core/report.py` | 报告生成和处理 |
| Base Types | `src/evidently/core/base_types.py` | 基础数据类型定义 |
资料来源：[src/evidently/sdk/configs.py:1-50]()
### 3.2 Workspace 服务层
Workspace 是项目管理的核心抽象，提供了项目级别的操作接口。
```mermaid
classDiagram
class Workspace {
<>
+create_project(name, description, org_id) Project
+add_project(project, org_id) Project
+get_project(project_id) Optional~Project~
+delete_project(project_id)
+list_projects(org_id) Sequence~Project~
}
class Project {
+id: STR_UUID
+name: str
+description: str
+org_id: Optional~OrgID~
}
```
**Workspace 核心接口：**
| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| create_project | name, description, org_id | Project | 创建新项目 |
| add_project | project, org_id | Project | 添加项目到工作区 |
| get_project | project_id | Optional[Project] | 根据 ID 获取项目 |
| delete_project | project_id | None | 删除指定项目 |
| list_projects | org_id | Sequence[Project] | 列出工作区中的项目 |
资料来源：[src/evidently/ui/workspace.py:1-60]()
### 3.3 配置版本管理
系统采用 ConfigVersion 机制管理配置的版本，支持配置的创建、更新和历史追溯。
```mermaid
graph TD
A[ConfigVersion] --> B[ConfigMetadata]
A --> C[ConfigContent]
B --> D[created_at]
B --> E[updated_at]
B --> F[author]
B --> G[description]
H[CloudConfigAPI] --> I[create_descriptor]
H --> J[get_descriptor]
H --> K[update_descriptor]
```
**配置类型支持：**
| 配置类型 | 说明 | 支持版本管理 |
|----------|------|--------------|
| Descriptor | 描述符配置 | 是 |
| Artifact | 工件配置 | 是 |
| Metric | 指标配置 | 是 |
| Report | 报告配置 | 是 |
资料来源：[src/evidently/sdk/adapters.py:1-40]()
## 4. 前端架构
### 4.1 UI 组件结构
Web UI 采用 React + TypeScript 构建，主要组件位于 `ui/packages/evidently-ui-lib/`。
```mermaid
graph TD
subgraph "UI Components"
Dashboard[Dashboard]
Prompts[Prompts]
Traces[Traces]
Descriptors[Descriptors]
Utils[Utils]
end
subgraph "Widgets"
Widget[Widget]
TestSuiteWidget[TestSuiteWidget]
end
Dashboard --> Widget
Prompts --> Utils
Traces --> Utils
Descriptors --> Utils
```
**核心组件：**
| 组件目录 | 组件名称 | 功能 |
|----------|----------|------|
| Dashboard | DashboardDateFilter | 日期范围筛选 |
| Prompts | CreatePromptForm, PromptsTable | Prompt 创建和管理 |
| Traces | TracesTable, TraceViewer | 追踪记录查看 |
| Descriptors | LLMJudge/template | 描述符模板 |
| Widgets | Widget | 通用组件容器 |
资料来源：[ui/packages/evidently-ui-lib/src/widgets/Widget.tsx:1-30]()
### 4.2 状态管理
表单状态使用 React Hook Form 结合 Zod 进行验证：
```typescript
// 表单验证流程
Form → useForm → zodResolver → NameAndDescriptionForm
```
**表单验证模式：**
| 验证字段 | 验证规则 | 错误提示位置 |
|----------|----------|--------------|
| name | 必填，字符串 | helperText |
| description | 可选，字符串 | helperText |
| 日期范围 | dateFrom <= dateTo | AlertThemed |
资料来源：[ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx:1-40]()
## 5. 报告与评估系统
### 5.1 Report 核心流程
```mermaid
graph LR
A[Input Data] --> B[Dataset]
B --> C[Descriptors]
C --> D[Evaluators]
D --> E[Report]
E --> F[Metrics]
F --> G[Visualization]
```
**Report 生成步骤：**
1. **数据准备**：将 DataFrame 转换为 Dataset 对象
2. **添加描述符**：定义行级评估器（如 Sentiment、TextLength）
3. **执行评估**：运行预设的评估套件
4. **生成报告**：汇总结果并生成可视化输出
**示例支持的描述符：**
| 描述符 | 功能 | 适用场景 |
|--------|------|----------|
| Sentiment | 情感分析 | LLM 响应评估 |
| TextLength | 文本长度统计 | 响应长度监控 |
| Contains | 关键词检测 | 拒绝/否认识别 |
资料来源：[README.md:80-120]()
### 5.2 评估预设
系统提供多种评估预设，简化常见评估场景的配置：
| 预设名称 | 说明 | 包含评估项 |
|----------|------|------------|
| TextEvals | 文本评估预设 | 情感、长度、关键词 |
| LLM Evals | LLM 专用评估 | 响应质量、多样性 |
资料来源：[README.md:60-80]()
## 6. API 参考文档生成
项目使用 pdoc 工具自动生成 API 参考文档。
```mermaid
graph TD
A[generate.py] --> B[Local Source]
A --> C[Git Revision]
B --> D[dist//]
C --> E[dist//]
F[local-dev.sh] --> G[Development Server]
G --> H[http://localhost:8080]
```
**文档生成命令：**
```bash
# 本地源码生成
./api-reference/generate.py --local-source-code
# 指定 Git 版本
./api-reference/generate.py --git-revision v0.7.17
# 添加额外模块
./api-reference/generate.py --local-source-code \
--additional-modules "evidently.metrics,evidently.guardrails"
```
**默认包含模块：**
- `evidently`
- `evidently.core`
**输出目录结构：**
- 本地构建：`dist//`
- Git 构建：`dist//`
资料来源：[api-reference/README.md:1-50]()
## 7. 部署架构
### 7.1 组件部署
```mermaid
graph TD
subgraph "客户端 Client"
PY[Python SDK]
WEB[Web Browser]
end
subgraph "服务端 Server"
API[Config API]
DB[(Database)]
WS[Workspace Service]
end
PY --> API
WEB --> WS
API --> DB
WS --> DB
```
### 7.2 安装方式
| 安装方式 | 命令 | 说明 |
|----------|------|------|
| PyPI | `pip install evidently` | 推荐标准方式 |
| Conda | `conda install -c conda-forge evidently` | 使用 conda 安装 |
资料来源：[README.md:40-55]()
## 8. 关键技术栈
| 层级 | 技术 | 用途 |
|------|------|------|
| 核心语言 | Python 3.11+ | SDK 实现 |
| Web 框架 | React + TypeScript | 前端 UI |
| 数据验证 | Zod | 表单验证 |
| 日期处理 | dayjs | 时间格式化 |
| 文档生成 | pdoc | API 文档 |
| 包管理 | uv | Python 包管理 |
## 9. 总结
Evidently 采用清晰的分层架构设计：
1. **核心层** (`evidently.core`)：定义基础数据类型和报告生成逻辑
2. **SDK 层** (`evidently.sdk`)：提供配置管理、适配器和 API 封装
3. **业务层** (`evidently.ui`)：实现工作区服务和项目管理
4. **展示层** (`ui/`): React 前端实现用户交互界面
这种设计使得系统既可以作为 Python 库独立使用，也可以通过 Web UI 进行可视化操作，同时支持本地部署和云端服务两种模式。
---
## 指标系统 (Metrics)
### 相关页面
相关主题：[预设评估 (Presets)](#page-4), [报告与测试套件](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [src/evidently/metrics/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/__init__.py)
- [src/evidently/metrics/classification.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/classification.py)
- [src/evidently/metrics/regression.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/regression.py)
- [src/evidently/metrics/data_quality.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/data_quality.py)
- [src/evidently/metrics/recsys.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/recsys.py)
- [src/evidently/core/metric_types.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/metric_types.py)
- [src/evidently/core/registries/metrics.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/metrics.py)
# 指标系统 (Metrics)
## 概述
指标系统是 Evidently 框架的核心组件之一，负责对机器学习模型和 LLM 支持的系统进行量化和评估。该系统提供了统一的接口来定义、计算、缓存和渲染各类评估指标，涵盖了分类任务、回归任务、数据质量评估以及推荐系统等多个领域。
指标系统通过抽象基类 `Metric` 和 `MetricContainer` 建立了灵活可扩展的架构，允许开发者自定义指标并将其集成到评估报告中。 资料来源：[src/evidently/core/metric_types.py:1-50]()
## 核心架构
### 指标类型层次结构
Evidently 的指标系统采用面向对象的继承设计，主要分为两大类：
1. **基础指标 (Metric)** - 单个指标实现，负责计算具体的评估维度
2. **指标容器 (MetricContainer)** - 组合多个指标的容器，支持批量计算和联合渲染
```mermaid
graph TD
A[Metric 基础抽象类] --> B[ClassificationMetrics]
A --> C[RegressionMetrics]
A --> D[DataQualityMetrics]
A --> E[RecSysMetrics]
A --> F[MetricContainer 容器基类]
F --> G[TextEvals 预设容器]
F --> H[CustomMetricContainer]
```
### 指标容器 (MetricContainer)
`MetricContainer` 是组合多个指标的抽象基类，定义在 `src/evidently/core/container.py` 中，提供了指标生成、缓存和渲染的统一接口。
```python
class MetricContainer(GenericContainer, abc.ABC):
"""指标容器基类"""
def __init__(self, include_tests: bool = True, **data):
"""初始化指标容器
Args:
include_tests: 如果为 True，生成的指标将包含默认测试
"""
self.include_tests = include_tests
super().__init__(**data)
@abc.abstractmethod
def generate_metrics(self, context: "Context") -> Sequence[MetricOrContainer]:
"""基于容器配置生成指标"""
raise NotImplementedError()
def metrics(self, context: "Context") -> List[MetricOrContainer]:
"""获取所有生成的指标，支持上下文缓存"""
metric_container_fp = self.get_fingerprint()
metrics = context.metrics_container(metric_container_fp)
if metrics is None:
metrics = list(self.generate_metrics(context))
context.set_metric_container_data(metric_container_fp, metrics)
return metrics
def render(self, context: "Context",
child_widgets: Optional[List[Tuple[Optional[MetricId], List[BaseWidgetInfo]]]] = None) -> List[BaseWidgetInfo]:
"""渲染可视化组件"""
# 实现细节
```
资料来源：[src/evidently/core/container.py:31-75]()
### 指标注册表机制
指标系统通过注册表 (Registry) 机制实现指标的集中管理和发现。`MetricRegistry` 类维护了所有可用指标的映射关系。
| 注册表操作 | 说明 |
|-----------|------|
| `register()` | 注册新指标到注册表 |
| `get()` | 根据名称获取指标类 |
| `list_metrics()` | 列出所有已注册的指标 |
| `_make` | 指标实例工厂方法 |
资料来源：[src/evidently/core/registries/metrics.py:1-100]()
## 指标分类
### 分类指标 (Classification Metrics)
分类指标用于评估分类模型的性能，支持二分类和多分类场景。
**主要指标包括：**
| 指标名称 | 说明 | 适用场景 |
|---------|------|---------|
| `ClassificationQualityMetric` | 整体分类质量评分 | 通用分类评估 |
| `PrecisionMetric` | 精确率 | 关注假阳性场景 |
| `RecallMetric` | 召回率 | 关注假阴性场景 |
| `F1ScoreMetric` | F1 分数 | 平衡精确率和召回率 |
| `RocAucMetric` | ROC-AUC 曲线下面积 | 概率预测评估 |
| `ConfusionMatrixMetric` | 混淆矩阵 | 详细错误分析 |
资料来源：[src/evidently/metrics/classification.py:1-200]()
### 回归指标 (Regression Metrics)
回归指标用于评估连续值预测模型的性能。
**核心指标：**
| 指标名称 | 说明 | 敏感度 |
|---------|------|--------|
| `MeanErrorMetric` | 平均误差 | 偏移 |
| `MeanAbsoluteErrorMetric` | 平均绝对误差 | 异常值鲁棒 |
| `MeanSquaredErrorMetric` | 均方误差 | 惩罚大误差 |
| `R2ScoreMetric` | R² 决定系数 | 模型解释力 |
| `ErrorDistributionMetric` | 误差分布 | 偏差分析 |
资料来源：[src/evidently/metrics/regression.py:1-200]()
### 数据质量指标 (Data Quality Metrics)
数据质量指标用于评估数据集本身的特性，包括完整性、一致性和统计分布。
| 指标类别 | 包含指标 |
|---------|---------|
| 完整性检查 | 缺失值比例、空值统计 |
| 唯一性检查 | 重复行检测、主键唯一性 |
| 范围检查 | 数值边界、类别覆盖 |
| 分布检查 | 直方图、分布偏移 |
资料来源：[src/evidently/metrics/data_quality.py:1-200]()
### 推荐系统指标 (RecSys Metrics)
推荐系统专用指标用于评估协同过滤和内容推荐算法。
| 指标名称 | 说明 |
|---------|------|
| `PrecisionAtK` | K 位精度 |
| `RecallAtK` | K 位召回率 |
| `NDCGMetric` | 归一化折扣累计增益 |
| `HitRateMetric` | 点击率 |
资料来源：[src/evidently/metrics/recsys.py:1-200]()
## 指标执行流程
```mermaid
sequenceDiagram
participant User as 用户
participant Report as Report
participant Container as MetricContainer
participant Metric as Metric
participant Context as Context
participant Renderer as WidgetRenderer
User->>Report: 创建 Report(metrics=[...])
Report->>Container: 初始化容器
Container->>Context: 调用 metrics()
Context->>Context: 检查缓存
alt 缓存未命中
Context->>Container: generate_metrics()
Container->>Metric: 实例化指标
Metric->>Metric: calculate(context)
Metric-->>Context: 返回计算结果
Context->>Context: 缓存结果
end
Context-->>Report: 返回指标列表
Report->>Container: render(context)
Container->>Metric: 获取 widget 信息
Metric-->>Container: BaseWidgetInfo
Container-->>Report: 渲染后的 widgets
Report-->>User: 生成 HTML/JSON 报告
```
## 指标定义接口
每个具体指标需要实现以下核心方法：
```python
class MyCustomMetric(Metric):
"""自定义指标示例"""
def calculate(self, context: Context) -> MetricResult:
"""执行指标计算
Args:
context: 包含数据集和配置的上下文对象
Returns:
MetricResult: 包含计算结果的指标结果对象
"""
# 1. 从 context 获取数据
current_data = context.get_current_data()
reference_data = context.get_reference_data()
# 2. 执行计算逻辑
value = self._compute_metric(current_data, reference_data)
# 3. 返回结果
return MetricResult(
value=value,
parameters=self.parameters
)
def get_widgets(self, context: Context) -> List[BaseWidgetInfo]:
"""返回可视化组件"""
# 返回用于渲染的 widget 配置
pass
def get_fingerprint(self) -> str:
"""计算指标指纹用于缓存"""
pass
```
资料来源：[src/evidently/core/metric_types.py:50-150]()
## 指标与报告集成
指标通过 `Report` 类与用户进行交互。以下是典型使用方式：
```python
from evidently import Report
from evidently.metrics import ClassificationQualityMetric, PrecisionMetric
# 创建报告并指定要使用的指标
report = Report(
metrics=[
ClassificationQualityMetric(),
PrecisionMetric(positive_label=1),
]
)
# 运行评估
report.run(
reference_data=reference_df,
current_data=current_df,
column_mapping=ColumnMapping(target="target", prediction="pred")
)
# 导出报告
report.save_html("report.html")
report.save_json("report.json")
```
## 指标预设 (Presets)
除了单个指标，Evidently 还提供了预配置的指标组合预设：
| 预设名称 | 说明 | 包含指标 |
|---------|------|---------|
| `TextEvals` | LLM 文本评估预设 | 情感分析、毒性检测、摘要质量 |
| `ClassificationPreset` | 分类任务完整评估 | 质量、精确率、召回率、混淆矩阵 |
| `RegressionPreset` | 回归任务完整评估 | MAE、MSE、误差分布、R² |
资料来源：[src/evidently/metrics/__init__.py:1-100]()
## 缓存机制
指标系统实现了高效的缓存机制以避免重复计算：
```mermaid
graph LR
A[请求指标] --> B{缓存存在?}
B -->|是| C[返回缓存结果]
B -->|否| D[调用 generate_metrics]
D --> E[执行指标计算]
E --> F[存入上下文缓存]
F --> G[返回结果]
```
缓存键基于指标容器的指纹 (fingerprint) 生成，确保配置变化时自动重新计算。
资料来源：[src/evidently/core/container.py:47-55]()
## 扩展开发指南
### 创建自定义指标
1. **继承 Metric 基类**
2. **实现必需方法**：calculate()、get_widgets()、get_fingerprint()
3. **注册到指标注册表**
```python
from evidently.core import Metric
class MyMetric(Metric):
"""自定义指标"""
alias = "my_metric"
def calculate(self, context):
# 实现计算逻辑
return MyMetricResult(...)
def get_widgets(self, context):
return [BaseWidgetInfo(...)]
def get_fingerprint(self):
return self.json()
```
### 创建自定义指标容器
```python
from evidently.core import MetricContainer
class MyMetricContainer(MetricContainer):
"""自定义指标容器"""
def generate_metrics(self, context):
return [
MyMetric(...),
AnotherMetric(...)
]
```
## 总结
Evidently 的指标系统提供了灵活、可扩展且功能完整的评估框架。通过抽象基类和注册表机制，开发者可以轻松添加新的指标类型；通过容器模式和缓存机制，系统能够高效处理复杂的评估场景。该系统支持从简单的数据质量检查到高级的 LLM 输出评估等多种应用场景，是 Evidently 框架的核心支柱。
---
## 预设评估 (Presets)
### 相关页面
相关主题：[指标系统 (Metrics)](#page-3), [报告与测试套件](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [src/evidently/presets/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/__init__.py)
- [src/evidently/presets/drift.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/drift.py)
- [src/evidently/presets/classification.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/classification.py)
- [src/evidently/presets/regression.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/regression.py)
- [src/evidently/presets/recsys.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/recsys.py)
- [src/evidently/core/preset_types.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/preset_types.py)
- [src/evidently/core/registries/presets.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/presets.py)
# 预设评估 (Presets)
## 概述
预设评估（Presets）是 Evidently 框架中提供的一种高级评估机制，它将一组相关的指标（Metrics）和测试（Tests）打包成可重用的配置单元。预设评估允许用户通过简单的接口快速对机器学习模型进行全面的性能评估，无需手动配置大量单独的指标。
Evidently 的预设评估系统涵盖多种 ML 任务类型，每种预设针对特定的应用场景提供针对性的评估方案。通过使用预设，用户可以：
- 简化评估流程，减少配置代码量
- 确保评估的一致性和标准化
- 快速获得全面的模型性能洞察
- 支持分类、回归、数据漂移和推荐系统等多种任务类型
## 架构设计
### 核心组件关系
预设系统的架构由以下几个核心组件构成：
```mermaid
graph TD
A[用户代码] --> B[Report / TestSuite]
B --> C[Preset 预设]
C --> D[Metrics 指标集合]
C --> E[Tests 测试集合]
D --> F[ColumnMetric]
D --> G[DatasetMetric]
E --> H[TestCase]
F --> I[Evidently Engine]
G --> I
H --> I
J[PresetRegistry 注册表] --> K[Preset Types 类型定义]
K --> C
```
### 类型层次结构
预设类型系统采用继承和组合模式：
```mermaid
classDiagram
class Preset {
<>
+metrics: List[Metric]
+tests: List[Test]
+tabs: List[str]
+get_aspects() List[Aspect]
}
class DataDriftPreset {
+DataDriftPreset()
}
class ClassificationPreset {
+ClassificationPreset()
}
class RegressionPreset {
+RegressionPreset()
}
class RecSysPreset {
+RecSysPreset()
}
class TextEvalsPreset {
+TextEvalsPreset()
}
Preset <|-- DataDriftPreset
Preset <|-- ClassificationPreset
Preset <|-- RegressionPreset
Preset <|-- RecSysPreset
Preset <|-- TextEvalsPreset
```
## 预设类型详解
### 数据漂移检测预设 (DataDriftPreset)
数据漂移预设用于检测生产环境中的数据分布变化。当输入数据的统计特性发生显著变化时，可能表明模型性能下降或底层数据生成过程发生了变化。
**适用场景**：
- 生产环境监控
- 模型再训练触发条件判断
- 数据管道异常检测
**主要评估指标**：
| 指标类型 | 说明 |
|---------|------|
| 特征级漂移 | 检测单个特征的分布变化 |
| 整体漂移 | 聚合所有特征的漂移情况 |
| 目标漂移 | 检测目标变量分布变化 |
资料来源：[src/evidently/presets/drift.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/drift.py)
### 分类模型预设 (ClassificationPreset)
分类预设专为二分类和多分类任务设计，提供全面的分类器性能评估。
**适用场景**：
- 二分类问题（如欺诈检测、流失预测）
- 多分类问题（如图像分类、文本分类）
- 概率校准评估
**主要评估指标**：
| 指标 | 说明 | 适用分类类型 |
|------|------|-------------|
| Accuracy | 整体准确率 | 二分类/多分类 |
| Precision | 精确率 | 二分类/多分类 |
| Recall | 召回率 | 二分类/多分类 |
| F1-Score | F1 分数 | 二分类/多分类 |
| ROC-AUC | ROC 曲线下面积 | 二分类 |
| PR-AUC | PR 曲线下面积 | 二分类 |
| Confusion Matrix | 混淆矩阵 | 二分类/多分类 |
| Class Representation | 类别表示分布 | 多分类 |
资料来源：[src/evidently/presets/classification.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/classification.py)
### 回归模型预设 (RegressionPreset)
回归预设用于评估回归模型的预测性能。
**适用场景**：
- 连续值预测
- 时间序列预测
- 价格/数量预测
**主要评估指标**：
| 指标 | 说明 |
|------|------|
| MAE | 平均绝对误差 |
| MSE | 均方误差 |
| RMSE | 均方根误差 |
| MAPE | 平均绝对百分比误差 |
| R2 Score | 决定系数 |
| Max Error | 最大误差 |
| Median Error | 中位数误差 |
资料来源：[src/evidently/presets/regression.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/regression.py)
### 推荐系统预设 (RecSysPreset)
推荐系统预设专门针对协同过滤和推荐算法进行评估。
**适用场景**：
- 推荐系统性能评估
- 点击率预测
- 排名质量评估
**主要评估指标**：
| 指标 | 说明 |
|------|------|
| Precision@K | K 位精度 |
| Recall@K | K 位召回率 |
| NDCG | 归一化折损累计增益 |
| MRR | 平均倒数排名 |
| Hit Rate | 点击率 |
资料来源：[src/evidently/presets/recsys.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/recsys.py)
### 文本评估预设 (TextEvalsPreset)
文本评估预设用于评估 LLM 和文本生成模型的输出质量。
**适用场景**：
- LLM 输出质量评估
- 文本摘要评估
- 问答系统评估
- 语义相似度评估
**支持的评估描述符**：
| 描述符 | 功能 |
|--------|------|
| Sentiment | 情感分析 |
| TextLength | 文本长度统计 |
| Contains | 关键词检测 |
| LLM Judge | LLM 作为评判者 |
| PII Detection | 敏感信息检测 |
资料来源：[src/evidently/presets/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/__init__.py)
## 使用方式
### 在 Report 中使用预设
```python
from evidently import Report
from evidently.presets import DataDriftPreset, ClassificationPreset
# 创建带有预设的报告
report = Report(metrics=[
DataDriftPreset(),
ClassificationPreset()
])
report.run(reference_data=reference, current_data=current)
report.show()
```
### 在 TestSuite 中使用预设
```python
from evidently import TestSuite
from evidently.presets import RegressionPreset
# 创建带有预设的测试套件
suite = TestSuite(tests=[
RegressionPreset()
])
suite.run(reference_data=reference, current_data=current)
suite.show()
```
### 自定义预设组合
用户可以组合多个预设或添加自定义指标：
```python
from evidently import Report
from evidently.presets import DataDriftPreset, ClassificationPreset
from evidently.metrics import ColumnSummaryMetric
report = Report(metrics=[
DataDriftPreset(),
ClassificationPreset(),
ColumnSummaryMetric(column_name="feature_1")
])
```
## 注册表机制
预设系统使用注册表模式进行管理，确保所有预设类型都能被正确识别和实例化。
```mermaid
graph LR
A[PresetRegistry] -->|register| B[Preset Types]
B -->|实例化| C[DataDriftPreset]
B -->|实例化| D[ClassificationPreset]
B -->|实例化| E[RegressionPreset]
B -->|实例化| F[RecSysPreset]
G[load_preset] -->|按名称查找| A
G -->|返回实例| C
```
资料来源：[src/evidently/core/registries/presets.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/presets.py)
## 配置参数
### 通用配置选项
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `metrics` | List[Metric] | 指标列表 | [] |
| `tests` | List[Test] | 测试列表 | [] |
| `tabs` | List[str] | 展示标签页 | None |
| `include_widgets` | List[Widget] | 包含的可视化组件 | None |
### 分类预设配置
| 参数 | 类型 | 说明 |
|------|------|------|
| `generated_labels` | bool | 是否生成类别标签 |
| `probas_threshold` | float | 概率阈值 |
### 漂移预设配置
| 参数 | 类型 | 说明 |
|------|------|------|
| `drift_method` | str | 漂移检测方法 |
| `confidence_level` | float | 置信水平 |
## 工作流程
```mermaid
graph TD
A[初始化 Report/TestSuite] --> B[加载预设]
B --> C[解析数据集]
C --> D[计算参考指标]
D --> E[计算当前指标]
E --> F[对比分析]
F --> G{输出类型}
G -->|Report| H[生成可视化报告]
G -->|TestSuite| I[执行断言测试]
H --> J[展示结果]
I --> K[返回测试结果]
```
## 输出展示
预设评估的输出支持多种展示形式：
| 输出类型 | 说明 |
|---------|------|
| HTML 报告 | 交互式可视化报告 |
| JSON 格式 | 结构化数据导出 |
| Python 字典 | 程序化访问 |
| Markdown | 文档化输出 |
## 最佳实践
### 选择合适的预设
1. **数据类型驱动**：根据输入数据特征选择对应预设
2. **任务类型匹配**：二分类使用 ClassificationPreset，多分类考虑类别平衡
3. **监控场景**：生产监控优先考虑 DataDriftPreset
### 性能优化建议
- 避免在同一 Report 中使用过多预设
- 大数据集使用采样策略
- 漂移检测设置合理的检测窗口
### 常见陷阱
- 忽略数据预处理导致评估偏差
- 混淆参考数据集和当前数据集
- 忽视类别不平衡问题
## 扩展预设
用户可以创建自定义预设：
```python
from evidently.presets import Preset
from evidently.metrics import Metric
class CustomPreset(Preset):
def __init__(self):
super().__init__(
metrics=[
CustomMetric1(),
CustomMetric2()
],
tabs=["Custom Tab"]
)
```
资料来源：[src/evidently/core/preset_types.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/preset_types.py)
---
## 描述符系统 (Descriptors)
### 相关页面
相关主题：[LLM集成与评判器](#page-7), [报告与测试套件](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [src/evidently/descriptors/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/__init__.py)
- [src/evidently/descriptors/text_length.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/text_length.py)
- [src/evidently/descriptors/text_match.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/text_match.py)
- [src/evidently/descriptors/llm_judges.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/llm_judges.py)
- [src/evidently/descriptors/_context_relevance.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/_context_relevance.py)
- [src/evidently/core/registries/descriptors.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/descriptors.py)
- [src/evidently/descriptors/generated_descriptors.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/generated_descriptors.py)
# 描述符系统 (Descriptors)
## 1. 系统概述
描述符系统是 Evidently 框架中用于对数据集行级别进行评估和特征提取的核心组件。该系统允许用户通过声明式的方式定义文本处理任务，并将这些任务应用到 DataFrame 的指定列上，生成评估结果和衍生特征。
描述符的核心价值在于：
- **行级别评估**：对数据集中的每一行数据进行独立评估
- **特征提取**：将文本内容转换为可量化的数值特征
- **测试集成**：内置支持与测试框架集成，可设置阈值和预期范围
- **结果缓存**：通过装饰器实现计算结果缓存，避免重复计算
资料来源：[src/evidently/descriptors/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/__init__.py)
## 2. 核心架构
### 2.1 架构组件
描述符系统由以下核心组件构成：
```mermaid
graph TD
A[用户定义描述符] --> B[FeatureDescriptor]
B --> C[底层 Feature 实现]
C --> D[评估结果 / 特征值]
E[Dataset] --> F[描述符注册表]
F --> B
G[Test Suite] --> B
```
### 2.2 FeatureDescriptor 类
`FeatureDescriptor` 是描述符的顶层封装类，负责整合底层特征实现和可选的测试配置：
```python
FeatureDescriptor(feature=feature, alias=alias, tests=tests)
```
| 参数 | 类型 | 说明 |
|------|------|------|
| `feature` | `Feature` | 底层特征实现对象 |
| `alias` | `str` | 描述符别名，用于在结果中标识 |
| `tests` | `List[DescriptorTest \| GenericTest]` | 可选的测试配置列表 |
资料来源：[src/evidently/descriptors/generated_descriptors.py:1-50](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/generated_descriptors.py)
### 2.3 描述符注册表机制
描述符通过注册表进行统一管理，支持按类型和名称进行查找：
```mermaid
graph LR
A[描述符定义] --> B[DescriptorRegistry]
B --> C[按类型查找]
B --> D[按名称查找]
C --> E[返回描述符实例]
D --> E
```
注册表提供以下核心功能：
- 注册新的描述符类型
- 根据名称获取描述符
- 维护描述符与底层实现的映射关系
资料来源：[src/evidently/core/registries/descriptors.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/descriptors.py)
## 3. 内置描述符类型
### 3.1 文本基础描述符
文本基础描述符主要用于文本数据的量化处理。
| 描述符 | 功能 | 主要参数 |
|--------|------|----------|
| `Sentiment` | 情感分析 | `column_name`, `alias` |
| `TextLength` | 文本长度统计 | `column_name`, `alias` |
| `Contains` | 关键词匹配 | `column_name`, `words_list`, `mode`, `lemmatize`, `alias` |
#### Sentiment 描述符
情感分析描述符使用预训练模型对文本进行情感评分：
```python
Sentiment("answer", alias="Sentiment")
```
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `column_name` | `str` | 是 | 要分析的文本列名 |
| `alias` | `str` | 是 | 结果列别名 |
#### TextLength 描述符
文本长度描述符计算文本的字符数或词数：
```python
TextLength(column_name="response", alias="Response Length")
```
#### Contains 描述符
关键词匹配描述符检测文本中是否包含指定词语：
```python
Contains(
column_name="text",
words_list=["denial", "refuse", "can't"],
mode="any", # or "all"
lemmatize=True,
alias="Denial Indicator"
)
```
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `column_name` | `str` | - | 目标文本列名 |
| `words_list` | `List[str]` | - | 要匹配的词语列表 |
| `mode` | `"any" \| "all"` | `"any"` | 匹配模式 |
| `lemmatize` | `bool` | `False` | 是否进行词形还原 |
| `alias` | `str` | - | 结果别名 |
资料来源：[src/evidently/descriptors/text_match.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/text_match.py)
### 3.2 LLM Judge 描述符
LLM Judge 描述符利用大语言模型对文本进行高级语义评估。
| 描述符 | 功能 | 适用场景 |
|--------|------|----------|
| `ContextRelevance` | 上下文相关性评估 | RAG 系统评估 |
| `AnswerRelevance` | 回答相关性评估 | 问答系统 |
| `Faithfulness` | 回答忠实度评估 | 生成内容验证 |
#### ContextRelevance 描述符
用于评估检索到的上下文与查询的相关性：
```python
ContextRelevance(
column_name="context",
question_column="question",
alias="context_relevance",
criteria=default_context_relevance_criteria,
uncertainty=default_llm_judge_params
)
```
| 参数 | 类型 | 说明 |
|------|------|------|
| `column_name` | `str` | 上下文文本列 |
| `question_column` | `str` | 问题列名 |
| `alias` | `str` | 结果别名 |
| `criteria` | `dict` | 评估标准 |
| `uncertainty` | `dict` | 不确定性参数 |
资料来源：[src/evidently/descriptors/_context_relevance.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/_context_relevance.py)
### 3.3 HuggingFace 模型描述符
支持直接调用 HuggingFace 模型进行特定任务：
```python
HuggingFace(
column_name="text",
model="cardiffnlp/twitter-roberta-base-sentiment",
params={"max_length": 512},
alias="hf_sentiment"
)
```
#### HuggingFaceToxicity 描述符
专门用于检测文本毒性：
```python
HuggingFaceToxicity(
column_name="text",
alias="toxicity_score",
model=None, # 使用默认模型
toxic_label="toxic"
)
```
资料来源：[src/evidently/descriptors/generated_descriptors.py:40-70](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/generated_descriptors.py)
## 4. 使用方式
### 4.1 在 Dataset 中使用
描述符可以作为 Dataset 创建时的参数传入：
```python
from evidently import Dataset, DataDefinition
from evidently.descriptors import Sentiment, TextLength, Contains
eval_dataset = Dataset.from_pandas(
pd.DataFrame(eval_df),
data_definition=DataDefinition(),
descriptors=[
Sentiment("answer", alias="Sentiment"),
TextLength("answer", alias="Answer Length"),
Contains(
"answer",
words_list=["sorry", "can't", "refuse"],
mode="any",
alias="Denial Indicator"
)
]
)
```
### 4.2 与测试框架集成
描述符支持内置的测试配置，可设置阈值和预期范围：
```python
from evidently.descriptors import TextLength
from evidently.test_suits import DescriptorTest
tests = [
DescriptorTest(
alias="Length Check",
condition="gte",
threshold=10
)
]
TextLength("response", alias="Response Length", tests=tests)
```
### 4.3 工作流程
```mermaid
graph TD
A[创建 Dataset] --> B[应用描述符列表]
B --> C[对每行数据进行特征计算]
C --> D[缓存计算结果]
D --> E[生成评估报告]
E --> F{是否配置测试}
F -->|是| G[执行测试断言]
F -->|否| H[仅输出特征值]
G --> I[测试结果]
```
## 5. 描述符与 Report 集成
描述符生成的特征可以直接在 Report 中展示：
```python
from evidently import Report
from evidently.presets import TextEvals
report = Report(metrics=[
TextEvalsPreset()
])
report.run(reference_data=ref_df, current_data=curr_df)
report.show()
```
## 6. 自定义描述符
### 6.1 创建自定义 Feature
用户可以通过继承 `Feature` 基类创建自定义描述符：
```python
from evidently.legacy.features.base import Feature
class CustomFeature(Feature):
def __init__(self, column_name: str, **kwargs):
super().__init__(column_name=column_name, **kwargs)
def _calculate(self, data: pd.Series) -> pd.Series:
# 自定义计算逻辑
return data.apply(self._process)
def _process(self, value):
# 处理单个值
return processed_value
```
### 6.2 封装为 FeatureDescriptor
```python
from evidently.descriptors import FeatureDescriptor
def CustomDescriptor(
column_name: str,
alias: str,
tests: Optional[List[Union["DescriptorTest", "GenericTest"]]] = None
):
feature = CustomFeature(column_name=column_name, display_name=alias)
return FeatureDescriptor(feature=feature, alias=alias, tests=tests)
```
## 7. 性能优化
描述符系统提供以下性能优化机制：
| 优化方式 | 说明 |
|----------|------|
| 结果缓存 | 使用 `@lru_cache` 装饰器避免重复计算 |
| 向量化计算 | 底层使用 pandas 向量化操作 |
| 批量处理 | 支持批量数据处理减少 I/O 开销 |
## 8. 总结
描述符系统是 Evidently 框架中进行文本数据评估的核心模块，通过统一抽象的接口设计，提供了从简单的文本长度统计到复杂的 LLM Judge 语义评估的完整能力覆盖。其与 Dataset 和 Report 系统的深度集成，使得用户可以方便地在机器学习和 LLM 系统的评估流程中使用这些描述符。
描述符系统的设计遵循以下原则：
- **声明式配置**：通过参数配置而非代码实现定义评估逻辑
- **可组合性**：支持多个描述符组合使用
- **可扩展性**：通过继承机制支持自定义描述符
- **测试集成**：内置与测试框架的集成能力
---
## 报告与测试套件
### 相关页面
相关主题：[指标系统 (Metrics)](#page-3), [预设评估 (Presets)](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [src/evidently/core/report.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/report.py)
- [src/evidently/core/tests.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/tests.py)
- [src/evidently/core/serialization.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/serialization.py)
- [src/evidently/legacy/report/report.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/legacy/report/report.py)
- [src/evidently/legacy/test_suite/test_suite.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/legacy/test_suite/test_suite.py)
# 报告与测试套件
## 概述
报告（Report）与测试套件（Test Suite）是 Evidently 框架的两大核心功能模块，用于评估和监控机器学习及 LLM 支持的系统。这两个模块提供了互补的能力：报告专注于数据探索和可视化分析，而测试套件则用于验证数据质量和模型性能是否满足预期标准。
报告模块通过统计分析生成交互式的可视化图表，帮助数据科学家理解模型行为和数据分布变化。测试套件模块则将评估标准形式化为可执行的测试用例，返回明确的通过/失败状态，便于 CI/CD 流程集成和自动化监控。资料来源：[src/evidently/legacy/report/report.py:1-50]()
## 核心架构
### 模块关系图
```mermaid
graph TD
A[数据集输入] --> B[Report]
A --> C[Test Suite]
B --> D[MetricRegistry]
C --> E[TestRegistry]
D --> F[可视化渲染]
E --> G[测试结果输出]
F --> H[HTML/JSON报告]
G --> I[测试日志]
H --> J[Web UI展示]
I --> K[持续集成]
```
### 报告与测试套件对比
| 特性 | 报告 (Report) | 测试套件 (Test Suite) |
|:---|:---|:---|
| 输出形式 | 可视化图表、统计指标 | 通过/失败状态 |
| 交互性 | 支持 Web UI 交互查看 | 命令行批量执行 |
| 返回类型 | `Report` 对象 | `TestSuite` 对象 |
| 适用场景 | 数据探索、模型分析 | 自动化验证、CI/CD |
| 配置方式 | Metrics 注册 | Tests 定义 |
| 资料来源 | [src/evidently/core/report.py:1-30]() | [src/evidently/core/tests.py:1-30]() |
## Report 报告模块
### 功能特性
报告模块提供以下核心功能：
1. **多指标支持**：支持 100+ 内置评估指标，覆盖数据质量、分布漂移、分类性能、回归性能等多个维度
2. **灵活的指标组合**：通过 `metrics` 参数可自由组合不同类型的指标
3. **多种输出格式**：支持生成 HTML 交互式报告和 JSON 结构化数据
4. **数据集支持**：兼容 pandas DataFrame 以及 Evidently 的 Dataset 对象
### 基本使用流程
```mermaid
graph LR
A[准备数据] --> B[创建Report实例]
B --> C[添加Metrics]
C --> D[调用run方法]
D --> E[生成报告]
E --> F[保存/展示]
```
### 代码示例
```python
from evidently import Report
from evidently.descriptors import Sentiment, TextLength
from evidently.presets import TextEvals
# 创建报告实例
report = Report(
metrics=[
TextEvals(),
]
)
# 准备数据集
from evidently import Dataset
dataset = Dataset.from_pandas(df, descriptors=[
Sentiment("response"),
TextLength("response")
])
# 运行报告
result = report.run(reference_data=reference, current_data=current)
print(result.show())
```
### 报告生成参数
| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|:---|:---|:---|:---|:---|
| `metrics` | `List[Metric]` | 是 | - | 要计算的指标列表 |
| `date_column` | `str` | 否 | `None` | 时间戳列名 |
| `verbose_level` | `int` | 否 | `1` | 日志详细程度 |
| 资料来源 | [src/evidently/core/report.py:40-60]() | | | |
### 报告运行方法
```python
def run(
self,
reference_data: Optional[Any,
current_data: Any,
column_mapping: Optional[ColumnMapping] = None
) -> ReportResult:
"""执行报告生成"""
```
### 序列化支持
报告支持 JSON 和 pickle 格式的序列化，便于持久化存储和后续加载分析。资料来源：[src/evidently/core/serialization.py:1-50]()
## Test Suite 测试套件模块
### 功能特性
测试套件模块的核心特点包括：
1. **声明式测试定义**：通过声明式语法定义数据质量测试
2. **即时反馈**：运行后立即返回测试结果列表
3. **详细日志**：每个测试失败时提供详细的原因说明
4. **与报告互补**：测试套件可以复用报告中的指标定义
### 测试执行流程
```mermaid
graph TD
A[定义TestSuite] --> B[添加Tests]
B --> C[加载数据集]
C --> D[执行run方法]
D --> E{测试通过?}
E -->|是| F[记录通过状态]
E -->|否| G[记录失败详情]
F --> H[生成TestResult]
G --> H
H --> I[返回结果列表]
```
### 代码示例
```python
from evidently import TestSuite
from evidently.test_suite import TestSuite
from evidently.legacy.test_suite import TestSuite as LegacyTestSuite
# 创建测试套件
test_suite = TestSuite(tests=[
# 测试定义
])
# 运行测试
result = test_suite.run(reference_data=ref, current_data=cur)
# 检查结果
if result.passed:
print("所有测试通过")
else:
print(f"失败测试数: {result.get_fail_count()}")
```
### 测试结果结构
| 属性 | 类型 | 说明 |
|:---|:---|:---|
| `passed` | `bool` | 是否全部通过 |
| `total` | `int` | 测试总数 |
| `failed` | `int` | 失败数量 |
| `results` | `List[TestResult]` | 单个测试结果列表 |
| 资料来源 | [src/evidently/legacy/test_suite/test_suite.py:50-100]() |
## 指标与测试的对应关系
### 指标 (Metric) 到测试 (Test) 的转换
Evidently 框架支持将指标计算结果转换为测试用例，实现评估逻辑的复用：
```python
# 指标 → 测试的映射关系
from evidently.metrics import ColumnSummaryMetric
# 基于指标的测试定义
TestMetric = ColumnSummaryMetric(
column_name="target",
quantile=[0.05, 0.95]
)
```
### 常用指标分类
| 类别 | 指标名称 | 对应测试 |
|:---|:---|:---|
| 数据质量 | `MissingValuesMetric` | `TestMissingValues` |
| 分布漂移 | ` drift.DriftMetric` | `TestColumnDrift` |
| 分类性能 | `ClassificationQualityMetric` | `TestAccuracyScore` |
| 回归性能 | `RegressionQualityMetric` | `TestMAEScore` |
## 遗留版本兼容性
Evidently 保留了遗留版本的 API，确保向后兼容：
### Legacy Report
```python
from evidently.legacy.report.report import Report as LegacyReport
# 遗留版本报告创建方式
legacy_report = LegacyReport(
metrics=[],
mode='raw'
)
```
### Legacy Test Suite
```python
from evidently.legacy.test_suite.test_suite import TestSuite as LegacyTestSuite
# 遗留版本测试套件
legacy_suite = LegacyTestSuite(tests=[])
```
遗留版本模块位于 `src/evidently/legacy/` 目录下，新项目推荐使用核心模块 `src/evidently/core/` 下的实现。资料来源：[src/evidently/legacy/report/report.py:1-30]()
## 最佳实践
### 1. 选择合适的模块
- **使用 Report**：当需要可视化分析、探索性数据检查、或需要生成可分享的 HTML 报告时
- **使用 Test Suite**：当需要自动化验证、CI/CD 集成、或需要明确的通过/失败判断时
- **组合使用**：在实际项目中，可以先使用 Report 进行分析，再将关键指标转化为 Test Suite 进行持续监控
### 2. 数据准备
确保输入数据格式正确：
```python
from evidently import Dataset, DataDefinition
# 推荐的数据准备方式
dataset = Dataset.from_pandas(
pd.DataFrame(data),
data_definition=DataDefinition()
)
```
### 3. 性能优化
对于大规模数据集，建议：
- 使用 `verbose_level=0` 减少日志输出
- 分批次处理时间序列数据
- 复用 `ColumnMapping` 配置
## 输出格式与集成
### HTML 报告输出
```python
# 保存为 HTML 文件
report.save_html("output/report.html")
# 或者获取 HTML 字符串
html_content = report.get_html()
```
### JSON 序列化
```python
import json
# 序列化为 JSON
json_data = report.json()
with open("report.json", "w") as f:
json.dump(json_data, f)
```
### 与 Web UI 集成
Evidently UI 支持加载报告文件进行交互式查看：
```bash
evidently ui --projects ./projects
```
生成的报告文件可通过 UI 的文件链接功能展示，模板定义位于 `src/evidently/ui/utils.py`。资料来源：[src/evidently/ui/utils.py:1-50]()
## 总结
报告与测试套件共同构成了 Evidently 框架的评估基础设施。报告模块侧重于深入的数据分析和可视化呈现，帮助用户理解模型行为；测试套件模块则提供可自动化的验证机制，确保生产环境的稳定性。两者基于共同的指标体系设计，可实现分析与监控的无缝衔接，是 ML/LLM 系统可靠性的重要保障。
---
## LLM集成与评判器
### 相关页面
相关主题：[描述符系统 (Descriptors)](#page-5), [Guardrails安全护栏](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [src/evidently/llm/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/__init__.py)
- [src/evidently/llm/models.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/models.py)
- [src/evidently/llm/prompts/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/prompts/__init__.py)
- [src/evidently/llm/rag/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/rag/__init__.py)
- [src/evidently/llm/datagen/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/datagen/__init__.py)
- [src/evidently/llm/optimization/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/optimization/__init__.py)
- [src/evidently/utils/llm/wrapper.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/utils/llm/wrapper.py)
# LLM集成与评判器
## 概述
LLM集成与评判器是Evidently框架中用于评估和测试大型语言模型(LLM)输出质量的核心模块。该系统提供了完整的LLM驱动评估能力，支持通过预定义或自定义的评判标准对文本输出进行自动化质量评估。
Evidently的LLM评判器允许用户创建结构化的评估流程，通过提示词模板(prompt templates)定义评估规则，并支持多类别分类、置信度评分等高级评估场景。
## 系统架构
### 核心模块结构
| 模块 | 路径 | 功能描述 |
|------|------|----------|
| `llm` | `src/evidently/llm/` | LLM集成核心模块 |
| `prompts` | `src/evidently/llm/prompts/` | 提示词模板管理 |
| `rag` | `src/evidently/llm/rag/` | RAG相关评估 |
| `datagen` | `src/evidently/llm/datagen/` | 测试数据生成 |
| `optimization` | `src/evidently/llm/optimization/` | 提示词优化 |
| `wrapper` | `src/evidently/utils/llm/wrapper.py` | LLM调用封装 |
## 评判器配置
### 描述符配置(Descriptor Config)
描述符配置用于定义单个评估指标的元数据和参数。系统通过`ConfigAPI`类管理描述符配置的版本化存储。
主要配置方法：
- **创建描述符**：`add_descriptor()` - 添加新的描述符配置
- **获取描述符**：`get_descriptor()` - 根据名称和版本获取描述符
- **更新描述符**：通过版本控制机制实现配置的增量更新
### 多分类评判模板
系统支持多分类评判模板(`MulticlassClassificationPromptTemplate`)，用于需要将输入分类到多个预定义类别的评估场景。
```typescript
// 资料来源：ui/packages/evidently-ui-lib/src/components/Descriptors/Features/LLMJudge/template.tsx:67
{state.type === 'evidently:prompt_template:MulticlassClassificationPromptTemplate' && (
Classes
Provide classes for multiclass classification mode.
{/* 类别配置表单 */}
)}
```
### 评判标准配置
评判器支持为每个分类类别定义独立的评判标准，通过`category_criteria`字典存储类别与对应评判规则的映射关系。
## 用户界面集成
### 评判模板编辑组件
前端组件`LLMJudge/template.tsx`提供了可视化的评判模板配置界面，支持：
- 评判类型选择
- 类别定义与管理
- 置信度阈值配置
- 错误状态展示
### 提示词管理界面
系统提供完整的提示词生命周期管理：
```typescript
// 资料来源：ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx
{
key: 'actions',
label: 'Action',
render: (prompt) => (
onDelete(prompt.id ?? '')}>
)
}
```
支持的操作包括：
- 创建新提示词
- 编辑现有提示词
- 删除提示词
- 复制提示词ID
## 工作流程
### LLM评估流程
```mermaid
graph TD
A[输入数据] --> B[创建Dataset]
B --> C[应用Descriptors]
C --> D[LLM评判器处理]
D --> E[生成评估结果]
E --> F[生成Report]
```
### 提示词模板配置流程
```mermaid
graph LR
A[选择评判类型] --> B[配置评判标准]
B --> C[设置类别阈值]
C --> D[保存配置版本]
D --> E[关联到Descriptor]
```
## SDK配置与API
### 云端配置管理
系统通过`CloudConfigAPI`类提供云端配置管理能力，支持：
- 配置版本化存储
- 元数据管理
- 远程配置同步
```python
# 资料来源：src/evidently/sdk/configs.py
def add_descriptor(self, project_id: STR_UUID, name: str, descriptor: Descriptor) -> ConfigVersion:
"""添加描述符配置"""
return self._add_typed_version(project_id, name, descriptor)
```
### 适配器层
`RemoteGenericConfig`适配器负责处理与远程服务的通信，包括：
- 配置上传与下载
- 版本历史查询
- 内容序列化与反序列化
## 数据模型
### 配置版本元数据
| 字段 | 类型 | 描述 |
|------|------|------|
| `id` | UUID | 配置版本唯一标识 |
| `artifact_id` | UUID | 关联的描述符ID |
| `version` | int | 版本号 |
| `content` | Any | 配置内容 |
| `metadata.created_at` | datetime | 创建时间 |
| `metadata.updated_at` | datetime | 更新时间 |
| `metadata.author` | str | 作者 |
| `metadata.comment` | str | 版本注释 |
### 评判器状态
评判器状态通过React组件管理，包含：
- 当前评判类型
- 类别评判标准映射
- 错误状态与消息
- 不确定性阈值配置
## 使用示例
### 创建LLM评估数据集
```python
from evidently import Report, Dataset, DataDefinition
from evidently.descriptors import Sentiment, TextLength, Contains
eval_dataset = Dataset.from_pandas(
pd.DataFrame(eval_df),
data_definition=DataDefinition(),
descriptors=[
Sentiment("answer", alias="Sentiment"),
TextLength("answer", alias="Length"),
Contains("answer", pattern="denial_words", alias="ContainsDenial")
]
)
```
### 生成评估报告
```python
report = Report(metrics=[
TextEvals()
])
report.run(reference_dataset=reference_data, current_dataset=current_data)
report.save_html("evaluation_report.html")
```
## 技术实现要点
### 前端状态管理
评判器模板组件使用React Hook Form进行表单状态管理，配合Zod进行数据验证：
```typescript
// 资料来源：ui/packages/evidently-ui-lib/src/components/Descriptors/Features/LLMJudge/template.tsx
type FormSchema = z.infer
const formSchema = z.object({...})
```
### 错误处理机制
系统实现了多层次的错误处理：
1. **表单级错误**：通过`errors`对象捕获并展示字段级验证错误
2. **API级错误**：通过`isLoading`状态管理异步操作错误
3. **业务逻辑错误**：通过`AlertThemed`组件展示业务规则违反
## 相关资源
- [API Reference Documentation](https://evidentlyai.github.io/evidently/api-reference)
- [LLM Evaluation Tutorial](https://docs.evidentlyai.com/quickstart_llm)
- [Descriptor Configuration Guide](https://docs.evidentlyai.com/descriptors)
---
## Guardrails安全护栏
### 相关页面
相关主题：[LLM集成与评判器](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [ui/packages/evidently-ui-lib/src/components/Traces/TraceViewer/components/GuardRailsShowInfoButton.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Traces/TraceViewer/components/GuardRailsShowInfoButton.tsx)
- [ui/packages/evidently-ui-lib/src/components/Traces/TraceViewer/components/TraceTable.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Traces/TraceViewer/components/TraceTable.tsx)
- [ui/packages/evidently-ui-lib/src/components/Traces/TraceViewer/components/TraceComponent.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Traces/TraceViewer/components/TraceComponent.tsx)
- [ui/packages/evidently-ui-lib/src/components/Traces/TracesTable.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Traces/TracesTable.tsx)
- [ui/packages/evidently-ui-lib/src/components/Descriptors/Features/LLMJudge/template.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Descriptors/Features/LLMJudge/template.tsx)
- [src/evidently/ui/utils.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/utils.py)
# Guardrails安全护栏
## 概述
Guardrails（安全护栏）是Evidently框架中用于监控和验证LLM（大型语言模型）输出的安全机制。该功能允许用户在追踪（Traces）中记录、检查和展示护栏的检查结果，确保AI系统的输出符合预定的安全和合规标准。
在Evidently的架构中，Guardrails主要与Trace系统集成，通过`extractGuardRailsDataFromSpan`函数从span中提取护栏数据，并在UI层面提供可视化展示。资料来源：[TraceTable.tsx:22-32]()
## 核心功能
### 护栏数据提取
Guardrails的数据来源于Trace中的各个span。通过`extractGuardRailsDataFromSpan`函数，系统能够从span中提取护栏相关的检查信息，包括：
- **状态信息**：护栏检查通过或失败
- **名称标识**：具体护栏类型的名称
- **详细属性**：每个护栏的完整属性映射
```typescript
// 从span中提取GuardRails数据
trace.spans
.map(extractGuardRailsDataFromSpan)
.filter(isNotNull)
.flat()
```
资料来源：[TraceTable.tsx:22-32]()
### 护栏状态展示
UI层提供了专门的`GuardRailStatus`组件来可视化展示护栏的通过/失败状态，通过颜色编码（绿色表示通过，红色表示失败）帮助用户快速识别问题。
资料来源：[TraceComponent.tsx:12-16]()
## 架构设计
### 组件层级关系
```mermaid
graph TD
A[Trace] --> B[Spans]
B --> C[GuardRails Data]
C --> D[GuardRailsShowInfoButton]
D --> E[GuardRailDialog]
E --> F[GenericTable]
F --> G[GuardRailStatus]
A1[TraceTable] --> B1[GuardRails列]
B1 --> C1[GuardRailsShowInfoButton]
```
### 护栏对话框流程
```mermaid
sequenceDiagram
participant User as 用户
participant Button as GuardRailsShowInfoButton
participant Dialog as GuardRailDialog
participant Table as GenericTable
User->>Button: 查看护栏详情
Button->>Dialog: setIsGuardRailDialogOpen(true)
Dialog->>Table: 渲染护栏数据
Table->>User: 显示通过/失败统计
Note over Table: 统计passed/failed数量
```
## 数据结构
### 护栏数据模型
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 护栏唯一标识符 |
| `name` | string | 护栏名称（如toxicity、pii等） |
| `status` | enum | 护栏状态：passed/failed |
| `index` | number | 护栏在序列中的位置 |
### 护栏按钮状态
| 状态类型 | 条件 | 按钮样式 |
|----------|------|----------|
| all-passed | 所有护栏通过 | outlined + success颜色 |
| failed | 存在护栏失败 | contained + error颜色 |
资料来源：[GuardRailsShowInfoButton.tsx:10-20]()
## UI组件详解
### GuardRailsShowInfoButton
该组件是护栏信息的入口按钮，根据护栏通过/失败状态显示不同的UI样式：
```typescript
```
资料来源：[GuardRailsShowInfoButton.tsx:10-22]()
### GuardRailDialog
对话框组件用于展示完整的护栏检查结果：
```typescript
```
资料来源：[GuardRailsShowInfoButton.tsx:33-56]()
### TraceTable中的护栏列
在TraceTable组件中，护栏作为独立的列进行展示，支持条件渲染（当所有span均无护栏数据时跳过该列）：
```typescript
{
key: 'guardrails',
label: 'Guardrails',
align: 'center',
skipRender: data.every(
(trace) =>
trace.spans.map(extractGuardRailsDataFromSpan)
.filter(isNotNull).flat().length === 0
),
render: (trace) => (
)
}
```
资料来源：[TraceTable.tsx:22-42]()
## 护栏渲染详情
在TraceComponent中，护栏数据以表格形式展示每个属性的键值对：
```typescript
{Object.entries(guardRail).map(([k, v]) => (
{k}
{k === 'status' ? (
) : (
)}
))}
```
资料来源：[TraceComponent.tsx:18-34]()
## 配置选项
### 护栏对话框配置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `open` | boolean | - | 对话框打开状态 |
| `fullWidth` | boolean | true | 宽度占满容器 |
| `maxWidth` | string | 'md' | 最大宽度 |
| `PaperComponent` | component | Box | 纸张组件包装 |
### 按钮样式配置
| 样式条件 | color | variant |
|----------|-------|---------|
| 全部通过 | 'success' | 'outlined' |
| 存在失败 | 'error' | 'contained' |
资料来源：[GuardRailsShowInfoButton.tsx:10-22]()
## 使用场景
### 在Trace追踪中集成护栏
```typescript
// 在TraceViewer中展示护栏信息
{childSelectedSpans.length > 0 && (
Child spans
)}
```
### 条件渲染护栏列
当项目中没有任何护栏数据时，对应的表格列会被自动隐藏，优化用户界面：
```typescript
skipRender: data.every(
(trace) =>
trace.spans.map(extractGuardRailsDataFromSpan)
.filter(isNotNull).flat().length === 0
)
```
资料来源：[TraceTable.tsx:26-30]()
## 与其他模块的集成
### 与LLM Judge的关联
在LLM Judge模板中，护栏系统与评估标准协同工作，支持多类别评估标准的配置：
```typescript
{state.type === 'evidently:prompt_template:MulticlassClassificationPromptTemplate' && (
Classes
{Object.keys(state.category_criteria ?? {}).map((className) => (
))}
)}
```
资料来源：[LLMJudge/template.tsx:35-45]()
### 与项目管理的集成
通过ProjectCard组件，用户可以在项目管理界面中快速访问包含护栏数据的Trace记录，实现端到端的安全监控工作流。
## 最佳实践
### 护栏数据过滤
```typescript
// 使用filter和flat处理多span场景
trace.spans
.map(extractGuardRailsDataFromSpan)
.filter(isNotNull)
.flat()
```
### 状态判断逻辑
```typescript
const guardRailButtonInfoType =
passedGuardRailDataCount === allGuardRailDataCount
? 'all-passed'
: 'failed'
```
资料来源：[GuardRailsShowInfoButton.tsx:1-8]()
## 总结
Guardrails安全护栏是Evidently框架中保障LLM应用安全的重要组件。通过与Trace系统的深度集成，它提供了：
- **可视化监控**：直观的UI展示护栏检查结果
- **状态追踪**：通过颜色编码快速识别安全问题
- **条件渲染**：智能隐藏无数据列，保持界面整洁
- **详情查看**：对话框形式展示完整护栏属性
该系统为AI安全工程师和开发团队提供了有效的工具，用于监控和验证AI模型的输出是否符合预期的安全标准。
---
## 数据管理与存储
### 相关页面
相关主题：[报告与测试套件](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [src/evidently/ui/service/datasets/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/datasets/__init__.py)
- [src/evidently/ui/service/storage/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/storage/__init__.py)
- [src/evidently/ui/service/storage/local/base.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/storage/local/base.py)
- [src/evidently/ui/service/storage/sql/base.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/storage/sql/base.py)
- [src/evidently/ui/service/storage/sql/dataset.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/storage/sql/dataset.py)
- [src/evidently/ui/service/datasets/models.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/datasets/models.py)
- [src/evidently/core/datasets.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/datasets.py)
# 数据管理与存储
## 概述
Evidently 的数据管理与存储系统是框架的核心组件之一，负责处理数据集的持久化、检索和管理。该系统采用分层架构设计，支持多种存储后端，为 ML 和 LLM 系统的评估、测试与监控提供了可靠的数据基础设施。
系统的主要职责包括：
- 数据集的创建、读取、更新和删除（CRUD）操作
- 支持本地文件系统存储和 SQL 数据库存储两种后端
- 提供统一的数据访问接口，屏蔽底层存储差异
- 管理数据集的元数据信息
- 支持数据集与项目、快照的关联关系
资料来源：[src/evidently/ui/service/storage/__init__.py]()
## 架构设计
### 整体架构
系统采用典型的分层架构模式，自上而下分为三个主要层次：
```mermaid
graph TD
A[应用层] --> B[服务层]
B --> C[存储层]
C --> D[本地存储]
C --> E[SQL 存储]
B --> F[数据集服务
Datasets Service]
F --> G[数据模型
DatasetModel]
D --> H[本地文件系统]
E --> I[(SQLite/PostgreSQL)]
```
### 存储后端类型
| 存储类型 | 文件路径 | 适用场景 |
|---------|---------|---------|
| 本地存储 | `storage/local/base.py` | 开发环境、单节点部署 |
| SQL 存储 | `storage/sql/base.py` | 生产环境、多用户协作 |
资料来源：[src/evidently/ui/service/storage/local/base.py](), [src/evidently/ui/service/storage/sql/base.py]()
## 核心数据模型
### 数据集模型
`DatasetModel` 是数据集的核心数据结构，定义了数据集的所有属性：
```python
class DatasetModel:
id: DatasetID # 唯一标识符
project_id: ProjectID # 所属项目ID
name: str # 数据集名称
description: Optional[str] # 数据集描述
metadata: DatasetMetadata # 元数据信息
created_at: datetime # 创建时间
updated_at: datetime # 更新时间
author: Optional[str] # 创建者
```
资料来源：[src/evidently/ui/service/datasets/models.py]()
### 元数据结构
```python
@dataclass
class DatasetMetadata:
created_at: datetime # 创建时间戳
updated_at: datetime # 更新时间戳
author: Optional[str] # 创建者信息
description: Optional[str] # 描述信息
tags: Optional[List[str]] # 标签列表
link: Optional[str] # 关联链接
```
资料来源：[src/evidently/ui/service/datasets/models.py]()
## 服务层组件
### 数据集服务
数据集服务（`DatasetsService`）是应用层与存储层之间的桥梁，提供统一的数据集操作接口：
| 方法 | 功能描述 |
|-----|---------|
| `add()` | 创建新数据集 |
| `load()` | 加载数据集内容 |
| `list()` | 列出项目中的所有数据集 |
| `delete()` | 删除指定数据集 |
资料来源：[src/evidently/ui/service/datasets/__init__.py]()
### 服务工作流
```mermaid
sequenceDiagram
participant Client
participant DatasetsService
participant StorageLayer
participant Backend
Client->>DatasetsService: add_dataset(project_id, dataset)
DatasetsService->>StorageLayer: save(dataset)
StorageLayer->>Backend: write data
Backend-->>StorageLayer: confirmation
StorageLayer-->>DatasetsService: saved dataset
DatasetsService-->>Client: dataset ID
Client->>DatasetsService: load_dataset(dataset_id)
DatasetsService->>StorageLayer: retrieve(dataset_id)
StorageLayer->>Backend: read data
Backend-->>StorageLayer: data
StorageLayer-->>DatasetsService: Dataset object
DatasetsService-->>Client: Dataset
```
## 存储层实现
### 存储接口抽象
存储层定义了统一的抽象接口，具体实现类负责与不同的存储后端交互：
```python
class BaseStorage(ABC):
"""存储层抽象基类"""
@abstractmethod
def save(self, dataset: Dataset) -> DatasetID: ...
@abstractmethod
def load(self, dataset_id: DatasetID) -> Dataset: ...
@abstractmethod
def list(self, project_id: ProjectID) -> DatasetList: ...
@abstractmethod
def delete(self, dataset_id: DatasetID) -> None: ...
```
资料来源：[src/evidently/ui/service/storage/__init__.py]()
### 本地存储实现
本地存储适配器使用文件系统作为数据持久化后端：
| 配置项 | 说明 |
|-------|------|
| `base_path` | 存储根目录路径 |
| `format` | 数据序列化格式（JSON/Parquet） |
| `max_size_mb` | 单个数据集大小限制 |
**数据组织结构：**
```
{base_path}/
└── {project_id}/
└── {dataset_id}/
├── data.{format}
└── metadata.json
```
资料来源：[src/evidently/ui/service/storage/local/base.py]()
### SQL 存储实现
SQL 存储适配器支持多种关系型数据库：
```python
class SQLStorage(BaseStorage):
"""SQL 数据库存储实现"""
def __init__(
self,
connection_string: str,
table_prefix: str = "evidently_"
):
self.engine = create_engine(connection_string)
self.table_prefix = table_prefix
```
**支持的数据库：**
| 数据库 | 连接字符串格式 |
|-------|---------------|
| SQLite | `sqlite:///path/to/db.sqlite` |
| PostgreSQL | `postgresql://user:pass@host:5432/db` |
资料来源：[src/evidently/ui/service/storage/sql/base.py](), [src/evidently/ui/service/storage/sql/dataset.py]()
## 核心数据集模块
### 核心数据集类
`Dataset` 类是框架层面的数据集抽象，定义在核心模块中：
```python
class Dataset:
"""数据集核心抽象"""
def __init__(
self,
dataframe: pd.DataFrame,
data_definition: DataDefinition,
descriptors: Optional[List[Descriptor]] = None
):
self._dataframe = dataframe
self._data_definition = data_definition
self._descriptors = descriptors or []
```
资料来源：[src/evidently/core/datasets.py]()
### 数据集工厂方法
```python
@classmethod
def from_pandas(
cls,
dataframe: pd.DataFrame,
data_definition: DataDefinition = None,
descriptors: List[Descriptor] = None
) -> "Dataset":
"""从 Pandas DataFrame 创建数据集"""
...
```
资料来源：[src/evidently/core/datasets.py]()
## API 端点
数据集相关的 REST API 端点：
| 方法 | 端点 | 功能 |
|-----|------|-----|
| POST | `/api/v2/datasets/{project_id}` | 创建数据集 |
| GET | `/api/v2/datasets/{dataset_id}` | 获取数据集 |
| GET | `/api/v2/datasets` | 列出数据集 |
| PUT | `/api/v2/datasets/{dataset_id}` | 更新数据集 |
| DELETE | `/api/v2/datasets/{dataset_id}` | 删除数据集 |
## 配置指南
### 存储后端配置
```python
from evidently.ui.service.storage import WorkspaceStorage
# 本地存储配置
local_storage = WorkspaceStorage.local(
base_path="./data/evidently",
format="parquet"
)
# SQL 存储配置
sql_storage = WorkspaceStorage.sql(
connection_string="sqlite:///evidently.db",
table_prefix="ev_"
)
```
### 环境变量配置
| 变量名 | 说明 | 默认值 |
|-------|------|-------|
| `EVIDENTLY_DATA_DIR` | 本地存储路径 | `./evidently_data` |
| `EVIDENTLY_DB_URL` | 数据库连接字符串 | SQLite 本地文件 |
| `EVIDENTLY_STORAGE_TYPE` | 存储类型 | `local` |
## 数据流转
```mermaid
graph LR
A[CSV/Parquet] --> B[DataLoader]
B --> C[Dataset]
C --> D[Descriptors]
D --> E[Evaluations]
F[Report] --> G[Snapshot]
G --> H[Storage]
C -.->|持久化| H
```
## 最佳实践
### 数据集命名规范
- 使用有意义的名称，包含项目标识和用途
- 避免使用特殊字符和空格
- 推荐格式：`{project}_{purpose}_{version}`
### 存储策略建议
1. **小数据集（< 100MB）**：使用本地存储或 SQLite
2. **中等数据集（100MB - 1GB）**：使用 PostgreSQL
3. **大数据集（> 1GB）**：考虑分区存储或外部存储服务
### 性能优化
- 为 `project_id` 和 `created_at` 字段建立索引
- 定期清理过期数据集
- 使用 Parquet 格式减少存储空间
## 相关模块
- [evidently.sdk.adapters](./sdk/adapters) - 云端适配器
- [evidently.ui.workspace](./ui/workspace) - 工作空间管理
- [evidently.legacy.metrics](./legacy/metrics) - 指标计算
---
## 前端UI组件库
相关源码文件
以下源码文件用于生成本页说明：
- [ui/packages/evidently-ui-lib/src/components/Widgets/DashboardWidgets.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Widgets/DashboardWidgets.tsx)
- [ui/packages/evidently-ui-lib/src/widgets/Widget.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/widgets/Widget.tsx)
- [ui/packages/evidently-ui-lib/src/widgets/BigTableWidget/BigTableDetails.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/widgets/BigTableWidget/BigTableDetails.tsx)
- [ui/packages/evidently-ui-lib/src/components/Traces/TracesTable.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Traces/TracesTable.tsx)
- [ui/packages/evidently-ui-lib/src/components/Traces/TraceViewer/components/TraceTable.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Traces/TraceViewer/components/TraceTable.tsx)
- [ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx)
- [ui/packages/evidently-ui-lib/src/components/Dashboard/Panels/implementations/Text.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Dashboard/Panels/implementations/Text.tsx)
- [ui/packages/evidently-ui-lib/src/components/Tabs/BaseTabs.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Tabs/BaseTabs.tsx)
- [ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx)
- [ui/packages/evidently-ui-lib/src/components/Dashboard/DashboardDateFilter.tsx](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/src/components/Dashboard/DashboardDateFilter.tsx)
# 前端UI组件库
## 概述
Evidently UI组件库（`evidently-ui-lib`）是一个共享的前端组件包，同时服务于 `service`（服务模式）和 `standalone`（独立模式）两种部署场景。该组件库基于React和TypeScript构建，集成了Material UI（@mui/material）作为基础UI框架，提供数据可视化、仪表板、追踪管理、提示词管理等核心功能模块。
资料来源：[ui/packages/evidently-ui-lib/README.md](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/README.md)
## 架构概览
```mermaid
graph TD
A[evidently-ui-lib] --> B[Dashboard 模块]
A --> C[Traces 模块]
A --> D[Prompts 模块]
A --> E[Datasets 模块]
A --> F[Widgets 模块]
A --> G[通用组件]
B --> B1[DashboardWidgets]
B --> B2[DashboardPanel]
B --> B3[DashboardDateFilter]
C --> C1[TracesTable]
C --> C2[TraceTable]
C --> C3[DialogViewer]
C --> C4[TraceViewer]
D --> D1[PromptsTable]
D --> D2[CreatePromptForm]
D --> D3[Edit Prompt]
F --> F1[Widget]
F --> F2[BigTableDetails]
F --> F3[AlertBlock]
F --> F4[InsightBlock]
G --> G1[BaseTabs]
G --> G2[NameAndDescriptionForm]
G --> G3[TextPanel]
```
## 核心模块
### 1. 仪表板模块（Dashboard）
仪表板模块负责展示监控面板和数据可视化组件，支持时间范围过滤和多种面板类型。
#### DashboardWidgets 组件
主仪表板渲染组件，根据传入的 `WidgetInfo[]` 数组动态渲染监控面板。
| 属性 | 类型 | 说明 |
|------|------|------|
| `widgets` | `WidgetInfo[]` | 要渲染的组件信息数组 |
```tsx
// 资料来源：ui/packages/evidently-ui-lib/src/components/Widgets/DashboardWidgets.tsx
export const DashboardWidgets = ({ widgets }: { widgets: WidgetInfo[] }) => {
if (widgets.length === 0) {
return (
This dashboard is currently empty. Please add a monitoring panel to start.
)
}
return
}
```
#### DashboardPanel 面板系统
支持多种面板类型，包括文本面板、数值面板、图表面板等。
```mermaid
graph LR
A[面板类型] --> B[text 文本面板]
A --> C[line_plot 线图面板]
A --> D[big_table 大表格面板]
B --> B1[PanelCardGeneral]
C --> C1[LinePlot 渲染]
D --> D1[BigTableDetails]
```
**Text 文本面板**实现示例：
```tsx
// 资料来源：ui/packages/evidently-ui-lib/src/components/Dashboard/Panels/implementations/Text.tsx
export type TextPanelProps = MakePanel<{
type: 'text'
size: 'full' | 'half'
title?: string
description?: string
}>
export const TextDashboardPanel = ({ title, description }: TextPanelProps) => {
return (
)
}
```
#### 日期过滤器
仪表板支持日期范围过滤，用于限制数据展示的时间区间。
```tsx
// 资料来源：ui/packages/evidently-ui-lib/src/components/Dashboard/DashboardDateFilter.tsx
// 支持 dateFrom 和 dateTo 两个日期选择器
// 当 dateFrom 晚于 dateTo 时显示错误提示
Error
Incorrect time interval
```
### 2. 追踪模块（Traces）
追踪模块负责展示和管理AI应用执行追踪数据，支持查看、过滤、编辑和删除操作。
#### TracesTable 组件
主追踪列表表格，支持排序、分页和多种列展示。
| 列名 | 类型 | 说明 | 可排序 |
|------|------|------|--------|
| `tags` | ReactNode | 追踪标签 | 否 |
| `metadata` | ReactNode | 元数据（JSON格式） | 否 |
| `type` | ReactNode | 追踪来源类型 | 否 |
| `created_at` | string | 创建时间 | 是 |
| `actions` | ReactNode | 操作按钮组 | 否 |
```tsx
// 资料来源：ui/packages/evidently-ui-lib/src/components/Traces/TracesTable.tsx
{
key: 'created_at',
label: 'Created at',
sortable: {
getSortValue: (trace) => trace.created_at,
isDateString: true
},
render: (trace) => (
{dayjs(trace.created_at).locale('en-gb').format('llll')}
)
}
```
#### TraceTable 详情表格
用于追踪详情页面，包含token使用量、Guardrails状态等高级信息。
| 列名 | 说明 | 特殊属性 |
|------|------|----------|
| `end_time` | 结束时间 | - |
| `token_usage` | Token使用量 | - |
| `guardrails` | Guardrails信息 | 条件显示 |
| `actions` | 操作按钮 | sticky |
```tsx
// 资料来源：ui/packages/evidently-ui-lib/src/components/Traces/TraceViewer/components/TraceTable.tsx
{
key: 'guardrails',
label: 'Guardrails',
align: 'center',
skipRender: data.every(
(trace) =>
trace.spans.map(extractGuardRailsDataFromSpan).filter(isNotNull).flat().length === 0
),
render: (trace) => (
)
}
```
#### DialogViewer 对话查看器
用于会话消息展示，支持用户消息和代理消息的双栏显示。
```tsx
// 资料来源：ui/packages/evidently-ui-lib/src/components/Traces/DialogViewer/components/Message.tsx
// 消息组件关键属性
{
message: string // 消息内容
align: 'left' | 'right' // 对齐方向
time: string // 时间戳
}
```
### 3. 提示词模块（Prompts）
提示词管理模块，支持提示词的列表展示、创建、编辑和版本管理。
#### PromptsTable 组件
提示词列表表格，包含以下列：
| 列名 | 渲染内容 | 说明 |
|------|----------|------|
| `id` | ID + 复制按钮 | 支持一键复制 |
| `name` | 文本（最大宽度200px） | 提示词名称 |
| `created_at` | 日期时间格式 | 创建时间 |
| `actions` | 链接 + 删除按钮 | 操作区 |
```tsx
// 资料来源：ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx
{
key: 'id',
label: 'ID',
align: 'center',
render: (prompt) => (
{prompt.id}
)
}
```
#### 表单组件
**通用名称描述表单**：
```tsx
// 资料来源：ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx
export type NameAndDescriptionFormProps = {
defaultValues: {
name?: string
description?: string
}
onSubmit: (data: { name: string; description: string }) => void
isLoading?: boolean
allowSubmitDefaults?: boolean
submitButtonTitle?: string
}
// 使用 zod 进行表单验证
const nameAndDescriptionSchema = z.object({
name: z.string().min(1),
description: z.string()
})
```
**创建提示词表单**：
```tsx
// 资料来源：ui/packages/evidently-ui-lib/src/components/Prompts/Forms/CreatePromptForm.tsx
// 包含 name 字段验证
// 禁用条件：isLoading || !isDirty || Object.keys(errors).length > 0
```
### 4. 组件模块（Widgets）
核心可视化组件系统，负责渲染各类监控面板、告警和洞察信息。
#### Widget 主组件
主组件渲染器，支持标题、内容、详情、告警统计和洞察展示。
```tsx
// 资料来源：ui/packages/evidently-ui-lib/src/widgets/Widget.tsx
// 组件结构
{/* 标题和内容 */}
{title}
{content}
{/* 告警区域 */}
{isAlertsExists ? (
<>
{alertStats ? : <>}
{alerts?.map((alert) => )}
) : <>}
{/* 洞察区域 */}
{isInsightsExists ? (
insights?.map((insight) => )
) : <>}
```
#### BigTableDetails 大表格详情
支持多部分详情展示和洞察信息渲染。
```tsx
// 资料来源：ui/packages/evidently-ui-lib/src/widgets/BigTableWidget/BigTableDetails.tsx
export const BigTableDetails: React.FunctionComponent = (props) => {
return (
{(dashboardContext) => (
{/* 多部分使用 AutoTabs 切换 */}
{props.details.parts.length > 1 ? (
({
title: part.title,
tab: RenderPart(dashboardContext, part, props.widgetSize)
}))}
/>
) : (
RenderPart(dashboardContext, props.details.parts[0], props.widgetSize)
)}
{/* 洞察块渲染 */}
{props.details.insights === undefined ? (
<>
) : (
props.details.insights.map((row) => (
))
)}
)}
)
}
```
### 5. 通用组件
#### BaseTabs 标签页组件
通用的标签页切换组件，支持手风琴模式。
```tsx
// 资料来源：ui/packages/evidently-ui-lib/src/components/Tabs/BaseTabs.tsx
// 属性接口
{
tabs: Array<{
title: string // 标签标题
tab: ReactNode // 标签内容
content?: ReactNode // 可选的额外内容
}>
activeTab: number // 当前激活索引，-1表示全部显示
}
```
#### 工具类组件
| 组件名 | 功能 |
|--------|------|
| `TextWithCopyIcon` | 带复制图标的文本展示 |
| `LoadableView` | 加载状态包装器 |
| `JsonViewThemed` | 主题化JSON查看器 |
| `HidedTags` | 折叠标签组件 |
| `Tooltip` | 提示气泡 |
| `AlertThemed` | 主题化警告框 |
## 数据流向
```mermaid
graph TD
A[API 数据源] --> B[evidently-ui-lib API 模块]
B --> C[组件状态管理]
C --> D[UI 渲染层]
D --> E[DashboardWidgets]
D --> F[TracesTable]
D --> G[PromptsTable]
D --> H[Widget]
E --> I[DrawWidgets]
F --> J[DialogViewer]
G --> K[CreatePromptForm]
H --> L[AlertBlock / InsightBlock]
```
## 类型定义
核心类型定义位于各组件文件及 `api/index.tsx` 模块中：
```tsx
// WidgetInfo 类型（示例）
interface WidgetInfo {
id: string
type: string
title?: string
size: 'full' | 'half'
// ... 其他属性
}
// Trace 类型（示例）
interface Trace {
id: string
trace_id: string
created_at: string
tags: Record[]
metadata: object
origin: string
spans: Span[]
}
// Prompt 类型（示例）
interface Prompt {
id: string | null
name: string
metadata?: {
created_at: string
}
}
```
## 依赖关系
| 依赖包 | 版本/用途 |
|--------|----------|
| React | 18.x - UI框架 |
| @mui/material | Material UI组件库 |
| @emotion/react | 样式解决方案 |
| dayjs | 日期时间处理 |
| zod | 表单验证 |
| react-hook-form | 表单状态管理 |
## 部署模式
组件库支持两种部署模式，通过 `ui/packages/evidently-ui-lib/README.md` 说明：
1. **Service 模式**：作为后端服务的集成UI组件
2. **Standalone 模式**：独立运行的Web应用
两种模式共享同一套组件库，确保UI一致性和代码复用。
---
---
## Doramagic 踩坑日志
项目：evidentlyai/evidently
摘要：发现 19 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Update scikit-learn version requirement to support v1.6.0。
## 1. 安装坑 · 来源证据：Update scikit-learn version requirement to support v1.6.0
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update scikit-learn version requirement to support v1.6.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e82e24d201134e7f8dfa0b564d73fce8 | https://github.com/evidentlyai/evidently/issues/1407 | 来源类型 github_issue 暴露的待验证使用条件。
## 2. 配置坑 · 来源证据：PromptOptimizer throws OpenAIError when using Vertex AI judge
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：PromptOptimizer throws OpenAIError when using Vertex AI judge
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_abf6f9b183ff4892be78fd198f60d8e8 | https://github.com/evidentlyai/evidently/issues/1856 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 3. 运行坑 · 来源证据：IndexError in infer_column_type when column contains only null values
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：IndexError in infer_column_type when column contains only null values
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_44cdd5f2b657432eb8418fb132959ada | https://github.com/evidentlyai/evidently/issues/1764 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 4. 安全/权限坑 · 来源证据：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_872f2b57cd3a4c61ad5c387c8be3208b | https://github.com/evidentlyai/evidently/issues/1410 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：Numpy 2.x support?
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Numpy 2.x support?
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2fc84415b55a43d2be4f7f47cf46d7a1 | https://github.com/evidentlyai/evidently/issues/1557 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 6. 安装坑 · 来源证据：v0.7.12
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.12
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_fcf994a3bcf94b0d9b2c5d6159816728 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.12 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 安装坑 · 来源证据：v0.7.15
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.15
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a9de117bd8e440beab9f7be4af50d710 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.15 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。
## 8. 安装坑 · 来源证据：v0.7.20
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.20
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f0d67058bf2a40218adfb0eea1f1665f | https://github.com/evidentlyai/evidently/releases/tag/v0.7.20 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 9. 能力坑 · 来源证据：v0.7.19
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.7.19
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_52e6ab37edca4901a0aa9fe7b5ba12f1 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.19 | 来源类型 github_release 暴露的待验证使用条件。
## 10. 能力坑 · 来源证据：v0.7.21
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.7.21
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_fe9f0e6e29564afeb5610928cc9bc834 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.21 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 11. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:315977578 | https://github.com/evidentlyai/evidently | README/documentation is current enough for a first validation pass.
## 12. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | last_activity_observed missing
## 13. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:315977578 | https://github.com/evidentlyai/evidently | no_demo; severity=medium
## 14. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:315977578 | https://github.com/evidentlyai/evidently | no_demo; severity=medium
## 15. 安全/权限坑 · 来源证据：Protect this repo from AI-generated PRs
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Protect this repo from AI-generated PRs
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_cfcf13543c3941e88fd7c5f527f95dc3 | https://github.com/evidentlyai/evidently/issues/1879 | 来源类型 github_issue 暴露的待验证使用条件。
## 16. 安全/权限坑 · 来源证据：v0.7.17
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.17
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_305e0831e389460096b4d4b908731b41 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.17 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
## 17. 安全/权限坑 · 来源证据：v0.7.18
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.18
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_19a463a1bb2a4fb2bd5bd894c914cc36 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.18 | 来源类型 github_release 暴露的待验证使用条件。
## 18. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | issue_or_pr_quality=unknown
## 19. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | release_recency=unknown