项目概述

Evidently 是一个开源 Python 框架，专门用于评估、测试和监控机器学习（ML）以及基于大语言模型（LLM）的系统。该项目旨在为数据科学家和 ML 工程师提供全面的模型性能评估工具，支持从离线评估到在线监控的完整生命周期管理。

项目具有以下核心特性：

• 开源免费：采用开源许可证，可自由使用和修改
• 多场景支持：支持分类、回归、自然语言处理等多种模型评估场景
• 丰富的可视化：提供直观的仪表板和报告展示评估结果
• 易于集成：可通过 Python API 或 Web UI 进行集成
• 云端协作：提供 Evidently Cloud 服务支持团队协作

资料来源：README.md

系统架构

Evidently 采用模块化的系统架构，主要包含以下核心组件：

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]

核心模块说明

资料来源：src/evidently/sdk/configs.py

安装方式

基础安装

使用 pip 安装稳定版本：

pip install evidently

开发版本安装

从源码安装最新开发版本：

pip install git+https://github.com/evidentlyai/evidently.git

扩展模块安装

根据需要安装额外的依赖模块：

# 基础模块
pip install evidently

# 扩展指标模块
pip install evidently.metrics

# LLM Guardrails 模块
pip install evidently.guardrails

资料来源：api-reference/README.md

SDK 配置与使用

配置元数据

Evidently SDK 提供了完整的配置管理功能，通过 ConfigMetadata 类管理配置元信息：

ConfigMetadata(
    created_at=datetime,      # 创建时间
    updated_at=datetime,      # 更新时间
    author=str,               # 作者
    description=str           # 配置描述
)

资料来源：src/evidently/sdk/configs.py:1-20

工作区管理

Workspace 模块负责管理项目和实验配置：

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

关键方法说明：

资料来源：src/evidently/ui/workspace.py

描述符配置

Descriptor Config 用于存储和版本化管理描述符配置：

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

依赖要求

最小依赖

Evidently 的核心功能需要以下最小依赖集：

• Python >= 3.8
• pandas
• numpy
• scikit-learn

完整依赖

完整安装包含所有可选依赖，适用于完整的模型评估和监控场景。

资料来源：requirements.min.txt

Web UI 组件

前端组件架构

Evidently UI 采用 React 和 Material-UI 构建，提供现代化的用户界面：

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 组件

资料来源：ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx

快速开始

步骤一：安装 Evidently

pip install evidently

步骤二：创建评估报告

from evidently.dashboard import Dashboard
from evidently.tabs import DataDriftTab, CatTargetDriftTab

# 创建仪表板
dashboard = Dashboard(tabs=[DataDriftTab(), CatTargetDriftTab()])

# 运行评估
dashboard.calculate(reference_data, current_data)

步骤三：导出报告

dashboard.save_html("report.html")

进一步资源

1. 概述

Evidently 是一个开源的机器学习与 LLM 驱动系统的评估、测试和监控框架。该项目采用模块化设计，将核心评估逻辑与用户界面分离，同时提供 SDK 和 Web UI 两种交互方式。

核心设计目标：

• 提供可复用的评估指标和报告生成能力
• 支持本地运行和云端服务两种部署模式
• 实现配置版本化管理
• 支持多项目组织和团队协作

资料来源：README.md:1-10

2. 整体架构

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 是系统的核心，提供了评估、报告生成和配置管理的功能。

graph LR
    subgraph "SDK Module"
        CONFIGS[Configs]
        ADAPTERS[Adapters]
        REPORT[Report]
        METRICS[Metrics]
    end
    
    CONFIGS --> ADAPTERS
    REPORT --> METRICS

主要组件：

资料来源：src/evidently/sdk/configs.py:1-50

3.2 Workspace 服务层

Workspace 是项目管理的核心抽象，提供了项目级别的操作接口。

classDiagram
    class Workspace {
        <<abstract>>
        +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 核心接口：

资料来源：src/evidently/ui/workspace.py:1-60

3.3 配置版本管理

系统采用 ConfigVersion 机制管理配置的版本，支持配置的创建、更新和历史追溯。

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]

配置类型支持：

资料来源：src/evidently/sdk/adapters.py:1-40

4. 前端架构

4.1 UI 组件结构

Web UI 采用 React + TypeScript 构建，主要组件位于 ui/packages/evidently-ui-lib/。

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

核心组件：

资料来源：ui/packages/evidently-ui-lib/src/widgets/Widget.tsx:1-30

4.2 状态管理

表单状态使用 React Hook Form 结合 Zod 进行验证：

// 表单验证流程
Form → useForm → zodResolver → NameAndDescriptionForm

表单验证模式：

资料来源：ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx:1-40

5. 报告与评估系统

5.1 Report 核心流程

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. 生成报告：汇总结果并生成可视化输出

示例支持的描述符：

资料来源：README.md:80-120

5.2 评估预设

系统提供多种评估预设，简化常见评估场景的配置：

资料来源：README.md:60-80

6. API 参考文档生成

项目使用 pdoc 工具自动生成 API 参考文档。

