Evidently 官方示例全览：从 Agentic 追踪到 ML 漂移检测的实战入口指南

• 人工智能
• 大模型
• 模型评测
• AI 评测
• 机器学习
• MLOps
• LLMOps
• 数据可视化

本指南以 Evidently 开源仓库中的 examples/README.md 为骨架，系统梳理官方示例体系的组织方式与使用路径。你将掌握如何从零开始快速上手三类核心场景（Agentic 工作流追踪、LLM 输入/输出质量校验、经典 ML 数据质量与漂移分析），以及 cookbook 短示例、本地服务（service）和 Grafana 可视化集成等进阶用法，并了解每个示例背后对应的源码实现位置，便于直接在本仓库中展开研读与二次开发。

示例仓库的整体定位

Evidently 是一个开源的 ML 与 LLM 可观测性框架，用于对任意 AI 系统或数据管线进行评估、测试与监控，覆盖从表格数据到生成式 AI 的多种场景。仓库中的 examples 目录正是围绕这一目标提供的实战示例集，目的是展示如何用 Evidently 评估、测试和监控不同类型的 AI 系统：Agentic 工作流、LLM 应用与传统 ML 模型。

该目录的核心组织逻辑是"由大到小、由入门到专项"：

• 三个顶层教程（top-level tutorials）给出端到端的最快上手路径；
• cookbook 提供聚焦单一功能的短示例；
• service 演示如何把 Evidently 作为完整系统在本地运行；
• grafana 演示如何把 Evidently 指标导出到 Grafana 外部看板；
• datasets 存放示例所用的样例数据。

官方 README 给出的推荐使用顺序是：先跑三个顶层教程获得整体认知，再用 cookbook 按需摘取实现片段，需要完整工作流时深入 tutorials，希望以完整系统形态运行则使用 service，需要外部可视化则转向 grafana。

三个顶层教程：最快的上手路径

官方文档明确建议新用户从以下三个教程开始：

Agentic 系统：追踪与评估

agentic_systems_tracing.ipynb 展示了 Evidently 在 Agentic 场景下的完整链路：先在 Notebook 内以后台方式启动 Evidently UI 服务，创建项目后通过tracely初始化追踪，随后用@tracely.trace_event()装饰器标记生成推文的多个函数，将每次 LLM 调用的中间步骤记录进项目；之后既可以在 UI 的 Traces 页面逐条查看，也可以通过workspace.load_dataset(dataset_id=export_id)把追踪数据当作普通数据集拉回 Notebook 分析。其关键调用关系如下：

import tracely import evidently.ui.runner as service_runner runner = service_runner.EvidentlyUIRunner() runner.run() workspace = runner.get_workspace() project = workspace.create_project(name="Example project") provider = tracely.init_tracing( address=runner.get_service_url(), api_key="", project_id=project.id, export_name="Tweets", ) @tracely.trace_event() def basic_tweet_generation(topic, model="gpt-3.5-turbo", instructions=""): ...

从源码结构看，src/evidently/ui/runner/ 目录承载了EvidentlyUIRunner的实现，而追踪数据的存储与查询能力与 src/evidently/ui/workspace.py 及 src/evidently/ui/storage/ 中的存储实现相关联。这一示例的价值在于：它把"追踪、回放、评估"三个阶段串成了一条可复用的 Agent 观测流水线。

LLM 输入与输出质量校验

llm_input_output_validation.ipynb 是理解 Evidently 新式Dataset/DataDefinition/ReportAPI 的典型范例，其核心流程分四步：

1. 构造数据：用question/answer两列的 DataFrame 模拟问答样本；
2. 逐行分析（Descriptors）：通过Dataset.from_pandas挂载Sentiment、TextLength、DeclineLLMEval、IncludesWords等描述符，对每条答案计算情感、长度、是否拒绝作答等信号，产出逐行分析表；
3. 汇总报告：用Report([TextEvals()])对描述符结果做汇总，得到整体质量概览；
4. 阈值测试：在描述符上直接挂测试，例如Sentiment(..., tests=[gte(0, alias="Is_non_negative")])、TextLength(..., tests=[lte(150, ...)])，并用TestSummary(success_all=True)汇总测试通过情况，最终再次通过TextEvals报告汇总。

