evidentlyai/evidently · 上手攻略

仓库：evidentlyai/evidently
链接：https://github.com/evidentlyai/evidently
分类：ai
作者：Tom
更新：2026-07-15

一、是什么

Evidently 是一个开源的 ML 和 LLM 可观测性（Observability）框架，用 Python 编写，用于评估、测试和监控 AI 系统——从传统机器学习模型到生成式 LLM 应用均可覆盖。

核心能力：

离线评测（Reports）：一次性评估模型或数据质量，输出交互式 HTML 报告或 JSON。
测试套件（Test Suites）：在 CI/CD 流水线中加入 pass/fail 断言，适合自动化回归测试。
在线监控（Monitoring）：自托管 UI 或 Evidently Cloud，支持指标随时间追踪和告警。
100+ 内置指标：涵盖数据漂移检测、模型性能（分类/回归/排序/推荐）、LLM 质量评估（Sentiment、Toxicity、RAG 检索相关性、摘要质量等）。

截至 2026 年 3 月，PyPI 下载量超过 3500 万次，GitHub Stars 超 7.3k，被数千家公司用于生产级 AI 质量保障。最新版本约 0.7.x（具体小版本号建议以 PyPI 页面为准）。

二、解决什么问题

AI 系统上线后面临三大隐性风险：

数据漂移（Data Drift）：生产数据分布逐渐偏离训练集，模型精度悄悄下降，却没有感知。
LLM 输出质量不可控：生成内容有无意义、有无毒性、是否幻觉，无法量化。
缺少统一的评估语言：Data Scientist 用 Jupyter 手动看指标，SRE 用另一套监控，两套割裂。

Evidently 提供了统一的评测语言，无论你是 Data Scientist（探索性分析）还是 DevOps（CI/CD 监控），都能用同一套 Python API 或 UI 工作流。

三、快速安装

pip（推荐）

pip install evidently

conda

conda install -c conda-forge evidently

启动本地 UI（可选，含 Demo 项目）

# 方式一：使用 uv（推荐，2025 年主流 Python 运行时）
uv run --with evidently evidently ui --demo-projects all

# 方式二：传统 venv
pip install virtualenv
virtualenv venv && source venv/bin/activate
pip install evidently
evidently ui --demo-projects all

访问 http://localhost:8000 即可使用本地 Demo UI。

四、核心用法

⚠️ 以下代码示例基于 v0.7.x API（2026年最新API细节请以官方文档为准）。Evidently API 在 1.x 版本前可能有 Breaking Changes，建议固化版本号使用。

4.1 快速上手：LLM 质量评测

import pandas as pd
from evidently import Report
from evidently import Dataset, DataDefinition
from evidently.descriptors import Sentiment, TextLength, Contains
from evidently.presets import TextEvals

# 构造问答数据集
eval_df = pd.DataFrame([
    ["What is the capital of Japan?", "The capital of Japan is Tokyo."],
    ["Who painted the Mona Lisa?", "Leonardo da Vinci."],
    ["Can you write an essay?", "I'm sorry, but I can't assist with homework."],
], columns=["question", "answer"])

# 创建 Dataset 并添加行级评估器
eval_dataset = Dataset.from_pandas(
    pd.DataFrame(eval_df),
    data_definition=DataDefinition(),
    descriptors=[
        Sentiment("answer", alias="Sentiment"),
        TextLength("answer", alias="Length"),
        Contains("answer", items=["sorry", "apologize"], mode="any", alias="Denials"),
    ],
)

# 生成评测报告
report = Report([TextEvals()])
my_eval = report.run(eval_dataset)
my_eval  # 在 Jupyter 中直接渲染交互式图表

# 导出
my_eval.json()       # JSON 格式
my_eval.dict()       # Python dict 格式
my_eval.save_html("report.html")  # HTML 文件（离线可分享）

4.2 表格数据漂移检测