graph TD
    A[generate.py] --> B[Local Source]
    A --> C[Git Revision]
    B --> D[dist/<path>/]
    C --> E[dist/<revision>/]
    
    F[local-dev.sh] --> G[Development Server]
    G --> H[http://localhost:8080]

文档生成命令：

# 本地源码生成
./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/<path-to-repo-with-dashes>/
• Git 构建：dist/<revision>/

资料来源：api-reference/README.md:1-50

7. 部署架构

7.1 组件部署

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 安装方式

资料来源：README.md:40-55

8. 关键技术栈

9. 总结

Evidently 采用清晰的分层架构设计：

1. 核心层 (evidently.core)：定义基础数据类型和报告生成逻辑
2. SDK 层 (evidently.sdk)：提供配置管理、适配器和 API 封装
3. 业务层 (evidently.ui)：实现工作区服务和项目管理
4. 展示层 (ui/): React 前端实现用户交互界面

这种设计使得系统既可以作为 Python 库独立使用，也可以通过 Web UI 进行可视化操作，同时支持本地部署和云端服务两种模式。

概述

指标系统是 Evidently 框架的核心组件之一，负责对机器学习模型和 LLM 支持的系统进行量化和评估。该系统提供了统一的接口来定义、计算、缓存和渲染各类评估指标，涵盖了分类任务、回归任务、数据质量评估以及推荐系统等多个领域。

指标系统通过抽象基类 Metric 和 MetricContainer 建立了灵活可扩展的架构，允许开发者自定义指标并将其集成到评估报告中。 资料来源：src/evidently/core/metric_types.py:1-50

核心架构

指标类型层次结构

Evidently 的指标系统采用面向对象的继承设计，主要分为两大类：

1. 基础指标 (Metric) - 单个指标实现，负责计算具体的评估维度
2. 指标容器 (MetricContainer) - 组合多个指标的容器，支持批量计算和联合渲染

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 中，提供了指标生成、缓存和渲染的统一接口。

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 类维护了所有可用指标的映射关系。

资料来源：src/evidently/core/registries/metrics.py:1-100

指标分类

分类指标 (Classification Metrics)

分类指标用于评估分类模型的性能，支持二分类和多分类场景。

主要指标包括：

资料来源：src/evidently/metrics/classification.py:1-200

回归指标 (Regression Metrics)

回归指标用于评估连续值预测模型的性能。

核心指标：

资料来源：src/evidently/metrics/regression.py:1-200

数据质量指标 (Data Quality Metrics)

数据质量指标用于评估数据集本身的特性，包括完整性、一致性和统计分布。

资料来源：src/evidently/metrics/data_quality.py:1-200

推荐系统指标 (RecSys Metrics)

推荐系统专用指标用于评估协同过滤和内容推荐算法。

资料来源：src/evidently/metrics/recsys.py:1-200

指标执行流程

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 报告

指标定义接口

每个具体指标需要实现以下核心方法：

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 类与用户进行交互。以下是典型使用方式：

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 还提供了预配置的指标组合预设：

资料来源：src/evidently/metrics/__init__.py:1-100

缓存机制

指标系统实现了高效的缓存机制以避免重复计算：

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. 注册到指标注册表

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()

创建自定义指标容器

from evidently.core import MetricContainer

class MyMetricContainer(MetricContainer):
    """自定义指标容器"""
    
    def generate_metrics(self, context):
        return [
            MyMetric(...),
            AnotherMetric(...)
        ]

总结

Evidently 的指标系统提供了灵活、可扩展且功能完整的评估框架。通过抽象基类和注册表机制，开发者可以轻松添加新的指标类型；通过容器模式和缓存机制，系统能够高效处理复杂的评估场景。该系统支持从简单的数据质量检查到高级的 LLM 输出评估等多种应用场景，是 Evidently 框架的核心支柱。

概述

预设评估（Presets）是 Evidently 框架中提供的一种高级评估机制，它将一组相关的指标（Metrics）和测试（Tests）打包成可重用的配置单元。预设评估允许用户通过简单的接口快速对机器学习模型进行全面的性能评估，无需手动配置大量单独的指标。

Evidently 的预设评估系统涵盖多种 ML 任务类型，每种预设针对特定的应用场景提供针对性的评估方案。通过使用预设，用户可以：

• 简化评估流程，减少配置代码量
• 确保评估的一致性和标准化
• 快速获得全面的模型性能洞察
• 支持分类、回归、数据漂移和推荐系统等多种任务类型

架构设计

核心组件关系

预设系统的架构由以下几个核心组件构成：

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

类型层次结构

预设类型系统采用继承和组合模式：

classDiagram
    class Preset {
        <<abstract>>
        +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

分类模型预设 (ClassificationPreset)

分类预设专为二分类和多分类任务设计，提供全面的分类器性能评估。

适用场景：

• 二分类问题（如欺诈检测、流失预测）
• 多分类问题（如图像分类、文本分类）
• 概率校准评估

主要评估指标：

资料来源：src/evidently/presets/classification.py

回归模型预设 (RegressionPreset)

回归预设用于评估回归模型的预测性能。

适用场景：

• 连续值预测
• 时间序列预测
• 价格/数量预测

主要评估指标：

资料来源：src/evidently/presets/regression.py

推荐系统预设 (RecSysPreset)

推荐系统预设专门针对协同过滤和推荐算法进行评估。

适用场景：

• 推荐系统性能评估
• 点击率预测
• 排名质量评估

主要评估指标：

资料来源：src/evidently/presets/recsys.py

文本评估预设 (TextEvalsPreset)

文本评估预设用于评估 LLM 和文本生成模型的输出质量。

适用场景：

• LLM 输出质量评估
• 文本摘要评估
• 问答系统评估
• 语义相似度评估

支持的评估描述符：

资料来源：src/evidently/presets/__init__.py

使用方式

在 Report 中使用预设

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 中使用预设

from evidently import TestSuite
from evidently.presets import RegressionPreset

# 创建带有预设的测试套件
suite = TestSuite(tests=[
    RegressionPreset()
])

suite.run(reference_data=reference, current_data=current)
suite.show()

自定义预设组合

用户可以组合多个预设或添加自定义指标：

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")
])