对于超出内置指标的自定义评判标准，示例演示了 LLM-as-a-judge 方案：用BinaryClassificationPromptTemplate定义评判准则与目标/非目标类别，再通过LLMEval("question", template=..., provider="openai", model="gpt-4o-mini")让 LLM 逐条评判问题是否属于合适范围。上述描述符、模板与测试的源码分别位于 src/evidently/descriptors/、src/evidently/llm/templates.py 与 src/evidently/tests/。

经典 ML：数据质量与漂移

classic_ml_validation.ipynb 面向传统表格型机器学习场景，同样走"零配置到精细配置"的两级路径：

• 零配置快速报告：直接Report([DataDriftPreset()], include_tests="True")，用adult_ref与adult_prod两个 DataFrame 运行，即可获得包含测试的漂移评估，并可输出drift_eval.json()/drift_eval.dict()供下游消费；
• 带 DataDefinition 的精细配置：先用DataDefinition(numerical_columns=[...], categorical_columns=[...])显式声明列角色，再用Dataset.from_pandas(df, data_definition=schema)包装参考集与当前集，最后用Report([DataSummaryPreset()])输出数据概要。

这一示例对应的 Preset 实现位于 src/evidently/presets/drift.py 与 src/evidently/presets/dataset_stats.py，而DataDefinition/Dataset的底层定义见 src/evidently/core/datasets.py 与 src/evidently/core/base_types.py。

Cookbook：聚焦单一功能的短示例

cookbook 目录下是"短、聚焦、可快速改造"的功能示例，其 README（examples/cookbook/README.md）列出了全部可用 Notebook：

Cookbook 的适用时机非常明确：想在隔离环境中尝试某个具体功能、想复制一个最小实现模式、想理解单个评估或监控任务而不必走完整工作流。下面按功能域拆解几个最具代表性的 Notebook。

metrics.ipynb：指标体系全景

metrics.ipynb 按主题分块演示了 Evidently 的指标矩阵：

• 数据质量（Data Quality）：ColumnCount、RowCount、EmptyRowsCount、DuplicatedRowCount、DatasetMissingValueCount、AlmostConstantColumnsCount等反映数据集整体健康状况的指标；对数值列使用MinValue/MaxValue/MeanValue/MedianValue/QuantileValue/StdValue，对类别列使用CategoryCount/UniqueValueCount/MissingValueCount/InListValueCount/OutListValueCount，对概率列使用InRangeValueCount(column=..., left=0.5, right=1.)与OutRangeValueCount。报告既支持仅当前数据（report.run(current)），也支持带参考数据（report.run(current, reference)），并可输出dict()/json()。指标实现集中在 src/evidently/metrics/data_quality.py 与 src/evidently/metrics/column_statistics.py；
• 数据漂移（Data Drift）：Notebook 明文列出了可用的统计检验列表——'anderson'、'chisquare'、'cramer_von_mises'、'ed'、'es'、'fisher_exact'、'g_test'、'hellinger'、'jensenshannon'、'kl_div'、'ks'、'mannw'、'empirical_mmd'、'psi'、't_test'、'perc_text_content_drift'、'abs_text_content_drift'、'TVD'、'wasserstein'、'z'。用法示例为ValueDrift(column="Feedback", method="psi", threshold=0.05)；对文本列可指定perc_text_content_drift/abs_text_content_drift。批量场景可用ColumnMetricGenerator(ValueDrift, columns=[...], metric_kwargs={...})自动对多列生成漂移指标。这些检验的实际实现位于 src/evidently/legacy/calculations/stattests/；嵌入漂移则通过EmbeddingsDrift(embeddings_name=..., drift_method=...)搭配DistanceDriftMethod/MMDDriftMethod/RatioDriftMethod/ModelDriftMethod完成，对应实现见 src/evidently/metrics/embeddings.py；
• 回归（Regression）：DataDefinition(..., regression=[Regression(target="Score", prediction="Predicted Score")])声明任务后，可计算MeanError、MAE、MAPE、RMSE、R2Score、AbsMaxError及DummyMAE/DummyMAPE/DummyRMSE等基线指标。特别值得注意的是MAPE的近零值处理策略：zero_handling="replace"（将|target| <= epsilon行的 APE 替换为replace_value，如 0.5）、zero_handling="none"（不做特殊处理）与zero_handling="drop"（直接剔除该类行）；
• 分类（Classification）：支持二分类（标签式BinaryClassification(target=..., prediction_labels=..., pos_label="Positive")与概率式prediction_probas=...）和多分类（标签式与概率式）。概率式场景可用probas_threshold=0.4统一调整决策阈值，并计算TPR/TNR/FPR/FNR/RocAuc/LogLoss及各类*ByLabel指标。相关实现见 src/evidently/metrics/classification.py；
• 自定义指标（Custom Metric）：Notebook 末尾展示了如何借助 src/evidently/core/report.py 的Context与 src/evidently/core/metric_types.py 的SingleValue等底层类型编写自定义指标。