import pandas as pd
from sklearn import datasets
from evidently import Report
from evidently.presets import DataDriftPreset

iris_data = datasets.load_iris(as_frame=True)
iris_frame = iris_data.frame

# 基准数据：前60行；当前数据：后90行
report = Report([
    DataDriftPreset(method="psi")  # PSI 方法检测分布漂移
], include_tests="True")

my_eval = report.run(iris_frame.iloc[:60], iris_frame.iloc[60:])
my_eval
my_eval.save_html("drift_report.html")

4.3 测试套件（CI/CD 用）

from evidently import TestSuite
from evidently.presets import DataDriftPreset

suite = TestSuite(tests=[
    DataDriftPreset(method="psi"),
])
suite.run(reference_data=iris_frame.iloc[:60], current_data=iris_frame.iloc[60:])

# 在 CI 中判断是否通过
if suite.as_dict()["summary"]["all_passed"]:
    print("✅ All tests passed")
else:
    print("❌ Tests failed")
    suite.show()  # 在 Jupyter 中查看

4.4 监控 UI（长期运行）

evidently ui --port 8000

或用 Docker：

docker run -p 8000:8000 \
  -v $(pwd)/storage:/evidently/storage \
  evidentlyai/evidently:latest

4.5 LLM-as-a-Judge（高级）

Evidently 支持接入 OpenAI 等 LLM API 做质量评估（需自行配置 API Key，不含在安装包里）：

# 注意：需配置 OPENAI_API_KEY 环境变量
from evidently.llm_evaluators import LLMEvaluator

evaluator = LLMEvaluator(
    provider="openai",
    model="gpt-4o-mini",  # 注：具体 API 用法请参考官方文档，此处示例
    task="relevance",
    reference_answers=["... 正确答案 ..."]
)

五、典型适用场景

场景	推荐的 Preset/工具
上线前模型质量验证	`DataDriftPreset`、`ClassificationPreset`、`RegressionPreset`
RAG 系统质量评估	`TextEvals` + `Sentiment`/`TextLength`/`Contains` 描述符
CI/CD 回归测试	`TestSuite` + `include_tests="True"`
LLM 输出质量监控	`TextEvals` + LLM-as-a-Judge
数据管道质量门禁	`DataQualityPreset`
长期生产监控	`evidently ui` 自托管或 Evidently Cloud

六、坑与注意

API 稳定性：Evidently 在 1.0 前仍有 Breaking Changes，建议在 requirements.txt 中锁定版本（如 evidently==0.7.21，具体稳定版本号请以 PyPI 为准）。
LLM-as-a-Judge 需要额外 API Key：框架本身免费，但调用 GPT-4 等评估模型会产生 OpenAI API 费用。
大文件导出：大型 Report 导出 HTML 可能达数十 MB，不建议直接发邮件。
中文文本支持：Sentiment 等内置描述符主要基于英文；中文场景建议用自定义 LLM-as-a-Judge 或自行接中文模型。
Monitoring UI 需要数据库：自托管监控服务需要额外配置存储（默认 SQLite，生产环境建议 PostgreSQL）。

七、与同类对比

工具	类型	侧重点	许可证
Evidently	开源库+监控平台	ML+LLM 全覆盖，离线+在线均可	Apache-2.0
Arize AI	商业 SaaS	模型监控，托管服务为主	专有
MLflow Tracking	开源	实验管理，非生产监控	Apache-2.0
Prometheus+Grafana	开源	通用指标监控，非 ML 特化	Apache-2.0
RAGAS	开源库	专注 RAG 评测	Apache-2.0

Evidently 的独特优势是同时覆盖传统 ML 和 LLM 评测，且完全自托管无需付费。

八、一句话推荐结论

无论是想给表格模型加数据漂移检测，还是给 RAG pipeline 上质量门禁，Evidently 都是目前最开箱即用的开源选择——一条 pip install evidently 就能开始评测。