注册表机制

预设系统使用注册表模式进行管理，确保所有预设类型都能被正确识别和实例化。

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

配置参数

通用配置选项

分类预设配置

漂移预设配置

工作流程

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[返回测试结果]

输出展示

预设评估的输出支持多种展示形式：

最佳实践

选择合适的预设

1. 数据类型驱动：根据输入数据特征选择对应预设
2. 任务类型匹配：二分类使用 ClassificationPreset，多分类考虑类别平衡
3. 监控场景：生产监控优先考虑 DataDriftPreset

性能优化建议

• 避免在同一 Report 中使用过多预设
• 大数据集使用采样策略
• 漂移检测设置合理的检测窗口

常见陷阱

• 忽略数据预处理导致评估偏差
• 混淆参考数据集和当前数据集
• 忽视类别不平衡问题

扩展预设

用户可以创建自定义预设：

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

1. 系统概述

描述符系统是 Evidently 框架中用于对数据集行级别进行评估和特征提取的核心组件。该系统允许用户通过声明式的方式定义文本处理任务，并将这些任务应用到 DataFrame 的指定列上，生成评估结果和衍生特征。

描述符的核心价值在于：

• 行级别评估：对数据集中的每一行数据进行独立评估
• 特征提取：将文本内容转换为可量化的数值特征
• 测试集成：内置支持与测试框架集成，可设置阈值和预期范围
• 结果缓存：通过装饰器实现计算结果缓存，避免重复计算

资料来源：src/evidently/descriptors/__init__.py

2. 核心架构

2.1 架构组件

描述符系统由以下核心组件构成：

graph TD
    A[用户定义描述符] --> B[FeatureDescriptor]
    B --> C[底层 Feature 实现]
    C --> D[评估结果 / 特征值]
    
    E[Dataset] --> F[描述符注册表]
    F --> B
    G[Test Suite] --> B

2.2 FeatureDescriptor 类

FeatureDescriptor 是描述符的顶层封装类，负责整合底层特征实现和可选的测试配置：

FeatureDescriptor(feature=feature, alias=alias, tests=tests)

资料来源：src/evidently/descriptors/generated_descriptors.py:1-50

2.3 描述符注册表机制

描述符通过注册表进行统一管理，支持按类型和名称进行查找：

graph LR
    A[描述符定义] --> B[DescriptorRegistry]
    B --> C[按类型查找]
    B --> D[按名称查找]
    C --> E[返回描述符实例]
    D --> E

注册表提供以下核心功能：

• 注册新的描述符类型
• 根据名称获取描述符
• 维护描述符与底层实现的映射关系

资料来源：src/evidently/core/registries/descriptors.py

3. 内置描述符类型

3.1 文本基础描述符

文本基础描述符主要用于文本数据的量化处理。

#### Sentiment 描述符

情感分析描述符使用预训练模型对文本进行情感评分：

Sentiment("answer", alias="Sentiment")

#### TextLength 描述符

文本长度描述符计算文本的字符数或词数：

TextLength(column_name="response", alias="Response Length")

#### Contains 描述符

关键词匹配描述符检测文本中是否包含指定词语：

Contains(
    column_name="text",
    words_list=["denial", "refuse", "can't"],
    mode="any",  # or "all"
    lemmatize=True,
    alias="Denial Indicator"
)

资料来源：src/evidently/descriptors/text_match.py

3.2 LLM Judge 描述符

LLM Judge 描述符利用大语言模型对文本进行高级语义评估。

#### ContextRelevance 描述符

用于评估检索到的上下文与查询的相关性：

ContextRelevance(
    column_name="context",
    question_column="question",
    alias="context_relevance",
    criteria=default_context_relevance_criteria,
    uncertainty=default_llm_judge_params
)

资料来源：src/evidently/descriptors/_context_relevance.py

3.3 HuggingFace 模型描述符

支持直接调用 HuggingFace 模型进行特定任务：

HuggingFace(
    column_name="text",
    model="cardiffnlp/twitter-roberta-base-sentiment",
    params={"max_length": 512},
    alias="hf_sentiment"
)

#### HuggingFaceToxicity 描述符

专门用于检测文本毒性：