descriptors.ipynb：描述符与特征分析

descriptors.ipynb 专门讲解描述符（Descriptor）机制——一种把原始列"派生"为新分析信号的功能。对应源码位于 src/evidently/descriptors/（含文本长度、情感、LLM 评判、正则匹配、词语出现等），并可通过 src/evidently/descriptors/_custom_descriptors.py 与 src/evidently/descriptors/_generate_descriptors.py 实现自定义与程序化生成描述符。

guardrails.ipynb：LLM 应用护栏

guardrails.ipynb 演示如何在 LLM 应用中对输入/输出设置"护栏"，其核心 API 有四种用法：

• 自定义 Python 函数校验器：PythonFunction(my_validator).validate(input)直接调用，校验失败抛出GuardException；
• 装饰器模式：@guard(PythonFunction(my_validator), input_arg="data")包裹函数；传入守卫列表可叠加多个校验器，例如@guard([PythonFunction(my_validator), PythonFunction(my_validator_2)], input_arg="data")；
• 代码内异常处理：try/except GuardException捕获失败并返回自定义提示，例如f"Validation failed: {e}"；
• 内置守卫：PIICheck()检测个人敏感信息、ToxicityCheck()与NegativityCheck()检测有害/消极内容、IncludesWords(["word"], mode="all", lemmatize=True)校验词语出现，并可与装饰器组合成完整处理链。

这些守卫的实现分布在 src/evidently/guardrails/guards/（negativity、pii_llm、python_function、toxicity、word_presence）以及 src/evidently/guardrails/core.py 与 src/evidently/guardrails/decorators.py。

prompt_registry.ipynb：提示词注册中心

prompt_registry.ipynb 演示在 UI 服务内对提示词做版本化管理的完整生命周期：

• 启动服务后通过workspace.prompts.get_or_create_prompt(project.id, "new prompt")创建或获取提示词；
• prompt.bump_version(system_instruction)追加新版本，prompt.list_versions()查看版本历史，prompt.get_version().content/prompt.get_version("latest").content.as_text()读取指定或最新版本内容；
• prompt.delete_version(prompt.get_version().id)删除某个版本，prompt_to_del.delete()删除整个提示词；
• 模板复用：把LLMJudge(provider="openai", model="gpt-4o-mini", template=BinaryClassificationPromptTemplate(...))的模板存入注册中心，之后用template_prompt.get_version().content.template重建新的 Judge，实现"模板存一处、多处复用"。

提示词相关的后端实现见 src/evidently/ui/api/ 与 src/evidently/sdk/prompts.py，模板类定义在 src/evidently/llm/templates.py。

datagen.ipynb：合成数据生成

datagen.ipynb 介绍evidently.llm.datagen合成数据 API，覆盖四类生成方式（对应实现见 src/evidently/llm/datagen/）：