HuggingFaceToxicity(
    column_name="text",
    alias="toxicity_score",
    model=None,  # 使用默认模型
    toxic_label="toxic"
)

资料来源：src/evidently/descriptors/generated_descriptors.py:40-70

4. 使用方式

4.1 在 Dataset 中使用

描述符可以作为 Dataset 创建时的参数传入：

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 与测试框架集成

描述符支持内置的测试配置，可设置阈值和预期范围：

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 工作流程

graph TD
    A[创建 Dataset] --> B[应用描述符列表]
    B --> C[对每行数据进行特征计算]
    C --> D[缓存计算结果]
    D --> E[生成评估报告]
    E --> F{是否配置测试}
    F -->|是| G[执行测试断言]
    F -->|否| H[仅输出特征值]
    G --> I[测试结果]

5. 描述符与 Report 集成

描述符生成的特征可以直接在 Report 中展示：

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 基类创建自定义描述符：

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

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. 性能优化

描述符系统提供以下性能优化机制：

8. 总结

描述符系统是 Evidently 框架中进行文本数据评估的核心模块，通过统一抽象的接口设计，提供了从简单的文本长度统计到复杂的 LLM Judge 语义评估的完整能力覆盖。其与 Dataset 和 Report 系统的深度集成，使得用户可以方便地在机器学习和 LLM 系统的评估流程中使用这些描述符。

描述符系统的设计遵循以下原则：

• 声明式配置：通过参数配置而非代码实现定义评估逻辑
• 可组合性：支持多个描述符组合使用
• 可扩展性：通过继承机制支持自定义描述符
• 测试集成：内置与测试框架的集成能力

概述

报告（Report）与测试套件（Test Suite）是 Evidently 框架的两大核心功能模块，用于评估和监控机器学习及 LLM 支持的系统。这两个模块提供了互补的能力：报告专注于数据探索和可视化分析，而测试套件则用于验证数据质量和模型性能是否满足预期标准。

报告模块通过统计分析生成交互式的可视化图表，帮助数据科学家理解模型行为和数据分布变化。测试套件模块则将评估标准形式化为可执行的测试用例，返回明确的通过/失败状态，便于 CI/CD 流程集成和自动化监控。资料来源：src/evidently/legacy/report/report.py:1-50

核心架构

模块关系图

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 报告模块

功能特性

报告模块提供以下核心功能：

1. 多指标支持：支持 100+ 内置评估指标，覆盖数据质量、分布漂移、分类性能、回归性能等多个维度
2. 灵活的指标组合：通过 metrics 参数可自由组合不同类型的指标
3. 多种输出格式：支持生成 HTML 交互式报告和 JSON 结构化数据
4. 数据集支持：兼容 pandas DataFrame 以及 Evidently 的 Dataset 对象

基本使用流程

graph LR
    A[准备数据] --> B[创建Report实例]
    B --> C[添加Metrics]
    C --> D[调用run方法]
    D --> E[生成报告]
    E --> F[保存/展示]

代码示例

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())

报告生成参数

报告运行方法

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. 与报告互补：测试套件可以复用报告中的指标定义

测试执行流程

graph TD
    A[定义TestSuite] --> B[添加Tests]
    B --> C[加载数据集]
    C --> D[执行run方法]
    D --> E{测试通过?}
    E -->|是| F[记录通过状态]
    E -->|否| G[记录失败详情]
    F --> H[生成TestResult]
    G --> H
    H --> I[返回结果列表]

代码示例

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()}")

测试结果结构

指标与测试的对应关系

指标 (Metric) 到测试 (Test) 的转换

Evidently 框架支持将指标计算结果转换为测试用例，实现评估逻辑的复用：

# 指标 → 测试的映射关系
from evidently.metrics import ColumnSummaryMetric

# 基于指标的测试定义
TestMetric = ColumnSummaryMetric(
    column_name="target",
    quantile=[0.05, 0.95]
)

常用指标分类

遗留版本兼容性

Evidently 保留了遗留版本的 API，确保向后兼容：

Legacy Report

from evidently.legacy.report.report import Report as LegacyReport

# 遗留版本报告创建方式
legacy_report = LegacyReport(
    metrics=[],
    mode='raw'
)

Legacy Test Suite

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. 数据准备

确保输入数据格式正确：

from evidently import Dataset, DataDefinition

# 推荐的数据准备方式
dataset = Dataset.from_pandas(
    pd.DataFrame(data),
    data_definition=DataDefinition()
)

3. 性能优化

对于大规模数据集，建议：

• 使用 verbose_level=0 减少日志输出
• 分批次处理时间序列数据
• 复用 ColumnMapping 配置

输出格式与集成

HTML 报告输出

# 保存为 HTML 文件
report.save_html("output/report.html")

# 或者获取 HTML 字符串
html_content = report.get_html()

JSON 序列化

import json

# 序列化为 JSON
json_data = report.json()
with open("report.json", "w") as f:
    json.dump(json_data, f)

与 Web UI 集成

Evidently UI 支持加载报告文件进行交互式查看：

evidently ui --projects ./projects

生成的报告文件可通过 UI 的文件链接功能展示，模板定义位于 src/evidently/ui/utils.py。资料来源：src/evidently/ui/utils.py:1-50