• 少样本生成（Few-shot）：FewShotDatasetGenerator(kind='twitter posts', count=2, user=UserProfile(role=..., intent=..., tone=...), complexity="medium", examples=[...])，可通过prepared_sample_template预览自动构造的提示词模板，generate()触发生成；默认使用 OpenAI 模型，也可通过provider="anthropic"、model=...、options=AnthropicOptions(api_key=...)无缝切换供应商（选项实现见 src/evidently/llm/options.py）；
• RAG 生成：FileDataCollectionProvider(path="booking_kb.txt")（实现见 src/evidently/llm/rag/index.py）加载知识库，RagDatasetGenerator(data, count=2, include_context=False, user=..., service="booking website")生成贴近真实用户的查询与回答；支持dump("booking_rag.yaml")导出生成配置、RagDatasetGenerator.load(...)重新加载复现；
• 领域化代码评审：把 Evidently 源码.py文件作为语料（FileDataCollectionProvider(path=..., recursive=True, pattern="*.py")），用RagQueryDatasetGenerator生成模拟git diff，再用RagResponseDatasetGenerator基于GenerationSpec(kind="code review")生成对应评审意见；
• 完全自定义模板：通过继承 src/evidently/llm/utils/blocks.py 的PromptBlock定义自定义提示块，配合query_template/response_template与additional_prompt_blocks构造风格化的数据管线。

prompt_optimization 系列与 recsys、regression

prompt_optimization_bookings_example.ipynb、prompt_optimization_code_review_example.ipynb 与 prompt_optimization_tweet_generation_example.ipynb 三个 Notebook 分别以预订助手、代码评审、推文生成为载体，演示提示词优化工作流，其优化器实现位于 src/evidently/llm/optimization/（optimizer.py、scorers.py、prompts.py）。

recsys_metrics.ipynb 覆盖推荐系统评估指标，对应实现集中在 src/evidently/metrics/recsys.py，并在 tests/metrics/recsys/ 下有大量对应测试（如 hit rate、MAP、MRR、NDCG、多样性、个性化、流行度偏差、惊喜度等）。regression_preset.ipynb 则演示回归任务中 Preset 的快捷用法，Preset 定义见 src/evidently/presets/regression.py。

Service 示例：把 Evidently 作为完整系统本地运行

examples/service/README.md 演示如何运行 Evidently UI 服务，并通过 Python API 远程上传、监控一个演示项目（bike rentals 监控）。目录内容如下：

• run_service.sh— 在 Docker 中启动 Evidently UI 服务的脚本；
• remote_demo_project.py— 向运行中的 Evidently 服务上传演示项目的 Python 脚本；
• workspace_tutorial.ipynb— Evidently UI API 的 Jupyter 教程；
• docker_s3_tutorial.ipynb— 使用官方 Docker 镜像配合 S3 / GCS 存储的完整教程。

官方 README 给出两种启动方式：

方式一：Docker（推荐）

bash run_service.sh

脚本内容（examples/service/run_service.sh）本质上是拉取官方镜像并映射端口与工作区目录：

docker run -p 8000:8000 \ -v $(pwd)/workspace:/app/workspace \ --name evidently-service \ --detach \ evidently/evidently-service:latest

启动后服务地址为http://127.0.0.1:8000。目录中还提供了docker-compose.yml与sqlite_config.yaml/postgres_config.yaml，用于配置 SQLite 或 PostgreSQL 存储后端（docker_s3_tutorial.ipynb 则展示了 S3/GCS 对象存储的配置方式）。

方式二：本地直接启动

evidently ui

前提是 Python 环境已安装evidently包，服务同样运行在http://127.0.0.1:8000。UI 服务的入口实现位于 src/evidently/ui/app.py，CLI 命令定义见 src/evidently/cli/ui.py。

上传演示项目

python remote_demo_project.py

脚本（examples/service/remote_demo_project.py）通过RemoteWorkspace("http://localhost:8000")连接服务，从DEMO_PROJECTS["bikes"]取用内置演示项目并执行创建/查询。从源码看，RemoteWorkspace实现于 src/evidently/ui/workspace.py，内置演示项目定义在 src/evidently/ui/service/demo_projects/（对应 legacy 目录下 src/evidently/legacy/ui/demo_projects/ 亦有历史版本）。上传完成后在浏览器打开http://127.0.0.1:8000即可浏览项目与报告。