总结

报告与测试套件共同构成了 Evidently 框架的评估基础设施。报告模块侧重于深入的数据分析和可视化呈现，帮助用户理解模型行为；测试套件模块则提供可自动化的验证机制，确保生产环境的稳定性。两者基于共同的指标体系设计，可实现分析与监控的无缝衔接，是 ML/LLM 系统可靠性的重要保障。

概述

LLM集成与评判器是Evidently框架中用于评估和测试大型语言模型(LLM)输出质量的核心模块。该系统提供了完整的LLM驱动评估能力，支持通过预定义或自定义的评判标准对文本输出进行自动化质量评估。

Evidently的LLM评判器允许用户创建结构化的评估流程，通过提示词模板(prompt templates)定义评估规则，并支持多类别分类、置信度评分等高级评估场景。

系统架构

核心模块结构

评判器配置

描述符配置(Descriptor Config)

描述符配置用于定义单个评估指标的元数据和参数。系统通过ConfigAPI类管理描述符配置的版本化存储。

主要配置方法：

• 创建描述符：add_descriptor() - 添加新的描述符配置
• 获取描述符：get_descriptor() - 根据名称和版本获取描述符
• 更新描述符：通过版本控制机制实现配置的增量更新

多分类评判模板

系统支持多分类评判模板(MulticlassClassificationPromptTemplate)，用于需要将输入分类到多个预定义类别的评估场景。

// 资料来源：ui/packages/evidently-ui-lib/src/components/Descriptors/Features/LLMJudge/template.tsx:67
{state.type === 'evidently:prompt_template:MulticlassClassificationPromptTemplate' && (
  <Stack>
    <Typography variant='h6'>Classes</Typography>
    <Typography variant='body2' color='text.secondary' gutterBottom>
      Provide classes for multiclass classification mode.
    </Typography>
    {/* 类别配置表单 */}
  </Stack>
)}

评判标准配置

评判器支持为每个分类类别定义独立的评判标准，通过category_criteria字典存储类别与对应评判规则的映射关系。

用户界面集成

评判模板编辑组件

前端组件LLMJudge/template.tsx提供了可视化的评判模板配置界面，支持：

• 评判类型选择
• 类别定义与管理
• 置信度阈值配置
• 错误状态展示

提示词管理界面

系统提供完整的提示词生命周期管理：

// 资料来源：ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx
{
  key: 'actions',
  label: 'Action',
  render: (prompt) => (
    <Stack direction='row' gap={1}>
      <GetPromptLinkByID promptId={prompt.id ?? 'none'} />
      <IconButton onClick={() => onDelete(prompt.id ?? '')}>
        <DeleteIcon />
      </IconButton>
    </Stack>
  )
}

支持的操作包括：

• 创建新提示词
• 编辑现有提示词
• 删除提示词
• 复制提示词ID

工作流程

LLM评估流程

graph TD
    A[输入数据] --> B[创建Dataset]
    B --> C[应用Descriptors]
    C --> D[LLM评判器处理]
    D --> E[生成评估结果]
    E --> F[生成Report]

提示词模板配置流程

graph LR
    A[选择评判类型] --> B[配置评判标准]
    B --> C[设置类别阈值]
    C --> D[保存配置版本]
    D --> E[关联到Descriptor]

SDK配置与API

云端配置管理

系统通过CloudConfigAPI类提供云端配置管理能力，支持：

• 配置版本化存储
• 元数据管理
• 远程配置同步

# 资料来源：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适配器负责处理与远程服务的通信，包括：

• 配置上传与下载
• 版本历史查询
• 内容序列化与反序列化

数据模型

配置版本元数据

评判器状态

评判器状态通过React组件管理，包含：

• 当前评判类型
• 类别评判标准映射
• 错误状态与消息
• 不确定性阈值配置

使用示例

创建LLM评估数据集

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")
    ]
)

生成评估报告

report = Report(metrics=[
    TextEvals()
])
report.run(reference_dataset=reference_data, current_dataset=current_data)
report.save_html("evaluation_report.html")

技术实现要点

前端状态管理

评判器模板组件使用React Hook Form进行表单状态管理，配合Zod进行数据验证：

// 资料来源：ui/packages/evidently-ui-lib/src/components/Descriptors/Features/LLMJudge/template.tsx
type FormSchema = z.infer<typeof formSchema>
const formSchema = z.object({...})

错误处理机制

系统实现了多层次的错误处理：

1. 表单级错误：通过errors对象捕获并展示字段级验证错误
2. API级错误：通过isLoading状态管理异步操作错误
3. 业务逻辑错误：通过AlertThemed组件展示业务规则违反

相关资源

• API Reference Documentation
• LLM Evaluation Tutorial
• Descriptor Configuration Guide

概述

Guardrails（安全护栏）是Evidently框架中用于监控和验证LLM（大型语言模型）输出的安全机制。该功能允许用户在追踪（Traces）中记录、检查和展示护栏的检查结果，确保AI系统的输出符合预定的安全和合规标准。

在Evidently的架构中，Guardrails主要与Trace系统集成，通过extractGuardRailsDataFromSpan函数从span中提取护栏数据，并在UI层面提供可视化展示。资料来源：TraceTable.tsx:22-32

核心功能

护栏数据提取

Guardrails的数据来源于Trace中的各个span。通过extractGuardRailsDataFromSpan函数，系统能够从span中提取护栏相关的检查信息，包括：

• 状态信息：护栏检查通过或失败
• 名称标识：具体护栏类型的名称
• 详细属性：每个护栏的完整属性映射

// 从span中提取GuardRails数据
trace.spans
  .map(extractGuardRailsDataFromSpan)
  .filter(isNotNull)
  .flat()

资料来源：TraceTable.tsx:22-32

护栏状态展示

UI层提供了专门的GuardRailStatus组件来可视化展示护栏的通过/失败状态，通过颜色编码（绿色表示通过，红色表示失败）帮助用户快速识别问题。

资料来源：TraceComponent.tsx:12-16

架构设计

组件层级关系

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]

护栏对话框流程

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数量

数据结构

护栏数据模型

护栏按钮状态

资料来源：GuardRailsShowInfoButton.tsx:10-20

UI组件详解

GuardRailsShowInfoButton

该组件是护栏信息的入口按钮，根据护栏通过/失败状态显示不同的UI样式：

<Button
  size='small'
  color={guardRailButtonInfoType === 'all-passed' ? 'success' : 'error'}
  variant={guardRailButtonInfoType === 'all-passed' ? 'outlined' : 'contained'}
>
  {guardRailButtonInfoType === 'all-passed'
    ? `${passedGuardRailDataCount}/${allGuardRailDataCount} passed`
    : `${failedGuardRailDataCount}/${allGuardRailDataCount} failed`}
</Button>

资料来源：GuardRailsShowInfoButton.tsx:10-22

GuardRailDialog

对话框组件用于展示完整的护栏检查结果：

<Dialog
  open={isGuardRailDialogOpen}
  fullWidth
  maxWidth='md'
>
  <DialogTitle>Guard rails</DialogTitle>
  <DialogContent>
    <GenericTable
      data={guardRailData}
      idField='id'
      defaultSort={{ column: 'status', ... }}
    />
  </DialogContent>
</Dialog>

资料来源：GuardRailsShowInfoButton.tsx:33-56

TraceTable中的护栏列

在TraceTable组件中，护栏作为独立的列进行展示，支持条件渲染（当所有span均无护栏数据时跳过该列）：

{
  key: 'guardrails',
  label: 'Guardrails',
  align: 'center',
  skipRender: data.every(
    (trace) =>
      trace.spans.map(extractGuardRailsDataFromSpan)
        .filter(isNotNull).flat().length === 0
  ),
  render: (trace) => (
    <GuardRailsShowInfoButton
      guardRailData={trace.spans
        .map(extractGuardRailsDataFromSpan)
        .filter(isNotNull)
        .flat()}
    />
  )
}

资料来源：TraceTable.tsx:22-42

护栏渲染详情

在TraceComponent中，护栏数据以表格形式展示每个属性的键值对：

{Object.entries(guardRail).map(([k, v]) => (
  <TableRow key={k}>
    <TableCell>
      <Typography>{k}</Typography>
    </TableCell>
    <TableCell>
      {k === 'status' ? (
        <GuardRailStatus guardRailStatus={guardRail.status} />
      ) : (
        <TextWithCopyButton text={String(v)} />
      )}
    </TableCell>
  </TableRow>
))}

资料来源：TraceComponent.tsx:18-34

配置选项

护栏对话框配置

按钮样式配置

资料来源：GuardRailsShowInfoButton.tsx:10-22

使用场景

在Trace追踪中集成护栏

// 在TraceViewer中展示护栏信息
<Stack direction={'row'} gap={1} justifyContent={'space-between'}>
  {childSelectedSpans.length > 0 && (
    <Typography variant='h6'>Child spans</Typography>
  )}
</Stack>

条件渲染护栏列

当项目中没有任何护栏数据时，对应的表格列会被自动隐藏，优化用户界面：

skipRender: data.every(
  (trace) =>
    trace.spans.map(extractGuardRailsDataFromSpan)
      .filter(isNotNull).flat().length === 0
)

资料来源：TraceTable.tsx:26-30

与其他模块的集成

与LLM Judge的关联

在LLM Judge模板中，护栏系统与评估标准协同工作，支持多类别评估标准的配置：

{state.type === 'evidently:prompt_template:MulticlassClassificationPromptTemplate' && (
  <Stack>
    <Typography variant='h6'>Classes</Typography>
    <Stack direction='row' gap={1} alignItems='center'>
      {Object.keys(state.category_criteria ?? {}).map((className) => (
        <Chip key={className} variant='filled' label={className} />
      ))}
    </Stack>
  </Stack>
)}

资料来源：LLMJudge/template.tsx:35-45

与项目管理的集成

通过ProjectCard组件，用户可以在项目管理界面中快速访问包含护栏数据的Trace记录，实现端到端的安全监控工作流。

最佳实践

护栏数据过滤

// 使用filter和flat处理多span场景
trace.spans
  .map(extractGuardRailsDataFromSpan)
  .filter(isNotNull)
  .flat()