运行前提：Python 3.10+，安装evidently包（pip install evidently），Docker 方式需要本地装有 Docker。仓库内还提供了本地开发用镜像配置 docker/Dockerfile.service 与 docker/Dockerfile.service.dev，可参考其内容理解服务镜像的构建依赖。

Grafana 示例：把 Evidently 指标接入外部看板

examples/grafana/README.md 说明如何将 Evidently 指标导出并可视化到 Grafana，包含两个可直接复用的子示例：

每个子示例都自带一套完整设施：Docker Compose 编排、预配置的 Grafana 看板（JSON 定义位于 dashboards/data_drift.json 与 dashboards/chatbot_evals.json）、数据源与看板挂载配置（config/grafana_datasources.yaml 与 config/grafana_dashboards.yaml），以及计算并导出 Evidently 指标的脚本（evidently_metrics_calculation.py）。

以数据漂移看板为例，evidently_metrics_calculation.py 展示了"指标计算 → 落库 → 供 Grafana 查询"的典型链路：用DataDefinition(numerical_columns=[...], categorical_columns=[...])声明 NYC 出租车数据（green_tripdata 2022-02）的列角色，构建含ValueDrift(column='prediction')、DriftedColumnsCount()、MissingValueCount(column='prediction')的Report，借助 Prefect 的@task/@flow按日回填 27 天数据，把逐日 drift 值、漂移列数与缺失值占比写入 PostgreSQL（dummy_metrics表），Grafana 再基于这些时序指标渲染看板。LLM 评估看板则围绕对话评测指标做类似处理，其预配置看板与对应说明见 examples/grafana/grafana_llm_evaluation_dashboard/。

适用场景很明确：需要把 Evidently 指标接入既有可观测性技术栈、构建自定义监控看板，或希望复用 Docker Compose 一键拉起 Grafana + 数据存储的环境。若你更想要 Evidently 内置的可视化与完整本地闭环，则优先参考前面的 service 示例。

使用建议与注意事项

综合官方 README 的指引，推荐的学习/使用路径如下：

1. 新用户：按顺序跑完三个顶层教程（agentic_systems_tracing.ipynb → llm_input_output_validation.ipynb → classic_ml_validation.ipynb），建立对追踪、LLM 校验、ML 漂移三条主线的整体认知；
2. 按需取用：用 cookbook 中的短示例摘取与当前任务匹配的实现片段（指标、描述符、护栏、提示词注册中心、合成数据、推荐系统指标、回归 Preset 等）；
3. 完整工作流：需要端到端综合方案时，参考 tutorials 类长示例（cookbook 目录下三个 prompt_optimization 示例可视作"多能力组合"的中间形态）；
4. 系统化运行：需要以服务形态长期运行 Evidently 时，使用 service 的 Docker 方案，并按需切换 SQLite / PostgreSQL / S3 / GCS 存储；
5. 外部可视化：需要把指标送入 Grafana 时，直接复用 grafana 两个子示例的 Docker Compose 与看板 JSON。

注意事项：正如官方 README 的 Notes 所强调，部分示例可能依赖本地数据集、外部服务（如 OpenAI / Anthropic API Key、PostgreSQL）或可选 Python 依赖（如 pyarrow、prefect、joblib、openinference-instrumentation-openai 等），请务必先阅读每个 Notebook 或子目录 README 内的说明完成环境准备；涉及 LLM 评判、合成数据生成的示例需要配置对应模型供应商的 API Key 才能完整运行。仓库中的样例数据（如 datasets/bookings.csv、datasets/code_review.csv）与 test_data/ 下的测试数据（如 adults.parquet、reviews.parquet）可作为实验数据源；若在经典 ML 教程中遇到 OpenML 下载问题，Notebook 内也提供了直接读取仓库内 test_data/adults.parquet 的备选路径。

• 人工智能
• 大模型
• 模型评测
• AI 评测
• 机器学习
• MLOps
• LLMOps
• 数据可视化