状态判断逻辑

const guardRailButtonInfoType = 
  passedGuardRailDataCount === allGuardRailDataCount
    ? 'all-passed'
    : 'failed'

资料来源：GuardRailsShowInfoButton.tsx:1-8

总结

Guardrails安全护栏是Evidently框架中保障LLM应用安全的重要组件。通过与Trace系统的深度集成，它提供了：

• 可视化监控：直观的UI展示护栏检查结果
• 状态追踪：通过颜色编码快速识别安全问题
• 条件渲染：智能隐藏无数据列，保持界面整洁
• 详情查看：对话框形式展示完整护栏属性

该系统为AI安全工程师和开发团队提供了有效的工具，用于监控和验证AI模型的输出是否符合预期的安全标准。

概述

Evidently 的数据管理与存储系统是框架的核心组件之一，负责处理数据集的持久化、检索和管理。该系统采用分层架构设计，支持多种存储后端，为 ML 和 LLM 系统的评估、测试与监控提供了可靠的数据基础设施。

系统的主要职责包括：

• 数据集的创建、读取、更新和删除（CRUD）操作
• 支持本地文件系统存储和 SQL 数据库存储两种后端
• 提供统一的数据访问接口，屏蔽底层存储差异
• 管理数据集的元数据信息
• 支持数据集与项目、快照的关联关系

资料来源：src/evidently/ui/service/storage/__init__.py

架构设计

整体架构

系统采用典型的分层架构模式，自上而下分为三个主要层次：

graph TD
    A[应用层] --> B[服务层]
    B --> C[存储层]
    C --> D[本地存储]
    C --> E[SQL 存储]
    
    B --> F[数据集服务<br/>Datasets Service]
    F --> G[数据模型<br/>DatasetModel]
    
    D --> H[本地文件系统]
    E --> I[(SQLite/PostgreSQL)]

存储后端类型

资料来源：src/evidently/ui/service/storage/local/base.py, src/evidently/ui/service/storage/sql/base.py

核心数据模型

数据集模型

DatasetModel 是数据集的核心数据结构，定义了数据集的所有属性：

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

元数据结构

@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）是应用层与存储层之间的桥梁，提供统一的数据集操作接口：

资料来源：src/evidently/ui/service/datasets/__init__.py

服务工作流

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

存储层实现

存储接口抽象

存储层定义了统一的抽象接口，具体实现类负责与不同的存储后端交互：

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}/
└── {project_id}/
    └── {dataset_id}/
        ├── data.{format}
        └── metadata.json

资料来源：src/evidently/ui/service/storage/local/base.py

SQL 存储实现

SQL 存储适配器支持多种关系型数据库：

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

支持的数据库：

资料来源：src/evidently/ui/service/storage/sql/base.py, src/evidently/ui/service/storage/sql/dataset.py

核心数据集模块

核心数据集类

Dataset 类是框架层面的数据集抽象，定义在核心模块中：

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

数据集工厂方法

@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 端点：

配置指南

存储后端配置

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_"
)

环境变量配置

数据流转

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 - 云端适配器
• evidently.ui.workspace - 工作空间管理
• evidently.legacy.metrics - 指标计算

概述

Evidently UI组件库（evidently-ui-lib）是一个共享的前端组件包，同时服务于 service（服务模式）和 standalone（独立模式）两种部署场景。该组件库基于React和TypeScript构建，集成了Material UI（@mui/material）作为基础UI框架，提供数据可视化、仪表板、追踪管理、提示词管理等核心功能模块。

资料来源：ui/packages/evidently-ui-lib/README.md

架构概览

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[] 数组动态渲染监控面板。

// 资料来源：ui/packages/evidently-ui-lib/src/components/Widgets/DashboardWidgets.tsx
export const DashboardWidgets = ({ widgets }: { widgets: WidgetInfo[] }) => {
  if (widgets.length === 0) {
    return (
      <Typography my={3} align='center' variant='h4'>
        This dashboard is currently empty. Please add a monitoring panel to start.
      </Typography>
    )
  }
  return <DrawWidgets widgets={widgets} />
}

#### DashboardPanel 面板系统

支持多种面板类型，包括文本面板、数值面板、图表面板等。

graph LR
    A[面板类型] --> B[text 文本面板]
    A --> C[line_plot 线图面板]
    A --> D[big_table 大表格面板]
    
    B --> B1[PanelCardGeneral]
    C --> C1[LinePlot 渲染]
    D --> D1[BigTableDetails]

Text 文本面板实现示例：

// 资料来源：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 (
    <PanelCardGeneral
      title={title}
      description={description}
      sxCardContent={{ p: '16px !important' }}
      textCenterAlign
    />
  )
}

#### 日期过滤器

仪表板支持日期范围过滤，用于限制数据展示的时间区间。

// 资料来源：ui/packages/evidently-ui-lib/src/components/Dashboard/DashboardDateFilter.tsx
// 支持 dateFrom 和 dateTo 两个日期选择器
// 当 dateFrom 晚于 dateTo 时显示错误提示
<Collapse in={Boolean(dates.dateFrom && dates.dateTo && dates.dateFrom?.isAfter(dates.dateTo))}>
  <AlertThemed severity='error'>
    <AlertTitle>Error</AlertTitle>
    Incorrect time interval
  </AlertThemed>
</Collapse>

2. 追踪模块（Traces）

追踪模块负责展示和管理AI应用执行追踪数据，支持查看、过滤、编辑和删除操作。

#### TracesTable 组件

主追踪列表表格，支持排序、分页和多种列展示。

// 资料来源：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) => (
    <Typography variant='body2' sx={{ minWidth: 200 }}>
      {dayjs(trace.created_at).locale('en-gb').format('llll')}
    </Typography>
  )
}

#### TraceTable 详情表格

用于追踪详情页面，包含token使用量、Guardrails状态等高级信息。

// 资料来源：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) => (
    <GuardRailsShowInfoButton
      guardRailData={trace.spans
        .map(extractGuardRailsDataFromSpan)
        .filter(isNotNull)
        .flat()}
    />
  )
}

#### DialogViewer 对话查看器

用于会话消息展示，支持用户消息和代理消息的双栏显示。

// 资料来源：ui/packages/evidently-ui-lib/src/components/Traces/DialogViewer/components/Message.tsx
// 消息组件关键属性
{
  message: string      // 消息内容
  align: 'left' | 'right'  // 对齐方向
  time: string         // 时间戳
}

3. 提示词模块（Prompts）

提示词管理模块，支持提示词的列表展示、创建、编辑和版本管理。

#### PromptsTable 组件

提示词列表表格，包含以下列：

// 资料来源：ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx
{
  key: 'id',
  label: 'ID',
  align: 'center',
  render: (prompt) => (
    <Stack direction='row' alignItems='center' justifyContent='center' useFlexGap gap={0.5}>
      <Typography variant='body2'>{prompt.id}</Typography>
      <TextWithCopyIcon showText='' copyText={prompt.id ?? ''} />
    </Stack>
  )
}

#### 表单组件

通用名称描述表单：

// 资料来源：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()
})

创建提示词表单：

// 资料来源：ui/packages/evidently-ui-lib/src/components/Prompts/Forms/CreatePromptForm.tsx
// 包含 name 字段验证
// 禁用条件：isLoading || !isDirty || Object.keys(errors).length > 0

4. 组件模块（Widgets）

核心可视化组件系统，负责渲染各类监控面板、告警和洞察信息。

#### Widget 主组件

主组件渲染器，支持标题、内容、详情、告警统计和洞察展示。

// 资料来源：ui/packages/evidently-ui-lib/src/widgets/Widget.tsx
// 组件结构
<WidgetWrapper>
  <Card>
    <CardContent>
      <Grid container>
        {/* 标题和内容 */}
        <Grid>
          <Typography variant='h5'>{title}</Typography>
          <div>{content}</div>
        </Grid>
        
        {/* 告警区域 */}
        {isAlertsExists ? (
          <>
            {alertStats ? <AlertStatBlock /> : <></>}
            {alerts?.map((alert) => <AlertBlock data={alert} />)}
          </>
        ) : <></>}
        
        {/* 洞察区域 */}
        {isInsightsExists ? (
          insights?.map((insight) => <InsightBlock data={insight} />)
        ) : <></>}
      </Grid>
    </CardContent>
  </Card>
</WidgetWrapper>

#### BigTableDetails 大表格详情

支持多部分详情展示和洞察信息渲染。

// 资料来源：ui/packages/evidently-ui-lib/src/widgets/BigTableWidget/BigTableDetails.tsx
export const BigTableDetails: React.FunctionComponent<BigTableDetailsProps> = (props) => {
  return (
    <DashboardContext.Consumer>
      {(dashboardContext) => (
        <Box>
          {/* 多部分使用 AutoTabs 切换 */}
          {props.details.parts.length > 1 ? (
            <AutoTabs
              tabs={props.details.parts.map((part) => ({
                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) => (
              <InsightBlock key={row.text + row.title + row.severity} data={row} />
            ))
          )}
        </Box>
      )}
    </DashboardContext.Consumer>
  )
}

5. 通用组件

#### BaseTabs 标签页组件

通用的标签页切换组件，支持手风琴模式。

// 资料来源：ui/packages/evidently-ui-lib/src/components/Tabs/BaseTabs.tsx
// 属性接口
{
  tabs: Array<{
    title: string      // 标签标题
    tab: ReactNode      // 标签内容
    content?: ReactNode // 可选的额外内容
  }>
  activeTab: number     // 当前激活索引，-1表示全部显示
}

#### 工具类组件

数据流向

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 模块中：

// 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<string, string>[]
  metadata: object
  origin: string
  spans: Span[]
}

// Prompt 类型（示例）
interface Prompt {
  id: string | null
  name: string
  metadata?: {
    created_at: string
  }
}

依赖关系

部署模式

组件库支持两种部署模式，通过 ui/packages/evidently-ui-lib/README.md 说明：

1. Service 模式：作为后端服务的集成UI组件
2. Standalone 模式：独立运行的Web应用

两种模式共享同一套组件库，确保UI一致性和代码复用。

Pitfall Log / 踩坑日志

项目：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