{
"canonical_name": "evidentlyai/evidently",
"compilation_id": "pack_77662cb54c4e4f8f91eca7aa9011429a",
"created_at": "2026-05-16T20:11:09.088825+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install evidently` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install evidently",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_11c89fa58d454f31ba9c4457c3c44874"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_4a61e3721dc01a4659b3fcbfe9279c15",
"canonical_name": "evidentlyai/evidently",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/evidentlyai/evidently",
"slug": "evidently",
"source_packet_id": "phit_a034e1beb2e74d109ae3f2cd7483bcbd",
"source_validation_id": "dval_fa1c64f5f5114e2b94febefe6ae8510a"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 847,
"github_stars": 7498,
"one_liner_en": "Evidently is \\u200b\\u200ban open-source ML and LLM observability framework. Evaluate, test, and monitor any AI-powered system or data pipeline. From tabular data to Gen AI. 100+ metrics.",
"one_liner_zh": "Evidently is \\u200b\\u200ban open-source ML and LLM observability framework. Evaluate, test, and monitor any AI-powered system or data pipeline. From tabular data to Gen AI. 100+ metrics.",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:test, git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "evidently",
"title_zh": "evidently 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_a034e1beb2e74d109ae3f2cd7483bcbd",
"page_model": {
"artifacts": {
"artifact_slug": "evidently",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install evidently",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/evidentlyai/evidently#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"断点恢复流程",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Evidently is \\u200b\\u200ban open-source ML and LLM observability framework. Evaluate, test, and monitor any AI-powered system or data pipeline. From tabular data to Gen AI. 100+ metrics."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update scikit-learn version requirement to support v1.6.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_e82e24d201134e7f8dfa0b564d73fce8 | https://github.com/evidentlyai/evidently/issues/1407 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Update scikit-learn version requirement to support v1.6.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：PromptOptimizer throws OpenAIError when using Vertex AI judge",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_abf6f9b183ff4892be78fd198f60d8e8 | https://github.com/evidentlyai/evidently/issues/1856 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：PromptOptimizer throws OpenAIError when using Vertex AI judge",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：IndexError in infer_column_type when column contains only null values",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_44cdd5f2b657432eb8418fb132959ada | https://github.com/evidentlyai/evidently/issues/1764 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：IndexError in infer_column_type when column contains only null values",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_872f2b57cd3a4c61ad5c387c8be3208b | https://github.com/evidentlyai/evidently/issues/1410 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Numpy 2.x support?",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_2fc84415b55a43d2be4f7f47cf46d7a1 | https://github.com/evidentlyai/evidently/issues/1557 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Numpy 2.x support?",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.12",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_fcf994a3bcf94b0d9b2c5d6159816728 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.12 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.7.12",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.15",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_a9de117bd8e440beab9f7be4af50d710 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.15 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.7.15",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.20",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_f0d67058bf2a40218adfb0eea1f1665f | https://github.com/evidentlyai/evidently/releases/tag/v0.7.20 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.7.20",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.7.19",
"category": "能力坑",
"evidence": [
"community_evidence:github | cevd_52e6ab37edca4901a0aa9fe7b5ba12f1 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.19 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.7.19",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.7.21",
"category": "能力坑",
"evidence": [
"community_evidence:github | cevd_fe9f0e6e29564afeb5610928cc9bc834 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.21 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.7.21",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:315977578 | https://github.com/evidentlyai/evidently | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:315977578 | https://github.com/evidentlyai/evidently | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:315977578 | https://github.com/evidentlyai/evidently | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Protect this repo from AI-generated PRs",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_cfcf13543c3941e88fd7c5f527f95dc3 | https://github.com/evidentlyai/evidently/issues/1879 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Protect this repo from AI-generated PRs",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.17",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_305e0831e389460096b4d4b908731b41 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.17 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.7.17",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 19 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Update scikit-learn version requirement to support v1.6.0。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 97,
"forks": 847,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 7498
},
"source_url": "https://github.com/evidentlyai/evidently",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Evidently is \\u200b\\u200ban open-source ML and LLM observability framework. Evaluate, test, and monitor any AI-powered system or data pipeline. From tabular data to Gen AI. 100+ metrics.",
"title": "evidently 能力包",
"trial_prompt": "# evidently - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 evidently 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Evidently is \\u200b\\u200ban open-source ML and LLM observability framework. Evaluate, test, and monitor any AI-powered system or data pipeline. From tabular data to Gen AI. 100+ metrics. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目介绍与安装。围绕“项目介绍与安装”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：指标系统 (Metrics)。围绕“指标系统 (Metrics)”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：预设评估 (Presets)。围绕“预设评估 (Presets)”模拟一次用户任务，不展示安装或运行结果。\n5. page-5：描述符系统 (Descriptors)。围绕“描述符系统 (Descriptors)”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目介绍与安装”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“指标系统 (Metrics)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“预设评估 (Presets)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-5\n输入：用户提供的“描述符系统 (Descriptors)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目介绍与安装”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“指标系统 (Metrics)”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“预设评估 (Presets)”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-5：Step 5 必须围绕“描述符系统 (Descriptors)”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/evidentlyai/evidently\n- https://github.com/evidentlyai/evidently#readme\n- README.md\n- pyproject.toml\n- requirements.min.txt\n- src/evidently/__init__.py\n- src/evidently/core/__init__.py\n- src/evidently/core/base_types.py\n- src/evidently/core/report.py\n- src/evidently/legacy/__init__.py\n- src/evidently/metrics/__init__.py\n- src/evidently/metrics/classification.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 evidently 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: IndexError in infer_column_type when column contains only null values（https://github.com/evidentlyai/evidently/issues/1764）；github/github_issue: Protect this repo from AI-generated PRs（https://github.com/evidentlyai/evidently/issues/1879）；github/github_issue: Numpy 2.x support?（https://github.com/evidentlyai/evidently/issues/1557）；github/github_issue: PromptOptimizer throws OpenAIError when using Vertex AI judge（https://github.com/evidentlyai/evidently/issues/1856）；github/github_issue: Update scikit-learn version requirement to support v1.6.0（https://github.com/evidentlyai/evidently/issues/1407）；github/github_issue: Update evidently hashlib usage for FIPS-Compliant Systems and Security B（https://github.com/evidentlyai/evidently/issues/1410）；github/github_release: v0.7.21（https://github.com/evidentlyai/evidently/releases/tag/v0.7.21）；github/github_release: v0.7.20（https://github.com/evidentlyai/evidently/releases/tag/v0.7.20）；github/github_release: v0.7.19（https://github.com/evidentlyai/evidently/releases/tag/v0.7.19）；github/github_release: v0.7.18（https://github.com/evidentlyai/evidently/releases/tag/v0.7.18）；github/github_release: v0.7.17（https://github.com/evidentlyai/evidently/releases/tag/v0.7.17）；github/github_release: v0.7.16（https://github.com/evidentlyai/evidently/releases/tag/v0.7.16）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "IndexError in infer_column_type when column contains only null values",
"url": "https://github.com/evidentlyai/evidently/issues/1764"
},
{
"kind": "github_issue",
"source": "github",
"title": "Protect this repo from AI-generated PRs",
"url": "https://github.com/evidentlyai/evidently/issues/1879"
},
{
"kind": "github_issue",
"source": "github",
"title": "Numpy 2.x support?",
"url": "https://github.com/evidentlyai/evidently/issues/1557"
},
{
"kind": "github_issue",
"source": "github",
"title": "PromptOptimizer throws OpenAIError when using Vertex AI judge",
"url": "https://github.com/evidentlyai/evidently/issues/1856"
},
{
"kind": "github_issue",
"source": "github",
"title": "Update scikit-learn version requirement to support v1.6.0",
"url": "https://github.com/evidentlyai/evidently/issues/1407"
},
{
"kind": "github_issue",
"source": "github",
"title": "Update evidently hashlib usage for FIPS-Compliant Systems and Security B",
"url": "https://github.com/evidentlyai/evidently/issues/1410"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.7.21",
"url": "https://github.com/evidentlyai/evidently/releases/tag/v0.7.21"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.7.20",
"url": "https://github.com/evidentlyai/evidently/releases/tag/v0.7.20"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.7.19",
"url": "https://github.com/evidentlyai/evidently/releases/tag/v0.7.19"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.7.18",
"url": "https://github.com/evidentlyai/evidently/releases/tag/v0.7.18"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.7.17",
"url": "https://github.com/evidentlyai/evidently/releases/tag/v0.7.17"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.7.16",
"url": "https://github.com/evidentlyai/evidently/releases/tag/v0.7.16"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Evidently is \\u200b\\u200ban open-source ML and LLM observability framework. Evaluate, test, and monitor any AI-powered system or data pipeline. From tabular data to Gen AI. 100+ metrics.",
"effort": "安装已验证",
"forks": 847,
"icon": "code",
"name": "evidently 能力包",
"risk": "可发布",
"slug": "evidently",
"stars": 7498,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"断点恢复流程",
"评测体系"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/evidentlyai/evidently 项目说明书\n\n生成时间：2026-05-16 20:09:11 UTC\n\n## 目录\n\n- [项目介绍与安装](#page-1)\n- [系统架构设计](#page-2)\n- [指标系统 (Metrics)](#page-3)\n- [预设评估 (Presets)](#page-4)\n- [描述符系统 (Descriptors)](#page-5)\n- [报告与测试套件](#page-6)\n- [LLM集成与评判器](#page-7)\n- [Guardrails安全护栏](#page-8)\n- [数据管理与存储](#page-9)\n- [前端UI组件库](#page-10)\n\n\n\n## 项目介绍与安装\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/evidentlyai/evidently/blob/main/README.md)\n- [api-reference/README.md](https://github.com/evidentlyai/evidently/blob/main/api-reference/README.md)\n- [src/evidently/sdk/configs.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)\n- [src/evidently/sdk/adapters.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/adapters.py)\n- [src/evidently/ui/workspace.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/workspace.py)\n- [src/evidently/ui/utils.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/utils.py)\n \n\n# 项目介绍与安装\n\n## 项目概述\n\nEvidently 是一个开源 Python 框架，专门用于评估、测试和监控机器学习（ML）以及基于大语言模型（LLM）的系统。该项目旨在为数据科学家和 ML 工程师提供全面的模型性能评估工具，支持从离线评估到在线监控的完整生命周期管理。\n\n项目具有以下核心特性：\n\n- **开源免费**：采用开源许可证，可自由使用和修改\n- **多场景支持**：支持分类、回归、自然语言处理等多种模型评估场景\n- **丰富的可视化**：提供直观的仪表板和报告展示评估结果\n- **易于集成**：可通过 Python API 或 Web UI 进行集成\n- **云端协作**：提供 Evidently Cloud 服务支持团队协作\n\n资料来源：[README.md](https://github.com/evidentlyai/evidently/blob/main/README.md)\n\n## 系统架构\n\nEvidently 采用模块化的系统架构，主要包含以下核心组件：\n\n```mermaid\ngraph TD\n A[Evidently Core] --> B[Metrics 模块]\n A --> C[Dashboard 模块]\n A --> D[SDK 模块]\n B --> E[数据漂移检测]\n B --> F[模型性能评估]\n B --> G[统计测试]\n C --> H[Web UI]\n C --> I[报告生成]\n D --> J[Cloud API]\n D --> K[Workspace]\n```\n\n### 核心模块说明\n\n| 模块名称 | 功能描述 | 主要类/文件 |\n|---------|---------|------------|\n| Metrics | 核心指标计算 | `evidently.metrics` |\n| Dashboard | 可视化报告 | `ui/packages/evidently-ui-lib` |\n| SDK | 编程接口 | `src/evidently/sdk/` |\n| Workspace | 项目工作区管理 | `src/evidently/ui/workspace.py` |\n| Guardrails | LLM 输出验证 | `evidently.guardrails` |\n\n资料来源：[src/evidently/sdk/configs.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)\n\n## 安装方式\n\n### 基础安装\n\n使用 pip 安装稳定版本：\n\n```bash\npip install evidently\n```\n\n### 开发版本安装\n\n从源码安装最新开发版本：\n\n```bash\npip install git+https://github.com/evidentlyai/evidently.git\n```\n\n### 扩展模块安装\n\n根据需要安装额外的依赖模块：\n\n```bash\n# 基础模块\npip install evidently\n\n# 扩展指标模块\npip install evidently.metrics\n\n# LLM Guardrails 模块\npip install evidently.guardrails\n```\n\n资料来源：[api-reference/README.md](https://github.com/evidentlyai/evidently/blob/main/api-reference/README.md)\n\n## SDK 配置与使用\n\n### 配置元数据\n\nEvidently SDK 提供了完整的配置管理功能，通过 `ConfigMetadata` 类管理配置元信息：\n\n```python\nConfigMetadata(\n created_at=datetime, # 创建时间\n updated_at=datetime, # 更新时间\n author=str, # 作者\n description=str # 配置描述\n)\n```\n\n资料来源：[src/evidently/sdk/configs.py:1-20](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)\n\n### 工作区管理\n\nWorkspace 模块负责管理项目和实验配置：\n\n```mermaid\nclassDiagram\n class Workspace {\n +create_project(name, description, org_id)\n +add_project(project)\n +get_project(project_id)\n +delete_project(project_id)\n +list_projects(org_id)\n }\n \n class ProjectModel {\n +name: str\n +description: str\n +org_id: Optional[OrgID]\n }\n \n Workspace --> ProjectModel\n```\n\n关键方法说明：\n\n| 方法 | 参数 | 返回值 | 功能 |\n|-----|------|-------|------|\n| `create_project` | name, description, org_id | Project | 创建新项目 |\n| `add_project` | project: ProjectModel | Project | 添加项目 |\n| `get_project` | project_id | Optional[Project] | 获取项目 |\n| `delete_project` | project_id | None | 删除项目 |\n| `list_projects` | org_id | Sequence[Project] | 列出项目 |\n\n资料来源：[src/evidently/ui/workspace.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/workspace.py)\n\n### 描述符配置\n\nDescriptor Config 用于存储和版本化管理描述符配置：\n\n```python\ndef save_descriptor(\n project_id: STR_UUID,\n name: str,\n descriptor: Descriptor\n) -> ConfigVersion\n\ndef get_descriptor(\n project_id: STR_UUID,\n name: str,\n version: VersionOrLatest = \"latest\"\n) -> Descriptor\n```\n\n资料来源：[src/evidently/sdk/configs.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)\n\n## 依赖要求\n\n### 最小依赖\n\nEvidently 的核心功能需要以下最小依赖集：\n\n- Python >= 3.8\n- pandas\n- numpy\n- scikit-learn\n\n### 完整依赖\n\n完整安装包含所有可选依赖，适用于完整的模型评估和监控场景。\n\n资料来源：[requirements.min.txt](https://github.com/evidentlyai/evidently/blob/main/requirements.min.txt)\n\n## Web UI 组件\n\n### 前端组件架构\n\nEvidently UI 采用 React 和 Material-UI 构建，提供现代化的用户界面：\n\n```mermaid\ngraph LR\n A[用户界面] --> B[Dashboard 组件]\n A --> C[Prompts 组件]\n A --> D[Traces 组件]\n A --> E[Descriptors 组件]\n B --> F[Widget]\n C --> G[Forms]\n D --> H[Table]\n E --> I[Features]\n```\n\n### 核心 UI 组件\n\n| 组件名称 | 功能 | 文件路径 |\n|---------|------|---------|\n| NameAndDescriptionForm | 名称描述表单 | `ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx` |\n| PromptsTable | 提示词表格 | `ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx` |\n| TracesTable | 追踪记录表格 | `ui/packages/evidently-ui-lib/src/components/Traces/TracesTable.tsx` |\n| DashboardDateFilter | 日期过滤器 | `ui/packages/evidently-ui-lib/src/components/Dashboard/DashboardDateFilter.tsx` |\n\n资料来源：[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)\n\n## 快速开始\n\n### 步骤一：安装 Evidently\n\n```bash\npip install evidently\n```\n\n### 步骤二：创建评估报告\n\n```python\nfrom evidently.dashboard import Dashboard\nfrom evidently.tabs import DataDriftTab, CatTargetDriftTab\n\n# 创建仪表板\ndashboard = Dashboard(tabs=[DataDriftTab(), CatTargetDriftTab()])\n\n# 运行评估\ndashboard.calculate(reference_data, current_data)\n```\n\n### 步骤三：导出报告\n\n```python\ndashboard.save_html(\"report.html\")\n```\n\n## 进一步资源\n\n| 资源 | 链接 |\n|-----|------|\n| 官方文档 | https://docs.evidentlyai.com |\n| API 参考 | https://evidentlyai.github.io/evidently/api-reference |\n| Discord 社区 | https://discord.gg/xZjKRaNp8b |\n| Evidently Cloud | https://www.evidentlyai.com/register |\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目介绍与安装](#page-1), [指标系统 (Metrics)](#page-3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/ui/utils.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/utils.py)\n- [src/evidently/sdk/configs.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)\n- [src/evidently/ui/workspace.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/workspace.py)\n- [src/evidently/sdk/adapters.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/adapters.py)\n- [README.md](https://github.com/evidentlyai/evidently/blob/main/README.md)\n- [api-reference/README.md](https://github.com/evidentlyai/evidently/blob/main/api-reference/README.md)\n \n\n# 系统架构设计\n\n## 1. 概述\n\nEvidently 是一个开源的机器学习与 LLM 驱动系统的评估、测试和监控框架。该项目采用模块化设计，将核心评估逻辑与用户界面分离，同时提供 SDK 和 Web UI 两种交互方式。\n\n**核心设计目标：**\n- 提供可复用的评估指标和报告生成能力\n- 支持本地运行和云端服务两种部署模式\n- 实现配置版本化管理\n- 支持多项目组织和团队协作\n\n资料来源：[README.md:1-10]()\n\n## 2. 整体架构\n\n```mermaid\ngraph TD\n subgraph \"前端层 UI Layer\"\n WEB[Web UI - React]\n API_REF[API Reference Docs]\n end\n \n subgraph \"业务逻辑层 Business Logic\"\n SDK[Evidently SDK]\n METRICS[Metrics & Evaluators]\n GUARDRAILS[Guardrails]\n end\n \n subgraph \"数据模型层 Data Models\"\n CORE[Core Module]\n BASE_TYPES[Base Types]\n LEGACY[Legacy Module]\n end\n \n subgraph \"服务层 Services\"\n WORKSPACE[Workspace Service]\n CONFIGS[Config API]\n ADAPTERS[Adapters]\n end\n \n WEB --> SDK\n SDK --> METRICS\n SDK --> GUARDRAILS\n SDK --> CORE\n CORE --> BASE_TYPES\n SDK --> WORKSPACE\n SDK --> CONFIGS\n SDK --> ADAPTERS\n```\n\n## 3. 核心模块架构\n\n### 3.1 SDK 模块结构\n\nEvidently SDK 是系统的核心，提供了评估、报告生成和配置管理的功能。\n\n```mermaid\ngraph LR\n subgraph \"SDK Module\"\n CONFIGS[Configs]\n ADAPTERS[Adapters]\n REPORT[Report]\n METRICS[Metrics]\n end\n \n CONFIGS --> ADAPTERS\n REPORT --> METRICS\n```\n\n**主要组件：**\n\n| 模块 | 文件路径 | 功能说明 |\n|------|----------|----------|\n| ConfigAPI | `src/evidently/sdk/configs.py` | 提供配置的增删改查和版本管理 |\n| Adapters | `src/evidently/sdk/adapters.py` | 配置与 API 之间的适配器 |\n| Report | `src/evidently/core/report.py` | 报告生成和处理 |\n| Base Types | `src/evidently/core/base_types.py` | 基础数据类型定义 |\n\n资料来源：[src/evidently/sdk/configs.py:1-50]()\n\n### 3.2 Workspace 服务层\n\nWorkspace 是项目管理的核心抽象，提供了项目级别的操作接口。\n\n```mermaid\nclassDiagram\n class Workspace {\n <>\n +create_project(name, description, org_id) Project\n +add_project(project, org_id) Project\n +get_project(project_id) Optional~Project~\n +delete_project(project_id)\n +list_projects(org_id) Sequence~Project~\n }\n \n class Project {\n +id: STR_UUID\n +name: str\n +description: str\n +org_id: Optional~OrgID~\n }\n```\n\n**Workspace 核心接口：**\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| create_project | name, description, org_id | Project | 创建新项目 |\n| add_project | project, org_id | Project | 添加项目到工作区 |\n| get_project | project_id | Optional[Project] | 根据 ID 获取项目 |\n| delete_project | project_id | None | 删除指定项目 |\n| list_projects | org_id | Sequence[Project] | 列出工作区中的项目 |\n\n资料来源：[src/evidently/ui/workspace.py:1-60]()\n\n### 3.3 配置版本管理\n\n系统采用 ConfigVersion 机制管理配置的版本，支持配置的创建、更新和历史追溯。\n\n```mermaid\ngraph TD\n A[ConfigVersion] --> B[ConfigMetadata]\n A --> C[ConfigContent]\n B --> D[created_at]\n B --> E[updated_at]\n B --> F[author]\n B --> G[description]\n \n H[CloudConfigAPI] --> I[create_descriptor]\n H --> J[get_descriptor]\n H --> K[update_descriptor]\n```\n\n**配置类型支持：**\n\n| 配置类型 | 说明 | 支持版本管理 |\n|----------|------|--------------|\n| Descriptor | 描述符配置 | 是 |\n| Artifact | 工件配置 | 是 |\n| Metric | 指标配置 | 是 |\n| Report | 报告配置 | 是 |\n\n资料来源：[src/evidently/sdk/adapters.py:1-40]()\n\n## 4. 前端架构\n\n### 4.1 UI 组件结构\n\nWeb UI 采用 React + TypeScript 构建，主要组件位于 `ui/packages/evidently-ui-lib/`。\n\n```mermaid\ngraph TD\n subgraph \"UI Components\"\n Dashboard[Dashboard]\n Prompts[Prompts]\n Traces[Traces]\n Descriptors[Descriptors]\n Utils[Utils]\n end\n \n subgraph \"Widgets\"\n Widget[Widget]\n TestSuiteWidget[TestSuiteWidget]\n end\n \n Dashboard --> Widget\n Prompts --> Utils\n Traces --> Utils\n Descriptors --> Utils\n```\n\n**核心组件：**\n\n| 组件目录 | 组件名称 | 功能 |\n|----------|----------|------|\n| Dashboard | DashboardDateFilter | 日期范围筛选 |\n| Prompts | CreatePromptForm, PromptsTable | Prompt 创建和管理 |\n| Traces | TracesTable, TraceViewer | 追踪记录查看 |\n| Descriptors | LLMJudge/template | 描述符模板 |\n| Widgets | Widget | 通用组件容器 |\n\n资料来源：[ui/packages/evidently-ui-lib/src/widgets/Widget.tsx:1-30]()\n\n### 4.2 状态管理\n\n表单状态使用 React Hook Form 结合 Zod 进行验证：\n\n```typescript\n// 表单验证流程\nForm → useForm → zodResolver → NameAndDescriptionForm\n```\n\n**表单验证模式：**\n\n| 验证字段 | 验证规则 | 错误提示位置 |\n|----------|----------|--------------|\n| name | 必填，字符串 | helperText |\n| description | 可选，字符串 | helperText |\n| 日期范围 | dateFrom <= dateTo | AlertThemed |\n\n资料来源：[ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx:1-40]()\n\n## 5. 报告与评估系统\n\n### 5.1 Report 核心流程\n\n```mermaid\ngraph LR\n A[Input Data] --> B[Dataset]\n B --> C[Descriptors]\n C --> D[Evaluators]\n D --> E[Report]\n E --> F[Metrics]\n F --> G[Visualization]\n```\n\n**Report 生成步骤：**\n\n1. **数据准备**：将 DataFrame 转换为 Dataset 对象\n2. **添加描述符**：定义行级评估器（如 Sentiment、TextLength）\n3. **执行评估**：运行预设的评估套件\n4. **生成报告**：汇总结果并生成可视化输出\n\n**示例支持的描述符：**\n\n| 描述符 | 功能 | 适用场景 |\n|--------|------|----------|\n| Sentiment | 情感分析 | LLM 响应评估 |\n| TextLength | 文本长度统计 | 响应长度监控 |\n| Contains | 关键词检测 | 拒绝/否认识别 |\n\n资料来源：[README.md:80-120]()\n\n### 5.2 评估预设\n\n系统提供多种评估预设，简化常见评估场景的配置：\n\n| 预设名称 | 说明 | 包含评估项 |\n|----------|------|------------|\n| TextEvals | 文本评估预设 | 情感、长度、关键词 |\n| LLM Evals | LLM 专用评估 | 响应质量、多样性 |\n\n资料来源：[README.md:60-80]()\n\n## 6. API 参考文档生成\n\n项目使用 pdoc 工具自动生成 API 参考文档。\n\n```mermaid\ngraph TD\n A[generate.py] --> B[Local Source]\n A --> C[Git Revision]\n B --> D[dist//]\n C --> E[dist//]\n \n F[local-dev.sh] --> G[Development Server]\n G --> H[http://localhost:8080]\n```\n\n**文档生成命令：**\n\n```bash\n# 本地源码生成\n./api-reference/generate.py --local-source-code\n\n# 指定 Git 版本\n./api-reference/generate.py --git-revision v0.7.17\n\n# 添加额外模块\n./api-reference/generate.py --local-source-code \\\n --additional-modules \"evidently.metrics,evidently.guardrails\"\n```\n\n**默认包含模块：**\n- `evidently`\n- `evidently.core`\n\n**输出目录结构：**\n- 本地构建：`dist//`\n- Git 构建：`dist//`\n\n资料来源：[api-reference/README.md:1-50]()\n\n## 7. 部署架构\n\n### 7.1 组件部署\n\n```mermaid\ngraph TD\n subgraph \"客户端 Client\"\n PY[Python SDK]\n WEB[Web Browser]\n end\n \n subgraph \"服务端 Server\"\n API[Config API]\n DB[(Database)]\n WS[Workspace Service]\n end\n \n PY --> API\n WEB --> WS\n API --> DB\n WS --> DB\n```\n\n### 7.2 安装方式\n\n| 安装方式 | 命令 | 说明 |\n|----------|------|------|\n| PyPI | `pip install evidently` | 推荐标准方式 |\n| Conda | `conda install -c conda-forge evidently` | 使用 conda 安装 |\n\n资料来源：[README.md:40-55]()\n\n## 8. 关键技术栈\n\n| 层级 | 技术 | 用途 |\n|------|------|------|\n| 核心语言 | Python 3.11+ | SDK 实现 |\n| Web 框架 | React + TypeScript | 前端 UI |\n| 数据验证 | Zod | 表单验证 |\n| 日期处理 | dayjs | 时间格式化 |\n| 文档生成 | pdoc | API 文档 |\n| 包管理 | uv | Python 包管理 |\n\n## 9. 总结\n\nEvidently 采用清晰的分层架构设计：\n\n1. **核心层** (`evidently.core`)：定义基础数据类型和报告生成逻辑\n2. **SDK 层** (`evidently.sdk`)：提供配置管理、适配器和 API 封装\n3. **业务层** (`evidently.ui`)：实现工作区服务和项目管理\n4. **展示层** (`ui/`): React 前端实现用户交互界面\n\n这种设计使得系统既可以作为 Python 库独立使用，也可以通过 Web UI 进行可视化操作，同时支持本地部署和云端服务两种模式。\n\n---\n\n\n\n## 指标系统 (Metrics)\n\n### 相关页面\n\n相关主题：[预设评估 (Presets)](#page-4), [报告与测试套件](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/metrics/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/__init__.py)\n- [src/evidently/metrics/classification.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/classification.py)\n- [src/evidently/metrics/regression.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/regression.py)\n- [src/evidently/metrics/data_quality.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/data_quality.py)\n- [src/evidently/metrics/recsys.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/recsys.py)\n- [src/evidently/core/metric_types.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/metric_types.py)\n- [src/evidently/core/registries/metrics.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/metrics.py)\n \n\n# 指标系统 (Metrics)\n\n## 概述\n\n指标系统是 Evidently 框架的核心组件之一，负责对机器学习模型和 LLM 支持的系统进行量化和评估。该系统提供了统一的接口来定义、计算、缓存和渲染各类评估指标，涵盖了分类任务、回归任务、数据质量评估以及推荐系统等多个领域。\n\n指标系统通过抽象基类 `Metric` 和 `MetricContainer` 建立了灵活可扩展的架构，允许开发者自定义指标并将其集成到评估报告中。 资料来源：[src/evidently/core/metric_types.py:1-50]()\n\n## 核心架构\n\n### 指标类型层次结构\n\nEvidently 的指标系统采用面向对象的继承设计，主要分为两大类：\n\n1. **基础指标 (Metric)** - 单个指标实现，负责计算具体的评估维度\n2. **指标容器 (MetricContainer)** - 组合多个指标的容器，支持批量计算和联合渲染\n\n```mermaid\ngraph TD\n A[Metric 基础抽象类] --> B[ClassificationMetrics]\n A --> C[RegressionMetrics]\n A --> D[DataQualityMetrics]\n A --> E[RecSysMetrics]\n A --> F[MetricContainer 容器基类]\n F --> G[TextEvals 预设容器]\n F --> H[CustomMetricContainer]\n```\n\n### 指标容器 (MetricContainer)\n\n`MetricContainer` 是组合多个指标的抽象基类，定义在 `src/evidently/core/container.py` 中，提供了指标生成、缓存和渲染的统一接口。\n\n```python\nclass MetricContainer(GenericContainer, abc.ABC):\n \"\"\"指标容器基类\"\"\"\n \n def __init__(self, include_tests: bool = True, **data):\n \"\"\"初始化指标容器\n \n Args:\n include_tests: 如果为 True，生成的指标将包含默认测试\n \"\"\"\n self.include_tests = include_tests\n super().__init__(**data)\n \n @abc.abstractmethod\n def generate_metrics(self, context: \"Context\") -> Sequence[MetricOrContainer]:\n \"\"\"基于容器配置生成指标\"\"\"\n raise NotImplementedError()\n \n def metrics(self, context: \"Context\") -> List[MetricOrContainer]:\n \"\"\"获取所有生成的指标，支持上下文缓存\"\"\"\n metric_container_fp = self.get_fingerprint()\n metrics = context.metrics_container(metric_container_fp)\n if metrics is None:\n metrics = list(self.generate_metrics(context))\n context.set_metric_container_data(metric_container_fp, metrics)\n return metrics\n \n def render(self, context: \"Context\", \n child_widgets: Optional[List[Tuple[Optional[MetricId], List[BaseWidgetInfo]]]] = None) -> List[BaseWidgetInfo]:\n \"\"\"渲染可视化组件\"\"\"\n # 实现细节\n```\n\n资料来源：[src/evidently/core/container.py:31-75]()\n\n### 指标注册表机制\n\n指标系统通过注册表 (Registry) 机制实现指标的集中管理和发现。`MetricRegistry` 类维护了所有可用指标的映射关系。\n\n| 注册表操作 | 说明 |\n|-----------|------|\n| `register()` | 注册新指标到注册表 |\n| `get()` | 根据名称获取指标类 |\n| `list_metrics()` | 列出所有已注册的指标 |\n| `_make` | 指标实例工厂方法 |\n\n资料来源：[src/evidently/core/registries/metrics.py:1-100]()\n\n## 指标分类\n\n### 分类指标 (Classification Metrics)\n\n分类指标用于评估分类模型的性能，支持二分类和多分类场景。\n\n**主要指标包括：**\n\n| 指标名称 | 说明 | 适用场景 |\n|---------|------|---------|\n| `ClassificationQualityMetric` | 整体分类质量评分 | 通用分类评估 |\n| `PrecisionMetric` | 精确率 | 关注假阳性场景 |\n| `RecallMetric` | 召回率 | 关注假阴性场景 |\n| `F1ScoreMetric` | F1 分数 | 平衡精确率和召回率 |\n| `RocAucMetric` | ROC-AUC 曲线下面积 | 概率预测评估 |\n| `ConfusionMatrixMetric` | 混淆矩阵 | 详细错误分析 |\n\n资料来源：[src/evidently/metrics/classification.py:1-200]()\n\n### 回归指标 (Regression Metrics)\n\n回归指标用于评估连续值预测模型的性能。\n\n**核心指标：**\n\n| 指标名称 | 说明 | 敏感度 |\n|---------|------|--------|\n| `MeanErrorMetric` | 平均误差 | 偏移 |\n| `MeanAbsoluteErrorMetric` | 平均绝对误差 | 异常值鲁棒 |\n| `MeanSquaredErrorMetric` | 均方误差 | 惩罚大误差 |\n| `R2ScoreMetric` | R² 决定系数 | 模型解释力 |\n| `ErrorDistributionMetric` | 误差分布 | 偏差分析 |\n\n资料来源：[src/evidently/metrics/regression.py:1-200]()\n\n### 数据质量指标 (Data Quality Metrics)\n\n数据质量指标用于评估数据集本身的特性，包括完整性、一致性和统计分布。\n\n| 指标类别 | 包含指标 |\n|---------|---------|\n| 完整性检查 | 缺失值比例、空值统计 |\n| 唯一性检查 | 重复行检测、主键唯一性 |\n| 范围检查 | 数值边界、类别覆盖 |\n| 分布检查 | 直方图、分布偏移 |\n\n资料来源：[src/evidently/metrics/data_quality.py:1-200]()\n\n### 推荐系统指标 (RecSys Metrics)\n\n推荐系统专用指标用于评估协同过滤和内容推荐算法。\n\n| 指标名称 | 说明 |\n|---------|------|\n| `PrecisionAtK` | K 位精度 |\n| `RecallAtK` | K 位召回率 |\n| `NDCGMetric` | 归一化折扣累计增益 |\n| `HitRateMetric` | 点击率 |\n\n资料来源：[src/evidently/metrics/recsys.py:1-200]()\n\n## 指标执行流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Report as Report\n participant Container as MetricContainer\n participant Metric as Metric\n participant Context as Context\n participant Renderer as WidgetRenderer\n \n User->>Report: 创建 Report(metrics=[...])\n Report->>Container: 初始化容器\n Container->>Context: 调用 metrics()\n Context->>Context: 检查缓存\n alt 缓存未命中\n Context->>Container: generate_metrics()\n Container->>Metric: 实例化指标\n Metric->>Metric: calculate(context)\n Metric-->>Context: 返回计算结果\n Context->>Context: 缓存结果\n end\n Context-->>Report: 返回指标列表\n Report->>Container: render(context)\n Container->>Metric: 获取 widget 信息\n Metric-->>Container: BaseWidgetInfo\n Container-->>Report: 渲染后的 widgets\n Report-->>User: 生成 HTML/JSON 报告\n```\n\n## 指标定义接口\n\n每个具体指标需要实现以下核心方法：\n\n```python\nclass MyCustomMetric(Metric):\n \"\"\"自定义指标示例\"\"\"\n \n def calculate(self, context: Context) -> MetricResult:\n \"\"\"执行指标计算\n \n Args:\n context: 包含数据集和配置的上下文对象\n \n Returns:\n MetricResult: 包含计算结果的指标结果对象\n \"\"\"\n # 1. 从 context 获取数据\n current_data = context.get_current_data()\n reference_data = context.get_reference_data()\n \n # 2. 执行计算逻辑\n value = self._compute_metric(current_data, reference_data)\n \n # 3. 返回结果\n return MetricResult(\n value=value,\n parameters=self.parameters\n )\n \n def get_widgets(self, context: Context) -> List[BaseWidgetInfo]:\n \"\"\"返回可视化组件\"\"\"\n # 返回用于渲染的 widget 配置\n pass\n \n def get_fingerprint(self) -> str:\n \"\"\"计算指标指纹用于缓存\"\"\"\n pass\n```\n\n资料来源：[src/evidently/core/metric_types.py:50-150]()\n\n## 指标与报告集成\n\n指标通过 `Report` 类与用户进行交互。以下是典型使用方式：\n\n```python\nfrom evidently import Report\nfrom evidently.metrics import ClassificationQualityMetric, PrecisionMetric\n\n# 创建报告并指定要使用的指标\nreport = Report(\n metrics=[\n ClassificationQualityMetric(),\n PrecisionMetric(positive_label=1),\n ]\n)\n\n# 运行评估\nreport.run(\n reference_data=reference_df,\n current_data=current_df,\n column_mapping=ColumnMapping(target=\"target\", prediction=\"pred\")\n)\n\n# 导出报告\nreport.save_html(\"report.html\")\nreport.save_json(\"report.json\")\n```\n\n## 指标预设 (Presets)\n\n除了单个指标，Evidently 还提供了预配置的指标组合预设：\n\n| 预设名称 | 说明 | 包含指标 |\n|---------|------|---------|\n| `TextEvals` | LLM 文本评估预设 | 情感分析、毒性检测、摘要质量 |\n| `ClassificationPreset` | 分类任务完整评估 | 质量、精确率、召回率、混淆矩阵 |\n| `RegressionPreset` | 回归任务完整评估 | MAE、MSE、误差分布、R² |\n\n资料来源：[src/evidently/metrics/__init__.py:1-100]()\n\n## 缓存机制\n\n指标系统实现了高效的缓存机制以避免重复计算：\n\n```mermaid\ngraph LR\n A[请求指标] --> B{缓存存在?}\n B -->|是| C[返回缓存结果]\n B -->|否| D[调用 generate_metrics]\n D --> E[执行指标计算]\n E --> F[存入上下文缓存]\n F --> G[返回结果]\n```\n\n缓存键基于指标容器的指纹 (fingerprint) 生成，确保配置变化时自动重新计算。\n\n资料来源：[src/evidently/core/container.py:47-55]()\n\n## 扩展开发指南\n\n### 创建自定义指标\n\n1. **继承 Metric 基类**\n2. **实现必需方法**：calculate()、get_widgets()、get_fingerprint()\n3. **注册到指标注册表**\n\n```python\nfrom evidently.core import Metric\n\nclass MyMetric(Metric):\n \"\"\"自定义指标\"\"\"\n alias = \"my_metric\"\n \n def calculate(self, context):\n # 实现计算逻辑\n return MyMetricResult(...)\n \n def get_widgets(self, context):\n return [BaseWidgetInfo(...)]\n \n def get_fingerprint(self):\n return self.json()\n```\n\n### 创建自定义指标容器\n\n```python\nfrom evidently.core import MetricContainer\n\nclass MyMetricContainer(MetricContainer):\n \"\"\"自定义指标容器\"\"\"\n \n def generate_metrics(self, context):\n return [\n MyMetric(...),\n AnotherMetric(...)\n ]\n```\n\n## 总结\n\nEvidently 的指标系统提供了灵活、可扩展且功能完整的评估框架。通过抽象基类和注册表机制，开发者可以轻松添加新的指标类型；通过容器模式和缓存机制，系统能够高效处理复杂的评估场景。该系统支持从简单的数据质量检查到高级的 LLM 输出评估等多种应用场景，是 Evidently 框架的核心支柱。\n\n---\n\n\n\n## 预设评估 (Presets)\n\n### 相关页面\n\n相关主题：[指标系统 (Metrics)](#page-3), [报告与测试套件](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/presets/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/__init__.py)\n- [src/evidently/presets/drift.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/drift.py)\n- [src/evidently/presets/classification.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/classification.py)\n- [src/evidently/presets/regression.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/regression.py)\n- [src/evidently/presets/recsys.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/recsys.py)\n- [src/evidently/core/preset_types.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/preset_types.py)\n- [src/evidently/core/registries/presets.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/presets.py)\n \n\n# 预设评估 (Presets)\n\n## 概述\n\n预设评估（Presets）是 Evidently 框架中提供的一种高级评估机制，它将一组相关的指标（Metrics）和测试（Tests）打包成可重用的配置单元。预设评估允许用户通过简单的接口快速对机器学习模型进行全面的性能评估，无需手动配置大量单独的指标。\n\nEvidently 的预设评估系统涵盖多种 ML 任务类型，每种预设针对特定的应用场景提供针对性的评估方案。通过使用预设，用户可以：\n\n- 简化评估流程，减少配置代码量\n- 确保评估的一致性和标准化\n- 快速获得全面的模型性能洞察\n- 支持分类、回归、数据漂移和推荐系统等多种任务类型\n\n## 架构设计\n\n### 核心组件关系\n\n预设系统的架构由以下几个核心组件构成：\n\n```mermaid\ngraph TD\n A[用户代码] --> B[Report / TestSuite]\n B --> C[Preset 预设]\n C --> D[Metrics 指标集合]\n C --> E[Tests 测试集合]\n D --> F[ColumnMetric]\n D --> G[DatasetMetric]\n E --> H[TestCase]\n F --> I[Evidently Engine]\n G --> I\n H --> I\n \n J[PresetRegistry 注册表] --> K[Preset Types 类型定义]\n K --> C\n```\n\n### 类型层次结构\n\n预设类型系统采用继承和组合模式：\n\n```mermaid\nclassDiagram\n class Preset {\n <>\n +metrics: List[Metric]\n +tests: List[Test]\n +tabs: List[str]\n +get_aspects() List[Aspect]\n }\n \n class DataDriftPreset {\n +DataDriftPreset()\n }\n \n class ClassificationPreset {\n +ClassificationPreset()\n }\n \n class RegressionPreset {\n +RegressionPreset()\n }\n \n class RecSysPreset {\n +RecSysPreset()\n }\n \n class TextEvalsPreset {\n +TextEvalsPreset()\n }\n \n Preset <|-- DataDriftPreset\n Preset <|-- ClassificationPreset\n Preset <|-- RegressionPreset\n Preset <|-- RecSysPreset\n Preset <|-- TextEvalsPreset\n```\n\n## 预设类型详解\n\n### 数据漂移检测预设 (DataDriftPreset)\n\n数据漂移预设用于检测生产环境中的数据分布变化。当输入数据的统计特性发生显著变化时，可能表明模型性能下降或底层数据生成过程发生了变化。\n\n**适用场景**：\n\n- 生产环境监控\n- 模型再训练触发条件判断\n- 数据管道异常检测\n\n**主要评估指标**：\n\n| 指标类型 | 说明 |\n|---------|------|\n| 特征级漂移 | 检测单个特征的分布变化 |\n| 整体漂移 | 聚合所有特征的漂移情况 |\n| 目标漂移 | 检测目标变量分布变化 |\n\n资料来源：[src/evidently/presets/drift.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/drift.py)\n\n### 分类模型预设 (ClassificationPreset)\n\n分类预设专为二分类和多分类任务设计，提供全面的分类器性能评估。\n\n**适用场景**：\n\n- 二分类问题（如欺诈检测、流失预测）\n- 多分类问题（如图像分类、文本分类）\n- 概率校准评估\n\n**主要评估指标**：\n\n| 指标 | 说明 | 适用分类类型 |\n|------|------|-------------|\n| Accuracy | 整体准确率 | 二分类/多分类 |\n| Precision | 精确率 | 二分类/多分类 |\n| Recall | 召回率 | 二分类/多分类 |\n| F1-Score | F1 分数 | 二分类/多分类 |\n| ROC-AUC | ROC 曲线下面积 | 二分类 |\n| PR-AUC | PR 曲线下面积 | 二分类 |\n| Confusion Matrix | 混淆矩阵 | 二分类/多分类 |\n| Class Representation | 类别表示分布 | 多分类 |\n\n资料来源：[src/evidently/presets/classification.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/classification.py)\n\n### 回归模型预设 (RegressionPreset)\n\n回归预设用于评估回归模型的预测性能。\n\n**适用场景**：\n\n- 连续值预测\n- 时间序列预测\n- 价格/数量预测\n\n**主要评估指标**：\n\n| 指标 | 说明 |\n|------|------|\n| MAE | 平均绝对误差 |\n| MSE | 均方误差 |\n| RMSE | 均方根误差 |\n| MAPE | 平均绝对百分比误差 |\n| R2 Score | 决定系数 |\n| Max Error | 最大误差 |\n| Median Error | 中位数误差 |\n\n资料来源：[src/evidently/presets/regression.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/regression.py)\n\n### 推荐系统预设 (RecSysPreset)\n\n推荐系统预设专门针对协同过滤和推荐算法进行评估。\n\n**适用场景**：\n\n- 推荐系统性能评估\n- 点击率预测\n- 排名质量评估\n\n**主要评估指标**：\n\n| 指标 | 说明 |\n|------|------|\n| Precision@K | K 位精度 |\n| Recall@K | K 位召回率 |\n| NDCG | 归一化折损累计增益 |\n| MRR | 平均倒数排名 |\n| Hit Rate | 点击率 |\n\n资料来源：[src/evidently/presets/recsys.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/recsys.py)\n\n### 文本评估预设 (TextEvalsPreset)\n\n文本评估预设用于评估 LLM 和文本生成模型的输出质量。\n\n**适用场景**：\n\n- LLM 输出质量评估\n- 文本摘要评估\n- 问答系统评估\n- 语义相似度评估\n\n**支持的评估描述符**：\n\n| 描述符 | 功能 |\n|--------|------|\n| Sentiment | 情感分析 |\n| TextLength | 文本长度统计 |\n| Contains | 关键词检测 |\n| LLM Judge | LLM 作为评判者 |\n| PII Detection | 敏感信息检测 |\n\n资料来源：[src/evidently/presets/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/__init__.py)\n\n## 使用方式\n\n### 在 Report 中使用预设\n\n```python\nfrom evidently import Report\nfrom evidently.presets import DataDriftPreset, ClassificationPreset\n\n# 创建带有预设的报告\nreport = Report(metrics=[\n DataDriftPreset(),\n ClassificationPreset()\n])\n\nreport.run(reference_data=reference, current_data=current)\nreport.show()\n```\n\n### 在 TestSuite 中使用预设\n\n```python\nfrom evidently import TestSuite\nfrom evidently.presets import RegressionPreset\n\n# 创建带有预设的测试套件\nsuite = TestSuite(tests=[\n RegressionPreset()\n])\n\nsuite.run(reference_data=reference, current_data=current)\nsuite.show()\n```\n\n### 自定义预设组合\n\n用户可以组合多个预设或添加自定义指标：\n\n```python\nfrom evidently import Report\nfrom evidently.presets import DataDriftPreset, ClassificationPreset\nfrom evidently.metrics import ColumnSummaryMetric\n\nreport = Report(metrics=[\n DataDriftPreset(),\n ClassificationPreset(),\n ColumnSummaryMetric(column_name=\"feature_1\")\n])\n```\n\n## 注册表机制\n\n预设系统使用注册表模式进行管理，确保所有预设类型都能被正确识别和实例化。\n\n```mermaid\ngraph LR\n A[PresetRegistry] -->|register| B[Preset Types]\n B -->|实例化| C[DataDriftPreset]\n B -->|实例化| D[ClassificationPreset]\n B -->|实例化| E[RegressionPreset]\n B -->|实例化| F[RecSysPreset]\n \n G[load_preset] -->|按名称查找| A\n G -->|返回实例| C\n```\n\n资料来源：[src/evidently/core/registries/presets.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/presets.py)\n\n## 配置参数\n\n### 通用配置选项\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `metrics` | List[Metric] | 指标列表 | [] |\n| `tests` | List[Test] | 测试列表 | [] |\n| `tabs` | List[str] | 展示标签页 | None |\n| `include_widgets` | List[Widget] | 包含的可视化组件 | None |\n\n### 分类预设配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `generated_labels` | bool | 是否生成类别标签 |\n| `probas_threshold` | float | 概率阈值 |\n\n### 漂移预设配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `drift_method` | str | 漂移检测方法 |\n| `confidence_level` | float | 置信水平 |\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[初始化 Report/TestSuite] --> B[加载预设]\n B --> C[解析数据集]\n C --> D[计算参考指标]\n D --> E[计算当前指标]\n E --> F[对比分析]\n F --> G{输出类型}\n G -->|Report| H[生成可视化报告]\n G -->|TestSuite| I[执行断言测试]\n H --> J[展示结果]\n I --> K[返回测试结果]\n```\n\n## 输出展示\n\n预设评估的输出支持多种展示形式：\n\n| 输出类型 | 说明 |\n|---------|------|\n| HTML 报告 | 交互式可视化报告 |\n| JSON 格式 | 结构化数据导出 |\n| Python 字典 | 程序化访问 |\n| Markdown | 文档化输出 |\n\n## 最佳实践\n\n### 选择合适的预设\n\n1. **数据类型驱动**：根据输入数据特征选择对应预设\n2. **任务类型匹配**：二分类使用 ClassificationPreset，多分类考虑类别平衡\n3. **监控场景**：生产监控优先考虑 DataDriftPreset\n\n### 性能优化建议\n\n- 避免在同一 Report 中使用过多预设\n- 大数据集使用采样策略\n- 漂移检测设置合理的检测窗口\n\n### 常见陷阱\n\n- 忽略数据预处理导致评估偏差\n- 混淆参考数据集和当前数据集\n- 忽视类别不平衡问题\n\n## 扩展预设\n\n用户可以创建自定义预设：\n\n```python\nfrom evidently.presets import Preset\nfrom evidently.metrics import Metric\n\nclass CustomPreset(Preset):\n def __init__(self):\n super().__init__(\n metrics=[\n CustomMetric1(),\n CustomMetric2()\n ],\n tabs=[\"Custom Tab\"]\n )\n```\n\n资料来源：[src/evidently/core/preset_types.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/preset_types.py)\n\n---\n\n\n\n## 描述符系统 (Descriptors)\n\n### 相关页面\n\n相关主题：[LLM集成与评判器](#page-7), [报告与测试套件](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/descriptors/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/__init__.py)\n- [src/evidently/descriptors/text_length.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/text_length.py)\n- [src/evidently/descriptors/text_match.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/text_match.py)\n- [src/evidently/descriptors/llm_judges.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/llm_judges.py)\n- [src/evidently/descriptors/_context_relevance.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/_context_relevance.py)\n- [src/evidently/core/registries/descriptors.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/descriptors.py)\n- [src/evidently/descriptors/generated_descriptors.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/generated_descriptors.py)\n \n\n# 描述符系统 (Descriptors)\n\n## 1. 系统概述\n\n描述符系统是 Evidently 框架中用于对数据集行级别进行评估和特征提取的核心组件。该系统允许用户通过声明式的方式定义文本处理任务，并将这些任务应用到 DataFrame 的指定列上，生成评估结果和衍生特征。\n\n描述符的核心价值在于：\n\n- **行级别评估**：对数据集中的每一行数据进行独立评估\n- **特征提取**：将文本内容转换为可量化的数值特征\n- **测试集成**：内置支持与测试框架集成，可设置阈值和预期范围\n- **结果缓存**：通过装饰器实现计算结果缓存，避免重复计算\n\n资料来源：[src/evidently/descriptors/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/__init__.py)\n\n## 2. 核心架构\n\n### 2.1 架构组件\n\n描述符系统由以下核心组件构成：\n\n```mermaid\ngraph TD\n A[用户定义描述符] --> B[FeatureDescriptor]\n B --> C[底层 Feature 实现]\n C --> D[评估结果 / 特征值]\n \n E[Dataset] --> F[描述符注册表]\n F --> B\n G[Test Suite] --> B\n```\n\n### 2.2 FeatureDescriptor 类\n\n`FeatureDescriptor` 是描述符的顶层封装类，负责整合底层特征实现和可选的测试配置：\n\n```python\nFeatureDescriptor(feature=feature, alias=alias, tests=tests)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `feature` | `Feature` | 底层特征实现对象 |\n| `alias` | `str` | 描述符别名，用于在结果中标识 |\n| `tests` | `List[DescriptorTest \\| GenericTest]` | 可选的测试配置列表 |\n\n资料来源：[src/evidently/descriptors/generated_descriptors.py:1-50](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/generated_descriptors.py)\n\n### 2.3 描述符注册表机制\n\n描述符通过注册表进行统一管理，支持按类型和名称进行查找：\n\n```mermaid\ngraph LR\n A[描述符定义] --> B[DescriptorRegistry]\n B --> C[按类型查找]\n B --> D[按名称查找]\n C --> E[返回描述符实例]\n D --> E\n```\n\n注册表提供以下核心功能：\n- 注册新的描述符类型\n- 根据名称获取描述符\n- 维护描述符与底层实现的映射关系\n\n资料来源：[src/evidently/core/registries/descriptors.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/descriptors.py)\n\n## 3. 内置描述符类型\n\n### 3.1 文本基础描述符\n\n文本基础描述符主要用于文本数据的量化处理。\n\n| 描述符 | 功能 | 主要参数 |\n|--------|------|----------|\n| `Sentiment` | 情感分析 | `column_name`, `alias` |\n| `TextLength` | 文本长度统计 | `column_name`, `alias` |\n| `Contains` | 关键词匹配 | `column_name`, `words_list`, `mode`, `lemmatize`, `alias` |\n\n#### Sentiment 描述符\n\n情感分析描述符使用预训练模型对文本进行情感评分：\n\n```python\nSentiment(\"answer\", alias=\"Sentiment\")\n```\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `column_name` | `str` | 是 | 要分析的文本列名 |\n| `alias` | `str` | 是 | 结果列别名 |\n\n#### TextLength 描述符\n\n文本长度描述符计算文本的字符数或词数：\n\n```python\nTextLength(column_name=\"response\", alias=\"Response Length\")\n```\n\n#### Contains 描述符\n\n关键词匹配描述符检测文本中是否包含指定词语：\n\n```python\nContains(\n column_name=\"text\",\n words_list=[\"denial\", \"refuse\", \"can't\"],\n mode=\"any\", # or \"all\"\n lemmatize=True,\n alias=\"Denial Indicator\"\n)\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `column_name` | `str` | - | 目标文本列名 |\n| `words_list` | `List[str]` | - | 要匹配的词语列表 |\n| `mode` | `\"any\" \\| \"all\"` | `\"any\"` | 匹配模式 |\n| `lemmatize` | `bool` | `False` | 是否进行词形还原 |\n| `alias` | `str` | - | 结果别名 |\n\n资料来源：[src/evidently/descriptors/text_match.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/text_match.py)\n\n### 3.2 LLM Judge 描述符\n\nLLM Judge 描述符利用大语言模型对文本进行高级语义评估。\n\n| 描述符 | 功能 | 适用场景 |\n|--------|------|----------|\n| `ContextRelevance` | 上下文相关性评估 | RAG 系统评估 |\n| `AnswerRelevance` | 回答相关性评估 | 问答系统 |\n| `Faithfulness` | 回答忠实度评估 | 生成内容验证 |\n\n#### ContextRelevance 描述符\n\n用于评估检索到的上下文与查询的相关性：\n\n```python\nContextRelevance(\n column_name=\"context\",\n question_column=\"question\",\n alias=\"context_relevance\",\n criteria=default_context_relevance_criteria,\n uncertainty=default_llm_judge_params\n)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `column_name` | `str` | 上下文文本列 |\n| `question_column` | `str` | 问题列名 |\n| `alias` | `str` | 结果别名 |\n| `criteria` | `dict` | 评估标准 |\n| `uncertainty` | `dict` | 不确定性参数 |\n\n资料来源：[src/evidently/descriptors/_context_relevance.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/_context_relevance.py)\n\n### 3.3 HuggingFace 模型描述符\n\n支持直接调用 HuggingFace 模型进行特定任务：\n\n```python\nHuggingFace(\n column_name=\"text\",\n model=\"cardiffnlp/twitter-roberta-base-sentiment\",\n params={\"max_length\": 512},\n alias=\"hf_sentiment\"\n)\n```\n\n#### HuggingFaceToxicity 描述符\n\n专门用于检测文本毒性：\n\n```python\nHuggingFaceToxicity(\n column_name=\"text\",\n alias=\"toxicity_score\",\n model=None, # 使用默认模型\n toxic_label=\"toxic\"\n)\n```\n\n资料来源：[src/evidently/descriptors/generated_descriptors.py:40-70](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/generated_descriptors.py)\n\n## 4. 使用方式\n\n### 4.1 在 Dataset 中使用\n\n描述符可以作为 Dataset 创建时的参数传入：\n\n```python\nfrom evidently import Dataset, DataDefinition\nfrom evidently.descriptors import Sentiment, TextLength, Contains\n\neval_dataset = Dataset.from_pandas(\n pd.DataFrame(eval_df),\n data_definition=DataDefinition(),\n descriptors=[\n Sentiment(\"answer\", alias=\"Sentiment\"),\n TextLength(\"answer\", alias=\"Answer Length\"),\n Contains(\n \"answer\",\n words_list=[\"sorry\", \"can't\", \"refuse\"],\n mode=\"any\",\n alias=\"Denial Indicator\"\n )\n ]\n)\n```\n\n### 4.2 与测试框架集成\n\n描述符支持内置的测试配置，可设置阈值和预期范围：\n\n```python\nfrom evidently.descriptors import TextLength\nfrom evidently.test_suits import DescriptorTest\n\ntests = [\n DescriptorTest(\n alias=\"Length Check\",\n condition=\"gte\",\n threshold=10\n )\n]\n\nTextLength(\"response\", alias=\"Response Length\", tests=tests)\n```\n\n### 4.3 工作流程\n\n```mermaid\ngraph TD\n A[创建 Dataset] --> B[应用描述符列表]\n B --> C[对每行数据进行特征计算]\n C --> D[缓存计算结果]\n D --> E[生成评估报告]\n E --> F{是否配置测试}\n F -->|是| G[执行测试断言]\n F -->|否| H[仅输出特征值]\n G --> I[测试结果]\n```\n\n## 5. 描述符与 Report 集成\n\n描述符生成的特征可以直接在 Report 中展示：\n\n```python\nfrom evidently import Report\nfrom evidently.presets import TextEvals\n\nreport = Report(metrics=[\n TextEvalsPreset()\n])\n\nreport.run(reference_data=ref_df, current_data=curr_df)\nreport.show()\n```\n\n## 6. 自定义描述符\n\n### 6.1 创建自定义 Feature\n\n用户可以通过继承 `Feature` 基类创建自定义描述符：\n\n```python\nfrom evidently.legacy.features.base import Feature\n\nclass CustomFeature(Feature):\n def __init__(self, column_name: str, **kwargs):\n super().__init__(column_name=column_name, **kwargs)\n \n def _calculate(self, data: pd.Series) -> pd.Series:\n # 自定义计算逻辑\n return data.apply(self._process)\n \n def _process(self, value):\n # 处理单个值\n return processed_value\n```\n\n### 6.2 封装为 FeatureDescriptor\n\n```python\nfrom evidently.descriptors import FeatureDescriptor\n\ndef CustomDescriptor(\n column_name: str,\n alias: str,\n tests: Optional[List[Union[\"DescriptorTest\", \"GenericTest\"]]] = None\n):\n feature = CustomFeature(column_name=column_name, display_name=alias)\n return FeatureDescriptor(feature=feature, alias=alias, tests=tests)\n```\n\n## 7. 性能优化\n\n描述符系统提供以下性能优化机制：\n\n| 优化方式 | 说明 |\n|----------|------|\n| 结果缓存 | 使用 `@lru_cache` 装饰器避免重复计算 |\n| 向量化计算 | 底层使用 pandas 向量化操作 |\n| 批量处理 | 支持批量数据处理减少 I/O 开销 |\n\n## 8. 总结\n\n描述符系统是 Evidently 框架中进行文本数据评估的核心模块，通过统一抽象的接口设计，提供了从简单的文本长度统计到复杂的 LLM Judge 语义评估的完整能力覆盖。其与 Dataset 和 Report 系统的深度集成，使得用户可以方便地在机器学习和 LLM 系统的评估流程中使用这些描述符。\n\n描述符系统的设计遵循以下原则：\n- **声明式配置**：通过参数配置而非代码实现定义评估逻辑\n- **可组合性**：支持多个描述符组合使用\n- **可扩展性**：通过继承机制支持自定义描述符\n- **测试集成**：内置与测试框架的集成能力\n\n---\n\n\n\n## 报告与测试套件\n\n### 相关页面\n\n相关主题：[指标系统 (Metrics)](#page-3), [预设评估 (Presets)](#page-4)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/core/report.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/report.py)\n- [src/evidently/core/tests.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/tests.py)\n- [src/evidently/core/serialization.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/serialization.py)\n- [src/evidently/legacy/report/report.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/legacy/report/report.py)\n- [src/evidently/legacy/test_suite/test_suite.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/legacy/test_suite/test_suite.py)\n \n\n# 报告与测试套件\n\n## 概述\n\n报告（Report）与测试套件（Test Suite）是 Evidently 框架的两大核心功能模块，用于评估和监控机器学习及 LLM 支持的系统。这两个模块提供了互补的能力：报告专注于数据探索和可视化分析，而测试套件则用于验证数据质量和模型性能是否满足预期标准。\n\n报告模块通过统计分析生成交互式的可视化图表，帮助数据科学家理解模型行为和数据分布变化。测试套件模块则将评估标准形式化为可执行的测试用例，返回明确的通过/失败状态，便于 CI/CD 流程集成和自动化监控。资料来源：[src/evidently/legacy/report/report.py:1-50]()\n\n## 核心架构\n\n### 模块关系图\n\n```mermaid\ngraph TD\n A[数据集输入] --> B[Report]\n A --> C[Test Suite]\n B --> D[MetricRegistry]\n C --> E[TestRegistry]\n D --> F[可视化渲染]\n E --> G[测试结果输出]\n F --> H[HTML/JSON报告]\n G --> I[测试日志]\n H --> J[Web UI展示]\n I --> K[持续集成]\n```\n\n### 报告与测试套件对比\n\n| 特性 | 报告 (Report) | 测试套件 (Test Suite) |\n|:---|:---|:---|\n| 输出形式 | 可视化图表、统计指标 | 通过/失败状态 |\n| 交互性 | 支持 Web UI 交互查看 | 命令行批量执行 |\n| 返回类型 | `Report` 对象 | `TestSuite` 对象 |\n| 适用场景 | 数据探索、模型分析 | 自动化验证、CI/CD |\n| 配置方式 | Metrics 注册 | Tests 定义 |\n| 资料来源 | [src/evidently/core/report.py:1-30]() | [src/evidently/core/tests.py:1-30]() |\n\n## Report 报告模块\n\n### 功能特性\n\n报告模块提供以下核心功能：\n\n1. **多指标支持**：支持 100+ 内置评估指标，覆盖数据质量、分布漂移、分类性能、回归性能等多个维度\n2. **灵活的指标组合**：通过 `metrics` 参数可自由组合不同类型的指标\n3. **多种输出格式**：支持生成 HTML 交互式报告和 JSON 结构化数据\n4. **数据集支持**：兼容 pandas DataFrame 以及 Evidently 的 Dataset 对象\n\n### 基本使用流程\n\n```mermaid\ngraph LR\n A[准备数据] --> B[创建Report实例]\n B --> C[添加Metrics]\n C --> D[调用run方法]\n D --> E[生成报告]\n E --> F[保存/展示]\n```\n\n### 代码示例\n\n```python\nfrom evidently import Report\nfrom evidently.descriptors import Sentiment, TextLength\nfrom evidently.presets import TextEvals\n\n# 创建报告实例\nreport = Report(\n metrics=[\n TextEvals(),\n ]\n)\n\n# 准备数据集\nfrom evidently import Dataset\ndataset = Dataset.from_pandas(df, descriptors=[\n Sentiment(\"response\"),\n TextLength(\"response\")\n])\n\n# 运行报告\nresult = report.run(reference_data=reference, current_data=current)\nprint(result.show())\n```\n\n### 报告生成参数\n\n| 参数名 | 类型 | 必需 | 默认值 | 说明 |\n|:---|:---|:---|:---|:---|\n| `metrics` | `List[Metric]` | 是 | - | 要计算的指标列表 |\n| `date_column` | `str` | 否 | `None` | 时间戳列名 |\n| `verbose_level` | `int` | 否 | `1` | 日志详细程度 |\n| 资料来源 | [src/evidently/core/report.py:40-60]() | | | |\n\n### 报告运行方法\n\n```python\ndef run(\n self,\n reference_data: Optional[Any,\n current_data: Any,\n column_mapping: Optional[ColumnMapping] = None\n) -> ReportResult:\n \"\"\"执行报告生成\"\"\"\n```\n\n### 序列化支持\n\n报告支持 JSON 和 pickle 格式的序列化，便于持久化存储和后续加载分析。资料来源：[src/evidently/core/serialization.py:1-50]()\n\n## Test Suite 测试套件模块\n\n### 功能特性\n\n测试套件模块的核心特点包括：\n\n1. **声明式测试定义**：通过声明式语法定义数据质量测试\n2. **即时反馈**：运行后立即返回测试结果列表\n3. **详细日志**：每个测试失败时提供详细的原因说明\n4. **与报告互补**：测试套件可以复用报告中的指标定义\n\n### 测试执行流程\n\n```mermaid\ngraph TD\n A[定义TestSuite] --> B[添加Tests]\n B --> C[加载数据集]\n C --> D[执行run方法]\n D --> E{测试通过?}\n E -->|是| F[记录通过状态]\n E -->|否| G[记录失败详情]\n F --> H[生成TestResult]\n G --> H\n H --> I[返回结果列表]\n```\n\n### 代码示例\n\n```python\nfrom evidently import TestSuite\nfrom evidently.test_suite import TestSuite\nfrom evidently.legacy.test_suite import TestSuite as LegacyTestSuite\n\n# 创建测试套件\ntest_suite = TestSuite(tests=[\n # 测试定义\n])\n\n# 运行测试\nresult = test_suite.run(reference_data=ref, current_data=cur)\n\n# 检查结果\nif result.passed:\n print(\"所有测试通过\")\nelse:\n print(f\"失败测试数: {result.get_fail_count()}\")\n```\n\n### 测试结果结构\n\n| 属性 | 类型 | 说明 |\n|:---|:---|:---|\n| `passed` | `bool` | 是否全部通过 |\n| `total` | `int` | 测试总数 |\n| `failed` | `int` | 失败数量 |\n| `results` | `List[TestResult]` | 单个测试结果列表 |\n| 资料来源 | [src/evidently/legacy/test_suite/test_suite.py:50-100]() |\n\n## 指标与测试的对应关系\n\n### 指标 (Metric) 到测试 (Test) 的转换\n\nEvidently 框架支持将指标计算结果转换为测试用例，实现评估逻辑的复用：\n\n```python\n# 指标 → 测试的映射关系\nfrom evidently.metrics import ColumnSummaryMetric\n\n# 基于指标的测试定义\nTestMetric = ColumnSummaryMetric(\n column_name=\"target\",\n quantile=[0.05, 0.95]\n)\n```\n\n### 常用指标分类\n\n| 类别 | 指标名称 | 对应测试 |\n|:---|:---|:---|\n| 数据质量 | `MissingValuesMetric` | `TestMissingValues` |\n| 分布漂移 | ` drift.DriftMetric` | `TestColumnDrift` |\n| 分类性能 | `ClassificationQualityMetric` | `TestAccuracyScore` |\n| 回归性能 | `RegressionQualityMetric` | `TestMAEScore` |\n\n## 遗留版本兼容性\n\nEvidently 保留了遗留版本的 API，确保向后兼容：\n\n### Legacy Report\n\n```python\nfrom evidently.legacy.report.report import Report as LegacyReport\n\n# 遗留版本报告创建方式\nlegacy_report = LegacyReport(\n metrics=[],\n mode='raw'\n)\n```\n\n### Legacy Test Suite\n\n```python\nfrom evidently.legacy.test_suite.test_suite import TestSuite as LegacyTestSuite\n\n# 遗留版本测试套件\nlegacy_suite = LegacyTestSuite(tests=[])\n```\n\n遗留版本模块位于 `src/evidently/legacy/` 目录下，新项目推荐使用核心模块 `src/evidently/core/` 下的实现。资料来源：[src/evidently/legacy/report/report.py:1-30]()\n\n## 最佳实践\n\n### 1. 选择合适的模块\n\n- **使用 Report**：当需要可视化分析、探索性数据检查、或需要生成可分享的 HTML 报告时\n- **使用 Test Suite**：当需要自动化验证、CI/CD 集成、或需要明确的通过/失败判断时\n- **组合使用**：在实际项目中，可以先使用 Report 进行分析，再将关键指标转化为 Test Suite 进行持续监控\n\n### 2. 数据准备\n\n确保输入数据格式正确：\n\n```python\nfrom evidently import Dataset, DataDefinition\n\n# 推荐的数据准备方式\ndataset = Dataset.from_pandas(\n pd.DataFrame(data),\n data_definition=DataDefinition()\n)\n```\n\n### 3. 性能优化\n\n对于大规模数据集，建议：\n\n- 使用 `verbose_level=0` 减少日志输出\n- 分批次处理时间序列数据\n- 复用 `ColumnMapping` 配置\n\n## 输出格式与集成\n\n### HTML 报告输出\n\n```python\n# 保存为 HTML 文件\nreport.save_html(\"output/report.html\")\n\n# 或者获取 HTML 字符串\nhtml_content = report.get_html()\n```\n\n### JSON 序列化\n\n```python\nimport json\n\n# 序列化为 JSON\njson_data = report.json()\nwith open(\"report.json\", \"w\") as f:\n json.dump(json_data, f)\n```\n\n### 与 Web UI 集成\n\nEvidently UI 支持加载报告文件进行交互式查看：\n\n```bash\nevidently ui --projects ./projects\n```\n\n生成的报告文件可通过 UI 的文件链接功能展示，模板定义位于 `src/evidently/ui/utils.py`。资料来源：[src/evidently/ui/utils.py:1-50]()\n\n## 总结\n\n报告与测试套件共同构成了 Evidently 框架的评估基础设施。报告模块侧重于深入的数据分析和可视化呈现，帮助用户理解模型行为；测试套件模块则提供可自动化的验证机制，确保生产环境的稳定性。两者基于共同的指标体系设计，可实现分析与监控的无缝衔接，是 ML/LLM 系统可靠性的重要保障。\n\n---\n\n\n\n## LLM集成与评判器\n\n### 相关页面\n\n相关主题：[描述符系统 (Descriptors)](#page-5), [Guardrails安全护栏](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/llm/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/__init__.py)\n- [src/evidently/llm/models.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/models.py)\n- [src/evidently/llm/prompts/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/prompts/__init__.py)\n- [src/evidently/llm/rag/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/rag/__init__.py)\n- [src/evidently/llm/datagen/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/datagen/__init__.py)\n- [src/evidently/llm/optimization/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/optimization/__init__.py)\n- [src/evidently/utils/llm/wrapper.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/utils/llm/wrapper.py)\n \n\n# LLM集成与评判器\n\n## 概述\n\nLLM集成与评判器是Evidently框架中用于评估和测试大型语言模型(LLM)输出质量的核心模块。该系统提供了完整的LLM驱动评估能力，支持通过预定义或自定义的评判标准对文本输出进行自动化质量评估。\n\nEvidently的LLM评判器允许用户创建结构化的评估流程，通过提示词模板(prompt templates)定义评估规则，并支持多类别分类、置信度评分等高级评估场景。\n\n## 系统架构\n\n### 核心模块结构\n\n| 模块 | 路径 | 功能描述 |\n|------|------|----------|\n| `llm` | `src/evidently/llm/` | LLM集成核心模块 |\n| `prompts` | `src/evidently/llm/prompts/` | 提示词模板管理 |\n| `rag` | `src/evidently/llm/rag/` | RAG相关评估 |\n| `datagen` | `src/evidently/llm/datagen/` | 测试数据生成 |\n| `optimization` | `src/evidently/llm/optimization/` | 提示词优化 |\n| `wrapper` | `src/evidently/utils/llm/wrapper.py` | LLM调用封装 |\n\n## 评判器配置\n\n### 描述符配置(Descriptor Config)\n\n描述符配置用于定义单个评估指标的元数据和参数。系统通过`ConfigAPI`类管理描述符配置的版本化存储。\n\n主要配置方法：\n\n- **创建描述符**：`add_descriptor()` - 添加新的描述符配置\n- **获取描述符**：`get_descriptor()` - 根据名称和版本获取描述符\n- **更新描述符**：通过版本控制机制实现配置的增量更新\n\n### 多分类评判模板\n\n系统支持多分类评判模板(`MulticlassClassificationPromptTemplate`)，用于需要将输入分类到多个预定义类别的评估场景。\n\n```typescript\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Descriptors/Features/LLMJudge/template.tsx:67\n{state.type === 'evidently:prompt_template:MulticlassClassificationPromptTemplate' && (\n \n Classes\n \n Provide classes for multiclass classification mode.\n \n {/* 类别配置表单 */}\n \n)}\n```\n\n### 评判标准配置\n\n评判器支持为每个分类类别定义独立的评判标准，通过`category_criteria`字典存储类别与对应评判规则的映射关系。\n\n## 用户界面集成\n\n### 评判模板编辑组件\n\n前端组件`LLMJudge/template.tsx`提供了可视化的评判模板配置界面，支持：\n\n- 评判类型选择\n- 类别定义与管理\n- 置信度阈值配置\n- 错误状态展示\n\n### 提示词管理界面\n\n系统提供完整的提示词生命周期管理：\n\n```typescript\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx\n{\n key: 'actions',\n label: 'Action',\n render: (prompt) => (\n \n \n onDelete(prompt.id ?? '')}>\n \n \n \n )\n}\n```\n\n支持的操作包括：\n- 创建新提示词\n- 编辑现有提示词\n- 删除提示词\n- 复制提示词ID\n\n## 工作流程\n\n### LLM评估流程\n\n```mermaid\ngraph TD\n A[输入数据] --> B[创建Dataset]\n B --> C[应用Descriptors]\n C --> D[LLM评判器处理]\n D --> E[生成评估结果]\n E --> F[生成Report]\n```\n\n### 提示词模板配置流程\n\n```mermaid\ngraph LR\n A[选择评判类型] --> B[配置评判标准]\n B --> C[设置类别阈值]\n C --> D[保存配置版本]\n D --> E[关联到Descriptor]\n```\n\n## SDK配置与API\n\n### 云端配置管理\n\n系统通过`CloudConfigAPI`类提供云端配置管理能力，支持：\n\n- 配置版本化存储\n- 元数据管理\n- 远程配置同步\n\n```python\n# 资料来源：src/evidently/sdk/configs.py\ndef add_descriptor(self, project_id: STR_UUID, name: str, descriptor: Descriptor) -> ConfigVersion:\n \"\"\"添加描述符配置\"\"\"\n return self._add_typed_version(project_id, name, descriptor)\n```\n\n### 适配器层\n\n`RemoteGenericConfig`适配器负责处理与远程服务的通信，包括：\n\n- 配置上传与下载\n- 版本历史查询\n- 内容序列化与反序列化\n\n## 数据模型\n\n### 配置版本元数据\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `id` | UUID | 配置版本唯一标识 |\n| `artifact_id` | UUID | 关联的描述符ID |\n| `version` | int | 版本号 |\n| `content` | Any | 配置内容 |\n| `metadata.created_at` | datetime | 创建时间 |\n| `metadata.updated_at` | datetime | 更新时间 |\n| `metadata.author` | str | 作者 |\n| `metadata.comment` | str | 版本注释 |\n\n### 评判器状态\n\n评判器状态通过React组件管理，包含：\n\n- 当前评判类型\n- 类别评判标准映射\n- 错误状态与消息\n- 不确定性阈值配置\n\n## 使用示例\n\n### 创建LLM评估数据集\n\n```python\nfrom evidently import Report, Dataset, DataDefinition\nfrom evidently.descriptors import Sentiment, TextLength, Contains\n\neval_dataset = Dataset.from_pandas(\n pd.DataFrame(eval_df),\n data_definition=DataDefinition(),\n descriptors=[\n Sentiment(\"answer\", alias=\"Sentiment\"),\n TextLength(\"answer\", alias=\"Length\"),\n Contains(\"answer\", pattern=\"denial_words\", alias=\"ContainsDenial\")\n ]\n)\n```\n\n### 生成评估报告\n\n```python\nreport = Report(metrics=[\n TextEvals()\n])\nreport.run(reference_dataset=reference_data, current_dataset=current_data)\nreport.save_html(\"evaluation_report.html\")\n```\n\n## 技术实现要点\n\n### 前端状态管理\n\n评判器模板组件使用React Hook Form进行表单状态管理，配合Zod进行数据验证：\n\n```typescript\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Descriptors/Features/LLMJudge/template.tsx\ntype FormSchema = z.infer\nconst formSchema = z.object({...})\n```\n\n### 错误处理机制\n\n系统实现了多层次的错误处理：\n\n1. **表单级错误**：通过`errors`对象捕获并展示字段级验证错误\n2. **API级错误**：通过`isLoading`状态管理异步操作错误\n3. **业务逻辑错误**：通过`AlertThemed`组件展示业务规则违反\n\n## 相关资源\n\n- [API Reference Documentation](https://evidentlyai.github.io/evidently/api-reference)\n- [LLM Evaluation Tutorial](https://docs.evidentlyai.com/quickstart_llm)\n- [Descriptor Configuration Guide](https://docs.evidentlyai.com/descriptors)\n\n---\n\n\n\n## Guardrails安全护栏\n\n### 相关页面\n\n相关主题：[LLM集成与评判器](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [src/evidently/ui/utils.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/utils.py)\n \n\n# Guardrails安全护栏\n\n## 概述\n\nGuardrails（安全护栏）是Evidently框架中用于监控和验证LLM（大型语言模型）输出的安全机制。该功能允许用户在追踪（Traces）中记录、检查和展示护栏的检查结果，确保AI系统的输出符合预定的安全和合规标准。\n\n在Evidently的架构中，Guardrails主要与Trace系统集成，通过`extractGuardRailsDataFromSpan`函数从span中提取护栏数据，并在UI层面提供可视化展示。资料来源：[TraceTable.tsx:22-32]()\n\n## 核心功能\n\n### 护栏数据提取\n\nGuardrails的数据来源于Trace中的各个span。通过`extractGuardRailsDataFromSpan`函数，系统能够从span中提取护栏相关的检查信息，包括：\n\n- **状态信息**：护栏检查通过或失败\n- **名称标识**：具体护栏类型的名称\n- **详细属性**：每个护栏的完整属性映射\n\n```typescript\n// 从span中提取GuardRails数据\ntrace.spans\n .map(extractGuardRailsDataFromSpan)\n .filter(isNotNull)\n .flat()\n```\n\n资料来源：[TraceTable.tsx:22-32]()\n\n### 护栏状态展示\n\nUI层提供了专门的`GuardRailStatus`组件来可视化展示护栏的通过/失败状态，通过颜色编码（绿色表示通过，红色表示失败）帮助用户快速识别问题。\n\n资料来源：[TraceComponent.tsx:12-16]()\n\n## 架构设计\n\n### 组件层级关系\n\n```mermaid\ngraph TD\n A[Trace] --> B[Spans]\n B --> C[GuardRails Data]\n C --> D[GuardRailsShowInfoButton]\n D --> E[GuardRailDialog]\n E --> F[GenericTable]\n F --> G[GuardRailStatus]\n \n A1[TraceTable] --> B1[GuardRails列]\n B1 --> C1[GuardRailsShowInfoButton]\n```\n\n### 护栏对话框流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Button as GuardRailsShowInfoButton\n participant Dialog as GuardRailDialog\n participant Table as GenericTable\n \n User->>Button: 查看护栏详情\n Button->>Dialog: setIsGuardRailDialogOpen(true)\n Dialog->>Table: 渲染护栏数据\n Table->>User: 显示通过/失败统计\n \n Note over Table: 统计passed/failed数量\n```\n\n## 数据结构\n\n### 护栏数据模型\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 护栏唯一标识符 |\n| `name` | string | 护栏名称（如toxicity、pii等） |\n| `status` | enum | 护栏状态：passed/failed |\n| `index` | number | 护栏在序列中的位置 |\n\n### 护栏按钮状态\n\n| 状态类型 | 条件 | 按钮样式 |\n|----------|------|----------|\n| all-passed | 所有护栏通过 | outlined + success颜色 |\n| failed | 存在护栏失败 | contained + error颜色 |\n\n资料来源：[GuardRailsShowInfoButton.tsx:10-20]()\n\n## UI组件详解\n\n### GuardRailsShowInfoButton\n\n该组件是护栏信息的入口按钮，根据护栏通过/失败状态显示不同的UI样式：\n\n```typescript\n\n {guardRailButtonInfoType === 'all-passed'\n ? `${passedGuardRailDataCount}/${allGuardRailDataCount} passed`\n : `${failedGuardRailDataCount}/${allGuardRailDataCount} failed`}\n\n```\n\n资料来源：[GuardRailsShowInfoButton.tsx:10-22]()\n\n### GuardRailDialog\n\n对话框组件用于展示完整的护栏检查结果：\n\n```typescript\n\n Guard rails\n \n \n \n\n```\n\n资料来源：[GuardRailsShowInfoButton.tsx:33-56]()\n\n### TraceTable中的护栏列\n\n在TraceTable组件中，护栏作为独立的列进行展示，支持条件渲染（当所有span均无护栏数据时跳过该列）：\n\n```typescript\n{\n key: 'guardrails',\n label: 'Guardrails',\n align: 'center',\n skipRender: data.every(\n (trace) =>\n trace.spans.map(extractGuardRailsDataFromSpan)\n .filter(isNotNull).flat().length === 0\n ),\n render: (trace) => (\n \n )\n}\n```\n\n资料来源：[TraceTable.tsx:22-42]()\n\n## 护栏渲染详情\n\n在TraceComponent中，护栏数据以表格形式展示每个属性的键值对：\n\n```typescript\n{Object.entries(guardRail).map(([k, v]) => (\n \n \n {k}\n \n \n {k === 'status' ? (\n \n ) : (\n \n )}\n \n \n))}\n```\n\n资料来源：[TraceComponent.tsx:18-34]()\n\n## 配置选项\n\n### 护栏对话框配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `open` | boolean | - | 对话框打开状态 |\n| `fullWidth` | boolean | true | 宽度占满容器 |\n| `maxWidth` | string | 'md' | 最大宽度 |\n| `PaperComponent` | component | Box | 纸张组件包装 |\n\n### 按钮样式配置\n\n| 样式条件 | color | variant |\n|----------|-------|---------|\n| 全部通过 | 'success' | 'outlined' |\n| 存在失败 | 'error' | 'contained' |\n\n资料来源：[GuardRailsShowInfoButton.tsx:10-22]()\n\n## 使用场景\n\n### 在Trace追踪中集成护栏\n\n```typescript\n// 在TraceViewer中展示护栏信息\n\n {childSelectedSpans.length > 0 && (\n Child spans\n )}\n\n```\n\n### 条件渲染护栏列\n\n当项目中没有任何护栏数据时，对应的表格列会被自动隐藏，优化用户界面：\n\n```typescript\nskipRender: data.every(\n (trace) =>\n trace.spans.map(extractGuardRailsDataFromSpan)\n .filter(isNotNull).flat().length === 0\n)\n```\n\n资料来源：[TraceTable.tsx:26-30]()\n\n## 与其他模块的集成\n\n### 与LLM Judge的关联\n\n在LLM Judge模板中，护栏系统与评估标准协同工作，支持多类别评估标准的配置：\n\n```typescript\n{state.type === 'evidently:prompt_template:MulticlassClassificationPromptTemplate' && (\n \n Classes\n \n {Object.keys(state.category_criteria ?? {}).map((className) => (\n \n ))}\n \n \n)}\n```\n\n资料来源：[LLMJudge/template.tsx:35-45]()\n\n### 与项目管理的集成\n\n通过ProjectCard组件，用户可以在项目管理界面中快速访问包含护栏数据的Trace记录，实现端到端的安全监控工作流。\n\n## 最佳实践\n\n### 护栏数据过滤\n\n```typescript\n// 使用filter和flat处理多span场景\ntrace.spans\n .map(extractGuardRailsDataFromSpan)\n .filter(isNotNull)\n .flat()\n```\n\n### 状态判断逻辑\n\n```typescript\nconst guardRailButtonInfoType = \n passedGuardRailDataCount === allGuardRailDataCount\n ? 'all-passed'\n : 'failed'\n```\n\n资料来源：[GuardRailsShowInfoButton.tsx:1-8]()\n\n## 总结\n\nGuardrails安全护栏是Evidently框架中保障LLM应用安全的重要组件。通过与Trace系统的深度集成，它提供了：\n\n- **可视化监控**：直观的UI展示护栏检查结果\n- **状态追踪**：通过颜色编码快速识别安全问题\n- **条件渲染**：智能隐藏无数据列，保持界面整洁\n- **详情查看**：对话框形式展示完整护栏属性\n\n该系统为AI安全工程师和开发团队提供了有效的工具，用于监控和验证AI模型的输出是否符合预期的安全标准。\n\n---\n\n\n\n## 数据管理与存储\n\n### 相关页面\n\n相关主题：[报告与测试套件](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/ui/service/datasets/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/datasets/__init__.py)\n- [src/evidently/ui/service/storage/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/storage/__init__.py)\n- [src/evidently/ui/service/storage/local/base.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/storage/local/base.py)\n- [src/evidently/ui/service/storage/sql/base.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/storage/sql/base.py)\n- [src/evidently/ui/service/storage/sql/dataset.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/storage/sql/dataset.py)\n- [src/evidently/ui/service/datasets/models.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/datasets/models.py)\n- [src/evidently/core/datasets.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/datasets.py)\n \n\n# 数据管理与存储\n\n## 概述\n\nEvidently 的数据管理与存储系统是框架的核心组件之一，负责处理数据集的持久化、检索和管理。该系统采用分层架构设计，支持多种存储后端，为 ML 和 LLM 系统的评估、测试与监控提供了可靠的数据基础设施。\n\n系统的主要职责包括：\n\n- 数据集的创建、读取、更新和删除（CRUD）操作\n- 支持本地文件系统存储和 SQL 数据库存储两种后端\n- 提供统一的数据访问接口，屏蔽底层存储差异\n- 管理数据集的元数据信息\n- 支持数据集与项目、快照的关联关系\n\n资料来源：[src/evidently/ui/service/storage/__init__.py]()\n\n## 架构设计\n\n### 整体架构\n\n系统采用典型的分层架构模式，自上而下分为三个主要层次：\n\n```mermaid\ngraph TD\n A[应用层] --> B[服务层]\n B --> C[存储层]\n C --> D[本地存储]\n C --> E[SQL 存储]\n \n B --> F[数据集服务
Datasets Service]\n F --> G[数据模型
DatasetModel]\n \n D --> H[本地文件系统]\n E --> I[(SQLite/PostgreSQL)]\n```\n\n### 存储后端类型\n\n| 存储类型 | 文件路径 | 适用场景 |\n|---------|---------|---------|\n| 本地存储 | `storage/local/base.py` | 开发环境、单节点部署 |\n| SQL 存储 | `storage/sql/base.py` | 生产环境、多用户协作 |\n\n资料来源：[src/evidently/ui/service/storage/local/base.py](), [src/evidently/ui/service/storage/sql/base.py]()\n\n## 核心数据模型\n\n### 数据集模型\n\n`DatasetModel` 是数据集的核心数据结构，定义了数据集的所有属性：\n\n```python\nclass DatasetModel:\n id: DatasetID # 唯一标识符\n project_id: ProjectID # 所属项目ID\n name: str # 数据集名称\n description: Optional[str] # 数据集描述\n metadata: DatasetMetadata # 元数据信息\n created_at: datetime # 创建时间\n updated_at: datetime # 更新时间\n author: Optional[str] # 创建者\n```\n\n资料来源：[src/evidently/ui/service/datasets/models.py]()\n\n### 元数据结构\n\n```python\n@dataclass\nclass DatasetMetadata:\n created_at: datetime # 创建时间戳\n updated_at: datetime # 更新时间戳\n author: Optional[str] # 创建者信息\n description: Optional[str] # 描述信息\n tags: Optional[List[str]] # 标签列表\n link: Optional[str] # 关联链接\n```\n\n资料来源：[src/evidently/ui/service/datasets/models.py]()\n\n## 服务层组件\n\n### 数据集服务\n\n数据集服务（`DatasetsService`）是应用层与存储层之间的桥梁，提供统一的数据集操作接口：\n\n| 方法 | 功能描述 |\n|-----|---------|\n| `add()` | 创建新数据集 |\n| `load()` | 加载数据集内容 |\n| `list()` | 列出项目中的所有数据集 |\n| `delete()` | 删除指定数据集 |\n\n资料来源：[src/evidently/ui/service/datasets/__init__.py]()\n\n### 服务工作流\n\n```mermaid\nsequenceDiagram\n participant Client\n participant DatasetsService\n participant StorageLayer\n participant Backend\n \n Client->>DatasetsService: add_dataset(project_id, dataset)\n DatasetsService->>StorageLayer: save(dataset)\n StorageLayer->>Backend: write data\n Backend-->>StorageLayer: confirmation\n StorageLayer-->>DatasetsService: saved dataset\n DatasetsService-->>Client: dataset ID\n \n Client->>DatasetsService: load_dataset(dataset_id)\n DatasetsService->>StorageLayer: retrieve(dataset_id)\n StorageLayer->>Backend: read data\n Backend-->>StorageLayer: data\n StorageLayer-->>DatasetsService: Dataset object\n DatasetsService-->>Client: Dataset\n```\n\n## 存储层实现\n\n### 存储接口抽象\n\n存储层定义了统一的抽象接口，具体实现类负责与不同的存储后端交互：\n\n```python\nclass BaseStorage(ABC):\n \"\"\"存储层抽象基类\"\"\"\n \n @abstractmethod\n def save(self, dataset: Dataset) -> DatasetID: ...\n \n @abstractmethod\n def load(self, dataset_id: DatasetID) -> Dataset: ...\n \n @abstractmethod\n def list(self, project_id: ProjectID) -> DatasetList: ...\n \n @abstractmethod\n def delete(self, dataset_id: DatasetID) -> None: ...\n```\n\n资料来源：[src/evidently/ui/service/storage/__init__.py]()\n\n### 本地存储实现\n\n本地存储适配器使用文件系统作为数据持久化后端：\n\n| 配置项 | 说明 |\n|-------|------|\n| `base_path` | 存储根目录路径 |\n| `format` | 数据序列化格式（JSON/Parquet） |\n| `max_size_mb` | 单个数据集大小限制 |\n\n**数据组织结构：**\n\n```\n{base_path}/\n└── {project_id}/\n └── {dataset_id}/\n ├── data.{format}\n └── metadata.json\n```\n\n资料来源：[src/evidently/ui/service/storage/local/base.py]()\n\n### SQL 存储实现\n\nSQL 存储适配器支持多种关系型数据库：\n\n```python\nclass SQLStorage(BaseStorage):\n \"\"\"SQL 数据库存储实现\"\"\"\n \n def __init__(\n self,\n connection_string: str,\n table_prefix: str = \"evidently_\"\n ):\n self.engine = create_engine(connection_string)\n self.table_prefix = table_prefix\n```\n\n**支持的数据库：**\n\n| 数据库 | 连接字符串格式 |\n|-------|---------------|\n| SQLite | `sqlite:///path/to/db.sqlite` |\n| PostgreSQL | `postgresql://user:pass@host:5432/db` |\n\n资料来源：[src/evidently/ui/service/storage/sql/base.py](), [src/evidently/ui/service/storage/sql/dataset.py]()\n\n## 核心数据集模块\n\n### 核心数据集类\n\n`Dataset` 类是框架层面的数据集抽象，定义在核心模块中：\n\n```python\nclass Dataset:\n \"\"\"数据集核心抽象\"\"\"\n \n def __init__(\n self,\n dataframe: pd.DataFrame,\n data_definition: DataDefinition,\n descriptors: Optional[List[Descriptor]] = None\n ):\n self._dataframe = dataframe\n self._data_definition = data_definition\n self._descriptors = descriptors or []\n```\n\n资料来源：[src/evidently/core/datasets.py]()\n\n### 数据集工厂方法\n\n```python\n@classmethod\ndef from_pandas(\n cls,\n dataframe: pd.DataFrame,\n data_definition: DataDefinition = None,\n descriptors: List[Descriptor] = None\n) -> \"Dataset\":\n \"\"\"从 Pandas DataFrame 创建数据集\"\"\"\n ...\n```\n\n资料来源：[src/evidently/core/datasets.py]()\n\n## API 端点\n\n数据集相关的 REST API 端点：\n\n| 方法 | 端点 | 功能 |\n|-----|------|-----|\n| POST | `/api/v2/datasets/{project_id}` | 创建数据集 |\n| GET | `/api/v2/datasets/{dataset_id}` | 获取数据集 |\n| GET | `/api/v2/datasets` | 列出数据集 |\n| PUT | `/api/v2/datasets/{dataset_id}` | 更新数据集 |\n| DELETE | `/api/v2/datasets/{dataset_id}` | 删除数据集 |\n\n## 配置指南\n\n### 存储后端配置\n\n```python\nfrom evidently.ui.service.storage import WorkspaceStorage\n\n# 本地存储配置\nlocal_storage = WorkspaceStorage.local(\n base_path=\"./data/evidently\",\n format=\"parquet\"\n)\n\n# SQL 存储配置\nsql_storage = WorkspaceStorage.sql(\n connection_string=\"sqlite:///evidently.db\",\n table_prefix=\"ev_\"\n)\n```\n\n### 环境变量配置\n\n| 变量名 | 说明 | 默认值 |\n|-------|------|-------|\n| `EVIDENTLY_DATA_DIR` | 本地存储路径 | `./evidently_data` |\n| `EVIDENTLY_DB_URL` | 数据库连接字符串 | SQLite 本地文件 |\n| `EVIDENTLY_STORAGE_TYPE` | 存储类型 | `local` |\n\n## 数据流转\n\n```mermaid\ngraph LR\n A[CSV/Parquet] --> B[DataLoader]\n B --> C[Dataset]\n C --> D[Descriptors]\n D --> E[Evaluations]\n \n F[Report] --> G[Snapshot]\n G --> H[Storage]\n \n C -.->|持久化| H\n```\n\n## 最佳实践\n\n### 数据集命名规范\n\n- 使用有意义的名称，包含项目标识和用途\n- 避免使用特殊字符和空格\n- 推荐格式：`{project}_{purpose}_{version}`\n\n### 存储策略建议\n\n1. **小数据集（< 100MB）**：使用本地存储或 SQLite\n2. **中等数据集（100MB - 1GB）**：使用 PostgreSQL\n3. **大数据集（> 1GB）**：考虑分区存储或外部存储服务\n\n### 性能优化\n\n- 为 `project_id` 和 `created_at` 字段建立索引\n- 定期清理过期数据集\n- 使用 Parquet 格式减少存储空间\n\n## 相关模块\n\n- [evidently.sdk.adapters](./sdk/adapters) - 云端适配器\n- [evidently.ui.workspace](./ui/workspace) - 工作空间管理\n- [evidently.legacy.metrics](./legacy/metrics) - 指标计算\n\n---\n\n\n\n## 前端UI组件库\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# 前端UI组件库\n\n## 概述\n\nEvidently UI组件库（`evidently-ui-lib`）是一个共享的前端组件包，同时服务于 `service`（服务模式）和 `standalone`（独立模式）两种部署场景。该组件库基于React和TypeScript构建，集成了Material UI（@mui/material）作为基础UI框架，提供数据可视化、仪表板、追踪管理、提示词管理等核心功能模块。\n\n资料来源：[ui/packages/evidently-ui-lib/README.md](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/README.md)\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[evidently-ui-lib] --> B[Dashboard 模块]\n A --> C[Traces 模块]\n A --> D[Prompts 模块]\n A --> E[Datasets 模块]\n A --> F[Widgets 模块]\n A --> G[通用组件]\n \n B --> B1[DashboardWidgets]\n B --> B2[DashboardPanel]\n B --> B3[DashboardDateFilter]\n \n C --> C1[TracesTable]\n C --> C2[TraceTable]\n C --> C3[DialogViewer]\n C --> C4[TraceViewer]\n \n D --> D1[PromptsTable]\n D --> D2[CreatePromptForm]\n D --> D3[Edit Prompt]\n \n F --> F1[Widget]\n F --> F2[BigTableDetails]\n F --> F3[AlertBlock]\n F --> F4[InsightBlock]\n \n G --> G1[BaseTabs]\n G --> G2[NameAndDescriptionForm]\n G --> G3[TextPanel]\n```\n\n## 核心模块\n\n### 1. 仪表板模块（Dashboard）\n\n仪表板模块负责展示监控面板和数据可视化组件，支持时间范围过滤和多种面板类型。\n\n#### DashboardWidgets 组件\n\n主仪表板渲染组件，根据传入的 `WidgetInfo[]` 数组动态渲染监控面板。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `widgets` | `WidgetInfo[]` | 要渲染的组件信息数组 |\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Widgets/DashboardWidgets.tsx\nexport const DashboardWidgets = ({ widgets }: { widgets: WidgetInfo[] }) => {\n if (widgets.length === 0) {\n return (\n \n This dashboard is currently empty. Please add a monitoring panel to start.\n \n )\n }\n return \n}\n```\n\n#### DashboardPanel 面板系统\n\n支持多种面板类型，包括文本面板、数值面板、图表面板等。\n\n```mermaid\ngraph LR\n A[面板类型] --> B[text 文本面板]\n A --> C[line_plot 线图面板]\n A --> D[big_table 大表格面板]\n \n B --> B1[PanelCardGeneral]\n C --> C1[LinePlot 渲染]\n D --> D1[BigTableDetails]\n```\n\n**Text 文本面板**实现示例：\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Dashboard/Panels/implementations/Text.tsx\nexport type TextPanelProps = MakePanel<{\n type: 'text'\n size: 'full' | 'half'\n title?: string\n description?: string\n}>\n\nexport const TextDashboardPanel = ({ title, description }: TextPanelProps) => {\n return (\n \n )\n}\n```\n\n#### 日期过滤器\n\n仪表板支持日期范围过滤，用于限制数据展示的时间区间。\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Dashboard/DashboardDateFilter.tsx\n// 支持 dateFrom 和 dateTo 两个日期选择器\n// 当 dateFrom 晚于 dateTo 时显示错误提示\n\n \n Error\n Incorrect time interval\n \n\n```\n\n### 2. 追踪模块（Traces）\n\n追踪模块负责展示和管理AI应用执行追踪数据，支持查看、过滤、编辑和删除操作。\n\n#### TracesTable 组件\n\n主追踪列表表格，支持排序、分页和多种列展示。\n\n| 列名 | 类型 | 说明 | 可排序 |\n|------|------|------|--------|\n| `tags` | ReactNode | 追踪标签 | 否 |\n| `metadata` | ReactNode | 元数据（JSON格式） | 否 |\n| `type` | ReactNode | 追踪来源类型 | 否 |\n| `created_at` | string | 创建时间 | 是 |\n| `actions` | ReactNode | 操作按钮组 | 否 |\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Traces/TracesTable.tsx\n{\n key: 'created_at',\n label: 'Created at',\n sortable: {\n getSortValue: (trace) => trace.created_at,\n isDateString: true\n },\n render: (trace) => (\n \n {dayjs(trace.created_at).locale('en-gb').format('llll')}\n \n )\n}\n```\n\n#### TraceTable 详情表格\n\n用于追踪详情页面，包含token使用量、Guardrails状态等高级信息。\n\n| 列名 | 说明 | 特殊属性 |\n|------|------|----------|\n| `end_time` | 结束时间 | - |\n| `token_usage` | Token使用量 | - |\n| `guardrails` | Guardrails信息 | 条件显示 |\n| `actions` | 操作按钮 | sticky |\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Traces/TraceViewer/components/TraceTable.tsx\n{\n key: 'guardrails',\n label: 'Guardrails',\n align: 'center',\n skipRender: data.every(\n (trace) =>\n trace.spans.map(extractGuardRailsDataFromSpan).filter(isNotNull).flat().length === 0\n ),\n render: (trace) => (\n \n )\n}\n```\n\n#### DialogViewer 对话查看器\n\n用于会话消息展示，支持用户消息和代理消息的双栏显示。\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Traces/DialogViewer/components/Message.tsx\n// 消息组件关键属性\n{\n message: string // 消息内容\n align: 'left' | 'right' // 对齐方向\n time: string // 时间戳\n}\n```\n\n### 3. 提示词模块（Prompts）\n\n提示词管理模块，支持提示词的列表展示、创建、编辑和版本管理。\n\n#### PromptsTable 组件\n\n提示词列表表格，包含以下列：\n\n| 列名 | 渲染内容 | 说明 |\n|------|----------|------|\n| `id` | ID + 复制按钮 | 支持一键复制 |\n| `name` | 文本（最大宽度200px） | 提示词名称 |\n| `created_at` | 日期时间格式 | 创建时间 |\n| `actions` | 链接 + 删除按钮 | 操作区 |\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx\n{\n key: 'id',\n label: 'ID',\n align: 'center',\n render: (prompt) => (\n \n {prompt.id}\n \n \n )\n}\n```\n\n#### 表单组件\n\n**通用名称描述表单**：\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx\nexport type NameAndDescriptionFormProps = {\n defaultValues: {\n name?: string\n description?: string\n }\n onSubmit: (data: { name: string; description: string }) => void\n isLoading?: boolean\n allowSubmitDefaults?: boolean\n submitButtonTitle?: string\n}\n\n// 使用 zod 进行表单验证\nconst nameAndDescriptionSchema = z.object({\n name: z.string().min(1),\n description: z.string()\n})\n```\n\n**创建提示词表单**：\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Prompts/Forms/CreatePromptForm.tsx\n// 包含 name 字段验证\n// 禁用条件：isLoading || !isDirty || Object.keys(errors).length > 0\n```\n\n### 4. 组件模块（Widgets）\n\n核心可视化组件系统，负责渲染各类监控面板、告警和洞察信息。\n\n#### Widget 主组件\n\n主组件渲染器，支持标题、内容、详情、告警统计和洞察展示。\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/widgets/Widget.tsx\n// 组件结构\n\n \n \n \n {/* 标题和内容 */}\n \n {title}\n {content}
\n \n \n {/* 告警区域 */}\n {isAlertsExists ? (\n <>\n {alertStats ? : <>}\n {alerts?.map((alert) => )}\n \n ) : <>}\n \n {/* 洞察区域 */}\n {isInsightsExists ? (\n insights?.map((insight) => )\n ) : <>}\n \n \n \n\n```\n\n#### BigTableDetails 大表格详情\n\n支持多部分详情展示和洞察信息渲染。\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/widgets/BigTableWidget/BigTableDetails.tsx\nexport const BigTableDetails: React.FunctionComponent = (props) => {\n return (\n \n {(dashboardContext) => (\n \n {/* 多部分使用 AutoTabs 切换 */}\n {props.details.parts.length > 1 ? (\n ({\n title: part.title,\n tab: RenderPart(dashboardContext, part, props.widgetSize)\n }))}\n />\n ) : (\n RenderPart(dashboardContext, props.details.parts[0], props.widgetSize)\n )}\n \n {/* 洞察块渲染 */}\n {props.details.insights === undefined ? (\n <>\n ) : (\n props.details.insights.map((row) => (\n \n ))\n )}\n \n )}\n \n )\n}\n```\n\n### 5. 通用组件\n\n#### BaseTabs 标签页组件\n\n通用的标签页切换组件，支持手风琴模式。\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Tabs/BaseTabs.tsx\n// 属性接口\n{\n tabs: Array<{\n title: string // 标签标题\n tab: ReactNode // 标签内容\n content?: ReactNode // 可选的额外内容\n }>\n activeTab: number // 当前激活索引，-1表示全部显示\n}\n```\n\n#### 工具类组件\n\n| 组件名 | 功能 |\n|--------|------|\n| `TextWithCopyIcon` | 带复制图标的文本展示 |\n| `LoadableView` | 加载状态包装器 |\n| `JsonViewThemed` | 主题化JSON查看器 |\n| `HidedTags` | 折叠标签组件 |\n| `Tooltip` | 提示气泡 |\n| `AlertThemed` | 主题化警告框 |\n\n## 数据流向\n\n```mermaid\ngraph TD\n A[API 数据源] --> B[evidently-ui-lib API 模块]\n B --> C[组件状态管理]\n C --> D[UI 渲染层]\n \n D --> E[DashboardWidgets]\n D --> F[TracesTable]\n D --> G[PromptsTable]\n D --> H[Widget]\n \n E --> I[DrawWidgets]\n F --> J[DialogViewer]\n G --> K[CreatePromptForm]\n H --> L[AlertBlock / InsightBlock]\n```\n\n## 类型定义\n\n核心类型定义位于各组件文件及 `api/index.tsx` 模块中：\n\n```tsx\n// WidgetInfo 类型（示例）\ninterface WidgetInfo {\n id: string\n type: string\n title?: string\n size: 'full' | 'half'\n // ... 其他属性\n}\n\n// Trace 类型（示例）\ninterface Trace {\n id: string\n trace_id: string\n created_at: string\n tags: Record[]\n metadata: object\n origin: string\n spans: Span[]\n}\n\n// Prompt 类型（示例）\ninterface Prompt {\n id: string | null\n name: string\n metadata?: {\n created_at: string\n }\n}\n```\n\n## 依赖关系\n\n| 依赖包 | 版本/用途 |\n|--------|----------|\n| React | 18.x - UI框架 |\n| @mui/material | Material UI组件库 |\n| @emotion/react | 样式解决方案 |\n| dayjs | 日期时间处理 |\n| zod | 表单验证 |\n| react-hook-form | 表单状态管理 |\n\n## 部署模式\n\n组件库支持两种部署模式，通过 `ui/packages/evidently-ui-lib/README.md` 说明：\n\n1. **Service 模式**：作为后端服务的集成UI组件\n2. **Standalone 模式**：独立运行的Web应用\n\n两种模式共享同一套组件库，确保UI一致性和代码复用。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：evidentlyai/evidently\n\n摘要：发现 19 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Update scikit-learn version requirement to support v1.6.0。\n\n## 1. 安装坑 · 来源证据：Update scikit-learn version requirement to support v1.6.0\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update scikit-learn version requirement to support v1.6.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e82e24d201134e7f8dfa0b564d73fce8 | https://github.com/evidentlyai/evidently/issues/1407 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：PromptOptimizer throws OpenAIError when using Vertex AI judge\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：PromptOptimizer throws OpenAIError when using Vertex AI judge\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abf6f9b183ff4892be78fd198f60d8e8 | https://github.com/evidentlyai/evidently/issues/1856 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 运行坑 · 来源证据：IndexError in infer_column_type when column contains only null values\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：IndexError in infer_column_type when column contains only null values\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_44cdd5f2b657432eb8418fb132959ada | https://github.com/evidentlyai/evidently/issues/1764 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_872f2b57cd3a4c61ad5c387c8be3208b | https://github.com/evidentlyai/evidently/issues/1410 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Numpy 2.x support?\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Numpy 2.x support?\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2fc84415b55a43d2be4f7f47cf46d7a1 | https://github.com/evidentlyai/evidently/issues/1557 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v0.7.12\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.12\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fcf994a3bcf94b0d9b2c5d6159816728 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.12 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v0.7.15\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.15\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a9de117bd8e440beab9f7be4af50d710 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.15 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v0.7.20\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.20\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f0d67058bf2a40218adfb0eea1f1665f | https://github.com/evidentlyai/evidently/releases/tag/v0.7.20 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 9. 能力坑 · 来源证据：v0.7.19\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.7.19\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_52e6ab37edca4901a0aa9fe7b5ba12f1 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.19 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 能力坑 · 来源证据：v0.7.21\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.7.21\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fe9f0e6e29564afeb5610928cc9bc834 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.21 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:315977578 | https://github.com/evidentlyai/evidently | README/documentation is current enough for a first validation pass.\n\n## 12. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | last_activity_observed missing\n\n## 13. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:315977578 | https://github.com/evidentlyai/evidently | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:315977578 | https://github.com/evidentlyai/evidently | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Protect this repo from AI-generated PRs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Protect this repo from AI-generated PRs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cfcf13543c3941e88fd7c5f527f95dc3 | https://github.com/evidentlyai/evidently/issues/1879 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：v0.7.17\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.17\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_305e0831e389460096b4d4b908731b41 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.17 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v0.7.18\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.18\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_19a463a1bb2a4fb2bd5bd894c914cc36 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.18 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | release_recency=unknown\n\n\n",
"markdown_key": "evidently",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:315977578",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/evidentlyai/evidently"
},
{
"evidence_id": "art_e0f9cd67e5e547ec994f4c58cc5c9526",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/evidentlyai/evidently#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "evidently 说明书",
"toc": [
"https://github.com/evidentlyai/evidently 项目说明书",
"目录",
"项目介绍与安装",
"项目概述",
"系统架构",
"安装方式",
"基础模块",
"扩展指标模块",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "a4aa4c2b37fe7a4344cc5031f566deccf3d69e4f",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"examples/README.md",
"examples/cookbook/README.md",
"examples/service/postgres_config.yaml",
"examples/service/sqlite_config.yaml",
"examples/service/README.md",
"examples/service/docker-compose.yml",
"examples/service/remote_demo_project.py",
"examples/grafana/README.md",
"examples/future_examples/future_reviews.py",
"examples/grafana/grafana_llm_evaluation_dashboard/README.md",
"examples/grafana/grafana_llm_evaluation_dashboard/docker-compose.yml",
"examples/grafana/grafana_llm_evaluation_dashboard/evidently_metrics_calculation.py",
"examples/grafana/grafana_data_drift_dashboard/README.md",
"examples/grafana/grafana_data_drift_dashboard/docker-compose.yml",
"examples/grafana/grafana_data_drift_dashboard/evidently_metrics_calculation.py",
"examples/grafana/grafana_llm_evaluation_dashboard/config/grafana_dashboards.yaml",
"examples/grafana/grafana_llm_evaluation_dashboard/config/grafana_datasources.yaml",
"examples/grafana/grafana_llm_evaluation_dashboard/dashboards/chatbot_evals.json",
"examples/grafana/grafana_data_drift_dashboard/config/grafana_dashboards.yaml",
"examples/grafana/grafana_data_drift_dashboard/config/grafana_datasources.yaml",
"examples/grafana/grafana_data_drift_dashboard/dashboards/data_drift.json",
"src/evidently/telemetry.py",
"src/evidently/_registry.py",
"src/evidently/_pydantic_compat.py",
"src/evidently/_version.py",
"src/evidently/pydantic_utils.py",
"src/evidently/errors.py",
"src/evidently/__init__.py",
"src/evidently/cli/migrate.py",
"src/evidently/cli/report.py",
"src/evidently/cli/main.py",
"src/evidently/cli/demo_project.py",
"src/evidently/cli/utils.py",
"src/evidently/cli/ui.py",
"src/evidently/cli/legacy_ui.py",
"src/evidently/cli/__init__.py",
"src/evidently/cli/__main__.py",
"src/evidently/widgets/__init__.py"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# html-visual-testing - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 html-visual-testing 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install evidently` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `pip install virtualenv` 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0005` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：1217\n- 重要文件覆盖：40/1217\n- 证据索引条目：64\n- 角色 / Skill 条目：15\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 html-visual-testing 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 html-visual-testing 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 html-visual-testing 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 15 个角色 / Skill / 项目文档条目。\n\n- **:bar chart: What is Evidently?**（project_doc）：An open-source framework to evaluate, test and monitor ML and LLM-powered systems. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Evidently API Reference Documentation**（project_doc）：Evidently API Reference Documentation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`api-reference/README.md`\n- **Examples**（project_doc）：This folder contains examples of how to use Evidently to evaluate, test, and monitor different types of AI systems: agentic workflows, LLM applications, and traditional ML models. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/README.md`\n- **Evidently UI**（project_doc）：- service service - monitoring UI - standalone standalone - additional package we use for embedding graphics for instance in jupyter notebook and other places 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`ui/README.md`\n- **Cookbook**（project_doc）：This folder contains short, focused examples for specific Evidently functionality. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/cookbook/README.md`\n- **Grafana**（project_doc）：This folder contains examples of using Evidently metrics with Grafana dashboards. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/grafana/README.md`\n- **Monitoring example**（project_doc）：You need following tools installed: - docker - docker-compose included to Docker Desktop for Mac and Docker Desktop for Windows 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/grafana/grafana_data_drift_dashboard/README.md`\n- **Monitoring example**（project_doc）：You need following tools installed: - docker - docker-compose included to Docker Desktop for Mac and Docker Desktop for Windows 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/grafana/grafana_llm_evaluation_dashboard/README.md`\n- **Evidently UI Demo: Remote Project Example**（project_doc）：Evidently UI Demo: Remote Project Example 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/service/README.md`\n- **Alembic Migrations for SQL Storage**（project_doc）：This directory contains Alembic migration scripts for managing database schema changes in the SQL storage backend. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`src/evidently/ui/service/storage/sql/migrations/README.md`\n- **Readme**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`ui/html-visual-testing/README.md`\n- **Evidently UI**（project_doc）：Package common to service and standalone 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`ui/packages/evidently-ui-lib/README.md`\n- **Evidently UI service**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`ui/service/README.md`\n- **Evidently standalone**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`ui/standalone/README.md`\n- **Contributing to Evidently**（project_doc）：Thank you for considering contributing to Evidently! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n\n## 证据索引\n\n- 共索引 64 条证据。\n\n- **:bar chart: What is Evidently?**（documentation）：An open-source framework to evaluate, test and monitor ML and LLM-powered systems. 证据：`README.md`\n- **Evidently API Reference Documentation**（documentation）：Evidently API Reference Documentation 证据：`api-reference/README.md`\n- **Examples**（documentation）：This folder contains examples of how to use Evidently to evaluate, test, and monitor different types of AI systems: agentic workflows, LLM applications, and traditional ML models. 证据：`examples/README.md`\n- **Evidently UI**（documentation）：- service service - monitoring UI - standalone standalone - additional package we use for embedding graphics for instance in jupyter notebook and other places 证据：`ui/README.md`\n- **Cookbook**（documentation）：This folder contains short, focused examples for specific Evidently functionality. 证据：`examples/cookbook/README.md`\n- **Grafana**（documentation）：This folder contains examples of using Evidently metrics with Grafana dashboards. 证据：`examples/grafana/README.md`\n- **Monitoring example**（documentation）：You need following tools installed: - docker - docker-compose included to Docker Desktop for Mac and Docker Desktop for Windows 证据：`examples/grafana/grafana_data_drift_dashboard/README.md`\n- **Monitoring example**（documentation）：You need following tools installed: - docker - docker-compose included to Docker Desktop for Mac and Docker Desktop for Windows 证据：`examples/grafana/grafana_llm_evaluation_dashboard/README.md`\n- **Evidently UI Demo: Remote Project Example**（documentation）：Evidently UI Demo: Remote Project Example 证据：`examples/service/README.md`\n- **Alembic Migrations for SQL Storage**（documentation）：This directory contains Alembic migration scripts for managing database schema changes in the SQL storage backend. 证据：`src/evidently/ui/service/storage/sql/migrations/README.md`\n- **Evidently UI**（documentation）：Package common to service and standalone 证据：`ui/packages/evidently-ui-lib/README.md`\n- **Evidently UI service**（documentation）：Evidently UI service 证据：`ui/service/README.md`\n- **Evidently standalone**（documentation）：Evidently standalone 证据：`ui/standalone/README.md`\n- **Package**（package_manifest）：{ \"version\": \"1.0.0\", \"description\": \"Evidently UI Monorepo\", \"scripts\": { \"type-check\": \"pnpm --workspace-concurrency 1 -r type-check\", \"code-check\": \"pnpm -r code-check\", \"build\": \"pnpm -r build\", \"clean-assets-service\": \"rm -rf ../src/evidently/ui/service/assets/ \", \"clean-assets-standalone\": \"rm -rf ../src/evidently/nbextension/static/index.js\", \"copy-assets-service\": \"cp -r ./service/dist/ ../src/evidently/ui/service/assets\", \"copy-assets-standalone\": \"cp ./standalone/dist/index.js ../src/evidently/nbextension/static\", \"clean-assets-all\": \"pnpm clean-assets-service && pnpm clean-assets-standalone\", \"copy-assets-all\": \"pnpm copy-assets-service && pnpm copy-assets-standalone\", \"full-buil… 证据：`ui/package.json`\n- **Contributing to Evidently**（documentation）：Thank you for considering contributing to Evidently! 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"html-visual-testing\", \"version\": \"1.0.0\", \"type\": \"module\", \"scripts\": { \"test\": \"playwright test\" }, \"dependencies\": { }, \"devDependencies\": { \"wait-on\": \"^7.1.0\", \"@playwright/test\": \"^1.43.0\" } } 证据：`ui/html-visual-testing/package.json`\n- **Package**（package_manifest）：{ \"name\": \"evidently-ui-lib\", \"version\": \"1.0.0\", \"type\": \"module\", \"scripts\": { \"tsc\": \"tsc\", \"code-check\": \"biome check\" }, \"exports\": { \"./routes-components/ /data\": { \"default\": \"./src/routes-components/ /data.tsx\" }, \"./routes-components/ \": { \"default\": \"./src/routes-components/ /index.tsx\" }, \"./ \": { \"default\": \"./src/ \", \"types\": \"./.tsc-dts/src/ /index.d.ts\", \"./.tsc-dts/src/ .d.ts\" } }, \"peerDependencies\": { \"react\": \"^18.2.0\", \"react-dom\": \"^18.2.0\" }, \"dependencies\": { \"@hookform/resolvers\": \"^3.3.1\", \"@material-table/core\": \"^6.4.4\", \"@mui/icons-material\": \"^7.0.2\", \"@mui/material\": \"^7.0.2\", \"@mui/x-date-pickers\": \"^8.2.0\", \"@mui/x-data-grid\": \"^7.16.0\", \"material-ui-popup-st… 证据：`ui/packages/evidently-ui-lib/package.json`\n- **Package**（package_manifest）：{ \"name\": \"service\", \"version\": \"1.0.0\", \"type\": \"module\", \"scripts\": { \"dev\": \"vite\", \"type-check\": \"tsc --build\", \"build\": \"vite build\", \"code-check\": \"biome check\", \"preview\": \"vite preview\", \"test\": \"playwright test\", \"sync-back\": \"cd ../.. && ./.github/scripts/get-types-from-back.sh\" }, \"dependencies\": { \"evidently-ui-lib\": \"workspace: \", \"dayjs\": \"^1.11.13\", \"react\": \"^18.2.0\", \"react-dom\": \"^18.2.0\", \"tiny-invariant\": \"^1.3.3\" }, \"devDependencies\": { \"wait-on\": \"^7.1.0\", \"@playwright/test\": \"^1.43.0\", \"@types/react\": \"^18.2.0\", \"@types/react-dom\": \"^18.2.0\", \"vite\": \"^7.0.6\", \"@vitejs/plugin-react-swc\": \"^3.11.0\", \"vite-tsconfig-paths\": \"^5.1.4\", \"typescript\": \"^5.7.2\" } } 证据：`ui/service/package.json`\n- **Package**（package_manifest）：{ \"name\": \"standalone\", \"version\": \"1.0.0\", \"type\": \"module\", \"scripts\": { \"dev\": \"vite\", \"type-check\": \"tsc --build\", \"build\": \"vite build\", \"code-check\": \"biome check\", \"preview\": \"vite preview\" }, \"dependencies\": { \"evidently-ui-lib\": \"workspace: \", \"react\": \"^18.2.0\", \"react-dom\": \"^18.2.0\" }, \"devDependencies\": { \"@types/react\": \"^18.2.0\", \"@types/react-dom\": \"^18.2.0\", \"@vitejs/plugin-react-swc\": \"^3.7.0\", \"typescript\": \"^5.7.2\", \"vite\": \"^5.2.12\", \"vite-tsconfig-paths\": \"^4.2.1\" } } 证据：`ui/standalone/package.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Devcontainer**（structured_config）：{ \"name\": \"Default Linux Universal\", \"image\": \"mcr.microsoft.com/devcontainers/universal:2\", \"onCreateCommand\": \"./.devcontainer/on-create.sh\", \"postAttachCommand\": { \"ui\": \"source ./venv/bin/activate && evidently ui --port 8000 --demo-projects all --workspace test-workspace\" }, \"forwardPorts\": 8000 , \"portsAttributes\": { \"8000\": { \"label\": \"evidently UI\", \"onAutoForward\": \"openBrowser\" } } } 证据：`.devcontainer/devcontainer.json`\n- **Config**（structured_config）：{ \"data format\": { \"separator\": \",\", \"header\": true, \"date column\": \"dteday\" }, \"column mapping\" : {}, \"dashboard tabs\": { \"data drift\": { }, \"cat target drift\":{ \"verbose level\": 0 } }, \"options\": { \"data drift\": { \"confidence\": 0.95, \"drift share\": 0.5, \"nbinsx\": null, \"xbins\": null } }, \"pretty print\": true, \"sampling\": { \"reference\": { \"type\": \"none\", \"n\": 1, \"ratio\": 0.1 }, \"current\": { \"type\": \"nth\", \"n\": 2, \"ratio\": 0.1 } } } 证据：`config.json`\n- **Tsconfig.Base.Ui**（structured_config）：{ \"compilerOptions\": { \"target\": \"ESNext\", \"useDefineForClassFields\": true, \"lib\": \"ESNext\", \"DOM\", \"DOM.Iterable\" , \"module\": \"ESNext\", \"skipLibCheck\": true, 证据：`ui/tsconfig.base.ui.json`\n- **Data Drift**（structured_config）：{ \"annotations\": { \"list\": { \"builtIn\": 1, \"datasource\": { \"type\": \"grafana\", \"uid\": \"-- Grafana --\" }, \"enable\": true, \"hide\": true, \"iconColor\": \"rgba 0, 211, 255, 1 \", \"name\": \"Annotations & Alerts\", \"target\": { \"limit\": 100, \"matchAny\": false, \"tags\": , \"type\": \"dashboard\" }, \"type\": \"dashboard\" } }, \"editable\": true, \"fiscalYearStartMonth\": 0, \"graphTooltip\": 0, \"id\": 1, \"links\": , \"liveNow\": false, \"panels\": { \"datasource\": { \"type\": \"postgres\", \"uid\": \"PCC52D03280B7034C\" }, \"fieldConfig\": { \"defaults\": { \"color\": { \"mode\": \"palette-classic\" }, \"custom\": { \"axisLabel\": \"\", \"axisPlacement\": \"auto\", \"barAlignment\": 0, \"drawStyle\": \"line\", \"fillOpacity\": 0, \"gradientMode\": \"none\", \"hideF… 证据：`examples/grafana/grafana_data_drift_dashboard/dashboards/data_drift.json`\n- **Chatbot Evals**（structured_config）：{ \"annotations\": { \"list\": { \"builtIn\": 1, \"datasource\": { \"type\": \"grafana\", \"uid\": \"-- Grafana --\" }, \"enable\": true, \"hide\": true, \"iconColor\": \"rgba 0, 211, 255, 1 \", \"name\": \"Annotations & Alerts\", \"type\": \"dashboard\" } }, \"editable\": true, \"fiscalYearStartMonth\": 0, \"graphTooltip\": 0, \"id\": 2, \"links\": , \"panels\": { \"datasource\": { \"type\": \"grafana-postgresql-datasource\", \"uid\": \"PCC52D03280B7034C\" }, \"fieldConfig\": { \"defaults\": { \"color\": { \"mode\": \"thresholds\" }, \"mappings\": , \"thresholds\": { \"mode\": \"absolute\", \"steps\": { \"color\": \"green\" }, { \"color\": \"red\", \"value\": 80 } } }, \"overrides\": }, \"gridPos\": { \"h\": 8, \"w\": 12, \"x\": 0, \"y\": 0 }, \"id\": 1, \"options\": { \"colorMode\": \"valu… 证据：`examples/grafana/grafana_llm_evaluation_dashboard/dashboards/chatbot_evals.json`\n- **Manifest**（structured_config）：{ \"short name\": \"Evidently.AI\", \"name\": \"Evidently.AI Dashboards\", \"icons\": { \"src\": \"favicon.ico\", \"sizes\": \"64x64 32x32 24x24 16x16\", \"type\": \"image/x-icon\" }, { \"src\": \"favicon-96x96.png\", \"type\": \"image/png\", \"sizes\": \"96x96\" } , \"start url\": \".\", \"display\": \"standalone\", \"theme color\": \" 000000\", \"background color\": \" ffffff\" } 证据：`src/evidently/legacy/ui/assets/manifest.json`\n- **Manifest**（structured_config）：{ \"short name\": \"Evidently.AI\", \"name\": \"Evidently.AI Dashboards\", \"icons\": { \"src\": \"favicon.ico\", \"sizes\": \"64x64 32x32 24x24 16x16\", \"type\": \"image/x-icon\" }, { \"src\": \"favicon-96x96.png\", \"type\": \"image/png\", \"sizes\": \"96x96\" } , \"start url\": \".\", \"display\": \"standalone\", \"theme color\": \" 000000\", \"background color\": \" ffffff\" } 证据：`src/evidently/ui/service/assets/manifest.json`\n- **Tsconfig**（structured_config）：{ \"extends\": \"../../tsconfig.base.ui\", \"compilerOptions\": { \"composite\": true, \"outDir\": \".tsc-dts\", \"noEmit\": false, \"emitDeclarationOnly\": true, \"declaration\": true, \"baseUrl\": \"./src\", \"paths\": { \"~/ \": \" \" } }, \"include\": \"src\" } 证据：`ui/packages/evidently-ui-lib/tsconfig.json`\n- **Manifest**（structured_config）：{ \"short name\": \"Evidently.AI\", \"name\": \"Evidently.AI Dashboards\", \"icons\": { \"src\": \"favicon.ico\", \"sizes\": \"64x64 32x32 24x24 16x16\", \"type\": \"image/x-icon\" }, { \"src\": \"favicon-96x96.png\", \"type\": \"image/png\", \"sizes\": \"96x96\" } , \"start url\": \".\", \"display\": \"standalone\", \"theme color\": \" 000000\", \"background color\": \" ffffff\" } 证据：`ui/service/public/manifest.json`\n- **Tsconfig**（structured_config）：{ \"extends\": \"../tsconfig.base.ui\", \"compilerOptions\": { \"baseUrl\": \"./src\", \"paths\": { \"~/ \": \" \" } }, \"include\": \"src\" , \"references\": { \"path\": \"../packages/evidently-ui-lib/\" } } 证据：`ui/service/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"extends\": \"../tsconfig.base.ui\", \"compilerOptions\": { \"baseUrl\": \"./src\" }, \"include\": \"src\" , \"references\": { \"path\": \"../packages/evidently-ui-lib/\" } } 证据：`ui/standalone/tsconfig.json`\n- **!/usr/bin/env bash**（source_file）：virtualenv venv source ./venv/bin/activate pip install -e \". dev \" 证据：`.devcontainer/on-create.sh`\n- **.dockerignore**（source_file）：ui 证据：`.dockerignore`\n- **.dvc/.gitignore**（source_file）：/config.local /tmp /cache 证据：`.dvc/.gitignore`\n- **Config**（source_file）：core remote = gs 'remote \"gs\"' url = gs://evidently-service-visual-testing 证据：`.dvc/config`\n- **Add patterns of files dvc should ignore, which could improve**（source_file）：Add patterns of files dvc should ignore, which could improve the performance. Learn more at https://dvc.org/doc/user-guide/dvcignore 证据：`.dvcignore`\n- **.Gitbook**（source_file）：structure: readme: README.md summary: SUMMARY.md 证据：`.gitbook.yaml`\n- **see .devcontainer/devcontainer.json**（source_file）：.egg-info venv .venv .vscode .DS Store examples/.DS Store example scripts .ipynb checkpoints .idea .mypy cache .pytest cache dist build pytest-reports/ MANIFEST uv.lock 证据：`.gitignore`\n- **.Pre Commit Config**（source_file）：repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: \"v4.6.0\" hooks: - id: check-case-conflict - id: check-merge-conflict - id: check-toml - id: check-yaml exclude: ' docs examples /. ' - id: end-of-file-fixer exclude: ' docs examples /. ' - id: trailing-whitespace exclude: ' docs examples /. ' 证据：`.pre-commit-config.yaml`\n- **Manifest**（source_file）：include setupbase.py include README.md 证据：`MANIFEST.in`\n- **!/usr/bin/env -S uv run --script**（source_file）：!/usr/bin/env -S uv run --script /// script requires-python = \" =3.11\" dependencies = \"pdoc =16.0.0\", \"tracely =0.2.12\", \"typer =0.3\", /// 证据：`api-reference/generate.py`\n- **!/bin/bash**（source_file）：SCRIPT DIR=\"$ cd \"$ dirname \"$0\" \" && pwd \" 证据：`api-reference/local-dev.sh`\n- **Biome**（source_file）：{ \"files\": { // endpoints.d.ts is autogenerated // JsonParser.ts copied from https://github.com/douglascrockford/JSON-js \"ignore\": \"ui/packages/evidently-ui-lib/src/ /JsonParser.ts\", \"ui/packages/evidently-ui-lib/src/ /endpoints.d.ts\", \"ui/packages/evidently-ui-lib/.tsc-dts/ \" , \"include\": \"ui/ /src/ \", \"ui/ /tests/ \", \"ui/packages/ /src/ \" }, \"formatter\": { \"enabled\": true, \"formatWithErrors\": false, \"indentStyle\": \"space\", \"indentWidth\": 2, \"lineEnding\": \"lf\", \"lineWidth\": 100, \"attributePosition\": \"auto\" }, \"css\": { \"linter\": { \"enabled\": true }, \"formatter\": { \"enabled\": true } }, \"javascript\": { \"formatter\": { \"arrowParentheses\": \"always\", \"bracketSameLine\": false, \"bracketSpacing\": tr… 证据：`biome.jsonc`\n- **Config**（source_file）：data format: separator: \",\" header: true date column: \"dteday\" column mapping: {} profile sections: - data drift: xbins: nbinsx: drift share: 0.5 pretty print: true sampling: reference: type: \"simple\" could be \"none\", \"simple\", \"random\" n: 5 used with simple sampling, number of rows to skip ratio: 0.1 used with random sampling, part of data to take from chunk random seed: 4 used with random sampling, used as seed for random generator current: type: \"nth\" could be \"none\", \"simple\", \"random\" n: 5 used with simple sampling, number of rows to skip ratio: 0.1 used with random sampling, part of data to take from chunk 证据：`config.yaml`\n- **Dockerfile**（source_file）：FROM python:3.11-slim-bookworm ARG BUILD DATE ARG VCS REF ARG VERSION ARG INSTALL EXTRAS=\" sql \" LABEL org.label-schema.build-date=$BUILD DATE \\ org.label-schema.name=\"Evidently AI Service\" \\ org.label-schema.url=\"https://github.com/evidentlyai/evidently\" \\ org.label-schema.vcs-ref=$VCS REF \\ org.label-schema.vcs-url=\"https://github.com/evidentlyai/evidently\" \\ org.label-schema.version=$VERSION \\ org.label-schema.schema-version=\"1.0\" LABEL maintainer=\"mike0sv@evidentlyai.com\" 证据：`docker/Dockerfile.service`\n- **Dockerfile.Service**（source_file）：FROM python:3.11-slim-bookworm ARG BUILD DATE ARG VCS REF ARG VERSION LABEL org.label-schema.build-date=$BUILD DATE \\ org.label-schema.name=\"Evidently AI Service\" \\ org.label-schema.url=\"https://github.com/evidentlyai/evidently\" \\ org.label-schema.vcs-ref=$VCS REF \\ org.label-schema.vcs-url=\"https://github.com/evidentlyai/evidently\" \\ org.label-schema.version=$VERSION \\ org.label-schema.schema-version=\"1.0\" LABEL maintainer=\"mike0sv@evidentlyai.com\" 证据：`docker/Dockerfile.service.dev`\n- **Build Docker image**（source_file）：Build Docker image build: docker build output 证据：`docker/Makefile`\n- **Example Test**（source_file）：excludes = \"nyc taxi data drift dashboard customization.py\", \"historical drift visualization.py\", \"mlflow integration.py\", \"ibm hr attrition model validation.py\", \"bicycle demand monitoring setup.py\", \"data and ml monitoring tutorial.py\", \"how to run drift report for text encoders.py\", \"comparing custom statest with classic distributions.py\", \"how to evaluate llm with text descriptors.py\", \"how to run drift report for text data.py\", too slow & torch version conflict? \"llm evaluation tutorial.py\", cloud usage \"llm tracing tutorial.py\", cloud usage 证据：`example_test.py`\n- **Agentic Systems Tracing**（source_file）：{ \"cells\": { \"cell type\": \"markdown\", \"id\": \"767f3682-1a00-4ca2-92db-8235879315ee\", \"metadata\": {}, \"source\": \" Agentic Systems: Tracing and Evaluation\" }, { \"cell type\": \"code\", \"execution count\": null, \"id\": \"1fbcabcc-b6ec-4ed4-9ae5-6c7c6a692084\", \"metadata\": {}, \"outputs\": , \"source\": \"import openai\\n\", \"import tracely\\n\", \"import evidently.ui.runner as service runner\" }, { \"cell type\": \"markdown\", \"id\": \"a23f3141-1636-4c66-baa8-c85044610740\", \"metadata\": {}, \"source\": \" Let's run evidently ui service in background\" }, { \"cell type\": \"code\", \"execution count\": null, \"id\": \"440d97b8-eff8-40e2-87bc-e15b30647375\", \"metadata\": {}, \"outputs\": , \"source\": \"runner = service runner.EvidentlyUIRu… 证据：`examples/agentic_systems_tracing.ipynb`\n- **Classic Ml Validation**（source_file）：{ \"cells\": { \"cell type\": \"markdown\", \"id\": \"fef71322-f97b-416c-bbb9-bf1dd39e40ab\", \"metadata\": {}, \"source\": \" Classic ML Validation: Data Quality and Drift\" }, { \"cell type\": \"code\", \"execution count\": null, \"id\": \"e5aa23cf-2d2c-46fa-bb66-05623f81e7d8\", \"metadata\": {}, \"outputs\": , \"source\": \"import pandas as pd\\n\", \"from sklearn import datasets\\n\", \"\\n\", \"from evidently import Dataset\\n\", \"from evidently import DataDefinition\\n\", \"from evidently import Report\\n\", \"from evidently.presets import DataDriftPreset, DataSummaryPreset\" }, { \"cell type\": \"markdown\", \"id\": \"dccb8957-33fc-4a43-90b4-202f2caffeba\", \"metadata\": {}, \"source\": \" Let's load tabular dataset for binary classification prob… 证据：`examples/classic_ml_validation.ipynb`\n- **Llm Input Output Validation**（source_file）：{ \"cells\": { \"cell type\": \"markdown\", \"id\": \"e94178b9-eb37-44dc-aa84-2a4ef489b4a3\", \"metadata\": {}, \"source\": \" LLM Validation: Input and Output Quality\" }, { \"cell type\": \"code\", \"execution count\": null, \"id\": \"ba78f1ae-cc47-4d50-a655-37f1e63869ed\", \"metadata\": {}, \"outputs\": , \"source\": \"import pandas as pd\\n\", \"\\n\", \"from evidently import Dataset\\n\", \"from evidently import DataDefinition\\n\", \"from evidently import Report\\n\", \"from evidently.presets import TextEvals\\n\", \"from evidently.tests import lte, gte, eq\\n\", \"from evidently.descriptors import LLMEval, TestSummary, DeclineLLMEval, Sentiment, TextLength, IncludesWords\\n\", \"from evidently.llm.templates import BinaryClassificationPromp… 证据：`examples/llm_input_output_validation.ipynb`\n- **Pyproject**（source_file）：build-system requires = \"hatchling\" build-backend = \"hatchling.build\" 证据：`pyproject.toml`\n- **keep in sync with pyproject.toml project.optional-dependencies dev block.**（source_file）：keep in sync with pyproject.toml project.optional-dependencies dev block. wheel==0.38.1 setuptools==65.5.1; python version = '3.12' jupyter==1.0.0 mypy==1.1.1 pandas-stubs pytest==7.4.4 pytest-asyncio==0.23.7 pytest-mock==3.14.0 pytest-html =4.2.0 types-PyYAML==6.0.1 types-requests==2.26.0 types-dataclasses==0.6 types-python-dateutil==2.8.19 types-ujson==5.4.0 pillow==11.3.0 pip-audit pyspark ruff==0.3.7 pre-commit==3.5.0 tracely =0.2.11 证据：`requirements.dev.txt`\n- **keep in sync with pyproject.toml project dependencies but there should be set as lower bound .**（source_file）：keep in sync with pyproject.toml project dependencies but there should be set as lower bound . plotly==5.10.0 statsmodels==0.14.0 scikit-learn==1.1.1 pandas parquet ==1.3.5 numpy==1.23.0 nltk==3.6.7 scipy==1.10.0 requests==2.32.0 PyYAML==6.0.1 pydantic==1.10.16 litestar==2.19.0 typing-inspect==0.9.0 uvicorn==0.22.0 watchdog==3.0.0 typer==0.3 rich==13 iterative-telemetry==0.0.5 dynaconf==3.2.4 pyarrow==14.0.1 pyspark==3.4.0 fsspec==2024.9.0 certifi==2024.7.4 urllib3==1.26.19 ujson==5.4.0 deprecation==2.1.0 uuid6==2024.7.10 cryptography==43.0.1 tracely==0.2.11 opentelemetry-proto==1.25.0 证据：`requirements.min.txt`\n- **Add the line-too-long rule to the enforced rule set. By default, Ruff omits rules that**（source_file）：lint.pycodestyle max-line-length = 140 allow unforamttable lines up to 140 chars 证据：`ruff.toml`\n- **test_data/.gitignore**（source_file）：/lfw-dataset.zip /20news-bydate py3.pkz 证据：`test_data/.gitignore`\n- **20News Bydate Py3.Pkz**（source_file）：outs: - md5: 795cc33db0b25fdf479a34c9bb776b3e size: 15302062 hash: md5 path: 20news-bydate py3.pkz 证据：`test_data/20news-bydate_py3.pkz.dvc`\n- **Adults**（source_file）：Title: Adult Description: Predict whether annual income of an individual exceeds $50K/yr based on census data. Also known as \"Census Income\" dataset. Dataset source: https://archive.ics.uci.edu/dataset/2/adult Creators: Barry Becker, Ronny Kohavi Licence: CC BY 4.0 证据：`test_data/adults.CITATION`\n- **Bike Sharing Dataset**（source_file）：========================================= License ========================================= Use of this dataset in publications must be cited to the following publication: 证据：`test_data/bike_sharing_dataset.CITATION`\n- **Lfw Dataset.Zip**（source_file）：outs: - md5: 658ceabf5ff1545c5ee12cbcfbd8f82b size: 318271483 hash: md5 path: lfw-dataset.zip 证据：`test_data/lfw-dataset.zip.dvc`\n- 其余 4 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `api-reference/README.md`, `examples/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `api-reference/README.md`, `examples/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍与安装**：importance `high`\n - source_paths: README.md, pyproject.toml, requirements.min.txt\n- **系统架构设计**：importance `high`\n - source_paths: src/evidently/__init__.py, src/evidently/core/__init__.py, src/evidently/core/base_types.py, src/evidently/core/report.py, src/evidently/legacy/__init__.py\n- **指标系统 (Metrics)**：importance `high`\n - source_paths: src/evidently/metrics/__init__.py, src/evidently/metrics/classification.py, src/evidently/metrics/regression.py, src/evidently/metrics/data_quality.py, src/evidently/metrics/recsys.py\n- **预设评估 (Presets)**：importance `high`\n - source_paths: src/evidently/presets/__init__.py, src/evidently/presets/drift.py, src/evidently/presets/classification.py, src/evidently/presets/regression.py, src/evidently/presets/recsys.py\n- **描述符系统 (Descriptors)**：importance `high`\n - source_paths: src/evidently/descriptors/__init__.py, src/evidently/descriptors/text_length.py, src/evidently/descriptors/text_match.py, src/evidently/descriptors/llm_judges.py, src/evidently/descriptors/_context_relevance.py\n- **报告与测试套件**：importance `high`\n - source_paths: src/evidently/core/report.py, src/evidently/core/tests.py, src/evidently/core/serialization.py, src/evidently/legacy/report/report.py, src/evidently/legacy/test_suite/test_suite.py\n- **LLM集成与评判器**：importance `high`\n - source_paths: src/evidently/llm/__init__.py, src/evidently/llm/models.py, src/evidently/llm/prompts/__init__.py, src/evidently/llm/rag/__init__.py, src/evidently/llm/datagen/__init__.py\n- **Guardrails安全护栏**：importance `medium`\n - source_paths: src/evidently/guardrails/__init__.py, src/evidently/guardrails/core.py, src/evidently/guardrails/decorators.py, src/evidently/guardrails/guards/__init__.py, src/evidently/guardrails/guards/toxicity.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `a4aa4c2b37fe7a4344cc5031f566deccf3d69e4f`\n- inspected_files: `pyproject.toml`, `README.md`, `examples/README.md`, `examples/cookbook/README.md`, `examples/service/postgres_config.yaml`, `examples/service/sqlite_config.yaml`, `examples/service/README.md`, `examples/service/docker-compose.yml`, `examples/service/remote_demo_project.py`, `examples/grafana/README.md`, `examples/future_examples/future_reviews.py`, `examples/grafana/grafana_llm_evaluation_dashboard/README.md`, `examples/grafana/grafana_llm_evaluation_dashboard/docker-compose.yml`, `examples/grafana/grafana_llm_evaluation_dashboard/evidently_metrics_calculation.py`, `examples/grafana/grafana_data_drift_dashboard/README.md`, `examples/grafana/grafana_data_drift_dashboard/docker-compose.yml`, `examples/grafana/grafana_data_drift_dashboard/evidently_metrics_calculation.py`, `examples/grafana/grafana_llm_evaluation_dashboard/config/grafana_dashboards.yaml`, `examples/grafana/grafana_llm_evaluation_dashboard/config/grafana_datasources.yaml`, `examples/grafana/grafana_llm_evaluation_dashboard/dashboards/chatbot_evals.json`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Update scikit-learn version requirement to support v1.6.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update scikit-learn version requirement to support v1.6.0\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_e82e24d201134e7f8dfa0b564d73fce8 | https://github.com/evidentlyai/evidently/issues/1407 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：PromptOptimizer throws OpenAIError when using Vertex AI judge\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：PromptOptimizer throws OpenAIError when using Vertex AI judge\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_abf6f9b183ff4892be78fd198f60d8e8 | https://github.com/evidentlyai/evidently/issues/1856 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：IndexError in infer_column_type when column contains only null values\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：IndexError in infer_column_type when column contains only null values\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_44cdd5f2b657432eb8418fb132959ada | https://github.com/evidentlyai/evidently/issues/1764 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_872f2b57cd3a4c61ad5c387c8be3208b | https://github.com/evidentlyai/evidently/issues/1410 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Numpy 2.x support?\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Numpy 2.x support?\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_2fc84415b55a43d2be4f7f47cf46d7a1 | https://github.com/evidentlyai/evidently/issues/1557 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v0.7.12\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.12\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_fcf994a3bcf94b0d9b2c5d6159816728 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.12 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v0.7.15\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.15\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a9de117bd8e440beab9f7be4af50d710 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.15 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v0.7.20\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.20\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_f0d67058bf2a40218adfb0eea1f1665f | https://github.com/evidentlyai/evidently/releases/tag/v0.7.20 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v0.7.19\n\n- Trigger: GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.7.19\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_52e6ab37edca4901a0aa9fe7b5ba12f1 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.19 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：v0.7.21\n\n- Trigger: GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.7.21\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_fe9f0e6e29564afeb5610928cc9bc834 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.21 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：evidentlyai/evidently\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Update scikit-learn version requirement to support v1.6.0（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：PromptOptimizer throws OpenAIError when using Vertex AI judge（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：IndexError in infer_column_type when column contains only null values（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Numpy 2.x support?（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/evidentlyai/evidently 项目说明书\n\n生成时间：2026-05-16 20:09:11 UTC\n\n## 目录\n\n- [项目介绍与安装](#page-1)\n- [系统架构设计](#page-2)\n- [指标系统 (Metrics)](#page-3)\n- [预设评估 (Presets)](#page-4)\n- [描述符系统 (Descriptors)](#page-5)\n- [报告与测试套件](#page-6)\n- [LLM集成与评判器](#page-7)\n- [Guardrails安全护栏](#page-8)\n- [数据管理与存储](#page-9)\n- [前端UI组件库](#page-10)\n\n\n\n## 项目介绍与安装\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-2)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/evidentlyai/evidently/blob/main/README.md)\n- [api-reference/README.md](https://github.com/evidentlyai/evidently/blob/main/api-reference/README.md)\n- [src/evidently/sdk/configs.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)\n- [src/evidently/sdk/adapters.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/adapters.py)\n- [src/evidently/ui/workspace.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/workspace.py)\n- [src/evidently/ui/utils.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/utils.py)\n \n\n# 项目介绍与安装\n\n## 项目概述\n\nEvidently 是一个开源 Python 框架，专门用于评估、测试和监控机器学习（ML）以及基于大语言模型（LLM）的系统。该项目旨在为数据科学家和 ML 工程师提供全面的模型性能评估工具，支持从离线评估到在线监控的完整生命周期管理。\n\n项目具有以下核心特性：\n\n- **开源免费**：采用开源许可证，可自由使用和修改\n- **多场景支持**：支持分类、回归、自然语言处理等多种模型评估场景\n- **丰富的可视化**：提供直观的仪表板和报告展示评估结果\n- **易于集成**：可通过 Python API 或 Web UI 进行集成\n- **云端协作**：提供 Evidently Cloud 服务支持团队协作\n\n资料来源：[README.md](https://github.com/evidentlyai/evidently/blob/main/README.md)\n\n## 系统架构\n\nEvidently 采用模块化的系统架构，主要包含以下核心组件：\n\n```mermaid\ngraph TD\n A[Evidently Core] --> B[Metrics 模块]\n A --> C[Dashboard 模块]\n A --> D[SDK 模块]\n B --> E[数据漂移检测]\n B --> F[模型性能评估]\n B --> G[统计测试]\n C --> H[Web UI]\n C --> I[报告生成]\n D --> J[Cloud API]\n D --> K[Workspace]\n```\n\n### 核心模块说明\n\n| 模块名称 | 功能描述 | 主要类/文件 |\n|---------|---------|------------|\n| Metrics | 核心指标计算 | `evidently.metrics` |\n| Dashboard | 可视化报告 | `ui/packages/evidently-ui-lib` |\n| SDK | 编程接口 | `src/evidently/sdk/` |\n| Workspace | 项目工作区管理 | `src/evidently/ui/workspace.py` |\n| Guardrails | LLM 输出验证 | `evidently.guardrails` |\n\n资料来源：[src/evidently/sdk/configs.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)\n\n## 安装方式\n\n### 基础安装\n\n使用 pip 安装稳定版本：\n\n```bash\npip install evidently\n```\n\n### 开发版本安装\n\n从源码安装最新开发版本：\n\n```bash\npip install git+https://github.com/evidentlyai/evidently.git\n```\n\n### 扩展模块安装\n\n根据需要安装额外的依赖模块：\n\n```bash\n# 基础模块\npip install evidently\n\n# 扩展指标模块\npip install evidently.metrics\n\n# LLM Guardrails 模块\npip install evidently.guardrails\n```\n\n资料来源：[api-reference/README.md](https://github.com/evidentlyai/evidently/blob/main/api-reference/README.md)\n\n## SDK 配置与使用\n\n### 配置元数据\n\nEvidently SDK 提供了完整的配置管理功能，通过 `ConfigMetadata` 类管理配置元信息：\n\n```python\nConfigMetadata(\n created_at=datetime, # 创建时间\n updated_at=datetime, # 更新时间\n author=str, # 作者\n description=str # 配置描述\n)\n```\n\n资料来源：[src/evidently/sdk/configs.py:1-20](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)\n\n### 工作区管理\n\nWorkspace 模块负责管理项目和实验配置：\n\n```mermaid\nclassDiagram\n class Workspace {\n +create_project(name, description, org_id)\n +add_project(project)\n +get_project(project_id)\n +delete_project(project_id)\n +list_projects(org_id)\n }\n \n class ProjectModel {\n +name: str\n +description: str\n +org_id: Optional[OrgID]\n }\n \n Workspace --> ProjectModel\n```\n\n关键方法说明：\n\n| 方法 | 参数 | 返回值 | 功能 |\n|-----|------|-------|------|\n| `create_project` | name, description, org_id | Project | 创建新项目 |\n| `add_project` | project: ProjectModel | Project | 添加项目 |\n| `get_project` | project_id | Optional[Project] | 获取项目 |\n| `delete_project` | project_id | None | 删除项目 |\n| `list_projects` | org_id | Sequence[Project] | 列出项目 |\n\n资料来源：[src/evidently/ui/workspace.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/workspace.py)\n\n### 描述符配置\n\nDescriptor Config 用于存储和版本化管理描述符配置：\n\n```python\ndef save_descriptor(\n project_id: STR_UUID,\n name: str,\n descriptor: Descriptor\n) -> ConfigVersion\n\ndef get_descriptor(\n project_id: STR_UUID,\n name: str,\n version: VersionOrLatest = \"latest\"\n) -> Descriptor\n```\n\n资料来源：[src/evidently/sdk/configs.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)\n\n## 依赖要求\n\n### 最小依赖\n\nEvidently 的核心功能需要以下最小依赖集：\n\n- Python >= 3.8\n- pandas\n- numpy\n- scikit-learn\n\n### 完整依赖\n\n完整安装包含所有可选依赖，适用于完整的模型评估和监控场景。\n\n资料来源：[requirements.min.txt](https://github.com/evidentlyai/evidently/blob/main/requirements.min.txt)\n\n## Web UI 组件\n\n### 前端组件架构\n\nEvidently UI 采用 React 和 Material-UI 构建，提供现代化的用户界面：\n\n```mermaid\ngraph LR\n A[用户界面] --> B[Dashboard 组件]\n A --> C[Prompts 组件]\n A --> D[Traces 组件]\n A --> E[Descriptors 组件]\n B --> F[Widget]\n C --> G[Forms]\n D --> H[Table]\n E --> I[Features]\n```\n\n### 核心 UI 组件\n\n| 组件名称 | 功能 | 文件路径 |\n|---------|------|---------|\n| NameAndDescriptionForm | 名称描述表单 | `ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx` |\n| PromptsTable | 提示词表格 | `ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx` |\n| TracesTable | 追踪记录表格 | `ui/packages/evidently-ui-lib/src/components/Traces/TracesTable.tsx` |\n| DashboardDateFilter | 日期过滤器 | `ui/packages/evidently-ui-lib/src/components/Dashboard/DashboardDateFilter.tsx` |\n\n资料来源：[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)\n\n## 快速开始\n\n### 步骤一：安装 Evidently\n\n```bash\npip install evidently\n```\n\n### 步骤二：创建评估报告\n\n```python\nfrom evidently.dashboard import Dashboard\nfrom evidently.tabs import DataDriftTab, CatTargetDriftTab\n\n# 创建仪表板\ndashboard = Dashboard(tabs=[DataDriftTab(), CatTargetDriftTab()])\n\n# 运行评估\ndashboard.calculate(reference_data, current_data)\n```\n\n### 步骤三：导出报告\n\n```python\ndashboard.save_html(\"report.html\")\n```\n\n## 进一步资源\n\n| 资源 | 链接 |\n|-----|------|\n| 官方文档 | https://docs.evidentlyai.com |\n| API 参考 | https://evidentlyai.github.io/evidently/api-reference |\n| Discord 社区 | https://discord.gg/xZjKRaNp8b |\n| Evidently Cloud | https://www.evidentlyai.com/register |\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目介绍与安装](#page-1), [指标系统 (Metrics)](#page-3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/ui/utils.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/utils.py)\n- [src/evidently/sdk/configs.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/configs.py)\n- [src/evidently/ui/workspace.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/workspace.py)\n- [src/evidently/sdk/adapters.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/sdk/adapters.py)\n- [README.md](https://github.com/evidentlyai/evidently/blob/main/README.md)\n- [api-reference/README.md](https://github.com/evidentlyai/evidently/blob/main/api-reference/README.md)\n \n\n# 系统架构设计\n\n## 1. 概述\n\nEvidently 是一个开源的机器学习与 LLM 驱动系统的评估、测试和监控框架。该项目采用模块化设计，将核心评估逻辑与用户界面分离，同时提供 SDK 和 Web UI 两种交互方式。\n\n**核心设计目标：**\n- 提供可复用的评估指标和报告生成能力\n- 支持本地运行和云端服务两种部署模式\n- 实现配置版本化管理\n- 支持多项目组织和团队协作\n\n资料来源：[README.md:1-10]()\n\n## 2. 整体架构\n\n```mermaid\ngraph TD\n subgraph \"前端层 UI Layer\"\n WEB[Web UI - React]\n API_REF[API Reference Docs]\n end\n \n subgraph \"业务逻辑层 Business Logic\"\n SDK[Evidently SDK]\n METRICS[Metrics & Evaluators]\n GUARDRAILS[Guardrails]\n end\n \n subgraph \"数据模型层 Data Models\"\n CORE[Core Module]\n BASE_TYPES[Base Types]\n LEGACY[Legacy Module]\n end\n \n subgraph \"服务层 Services\"\n WORKSPACE[Workspace Service]\n CONFIGS[Config API]\n ADAPTERS[Adapters]\n end\n \n WEB --> SDK\n SDK --> METRICS\n SDK --> GUARDRAILS\n SDK --> CORE\n CORE --> BASE_TYPES\n SDK --> WORKSPACE\n SDK --> CONFIGS\n SDK --> ADAPTERS\n```\n\n## 3. 核心模块架构\n\n### 3.1 SDK 模块结构\n\nEvidently SDK 是系统的核心，提供了评估、报告生成和配置管理的功能。\n\n```mermaid\ngraph LR\n subgraph \"SDK Module\"\n CONFIGS[Configs]\n ADAPTERS[Adapters]\n REPORT[Report]\n METRICS[Metrics]\n end\n \n CONFIGS --> ADAPTERS\n REPORT --> METRICS\n```\n\n**主要组件：**\n\n| 模块 | 文件路径 | 功能说明 |\n|------|----------|----------|\n| ConfigAPI | `src/evidently/sdk/configs.py` | 提供配置的增删改查和版本管理 |\n| Adapters | `src/evidently/sdk/adapters.py` | 配置与 API 之间的适配器 |\n| Report | `src/evidently/core/report.py` | 报告生成和处理 |\n| Base Types | `src/evidently/core/base_types.py` | 基础数据类型定义 |\n\n资料来源：[src/evidently/sdk/configs.py:1-50]()\n\n### 3.2 Workspace 服务层\n\nWorkspace 是项目管理的核心抽象，提供了项目级别的操作接口。\n\n```mermaid\nclassDiagram\n class Workspace {\n <>\n +create_project(name, description, org_id) Project\n +add_project(project, org_id) Project\n +get_project(project_id) Optional~Project~\n +delete_project(project_id)\n +list_projects(org_id) Sequence~Project~\n }\n \n class Project {\n +id: STR_UUID\n +name: str\n +description: str\n +org_id: Optional~OrgID~\n }\n```\n\n**Workspace 核心接口：**\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| create_project | name, description, org_id | Project | 创建新项目 |\n| add_project | project, org_id | Project | 添加项目到工作区 |\n| get_project | project_id | Optional[Project] | 根据 ID 获取项目 |\n| delete_project | project_id | None | 删除指定项目 |\n| list_projects | org_id | Sequence[Project] | 列出工作区中的项目 |\n\n资料来源：[src/evidently/ui/workspace.py:1-60]()\n\n### 3.3 配置版本管理\n\n系统采用 ConfigVersion 机制管理配置的版本，支持配置的创建、更新和历史追溯。\n\n```mermaid\ngraph TD\n A[ConfigVersion] --> B[ConfigMetadata]\n A --> C[ConfigContent]\n B --> D[created_at]\n B --> E[updated_at]\n B --> F[author]\n B --> G[description]\n \n H[CloudConfigAPI] --> I[create_descriptor]\n H --> J[get_descriptor]\n H --> K[update_descriptor]\n```\n\n**配置类型支持：**\n\n| 配置类型 | 说明 | 支持版本管理 |\n|----------|------|--------------|\n| Descriptor | 描述符配置 | 是 |\n| Artifact | 工件配置 | 是 |\n| Metric | 指标配置 | 是 |\n| Report | 报告配置 | 是 |\n\n资料来源：[src/evidently/sdk/adapters.py:1-40]()\n\n## 4. 前端架构\n\n### 4.1 UI 组件结构\n\nWeb UI 采用 React + TypeScript 构建，主要组件位于 `ui/packages/evidently-ui-lib/`。\n\n```mermaid\ngraph TD\n subgraph \"UI Components\"\n Dashboard[Dashboard]\n Prompts[Prompts]\n Traces[Traces]\n Descriptors[Descriptors]\n Utils[Utils]\n end\n \n subgraph \"Widgets\"\n Widget[Widget]\n TestSuiteWidget[TestSuiteWidget]\n end\n \n Dashboard --> Widget\n Prompts --> Utils\n Traces --> Utils\n Descriptors --> Utils\n```\n\n**核心组件：**\n\n| 组件目录 | 组件名称 | 功能 |\n|----------|----------|------|\n| Dashboard | DashboardDateFilter | 日期范围筛选 |\n| Prompts | CreatePromptForm, PromptsTable | Prompt 创建和管理 |\n| Traces | TracesTable, TraceViewer | 追踪记录查看 |\n| Descriptors | LLMJudge/template | 描述符模板 |\n| Widgets | Widget | 通用组件容器 |\n\n资料来源：[ui/packages/evidently-ui-lib/src/widgets/Widget.tsx:1-30]()\n\n### 4.2 状态管理\n\n表单状态使用 React Hook Form 结合 Zod 进行验证：\n\n```typescript\n// 表单验证流程\nForm → useForm → zodResolver → NameAndDescriptionForm\n```\n\n**表单验证模式：**\n\n| 验证字段 | 验证规则 | 错误提示位置 |\n|----------|----------|--------------|\n| name | 必填，字符串 | helperText |\n| description | 可选，字符串 | helperText |\n| 日期范围 | dateFrom <= dateTo | AlertThemed |\n\n资料来源：[ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx:1-40]()\n\n## 5. 报告与评估系统\n\n### 5.1 Report 核心流程\n\n```mermaid\ngraph LR\n A[Input Data] --> B[Dataset]\n B --> C[Descriptors]\n C --> D[Evaluators]\n D --> E[Report]\n E --> F[Metrics]\n F --> G[Visualization]\n```\n\n**Report 生成步骤：**\n\n1. **数据准备**：将 DataFrame 转换为 Dataset 对象\n2. **添加描述符**：定义行级评估器（如 Sentiment、TextLength）\n3. **执行评估**：运行预设的评估套件\n4. **生成报告**：汇总结果并生成可视化输出\n\n**示例支持的描述符：**\n\n| 描述符 | 功能 | 适用场景 |\n|--------|------|----------|\n| Sentiment | 情感分析 | LLM 响应评估 |\n| TextLength | 文本长度统计 | 响应长度监控 |\n| Contains | 关键词检测 | 拒绝/否认识别 |\n\n资料来源：[README.md:80-120]()\n\n### 5.2 评估预设\n\n系统提供多种评估预设，简化常见评估场景的配置：\n\n| 预设名称 | 说明 | 包含评估项 |\n|----------|------|------------|\n| TextEvals | 文本评估预设 | 情感、长度、关键词 |\n| LLM Evals | LLM 专用评估 | 响应质量、多样性 |\n\n资料来源：[README.md:60-80]()\n\n## 6. API 参考文档生成\n\n项目使用 pdoc 工具自动生成 API 参考文档。\n\n```mermaid\ngraph TD\n A[generate.py] --> B[Local Source]\n A --> C[Git Revision]\n B --> D[dist//]\n C --> E[dist//]\n \n F[local-dev.sh] --> G[Development Server]\n G --> H[http://localhost:8080]\n```\n\n**文档生成命令：**\n\n```bash\n# 本地源码生成\n./api-reference/generate.py --local-source-code\n\n# 指定 Git 版本\n./api-reference/generate.py --git-revision v0.7.17\n\n# 添加额外模块\n./api-reference/generate.py --local-source-code \\\n --additional-modules \"evidently.metrics,evidently.guardrails\"\n```\n\n**默认包含模块：**\n- `evidently`\n- `evidently.core`\n\n**输出目录结构：**\n- 本地构建：`dist//`\n- Git 构建：`dist//`\n\n资料来源：[api-reference/README.md:1-50]()\n\n## 7. 部署架构\n\n### 7.1 组件部署\n\n```mermaid\ngraph TD\n subgraph \"客户端 Client\"\n PY[Python SDK]\n WEB[Web Browser]\n end\n \n subgraph \"服务端 Server\"\n API[Config API]\n DB[(Database)]\n WS[Workspace Service]\n end\n \n PY --> API\n WEB --> WS\n API --> DB\n WS --> DB\n```\n\n### 7.2 安装方式\n\n| 安装方式 | 命令 | 说明 |\n|----------|------|------|\n| PyPI | `pip install evidently` | 推荐标准方式 |\n| Conda | `conda install -c conda-forge evidently` | 使用 conda 安装 |\n\n资料来源：[README.md:40-55]()\n\n## 8. 关键技术栈\n\n| 层级 | 技术 | 用途 |\n|------|------|------|\n| 核心语言 | Python 3.11+ | SDK 实现 |\n| Web 框架 | React + TypeScript | 前端 UI |\n| 数据验证 | Zod | 表单验证 |\n| 日期处理 | dayjs | 时间格式化 |\n| 文档生成 | pdoc | API 文档 |\n| 包管理 | uv | Python 包管理 |\n\n## 9. 总结\n\nEvidently 采用清晰的分层架构设计：\n\n1. **核心层** (`evidently.core`)：定义基础数据类型和报告生成逻辑\n2. **SDK 层** (`evidently.sdk`)：提供配置管理、适配器和 API 封装\n3. **业务层** (`evidently.ui`)：实现工作区服务和项目管理\n4. **展示层** (`ui/`): React 前端实现用户交互界面\n\n这种设计使得系统既可以作为 Python 库独立使用，也可以通过 Web UI 进行可视化操作，同时支持本地部署和云端服务两种模式。\n\n---\n\n\n\n## 指标系统 (Metrics)\n\n### 相关页面\n\n相关主题：[预设评估 (Presets)](#page-4), [报告与测试套件](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/metrics/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/__init__.py)\n- [src/evidently/metrics/classification.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/classification.py)\n- [src/evidently/metrics/regression.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/regression.py)\n- [src/evidently/metrics/data_quality.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/data_quality.py)\n- [src/evidently/metrics/recsys.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/metrics/recsys.py)\n- [src/evidently/core/metric_types.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/metric_types.py)\n- [src/evidently/core/registries/metrics.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/metrics.py)\n \n\n# 指标系统 (Metrics)\n\n## 概述\n\n指标系统是 Evidently 框架的核心组件之一，负责对机器学习模型和 LLM 支持的系统进行量化和评估。该系统提供了统一的接口来定义、计算、缓存和渲染各类评估指标，涵盖了分类任务、回归任务、数据质量评估以及推荐系统等多个领域。\n\n指标系统通过抽象基类 `Metric` 和 `MetricContainer` 建立了灵活可扩展的架构，允许开发者自定义指标并将其集成到评估报告中。 资料来源：[src/evidently/core/metric_types.py:1-50]()\n\n## 核心架构\n\n### 指标类型层次结构\n\nEvidently 的指标系统采用面向对象的继承设计，主要分为两大类：\n\n1. **基础指标 (Metric)** - 单个指标实现，负责计算具体的评估维度\n2. **指标容器 (MetricContainer)** - 组合多个指标的容器，支持批量计算和联合渲染\n\n```mermaid\ngraph TD\n A[Metric 基础抽象类] --> B[ClassificationMetrics]\n A --> C[RegressionMetrics]\n A --> D[DataQualityMetrics]\n A --> E[RecSysMetrics]\n A --> F[MetricContainer 容器基类]\n F --> G[TextEvals 预设容器]\n F --> H[CustomMetricContainer]\n```\n\n### 指标容器 (MetricContainer)\n\n`MetricContainer` 是组合多个指标的抽象基类，定义在 `src/evidently/core/container.py` 中，提供了指标生成、缓存和渲染的统一接口。\n\n```python\nclass MetricContainer(GenericContainer, abc.ABC):\n \"\"\"指标容器基类\"\"\"\n \n def __init__(self, include_tests: bool = True, **data):\n \"\"\"初始化指标容器\n \n Args:\n include_tests: 如果为 True，生成的指标将包含默认测试\n \"\"\"\n self.include_tests = include_tests\n super().__init__(**data)\n \n @abc.abstractmethod\n def generate_metrics(self, context: \"Context\") -> Sequence[MetricOrContainer]:\n \"\"\"基于容器配置生成指标\"\"\"\n raise NotImplementedError()\n \n def metrics(self, context: \"Context\") -> List[MetricOrContainer]:\n \"\"\"获取所有生成的指标，支持上下文缓存\"\"\"\n metric_container_fp = self.get_fingerprint()\n metrics = context.metrics_container(metric_container_fp)\n if metrics is None:\n metrics = list(self.generate_metrics(context))\n context.set_metric_container_data(metric_container_fp, metrics)\n return metrics\n \n def render(self, context: \"Context\", \n child_widgets: Optional[List[Tuple[Optional[MetricId], List[BaseWidgetInfo]]]] = None) -> List[BaseWidgetInfo]:\n \"\"\"渲染可视化组件\"\"\"\n # 实现细节\n```\n\n资料来源：[src/evidently/core/container.py:31-75]()\n\n### 指标注册表机制\n\n指标系统通过注册表 (Registry) 机制实现指标的集中管理和发现。`MetricRegistry` 类维护了所有可用指标的映射关系。\n\n| 注册表操作 | 说明 |\n|-----------|------|\n| `register()` | 注册新指标到注册表 |\n| `get()` | 根据名称获取指标类 |\n| `list_metrics()` | 列出所有已注册的指标 |\n| `_make` | 指标实例工厂方法 |\n\n资料来源：[src/evidently/core/registries/metrics.py:1-100]()\n\n## 指标分类\n\n### 分类指标 (Classification Metrics)\n\n分类指标用于评估分类模型的性能，支持二分类和多分类场景。\n\n**主要指标包括：**\n\n| 指标名称 | 说明 | 适用场景 |\n|---------|------|---------|\n| `ClassificationQualityMetric` | 整体分类质量评分 | 通用分类评估 |\n| `PrecisionMetric` | 精确率 | 关注假阳性场景 |\n| `RecallMetric` | 召回率 | 关注假阴性场景 |\n| `F1ScoreMetric` | F1 分数 | 平衡精确率和召回率 |\n| `RocAucMetric` | ROC-AUC 曲线下面积 | 概率预测评估 |\n| `ConfusionMatrixMetric` | 混淆矩阵 | 详细错误分析 |\n\n资料来源：[src/evidently/metrics/classification.py:1-200]()\n\n### 回归指标 (Regression Metrics)\n\n回归指标用于评估连续值预测模型的性能。\n\n**核心指标：**\n\n| 指标名称 | 说明 | 敏感度 |\n|---------|------|--------|\n| `MeanErrorMetric` | 平均误差 | 偏移 |\n| `MeanAbsoluteErrorMetric` | 平均绝对误差 | 异常值鲁棒 |\n| `MeanSquaredErrorMetric` | 均方误差 | 惩罚大误差 |\n| `R2ScoreMetric` | R² 决定系数 | 模型解释力 |\n| `ErrorDistributionMetric` | 误差分布 | 偏差分析 |\n\n资料来源：[src/evidently/metrics/regression.py:1-200]()\n\n### 数据质量指标 (Data Quality Metrics)\n\n数据质量指标用于评估数据集本身的特性，包括完整性、一致性和统计分布。\n\n| 指标类别 | 包含指标 |\n|---------|---------|\n| 完整性检查 | 缺失值比例、空值统计 |\n| 唯一性检查 | 重复行检测、主键唯一性 |\n| 范围检查 | 数值边界、类别覆盖 |\n| 分布检查 | 直方图、分布偏移 |\n\n资料来源：[src/evidently/metrics/data_quality.py:1-200]()\n\n### 推荐系统指标 (RecSys Metrics)\n\n推荐系统专用指标用于评估协同过滤和内容推荐算法。\n\n| 指标名称 | 说明 |\n|---------|------|\n| `PrecisionAtK` | K 位精度 |\n| `RecallAtK` | K 位召回率 |\n| `NDCGMetric` | 归一化折扣累计增益 |\n| `HitRateMetric` | 点击率 |\n\n资料来源：[src/evidently/metrics/recsys.py:1-200]()\n\n## 指标执行流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Report as Report\n participant Container as MetricContainer\n participant Metric as Metric\n participant Context as Context\n participant Renderer as WidgetRenderer\n \n User->>Report: 创建 Report(metrics=[...])\n Report->>Container: 初始化容器\n Container->>Context: 调用 metrics()\n Context->>Context: 检查缓存\n alt 缓存未命中\n Context->>Container: generate_metrics()\n Container->>Metric: 实例化指标\n Metric->>Metric: calculate(context)\n Metric-->>Context: 返回计算结果\n Context->>Context: 缓存结果\n end\n Context-->>Report: 返回指标列表\n Report->>Container: render(context)\n Container->>Metric: 获取 widget 信息\n Metric-->>Container: BaseWidgetInfo\n Container-->>Report: 渲染后的 widgets\n Report-->>User: 生成 HTML/JSON 报告\n```\n\n## 指标定义接口\n\n每个具体指标需要实现以下核心方法：\n\n```python\nclass MyCustomMetric(Metric):\n \"\"\"自定义指标示例\"\"\"\n \n def calculate(self, context: Context) -> MetricResult:\n \"\"\"执行指标计算\n \n Args:\n context: 包含数据集和配置的上下文对象\n \n Returns:\n MetricResult: 包含计算结果的指标结果对象\n \"\"\"\n # 1. 从 context 获取数据\n current_data = context.get_current_data()\n reference_data = context.get_reference_data()\n \n # 2. 执行计算逻辑\n value = self._compute_metric(current_data, reference_data)\n \n # 3. 返回结果\n return MetricResult(\n value=value,\n parameters=self.parameters\n )\n \n def get_widgets(self, context: Context) -> List[BaseWidgetInfo]:\n \"\"\"返回可视化组件\"\"\"\n # 返回用于渲染的 widget 配置\n pass\n \n def get_fingerprint(self) -> str:\n \"\"\"计算指标指纹用于缓存\"\"\"\n pass\n```\n\n资料来源：[src/evidently/core/metric_types.py:50-150]()\n\n## 指标与报告集成\n\n指标通过 `Report` 类与用户进行交互。以下是典型使用方式：\n\n```python\nfrom evidently import Report\nfrom evidently.metrics import ClassificationQualityMetric, PrecisionMetric\n\n# 创建报告并指定要使用的指标\nreport = Report(\n metrics=[\n ClassificationQualityMetric(),\n PrecisionMetric(positive_label=1),\n ]\n)\n\n# 运行评估\nreport.run(\n reference_data=reference_df,\n current_data=current_df,\n column_mapping=ColumnMapping(target=\"target\", prediction=\"pred\")\n)\n\n# 导出报告\nreport.save_html(\"report.html\")\nreport.save_json(\"report.json\")\n```\n\n## 指标预设 (Presets)\n\n除了单个指标，Evidently 还提供了预配置的指标组合预设：\n\n| 预设名称 | 说明 | 包含指标 |\n|---------|------|---------|\n| `TextEvals` | LLM 文本评估预设 | 情感分析、毒性检测、摘要质量 |\n| `ClassificationPreset` | 分类任务完整评估 | 质量、精确率、召回率、混淆矩阵 |\n| `RegressionPreset` | 回归任务完整评估 | MAE、MSE、误差分布、R² |\n\n资料来源：[src/evidently/metrics/__init__.py:1-100]()\n\n## 缓存机制\n\n指标系统实现了高效的缓存机制以避免重复计算：\n\n```mermaid\ngraph LR\n A[请求指标] --> B{缓存存在?}\n B -->|是| C[返回缓存结果]\n B -->|否| D[调用 generate_metrics]\n D --> E[执行指标计算]\n E --> F[存入上下文缓存]\n F --> G[返回结果]\n```\n\n缓存键基于指标容器的指纹 (fingerprint) 生成，确保配置变化时自动重新计算。\n\n资料来源：[src/evidently/core/container.py:47-55]()\n\n## 扩展开发指南\n\n### 创建自定义指标\n\n1. **继承 Metric 基类**\n2. **实现必需方法**：calculate()、get_widgets()、get_fingerprint()\n3. **注册到指标注册表**\n\n```python\nfrom evidently.core import Metric\n\nclass MyMetric(Metric):\n \"\"\"自定义指标\"\"\"\n alias = \"my_metric\"\n \n def calculate(self, context):\n # 实现计算逻辑\n return MyMetricResult(...)\n \n def get_widgets(self, context):\n return [BaseWidgetInfo(...)]\n \n def get_fingerprint(self):\n return self.json()\n```\n\n### 创建自定义指标容器\n\n```python\nfrom evidently.core import MetricContainer\n\nclass MyMetricContainer(MetricContainer):\n \"\"\"自定义指标容器\"\"\"\n \n def generate_metrics(self, context):\n return [\n MyMetric(...),\n AnotherMetric(...)\n ]\n```\n\n## 总结\n\nEvidently 的指标系统提供了灵活、可扩展且功能完整的评估框架。通过抽象基类和注册表机制，开发者可以轻松添加新的指标类型；通过容器模式和缓存机制，系统能够高效处理复杂的评估场景。该系统支持从简单的数据质量检查到高级的 LLM 输出评估等多种应用场景，是 Evidently 框架的核心支柱。\n\n---\n\n\n\n## 预设评估 (Presets)\n\n### 相关页面\n\n相关主题：[指标系统 (Metrics)](#page-3), [报告与测试套件](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/presets/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/__init__.py)\n- [src/evidently/presets/drift.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/drift.py)\n- [src/evidently/presets/classification.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/classification.py)\n- [src/evidently/presets/regression.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/regression.py)\n- [src/evidently/presets/recsys.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/recsys.py)\n- [src/evidently/core/preset_types.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/preset_types.py)\n- [src/evidently/core/registries/presets.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/presets.py)\n \n\n# 预设评估 (Presets)\n\n## 概述\n\n预设评估（Presets）是 Evidently 框架中提供的一种高级评估机制，它将一组相关的指标（Metrics）和测试（Tests）打包成可重用的配置单元。预设评估允许用户通过简单的接口快速对机器学习模型进行全面的性能评估，无需手动配置大量单独的指标。\n\nEvidently 的预设评估系统涵盖多种 ML 任务类型，每种预设针对特定的应用场景提供针对性的评估方案。通过使用预设，用户可以：\n\n- 简化评估流程，减少配置代码量\n- 确保评估的一致性和标准化\n- 快速获得全面的模型性能洞察\n- 支持分类、回归、数据漂移和推荐系统等多种任务类型\n\n## 架构设计\n\n### 核心组件关系\n\n预设系统的架构由以下几个核心组件构成：\n\n```mermaid\ngraph TD\n A[用户代码] --> B[Report / TestSuite]\n B --> C[Preset 预设]\n C --> D[Metrics 指标集合]\n C --> E[Tests 测试集合]\n D --> F[ColumnMetric]\n D --> G[DatasetMetric]\n E --> H[TestCase]\n F --> I[Evidently Engine]\n G --> I\n H --> I\n \n J[PresetRegistry 注册表] --> K[Preset Types 类型定义]\n K --> C\n```\n\n### 类型层次结构\n\n预设类型系统采用继承和组合模式：\n\n```mermaid\nclassDiagram\n class Preset {\n <>\n +metrics: List[Metric]\n +tests: List[Test]\n +tabs: List[str]\n +get_aspects() List[Aspect]\n }\n \n class DataDriftPreset {\n +DataDriftPreset()\n }\n \n class ClassificationPreset {\n +ClassificationPreset()\n }\n \n class RegressionPreset {\n +RegressionPreset()\n }\n \n class RecSysPreset {\n +RecSysPreset()\n }\n \n class TextEvalsPreset {\n +TextEvalsPreset()\n }\n \n Preset <|-- DataDriftPreset\n Preset <|-- ClassificationPreset\n Preset <|-- RegressionPreset\n Preset <|-- RecSysPreset\n Preset <|-- TextEvalsPreset\n```\n\n## 预设类型详解\n\n### 数据漂移检测预设 (DataDriftPreset)\n\n数据漂移预设用于检测生产环境中的数据分布变化。当输入数据的统计特性发生显著变化时，可能表明模型性能下降或底层数据生成过程发生了变化。\n\n**适用场景**：\n\n- 生产环境监控\n- 模型再训练触发条件判断\n- 数据管道异常检测\n\n**主要评估指标**：\n\n| 指标类型 | 说明 |\n|---------|------|\n| 特征级漂移 | 检测单个特征的分布变化 |\n| 整体漂移 | 聚合所有特征的漂移情况 |\n| 目标漂移 | 检测目标变量分布变化 |\n\n资料来源：[src/evidently/presets/drift.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/drift.py)\n\n### 分类模型预设 (ClassificationPreset)\n\n分类预设专为二分类和多分类任务设计，提供全面的分类器性能评估。\n\n**适用场景**：\n\n- 二分类问题（如欺诈检测、流失预测）\n- 多分类问题（如图像分类、文本分类）\n- 概率校准评估\n\n**主要评估指标**：\n\n| 指标 | 说明 | 适用分类类型 |\n|------|------|-------------|\n| Accuracy | 整体准确率 | 二分类/多分类 |\n| Precision | 精确率 | 二分类/多分类 |\n| Recall | 召回率 | 二分类/多分类 |\n| F1-Score | F1 分数 | 二分类/多分类 |\n| ROC-AUC | ROC 曲线下面积 | 二分类 |\n| PR-AUC | PR 曲线下面积 | 二分类 |\n| Confusion Matrix | 混淆矩阵 | 二分类/多分类 |\n| Class Representation | 类别表示分布 | 多分类 |\n\n资料来源：[src/evidently/presets/classification.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/classification.py)\n\n### 回归模型预设 (RegressionPreset)\n\n回归预设用于评估回归模型的预测性能。\n\n**适用场景**：\n\n- 连续值预测\n- 时间序列预测\n- 价格/数量预测\n\n**主要评估指标**：\n\n| 指标 | 说明 |\n|------|------|\n| MAE | 平均绝对误差 |\n| MSE | 均方误差 |\n| RMSE | 均方根误差 |\n| MAPE | 平均绝对百分比误差 |\n| R2 Score | 决定系数 |\n| Max Error | 最大误差 |\n| Median Error | 中位数误差 |\n\n资料来源：[src/evidently/presets/regression.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/regression.py)\n\n### 推荐系统预设 (RecSysPreset)\n\n推荐系统预设专门针对协同过滤和推荐算法进行评估。\n\n**适用场景**：\n\n- 推荐系统性能评估\n- 点击率预测\n- 排名质量评估\n\n**主要评估指标**：\n\n| 指标 | 说明 |\n|------|------|\n| Precision@K | K 位精度 |\n| Recall@K | K 位召回率 |\n| NDCG | 归一化折损累计增益 |\n| MRR | 平均倒数排名 |\n| Hit Rate | 点击率 |\n\n资料来源：[src/evidently/presets/recsys.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/recsys.py)\n\n### 文本评估预设 (TextEvalsPreset)\n\n文本评估预设用于评估 LLM 和文本生成模型的输出质量。\n\n**适用场景**：\n\n- LLM 输出质量评估\n- 文本摘要评估\n- 问答系统评估\n- 语义相似度评估\n\n**支持的评估描述符**：\n\n| 描述符 | 功能 |\n|--------|------|\n| Sentiment | 情感分析 |\n| TextLength | 文本长度统计 |\n| Contains | 关键词检测 |\n| LLM Judge | LLM 作为评判者 |\n| PII Detection | 敏感信息检测 |\n\n资料来源：[src/evidently/presets/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/presets/__init__.py)\n\n## 使用方式\n\n### 在 Report 中使用预设\n\n```python\nfrom evidently import Report\nfrom evidently.presets import DataDriftPreset, ClassificationPreset\n\n# 创建带有预设的报告\nreport = Report(metrics=[\n DataDriftPreset(),\n ClassificationPreset()\n])\n\nreport.run(reference_data=reference, current_data=current)\nreport.show()\n```\n\n### 在 TestSuite 中使用预设\n\n```python\nfrom evidently import TestSuite\nfrom evidently.presets import RegressionPreset\n\n# 创建带有预设的测试套件\nsuite = TestSuite(tests=[\n RegressionPreset()\n])\n\nsuite.run(reference_data=reference, current_data=current)\nsuite.show()\n```\n\n### 自定义预设组合\n\n用户可以组合多个预设或添加自定义指标：\n\n```python\nfrom evidently import Report\nfrom evidently.presets import DataDriftPreset, ClassificationPreset\nfrom evidently.metrics import ColumnSummaryMetric\n\nreport = Report(metrics=[\n DataDriftPreset(),\n ClassificationPreset(),\n ColumnSummaryMetric(column_name=\"feature_1\")\n])\n```\n\n## 注册表机制\n\n预设系统使用注册表模式进行管理，确保所有预设类型都能被正确识别和实例化。\n\n```mermaid\ngraph LR\n A[PresetRegistry] -->|register| B[Preset Types]\n B -->|实例化| C[DataDriftPreset]\n B -->|实例化| D[ClassificationPreset]\n B -->|实例化| E[RegressionPreset]\n B -->|实例化| F[RecSysPreset]\n \n G[load_preset] -->|按名称查找| A\n G -->|返回实例| C\n```\n\n资料来源：[src/evidently/core/registries/presets.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/presets.py)\n\n## 配置参数\n\n### 通用配置选项\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `metrics` | List[Metric] | 指标列表 | [] |\n| `tests` | List[Test] | 测试列表 | [] |\n| `tabs` | List[str] | 展示标签页 | None |\n| `include_widgets` | List[Widget] | 包含的可视化组件 | None |\n\n### 分类预设配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `generated_labels` | bool | 是否生成类别标签 |\n| `probas_threshold` | float | 概率阈值 |\n\n### 漂移预设配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `drift_method` | str | 漂移检测方法 |\n| `confidence_level` | float | 置信水平 |\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[初始化 Report/TestSuite] --> B[加载预设]\n B --> C[解析数据集]\n C --> D[计算参考指标]\n D --> E[计算当前指标]\n E --> F[对比分析]\n F --> G{输出类型}\n G -->|Report| H[生成可视化报告]\n G -->|TestSuite| I[执行断言测试]\n H --> J[展示结果]\n I --> K[返回测试结果]\n```\n\n## 输出展示\n\n预设评估的输出支持多种展示形式：\n\n| 输出类型 | 说明 |\n|---------|------|\n| HTML 报告 | 交互式可视化报告 |\n| JSON 格式 | 结构化数据导出 |\n| Python 字典 | 程序化访问 |\n| Markdown | 文档化输出 |\n\n## 最佳实践\n\n### 选择合适的预设\n\n1. **数据类型驱动**：根据输入数据特征选择对应预设\n2. **任务类型匹配**：二分类使用 ClassificationPreset，多分类考虑类别平衡\n3. **监控场景**：生产监控优先考虑 DataDriftPreset\n\n### 性能优化建议\n\n- 避免在同一 Report 中使用过多预设\n- 大数据集使用采样策略\n- 漂移检测设置合理的检测窗口\n\n### 常见陷阱\n\n- 忽略数据预处理导致评估偏差\n- 混淆参考数据集和当前数据集\n- 忽视类别不平衡问题\n\n## 扩展预设\n\n用户可以创建自定义预设：\n\n```python\nfrom evidently.presets import Preset\nfrom evidently.metrics import Metric\n\nclass CustomPreset(Preset):\n def __init__(self):\n super().__init__(\n metrics=[\n CustomMetric1(),\n CustomMetric2()\n ],\n tabs=[\"Custom Tab\"]\n )\n```\n\n资料来源：[src/evidently/core/preset_types.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/preset_types.py)\n\n---\n\n\n\n## 描述符系统 (Descriptors)\n\n### 相关页面\n\n相关主题：[LLM集成与评判器](#page-7), [报告与测试套件](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/descriptors/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/__init__.py)\n- [src/evidently/descriptors/text_length.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/text_length.py)\n- [src/evidently/descriptors/text_match.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/text_match.py)\n- [src/evidently/descriptors/llm_judges.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/llm_judges.py)\n- [src/evidently/descriptors/_context_relevance.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/_context_relevance.py)\n- [src/evidently/core/registries/descriptors.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/descriptors.py)\n- [src/evidently/descriptors/generated_descriptors.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/generated_descriptors.py)\n \n\n# 描述符系统 (Descriptors)\n\n## 1. 系统概述\n\n描述符系统是 Evidently 框架中用于对数据集行级别进行评估和特征提取的核心组件。该系统允许用户通过声明式的方式定义文本处理任务，并将这些任务应用到 DataFrame 的指定列上，生成评估结果和衍生特征。\n\n描述符的核心价值在于：\n\n- **行级别评估**：对数据集中的每一行数据进行独立评估\n- **特征提取**：将文本内容转换为可量化的数值特征\n- **测试集成**：内置支持与测试框架集成，可设置阈值和预期范围\n- **结果缓存**：通过装饰器实现计算结果缓存，避免重复计算\n\n资料来源：[src/evidently/descriptors/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/__init__.py)\n\n## 2. 核心架构\n\n### 2.1 架构组件\n\n描述符系统由以下核心组件构成：\n\n```mermaid\ngraph TD\n A[用户定义描述符] --> B[FeatureDescriptor]\n B --> C[底层 Feature 实现]\n C --> D[评估结果 / 特征值]\n \n E[Dataset] --> F[描述符注册表]\n F --> B\n G[Test Suite] --> B\n```\n\n### 2.2 FeatureDescriptor 类\n\n`FeatureDescriptor` 是描述符的顶层封装类，负责整合底层特征实现和可选的测试配置：\n\n```python\nFeatureDescriptor(feature=feature, alias=alias, tests=tests)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `feature` | `Feature` | 底层特征实现对象 |\n| `alias` | `str` | 描述符别名，用于在结果中标识 |\n| `tests` | `List[DescriptorTest \\| GenericTest]` | 可选的测试配置列表 |\n\n资料来源：[src/evidently/descriptors/generated_descriptors.py:1-50](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/generated_descriptors.py)\n\n### 2.3 描述符注册表机制\n\n描述符通过注册表进行统一管理，支持按类型和名称进行查找：\n\n```mermaid\ngraph LR\n A[描述符定义] --> B[DescriptorRegistry]\n B --> C[按类型查找]\n B --> D[按名称查找]\n C --> E[返回描述符实例]\n D --> E\n```\n\n注册表提供以下核心功能：\n- 注册新的描述符类型\n- 根据名称获取描述符\n- 维护描述符与底层实现的映射关系\n\n资料来源：[src/evidently/core/registries/descriptors.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/registries/descriptors.py)\n\n## 3. 内置描述符类型\n\n### 3.1 文本基础描述符\n\n文本基础描述符主要用于文本数据的量化处理。\n\n| 描述符 | 功能 | 主要参数 |\n|--------|------|----------|\n| `Sentiment` | 情感分析 | `column_name`, `alias` |\n| `TextLength` | 文本长度统计 | `column_name`, `alias` |\n| `Contains` | 关键词匹配 | `column_name`, `words_list`, `mode`, `lemmatize`, `alias` |\n\n#### Sentiment 描述符\n\n情感分析描述符使用预训练模型对文本进行情感评分：\n\n```python\nSentiment(\"answer\", alias=\"Sentiment\")\n```\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `column_name` | `str` | 是 | 要分析的文本列名 |\n| `alias` | `str` | 是 | 结果列别名 |\n\n#### TextLength 描述符\n\n文本长度描述符计算文本的字符数或词数：\n\n```python\nTextLength(column_name=\"response\", alias=\"Response Length\")\n```\n\n#### Contains 描述符\n\n关键词匹配描述符检测文本中是否包含指定词语：\n\n```python\nContains(\n column_name=\"text\",\n words_list=[\"denial\", \"refuse\", \"can't\"],\n mode=\"any\", # or \"all\"\n lemmatize=True,\n alias=\"Denial Indicator\"\n)\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `column_name` | `str` | - | 目标文本列名 |\n| `words_list` | `List[str]` | - | 要匹配的词语列表 |\n| `mode` | `\"any\" \\| \"all\"` | `\"any\"` | 匹配模式 |\n| `lemmatize` | `bool` | `False` | 是否进行词形还原 |\n| `alias` | `str` | - | 结果别名 |\n\n资料来源：[src/evidently/descriptors/text_match.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/text_match.py)\n\n### 3.2 LLM Judge 描述符\n\nLLM Judge 描述符利用大语言模型对文本进行高级语义评估。\n\n| 描述符 | 功能 | 适用场景 |\n|--------|------|----------|\n| `ContextRelevance` | 上下文相关性评估 | RAG 系统评估 |\n| `AnswerRelevance` | 回答相关性评估 | 问答系统 |\n| `Faithfulness` | 回答忠实度评估 | 生成内容验证 |\n\n#### ContextRelevance 描述符\n\n用于评估检索到的上下文与查询的相关性：\n\n```python\nContextRelevance(\n column_name=\"context\",\n question_column=\"question\",\n alias=\"context_relevance\",\n criteria=default_context_relevance_criteria,\n uncertainty=default_llm_judge_params\n)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `column_name` | `str` | 上下文文本列 |\n| `question_column` | `str` | 问题列名 |\n| `alias` | `str` | 结果别名 |\n| `criteria` | `dict` | 评估标准 |\n| `uncertainty` | `dict` | 不确定性参数 |\n\n资料来源：[src/evidently/descriptors/_context_relevance.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/_context_relevance.py)\n\n### 3.3 HuggingFace 模型描述符\n\n支持直接调用 HuggingFace 模型进行特定任务：\n\n```python\nHuggingFace(\n column_name=\"text\",\n model=\"cardiffnlp/twitter-roberta-base-sentiment\",\n params={\"max_length\": 512},\n alias=\"hf_sentiment\"\n)\n```\n\n#### HuggingFaceToxicity 描述符\n\n专门用于检测文本毒性：\n\n```python\nHuggingFaceToxicity(\n column_name=\"text\",\n alias=\"toxicity_score\",\n model=None, # 使用默认模型\n toxic_label=\"toxic\"\n)\n```\n\n资料来源：[src/evidently/descriptors/generated_descriptors.py:40-70](https://github.com/evidentlyai/evidently/blob/main/src/evidently/descriptors/generated_descriptors.py)\n\n## 4. 使用方式\n\n### 4.1 在 Dataset 中使用\n\n描述符可以作为 Dataset 创建时的参数传入：\n\n```python\nfrom evidently import Dataset, DataDefinition\nfrom evidently.descriptors import Sentiment, TextLength, Contains\n\neval_dataset = Dataset.from_pandas(\n pd.DataFrame(eval_df),\n data_definition=DataDefinition(),\n descriptors=[\n Sentiment(\"answer\", alias=\"Sentiment\"),\n TextLength(\"answer\", alias=\"Answer Length\"),\n Contains(\n \"answer\",\n words_list=[\"sorry\", \"can't\", \"refuse\"],\n mode=\"any\",\n alias=\"Denial Indicator\"\n )\n ]\n)\n```\n\n### 4.2 与测试框架集成\n\n描述符支持内置的测试配置，可设置阈值和预期范围：\n\n```python\nfrom evidently.descriptors import TextLength\nfrom evidently.test_suits import DescriptorTest\n\ntests = [\n DescriptorTest(\n alias=\"Length Check\",\n condition=\"gte\",\n threshold=10\n )\n]\n\nTextLength(\"response\", alias=\"Response Length\", tests=tests)\n```\n\n### 4.3 工作流程\n\n```mermaid\ngraph TD\n A[创建 Dataset] --> B[应用描述符列表]\n B --> C[对每行数据进行特征计算]\n C --> D[缓存计算结果]\n D --> E[生成评估报告]\n E --> F{是否配置测试}\n F -->|是| G[执行测试断言]\n F -->|否| H[仅输出特征值]\n G --> I[测试结果]\n```\n\n## 5. 描述符与 Report 集成\n\n描述符生成的特征可以直接在 Report 中展示：\n\n```python\nfrom evidently import Report\nfrom evidently.presets import TextEvals\n\nreport = Report(metrics=[\n TextEvalsPreset()\n])\n\nreport.run(reference_data=ref_df, current_data=curr_df)\nreport.show()\n```\n\n## 6. 自定义描述符\n\n### 6.1 创建自定义 Feature\n\n用户可以通过继承 `Feature` 基类创建自定义描述符：\n\n```python\nfrom evidently.legacy.features.base import Feature\n\nclass CustomFeature(Feature):\n def __init__(self, column_name: str, **kwargs):\n super().__init__(column_name=column_name, **kwargs)\n \n def _calculate(self, data: pd.Series) -> pd.Series:\n # 自定义计算逻辑\n return data.apply(self._process)\n \n def _process(self, value):\n # 处理单个值\n return processed_value\n```\n\n### 6.2 封装为 FeatureDescriptor\n\n```python\nfrom evidently.descriptors import FeatureDescriptor\n\ndef CustomDescriptor(\n column_name: str,\n alias: str,\n tests: Optional[List[Union[\"DescriptorTest\", \"GenericTest\"]]] = None\n):\n feature = CustomFeature(column_name=column_name, display_name=alias)\n return FeatureDescriptor(feature=feature, alias=alias, tests=tests)\n```\n\n## 7. 性能优化\n\n描述符系统提供以下性能优化机制：\n\n| 优化方式 | 说明 |\n|----------|------|\n| 结果缓存 | 使用 `@lru_cache` 装饰器避免重复计算 |\n| 向量化计算 | 底层使用 pandas 向量化操作 |\n| 批量处理 | 支持批量数据处理减少 I/O 开销 |\n\n## 8. 总结\n\n描述符系统是 Evidently 框架中进行文本数据评估的核心模块，通过统一抽象的接口设计，提供了从简单的文本长度统计到复杂的 LLM Judge 语义评估的完整能力覆盖。其与 Dataset 和 Report 系统的深度集成，使得用户可以方便地在机器学习和 LLM 系统的评估流程中使用这些描述符。\n\n描述符系统的设计遵循以下原则：\n- **声明式配置**：通过参数配置而非代码实现定义评估逻辑\n- **可组合性**：支持多个描述符组合使用\n- **可扩展性**：通过继承机制支持自定义描述符\n- **测试集成**：内置与测试框架的集成能力\n\n---\n\n\n\n## 报告与测试套件\n\n### 相关页面\n\n相关主题：[指标系统 (Metrics)](#page-3), [预设评估 (Presets)](#page-4)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/core/report.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/report.py)\n- [src/evidently/core/tests.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/tests.py)\n- [src/evidently/core/serialization.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/serialization.py)\n- [src/evidently/legacy/report/report.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/legacy/report/report.py)\n- [src/evidently/legacy/test_suite/test_suite.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/legacy/test_suite/test_suite.py)\n \n\n# 报告与测试套件\n\n## 概述\n\n报告（Report）与测试套件（Test Suite）是 Evidently 框架的两大核心功能模块，用于评估和监控机器学习及 LLM 支持的系统。这两个模块提供了互补的能力：报告专注于数据探索和可视化分析，而测试套件则用于验证数据质量和模型性能是否满足预期标准。\n\n报告模块通过统计分析生成交互式的可视化图表，帮助数据科学家理解模型行为和数据分布变化。测试套件模块则将评估标准形式化为可执行的测试用例，返回明确的通过/失败状态，便于 CI/CD 流程集成和自动化监控。资料来源：[src/evidently/legacy/report/report.py:1-50]()\n\n## 核心架构\n\n### 模块关系图\n\n```mermaid\ngraph TD\n A[数据集输入] --> B[Report]\n A --> C[Test Suite]\n B --> D[MetricRegistry]\n C --> E[TestRegistry]\n D --> F[可视化渲染]\n E --> G[测试结果输出]\n F --> H[HTML/JSON报告]\n G --> I[测试日志]\n H --> J[Web UI展示]\n I --> K[持续集成]\n```\n\n### 报告与测试套件对比\n\n| 特性 | 报告 (Report) | 测试套件 (Test Suite) |\n|:---|:---|:---|\n| 输出形式 | 可视化图表、统计指标 | 通过/失败状态 |\n| 交互性 | 支持 Web UI 交互查看 | 命令行批量执行 |\n| 返回类型 | `Report` 对象 | `TestSuite` 对象 |\n| 适用场景 | 数据探索、模型分析 | 自动化验证、CI/CD |\n| 配置方式 | Metrics 注册 | Tests 定义 |\n| 资料来源 | [src/evidently/core/report.py:1-30]() | [src/evidently/core/tests.py:1-30]() |\n\n## Report 报告模块\n\n### 功能特性\n\n报告模块提供以下核心功能：\n\n1. **多指标支持**：支持 100+ 内置评估指标，覆盖数据质量、分布漂移、分类性能、回归性能等多个维度\n2. **灵活的指标组合**：通过 `metrics` 参数可自由组合不同类型的指标\n3. **多种输出格式**：支持生成 HTML 交互式报告和 JSON 结构化数据\n4. **数据集支持**：兼容 pandas DataFrame 以及 Evidently 的 Dataset 对象\n\n### 基本使用流程\n\n```mermaid\ngraph LR\n A[准备数据] --> B[创建Report实例]\n B --> C[添加Metrics]\n C --> D[调用run方法]\n D --> E[生成报告]\n E --> F[保存/展示]\n```\n\n### 代码示例\n\n```python\nfrom evidently import Report\nfrom evidently.descriptors import Sentiment, TextLength\nfrom evidently.presets import TextEvals\n\n# 创建报告实例\nreport = Report(\n metrics=[\n TextEvals(),\n ]\n)\n\n# 准备数据集\nfrom evidently import Dataset\ndataset = Dataset.from_pandas(df, descriptors=[\n Sentiment(\"response\"),\n TextLength(\"response\")\n])\n\n# 运行报告\nresult = report.run(reference_data=reference, current_data=current)\nprint(result.show())\n```\n\n### 报告生成参数\n\n| 参数名 | 类型 | 必需 | 默认值 | 说明 |\n|:---|:---|:---|:---|:---|\n| `metrics` | `List[Metric]` | 是 | - | 要计算的指标列表 |\n| `date_column` | `str` | 否 | `None` | 时间戳列名 |\n| `verbose_level` | `int` | 否 | `1` | 日志详细程度 |\n| 资料来源 | [src/evidently/core/report.py:40-60]() | | | |\n\n### 报告运行方法\n\n```python\ndef run(\n self,\n reference_data: Optional[Any,\n current_data: Any,\n column_mapping: Optional[ColumnMapping] = None\n) -> ReportResult:\n \"\"\"执行报告生成\"\"\"\n```\n\n### 序列化支持\n\n报告支持 JSON 和 pickle 格式的序列化，便于持久化存储和后续加载分析。资料来源：[src/evidently/core/serialization.py:1-50]()\n\n## Test Suite 测试套件模块\n\n### 功能特性\n\n测试套件模块的核心特点包括：\n\n1. **声明式测试定义**：通过声明式语法定义数据质量测试\n2. **即时反馈**：运行后立即返回测试结果列表\n3. **详细日志**：每个测试失败时提供详细的原因说明\n4. **与报告互补**：测试套件可以复用报告中的指标定义\n\n### 测试执行流程\n\n```mermaid\ngraph TD\n A[定义TestSuite] --> B[添加Tests]\n B --> C[加载数据集]\n C --> D[执行run方法]\n D --> E{测试通过?}\n E -->|是| F[记录通过状态]\n E -->|否| G[记录失败详情]\n F --> H[生成TestResult]\n G --> H\n H --> I[返回结果列表]\n```\n\n### 代码示例\n\n```python\nfrom evidently import TestSuite\nfrom evidently.test_suite import TestSuite\nfrom evidently.legacy.test_suite import TestSuite as LegacyTestSuite\n\n# 创建测试套件\ntest_suite = TestSuite(tests=[\n # 测试定义\n])\n\n# 运行测试\nresult = test_suite.run(reference_data=ref, current_data=cur)\n\n# 检查结果\nif result.passed:\n print(\"所有测试通过\")\nelse:\n print(f\"失败测试数: {result.get_fail_count()}\")\n```\n\n### 测试结果结构\n\n| 属性 | 类型 | 说明 |\n|:---|:---|:---|\n| `passed` | `bool` | 是否全部通过 |\n| `total` | `int` | 测试总数 |\n| `failed` | `int` | 失败数量 |\n| `results` | `List[TestResult]` | 单个测试结果列表 |\n| 资料来源 | [src/evidently/legacy/test_suite/test_suite.py:50-100]() |\n\n## 指标与测试的对应关系\n\n### 指标 (Metric) 到测试 (Test) 的转换\n\nEvidently 框架支持将指标计算结果转换为测试用例，实现评估逻辑的复用：\n\n```python\n# 指标 → 测试的映射关系\nfrom evidently.metrics import ColumnSummaryMetric\n\n# 基于指标的测试定义\nTestMetric = ColumnSummaryMetric(\n column_name=\"target\",\n quantile=[0.05, 0.95]\n)\n```\n\n### 常用指标分类\n\n| 类别 | 指标名称 | 对应测试 |\n|:---|:---|:---|\n| 数据质量 | `MissingValuesMetric` | `TestMissingValues` |\n| 分布漂移 | ` drift.DriftMetric` | `TestColumnDrift` |\n| 分类性能 | `ClassificationQualityMetric` | `TestAccuracyScore` |\n| 回归性能 | `RegressionQualityMetric` | `TestMAEScore` |\n\n## 遗留版本兼容性\n\nEvidently 保留了遗留版本的 API，确保向后兼容：\n\n### Legacy Report\n\n```python\nfrom evidently.legacy.report.report import Report as LegacyReport\n\n# 遗留版本报告创建方式\nlegacy_report = LegacyReport(\n metrics=[],\n mode='raw'\n)\n```\n\n### Legacy Test Suite\n\n```python\nfrom evidently.legacy.test_suite.test_suite import TestSuite as LegacyTestSuite\n\n# 遗留版本测试套件\nlegacy_suite = LegacyTestSuite(tests=[])\n```\n\n遗留版本模块位于 `src/evidently/legacy/` 目录下，新项目推荐使用核心模块 `src/evidently/core/` 下的实现。资料来源：[src/evidently/legacy/report/report.py:1-30]()\n\n## 最佳实践\n\n### 1. 选择合适的模块\n\n- **使用 Report**：当需要可视化分析、探索性数据检查、或需要生成可分享的 HTML 报告时\n- **使用 Test Suite**：当需要自动化验证、CI/CD 集成、或需要明确的通过/失败判断时\n- **组合使用**：在实际项目中，可以先使用 Report 进行分析，再将关键指标转化为 Test Suite 进行持续监控\n\n### 2. 数据准备\n\n确保输入数据格式正确：\n\n```python\nfrom evidently import Dataset, DataDefinition\n\n# 推荐的数据准备方式\ndataset = Dataset.from_pandas(\n pd.DataFrame(data),\n data_definition=DataDefinition()\n)\n```\n\n### 3. 性能优化\n\n对于大规模数据集，建议：\n\n- 使用 `verbose_level=0` 减少日志输出\n- 分批次处理时间序列数据\n- 复用 `ColumnMapping` 配置\n\n## 输出格式与集成\n\n### HTML 报告输出\n\n```python\n# 保存为 HTML 文件\nreport.save_html(\"output/report.html\")\n\n# 或者获取 HTML 字符串\nhtml_content = report.get_html()\n```\n\n### JSON 序列化\n\n```python\nimport json\n\n# 序列化为 JSON\njson_data = report.json()\nwith open(\"report.json\", \"w\") as f:\n json.dump(json_data, f)\n```\n\n### 与 Web UI 集成\n\nEvidently UI 支持加载报告文件进行交互式查看：\n\n```bash\nevidently ui --projects ./projects\n```\n\n生成的报告文件可通过 UI 的文件链接功能展示，模板定义位于 `src/evidently/ui/utils.py`。资料来源：[src/evidently/ui/utils.py:1-50]()\n\n## 总结\n\n报告与测试套件共同构成了 Evidently 框架的评估基础设施。报告模块侧重于深入的数据分析和可视化呈现，帮助用户理解模型行为；测试套件模块则提供可自动化的验证机制，确保生产环境的稳定性。两者基于共同的指标体系设计，可实现分析与监控的无缝衔接，是 ML/LLM 系统可靠性的重要保障。\n\n---\n\n\n\n## LLM集成与评判器\n\n### 相关页面\n\n相关主题：[描述符系统 (Descriptors)](#page-5), [Guardrails安全护栏](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/llm/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/__init__.py)\n- [src/evidently/llm/models.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/models.py)\n- [src/evidently/llm/prompts/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/prompts/__init__.py)\n- [src/evidently/llm/rag/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/rag/__init__.py)\n- [src/evidently/llm/datagen/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/datagen/__init__.py)\n- [src/evidently/llm/optimization/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/llm/optimization/__init__.py)\n- [src/evidently/utils/llm/wrapper.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/utils/llm/wrapper.py)\n \n\n# LLM集成与评判器\n\n## 概述\n\nLLM集成与评判器是Evidently框架中用于评估和测试大型语言模型(LLM)输出质量的核心模块。该系统提供了完整的LLM驱动评估能力，支持通过预定义或自定义的评判标准对文本输出进行自动化质量评估。\n\nEvidently的LLM评判器允许用户创建结构化的评估流程，通过提示词模板(prompt templates)定义评估规则，并支持多类别分类、置信度评分等高级评估场景。\n\n## 系统架构\n\n### 核心模块结构\n\n| 模块 | 路径 | 功能描述 |\n|------|------|----------|\n| `llm` | `src/evidently/llm/` | LLM集成核心模块 |\n| `prompts` | `src/evidently/llm/prompts/` | 提示词模板管理 |\n| `rag` | `src/evidently/llm/rag/` | RAG相关评估 |\n| `datagen` | `src/evidently/llm/datagen/` | 测试数据生成 |\n| `optimization` | `src/evidently/llm/optimization/` | 提示词优化 |\n| `wrapper` | `src/evidently/utils/llm/wrapper.py` | LLM调用封装 |\n\n## 评判器配置\n\n### 描述符配置(Descriptor Config)\n\n描述符配置用于定义单个评估指标的元数据和参数。系统通过`ConfigAPI`类管理描述符配置的版本化存储。\n\n主要配置方法：\n\n- **创建描述符**：`add_descriptor()` - 添加新的描述符配置\n- **获取描述符**：`get_descriptor()` - 根据名称和版本获取描述符\n- **更新描述符**：通过版本控制机制实现配置的增量更新\n\n### 多分类评判模板\n\n系统支持多分类评判模板(`MulticlassClassificationPromptTemplate`)，用于需要将输入分类到多个预定义类别的评估场景。\n\n```typescript\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Descriptors/Features/LLMJudge/template.tsx:67\n{state.type === 'evidently:prompt_template:MulticlassClassificationPromptTemplate' && (\n \n Classes\n \n Provide classes for multiclass classification mode.\n \n {/* 类别配置表单 */}\n \n)}\n```\n\n### 评判标准配置\n\n评判器支持为每个分类类别定义独立的评判标准，通过`category_criteria`字典存储类别与对应评判规则的映射关系。\n\n## 用户界面集成\n\n### 评判模板编辑组件\n\n前端组件`LLMJudge/template.tsx`提供了可视化的评判模板配置界面，支持：\n\n- 评判类型选择\n- 类别定义与管理\n- 置信度阈值配置\n- 错误状态展示\n\n### 提示词管理界面\n\n系统提供完整的提示词生命周期管理：\n\n```typescript\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx\n{\n key: 'actions',\n label: 'Action',\n render: (prompt) => (\n \n \n onDelete(prompt.id ?? '')}>\n \n \n \n )\n}\n```\n\n支持的操作包括：\n- 创建新提示词\n- 编辑现有提示词\n- 删除提示词\n- 复制提示词ID\n\n## 工作流程\n\n### LLM评估流程\n\n```mermaid\ngraph TD\n A[输入数据] --> B[创建Dataset]\n B --> C[应用Descriptors]\n C --> D[LLM评判器处理]\n D --> E[生成评估结果]\n E --> F[生成Report]\n```\n\n### 提示词模板配置流程\n\n```mermaid\ngraph LR\n A[选择评判类型] --> B[配置评判标准]\n B --> C[设置类别阈值]\n C --> D[保存配置版本]\n D --> E[关联到Descriptor]\n```\n\n## SDK配置与API\n\n### 云端配置管理\n\n系统通过`CloudConfigAPI`类提供云端配置管理能力，支持：\n\n- 配置版本化存储\n- 元数据管理\n- 远程配置同步\n\n```python\n# 资料来源：src/evidently/sdk/configs.py\ndef add_descriptor(self, project_id: STR_UUID, name: str, descriptor: Descriptor) -> ConfigVersion:\n \"\"\"添加描述符配置\"\"\"\n return self._add_typed_version(project_id, name, descriptor)\n```\n\n### 适配器层\n\n`RemoteGenericConfig`适配器负责处理与远程服务的通信，包括：\n\n- 配置上传与下载\n- 版本历史查询\n- 内容序列化与反序列化\n\n## 数据模型\n\n### 配置版本元数据\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `id` | UUID | 配置版本唯一标识 |\n| `artifact_id` | UUID | 关联的描述符ID |\n| `version` | int | 版本号 |\n| `content` | Any | 配置内容 |\n| `metadata.created_at` | datetime | 创建时间 |\n| `metadata.updated_at` | datetime | 更新时间 |\n| `metadata.author` | str | 作者 |\n| `metadata.comment` | str | 版本注释 |\n\n### 评判器状态\n\n评判器状态通过React组件管理，包含：\n\n- 当前评判类型\n- 类别评判标准映射\n- 错误状态与消息\n- 不确定性阈值配置\n\n## 使用示例\n\n### 创建LLM评估数据集\n\n```python\nfrom evidently import Report, Dataset, DataDefinition\nfrom evidently.descriptors import Sentiment, TextLength, Contains\n\neval_dataset = Dataset.from_pandas(\n pd.DataFrame(eval_df),\n data_definition=DataDefinition(),\n descriptors=[\n Sentiment(\"answer\", alias=\"Sentiment\"),\n TextLength(\"answer\", alias=\"Length\"),\n Contains(\"answer\", pattern=\"denial_words\", alias=\"ContainsDenial\")\n ]\n)\n```\n\n### 生成评估报告\n\n```python\nreport = Report(metrics=[\n TextEvals()\n])\nreport.run(reference_dataset=reference_data, current_dataset=current_data)\nreport.save_html(\"evaluation_report.html\")\n```\n\n## 技术实现要点\n\n### 前端状态管理\n\n评判器模板组件使用React Hook Form进行表单状态管理，配合Zod进行数据验证：\n\n```typescript\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Descriptors/Features/LLMJudge/template.tsx\ntype FormSchema = z.infer\nconst formSchema = z.object({...})\n```\n\n### 错误处理机制\n\n系统实现了多层次的错误处理：\n\n1. **表单级错误**：通过`errors`对象捕获并展示字段级验证错误\n2. **API级错误**：通过`isLoading`状态管理异步操作错误\n3. **业务逻辑错误**：通过`AlertThemed`组件展示业务规则违反\n\n## 相关资源\n\n- [API Reference Documentation](https://evidentlyai.github.io/evidently/api-reference)\n- [LLM Evaluation Tutorial](https://docs.evidentlyai.com/quickstart_llm)\n- [Descriptor Configuration Guide](https://docs.evidentlyai.com/descriptors)\n\n---\n\n\n\n## Guardrails安全护栏\n\n### 相关页面\n\n相关主题：[LLM集成与评判器](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [src/evidently/ui/utils.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/utils.py)\n \n\n# Guardrails安全护栏\n\n## 概述\n\nGuardrails（安全护栏）是Evidently框架中用于监控和验证LLM（大型语言模型）输出的安全机制。该功能允许用户在追踪（Traces）中记录、检查和展示护栏的检查结果，确保AI系统的输出符合预定的安全和合规标准。\n\n在Evidently的架构中，Guardrails主要与Trace系统集成，通过`extractGuardRailsDataFromSpan`函数从span中提取护栏数据，并在UI层面提供可视化展示。资料来源：[TraceTable.tsx:22-32]()\n\n## 核心功能\n\n### 护栏数据提取\n\nGuardrails的数据来源于Trace中的各个span。通过`extractGuardRailsDataFromSpan`函数，系统能够从span中提取护栏相关的检查信息，包括：\n\n- **状态信息**：护栏检查通过或失败\n- **名称标识**：具体护栏类型的名称\n- **详细属性**：每个护栏的完整属性映射\n\n```typescript\n// 从span中提取GuardRails数据\ntrace.spans\n .map(extractGuardRailsDataFromSpan)\n .filter(isNotNull)\n .flat()\n```\n\n资料来源：[TraceTable.tsx:22-32]()\n\n### 护栏状态展示\n\nUI层提供了专门的`GuardRailStatus`组件来可视化展示护栏的通过/失败状态，通过颜色编码（绿色表示通过，红色表示失败）帮助用户快速识别问题。\n\n资料来源：[TraceComponent.tsx:12-16]()\n\n## 架构设计\n\n### 组件层级关系\n\n```mermaid\ngraph TD\n A[Trace] --> B[Spans]\n B --> C[GuardRails Data]\n C --> D[GuardRailsShowInfoButton]\n D --> E[GuardRailDialog]\n E --> F[GenericTable]\n F --> G[GuardRailStatus]\n \n A1[TraceTable] --> B1[GuardRails列]\n B1 --> C1[GuardRailsShowInfoButton]\n```\n\n### 护栏对话框流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Button as GuardRailsShowInfoButton\n participant Dialog as GuardRailDialog\n participant Table as GenericTable\n \n User->>Button: 查看护栏详情\n Button->>Dialog: setIsGuardRailDialogOpen(true)\n Dialog->>Table: 渲染护栏数据\n Table->>User: 显示通过/失败统计\n \n Note over Table: 统计passed/failed数量\n```\n\n## 数据结构\n\n### 护栏数据模型\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 护栏唯一标识符 |\n| `name` | string | 护栏名称（如toxicity、pii等） |\n| `status` | enum | 护栏状态：passed/failed |\n| `index` | number | 护栏在序列中的位置 |\n\n### 护栏按钮状态\n\n| 状态类型 | 条件 | 按钮样式 |\n|----------|------|----------|\n| all-passed | 所有护栏通过 | outlined + success颜色 |\n| failed | 存在护栏失败 | contained + error颜色 |\n\n资料来源：[GuardRailsShowInfoButton.tsx:10-20]()\n\n## UI组件详解\n\n### GuardRailsShowInfoButton\n\n该组件是护栏信息的入口按钮，根据护栏通过/失败状态显示不同的UI样式：\n\n```typescript\n\n {guardRailButtonInfoType === 'all-passed'\n ? `${passedGuardRailDataCount}/${allGuardRailDataCount} passed`\n : `${failedGuardRailDataCount}/${allGuardRailDataCount} failed`}\n\n```\n\n资料来源：[GuardRailsShowInfoButton.tsx:10-22]()\n\n### GuardRailDialog\n\n对话框组件用于展示完整的护栏检查结果：\n\n```typescript\n\n Guard rails\n \n \n \n\n```\n\n资料来源：[GuardRailsShowInfoButton.tsx:33-56]()\n\n### TraceTable中的护栏列\n\n在TraceTable组件中，护栏作为独立的列进行展示，支持条件渲染（当所有span均无护栏数据时跳过该列）：\n\n```typescript\n{\n key: 'guardrails',\n label: 'Guardrails',\n align: 'center',\n skipRender: data.every(\n (trace) =>\n trace.spans.map(extractGuardRailsDataFromSpan)\n .filter(isNotNull).flat().length === 0\n ),\n render: (trace) => (\n \n )\n}\n```\n\n资料来源：[TraceTable.tsx:22-42]()\n\n## 护栏渲染详情\n\n在TraceComponent中，护栏数据以表格形式展示每个属性的键值对：\n\n```typescript\n{Object.entries(guardRail).map(([k, v]) => (\n \n \n {k}\n \n \n {k === 'status' ? (\n \n ) : (\n \n )}\n \n \n))}\n```\n\n资料来源：[TraceComponent.tsx:18-34]()\n\n## 配置选项\n\n### 护栏对话框配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `open` | boolean | - | 对话框打开状态 |\n| `fullWidth` | boolean | true | 宽度占满容器 |\n| `maxWidth` | string | 'md' | 最大宽度 |\n| `PaperComponent` | component | Box | 纸张组件包装 |\n\n### 按钮样式配置\n\n| 样式条件 | color | variant |\n|----------|-------|---------|\n| 全部通过 | 'success' | 'outlined' |\n| 存在失败 | 'error' | 'contained' |\n\n资料来源：[GuardRailsShowInfoButton.tsx:10-22]()\n\n## 使用场景\n\n### 在Trace追踪中集成护栏\n\n```typescript\n// 在TraceViewer中展示护栏信息\n\n {childSelectedSpans.length > 0 && (\n Child spans\n )}\n\n```\n\n### 条件渲染护栏列\n\n当项目中没有任何护栏数据时，对应的表格列会被自动隐藏，优化用户界面：\n\n```typescript\nskipRender: data.every(\n (trace) =>\n trace.spans.map(extractGuardRailsDataFromSpan)\n .filter(isNotNull).flat().length === 0\n)\n```\n\n资料来源：[TraceTable.tsx:26-30]()\n\n## 与其他模块的集成\n\n### 与LLM Judge的关联\n\n在LLM Judge模板中，护栏系统与评估标准协同工作，支持多类别评估标准的配置：\n\n```typescript\n{state.type === 'evidently:prompt_template:MulticlassClassificationPromptTemplate' && (\n \n Classes\n \n {Object.keys(state.category_criteria ?? {}).map((className) => (\n \n ))}\n \n \n)}\n```\n\n资料来源：[LLMJudge/template.tsx:35-45]()\n\n### 与项目管理的集成\n\n通过ProjectCard组件，用户可以在项目管理界面中快速访问包含护栏数据的Trace记录，实现端到端的安全监控工作流。\n\n## 最佳实践\n\n### 护栏数据过滤\n\n```typescript\n// 使用filter和flat处理多span场景\ntrace.spans\n .map(extractGuardRailsDataFromSpan)\n .filter(isNotNull)\n .flat()\n```\n\n### 状态判断逻辑\n\n```typescript\nconst guardRailButtonInfoType = \n passedGuardRailDataCount === allGuardRailDataCount\n ? 'all-passed'\n : 'failed'\n```\n\n资料来源：[GuardRailsShowInfoButton.tsx:1-8]()\n\n## 总结\n\nGuardrails安全护栏是Evidently框架中保障LLM应用安全的重要组件。通过与Trace系统的深度集成，它提供了：\n\n- **可视化监控**：直观的UI展示护栏检查结果\n- **状态追踪**：通过颜色编码快速识别安全问题\n- **条件渲染**：智能隐藏无数据列，保持界面整洁\n- **详情查看**：对话框形式展示完整护栏属性\n\n该系统为AI安全工程师和开发团队提供了有效的工具，用于监控和验证AI模型的输出是否符合预期的安全标准。\n\n---\n\n\n\n## 数据管理与存储\n\n### 相关页面\n\n相关主题：[报告与测试套件](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/evidently/ui/service/datasets/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/datasets/__init__.py)\n- [src/evidently/ui/service/storage/__init__.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/storage/__init__.py)\n- [src/evidently/ui/service/storage/local/base.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/storage/local/base.py)\n- [src/evidently/ui/service/storage/sql/base.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/storage/sql/base.py)\n- [src/evidently/ui/service/storage/sql/dataset.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/storage/sql/dataset.py)\n- [src/evidently/ui/service/datasets/models.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/ui/service/datasets/models.py)\n- [src/evidently/core/datasets.py](https://github.com/evidentlyai/evidently/blob/main/src/evidently/core/datasets.py)\n \n\n# 数据管理与存储\n\n## 概述\n\nEvidently 的数据管理与存储系统是框架的核心组件之一，负责处理数据集的持久化、检索和管理。该系统采用分层架构设计，支持多种存储后端，为 ML 和 LLM 系统的评估、测试与监控提供了可靠的数据基础设施。\n\n系统的主要职责包括：\n\n- 数据集的创建、读取、更新和删除（CRUD）操作\n- 支持本地文件系统存储和 SQL 数据库存储两种后端\n- 提供统一的数据访问接口，屏蔽底层存储差异\n- 管理数据集的元数据信息\n- 支持数据集与项目、快照的关联关系\n\n资料来源：[src/evidently/ui/service/storage/__init__.py]()\n\n## 架构设计\n\n### 整体架构\n\n系统采用典型的分层架构模式，自上而下分为三个主要层次：\n\n```mermaid\ngraph TD\n A[应用层] --> B[服务层]\n B --> C[存储层]\n C --> D[本地存储]\n C --> E[SQL 存储]\n \n B --> F[数据集服务
Datasets Service]\n F --> G[数据模型
DatasetModel]\n \n D --> H[本地文件系统]\n E --> I[(SQLite/PostgreSQL)]\n```\n\n### 存储后端类型\n\n| 存储类型 | 文件路径 | 适用场景 |\n|---------|---------|---------|\n| 本地存储 | `storage/local/base.py` | 开发环境、单节点部署 |\n| SQL 存储 | `storage/sql/base.py` | 生产环境、多用户协作 |\n\n资料来源：[src/evidently/ui/service/storage/local/base.py](), [src/evidently/ui/service/storage/sql/base.py]()\n\n## 核心数据模型\n\n### 数据集模型\n\n`DatasetModel` 是数据集的核心数据结构，定义了数据集的所有属性：\n\n```python\nclass DatasetModel:\n id: DatasetID # 唯一标识符\n project_id: ProjectID # 所属项目ID\n name: str # 数据集名称\n description: Optional[str] # 数据集描述\n metadata: DatasetMetadata # 元数据信息\n created_at: datetime # 创建时间\n updated_at: datetime # 更新时间\n author: Optional[str] # 创建者\n```\n\n资料来源：[src/evidently/ui/service/datasets/models.py]()\n\n### 元数据结构\n\n```python\n@dataclass\nclass DatasetMetadata:\n created_at: datetime # 创建时间戳\n updated_at: datetime # 更新时间戳\n author: Optional[str] # 创建者信息\n description: Optional[str] # 描述信息\n tags: Optional[List[str]] # 标签列表\n link: Optional[str] # 关联链接\n```\n\n资料来源：[src/evidently/ui/service/datasets/models.py]()\n\n## 服务层组件\n\n### 数据集服务\n\n数据集服务（`DatasetsService`）是应用层与存储层之间的桥梁，提供统一的数据集操作接口：\n\n| 方法 | 功能描述 |\n|-----|---------|\n| `add()` | 创建新数据集 |\n| `load()` | 加载数据集内容 |\n| `list()` | 列出项目中的所有数据集 |\n| `delete()` | 删除指定数据集 |\n\n资料来源：[src/evidently/ui/service/datasets/__init__.py]()\n\n### 服务工作流\n\n```mermaid\nsequenceDiagram\n participant Client\n participant DatasetsService\n participant StorageLayer\n participant Backend\n \n Client->>DatasetsService: add_dataset(project_id, dataset)\n DatasetsService->>StorageLayer: save(dataset)\n StorageLayer->>Backend: write data\n Backend-->>StorageLayer: confirmation\n StorageLayer-->>DatasetsService: saved dataset\n DatasetsService-->>Client: dataset ID\n \n Client->>DatasetsService: load_dataset(dataset_id)\n DatasetsService->>StorageLayer: retrieve(dataset_id)\n StorageLayer->>Backend: read data\n Backend-->>StorageLayer: data\n StorageLayer-->>DatasetsService: Dataset object\n DatasetsService-->>Client: Dataset\n```\n\n## 存储层实现\n\n### 存储接口抽象\n\n存储层定义了统一的抽象接口，具体实现类负责与不同的存储后端交互：\n\n```python\nclass BaseStorage(ABC):\n \"\"\"存储层抽象基类\"\"\"\n \n @abstractmethod\n def save(self, dataset: Dataset) -> DatasetID: ...\n \n @abstractmethod\n def load(self, dataset_id: DatasetID) -> Dataset: ...\n \n @abstractmethod\n def list(self, project_id: ProjectID) -> DatasetList: ...\n \n @abstractmethod\n def delete(self, dataset_id: DatasetID) -> None: ...\n```\n\n资料来源：[src/evidently/ui/service/storage/__init__.py]()\n\n### 本地存储实现\n\n本地存储适配器使用文件系统作为数据持久化后端：\n\n| 配置项 | 说明 |\n|-------|------|\n| `base_path` | 存储根目录路径 |\n| `format` | 数据序列化格式（JSON/Parquet） |\n| `max_size_mb` | 单个数据集大小限制 |\n\n**数据组织结构：**\n\n```\n{base_path}/\n└── {project_id}/\n └── {dataset_id}/\n ├── data.{format}\n └── metadata.json\n```\n\n资料来源：[src/evidently/ui/service/storage/local/base.py]()\n\n### SQL 存储实现\n\nSQL 存储适配器支持多种关系型数据库：\n\n```python\nclass SQLStorage(BaseStorage):\n \"\"\"SQL 数据库存储实现\"\"\"\n \n def __init__(\n self,\n connection_string: str,\n table_prefix: str = \"evidently_\"\n ):\n self.engine = create_engine(connection_string)\n self.table_prefix = table_prefix\n```\n\n**支持的数据库：**\n\n| 数据库 | 连接字符串格式 |\n|-------|---------------|\n| SQLite | `sqlite:///path/to/db.sqlite` |\n| PostgreSQL | `postgresql://user:pass@host:5432/db` |\n\n资料来源：[src/evidently/ui/service/storage/sql/base.py](), [src/evidently/ui/service/storage/sql/dataset.py]()\n\n## 核心数据集模块\n\n### 核心数据集类\n\n`Dataset` 类是框架层面的数据集抽象，定义在核心模块中：\n\n```python\nclass Dataset:\n \"\"\"数据集核心抽象\"\"\"\n \n def __init__(\n self,\n dataframe: pd.DataFrame,\n data_definition: DataDefinition,\n descriptors: Optional[List[Descriptor]] = None\n ):\n self._dataframe = dataframe\n self._data_definition = data_definition\n self._descriptors = descriptors or []\n```\n\n资料来源：[src/evidently/core/datasets.py]()\n\n### 数据集工厂方法\n\n```python\n@classmethod\ndef from_pandas(\n cls,\n dataframe: pd.DataFrame,\n data_definition: DataDefinition = None,\n descriptors: List[Descriptor] = None\n) -> \"Dataset\":\n \"\"\"从 Pandas DataFrame 创建数据集\"\"\"\n ...\n```\n\n资料来源：[src/evidently/core/datasets.py]()\n\n## API 端点\n\n数据集相关的 REST API 端点：\n\n| 方法 | 端点 | 功能 |\n|-----|------|-----|\n| POST | `/api/v2/datasets/{project_id}` | 创建数据集 |\n| GET | `/api/v2/datasets/{dataset_id}` | 获取数据集 |\n| GET | `/api/v2/datasets` | 列出数据集 |\n| PUT | `/api/v2/datasets/{dataset_id}` | 更新数据集 |\n| DELETE | `/api/v2/datasets/{dataset_id}` | 删除数据集 |\n\n## 配置指南\n\n### 存储后端配置\n\n```python\nfrom evidently.ui.service.storage import WorkspaceStorage\n\n# 本地存储配置\nlocal_storage = WorkspaceStorage.local(\n base_path=\"./data/evidently\",\n format=\"parquet\"\n)\n\n# SQL 存储配置\nsql_storage = WorkspaceStorage.sql(\n connection_string=\"sqlite:///evidently.db\",\n table_prefix=\"ev_\"\n)\n```\n\n### 环境变量配置\n\n| 变量名 | 说明 | 默认值 |\n|-------|------|-------|\n| `EVIDENTLY_DATA_DIR` | 本地存储路径 | `./evidently_data` |\n| `EVIDENTLY_DB_URL` | 数据库连接字符串 | SQLite 本地文件 |\n| `EVIDENTLY_STORAGE_TYPE` | 存储类型 | `local` |\n\n## 数据流转\n\n```mermaid\ngraph LR\n A[CSV/Parquet] --> B[DataLoader]\n B --> C[Dataset]\n C --> D[Descriptors]\n D --> E[Evaluations]\n \n F[Report] --> G[Snapshot]\n G --> H[Storage]\n \n C -.->|持久化| H\n```\n\n## 最佳实践\n\n### 数据集命名规范\n\n- 使用有意义的名称，包含项目标识和用途\n- 避免使用特殊字符和空格\n- 推荐格式：`{project}_{purpose}_{version}`\n\n### 存储策略建议\n\n1. **小数据集（< 100MB）**：使用本地存储或 SQLite\n2. **中等数据集（100MB - 1GB）**：使用 PostgreSQL\n3. **大数据集（> 1GB）**：考虑分区存储或外部存储服务\n\n### 性能优化\n\n- 为 `project_id` 和 `created_at` 字段建立索引\n- 定期清理过期数据集\n- 使用 Parquet 格式减少存储空间\n\n## 相关模块\n\n- [evidently.sdk.adapters](./sdk/adapters) - 云端适配器\n- [evidently.ui.workspace](./ui/workspace) - 工作空间管理\n- [evidently.legacy.metrics](./legacy/metrics) - 指标计算\n\n---\n\n\n\n## 前端UI组件库\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n \n\n# 前端UI组件库\n\n## 概述\n\nEvidently UI组件库（`evidently-ui-lib`）是一个共享的前端组件包，同时服务于 `service`（服务模式）和 `standalone`（独立模式）两种部署场景。该组件库基于React和TypeScript构建，集成了Material UI（@mui/material）作为基础UI框架，提供数据可视化、仪表板、追踪管理、提示词管理等核心功能模块。\n\n资料来源：[ui/packages/evidently-ui-lib/README.md](https://github.com/evidentlyai/evidently/blob/main/ui/packages/evidently-ui-lib/README.md)\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[evidently-ui-lib] --> B[Dashboard 模块]\n A --> C[Traces 模块]\n A --> D[Prompts 模块]\n A --> E[Datasets 模块]\n A --> F[Widgets 模块]\n A --> G[通用组件]\n \n B --> B1[DashboardWidgets]\n B --> B2[DashboardPanel]\n B --> B3[DashboardDateFilter]\n \n C --> C1[TracesTable]\n C --> C2[TraceTable]\n C --> C3[DialogViewer]\n C --> C4[TraceViewer]\n \n D --> D1[PromptsTable]\n D --> D2[CreatePromptForm]\n D --> D3[Edit Prompt]\n \n F --> F1[Widget]\n F --> F2[BigTableDetails]\n F --> F3[AlertBlock]\n F --> F4[InsightBlock]\n \n G --> G1[BaseTabs]\n G --> G2[NameAndDescriptionForm]\n G --> G3[TextPanel]\n```\n\n## 核心模块\n\n### 1. 仪表板模块（Dashboard）\n\n仪表板模块负责展示监控面板和数据可视化组件，支持时间范围过滤和多种面板类型。\n\n#### DashboardWidgets 组件\n\n主仪表板渲染组件，根据传入的 `WidgetInfo[]` 数组动态渲染监控面板。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `widgets` | `WidgetInfo[]` | 要渲染的组件信息数组 |\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Widgets/DashboardWidgets.tsx\nexport const DashboardWidgets = ({ widgets }: { widgets: WidgetInfo[] }) => {\n if (widgets.length === 0) {\n return (\n \n This dashboard is currently empty. Please add a monitoring panel to start.\n \n )\n }\n return \n}\n```\n\n#### DashboardPanel 面板系统\n\n支持多种面板类型，包括文本面板、数值面板、图表面板等。\n\n```mermaid\ngraph LR\n A[面板类型] --> B[text 文本面板]\n A --> C[line_plot 线图面板]\n A --> D[big_table 大表格面板]\n \n B --> B1[PanelCardGeneral]\n C --> C1[LinePlot 渲染]\n D --> D1[BigTableDetails]\n```\n\n**Text 文本面板**实现示例：\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Dashboard/Panels/implementations/Text.tsx\nexport type TextPanelProps = MakePanel<{\n type: 'text'\n size: 'full' | 'half'\n title?: string\n description?: string\n}>\n\nexport const TextDashboardPanel = ({ title, description }: TextPanelProps) => {\n return (\n \n )\n}\n```\n\n#### 日期过滤器\n\n仪表板支持日期范围过滤，用于限制数据展示的时间区间。\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Dashboard/DashboardDateFilter.tsx\n// 支持 dateFrom 和 dateTo 两个日期选择器\n// 当 dateFrom 晚于 dateTo 时显示错误提示\n\n \n Error\n Incorrect time interval\n \n\n```\n\n### 2. 追踪模块（Traces）\n\n追踪模块负责展示和管理AI应用执行追踪数据，支持查看、过滤、编辑和删除操作。\n\n#### TracesTable 组件\n\n主追踪列表表格，支持排序、分页和多种列展示。\n\n| 列名 | 类型 | 说明 | 可排序 |\n|------|------|------|--------|\n| `tags` | ReactNode | 追踪标签 | 否 |\n| `metadata` | ReactNode | 元数据（JSON格式） | 否 |\n| `type` | ReactNode | 追踪来源类型 | 否 |\n| `created_at` | string | 创建时间 | 是 |\n| `actions` | ReactNode | 操作按钮组 | 否 |\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Traces/TracesTable.tsx\n{\n key: 'created_at',\n label: 'Created at',\n sortable: {\n getSortValue: (trace) => trace.created_at,\n isDateString: true\n },\n render: (trace) => (\n \n {dayjs(trace.created_at).locale('en-gb').format('llll')}\n \n )\n}\n```\n\n#### TraceTable 详情表格\n\n用于追踪详情页面，包含token使用量、Guardrails状态等高级信息。\n\n| 列名 | 说明 | 特殊属性 |\n|------|------|----------|\n| `end_time` | 结束时间 | - |\n| `token_usage` | Token使用量 | - |\n| `guardrails` | Guardrails信息 | 条件显示 |\n| `actions` | 操作按钮 | sticky |\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Traces/TraceViewer/components/TraceTable.tsx\n{\n key: 'guardrails',\n label: 'Guardrails',\n align: 'center',\n skipRender: data.every(\n (trace) =>\n trace.spans.map(extractGuardRailsDataFromSpan).filter(isNotNull).flat().length === 0\n ),\n render: (trace) => (\n \n )\n}\n```\n\n#### DialogViewer 对话查看器\n\n用于会话消息展示，支持用户消息和代理消息的双栏显示。\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Traces/DialogViewer/components/Message.tsx\n// 消息组件关键属性\n{\n message: string // 消息内容\n align: 'left' | 'right' // 对齐方向\n time: string // 时间戳\n}\n```\n\n### 3. 提示词模块（Prompts）\n\n提示词管理模块，支持提示词的列表展示、创建、编辑和版本管理。\n\n#### PromptsTable 组件\n\n提示词列表表格，包含以下列：\n\n| 列名 | 渲染内容 | 说明 |\n|------|----------|------|\n| `id` | ID + 复制按钮 | 支持一键复制 |\n| `name` | 文本（最大宽度200px） | 提示词名称 |\n| `created_at` | 日期时间格式 | 创建时间 |\n| `actions` | 链接 + 删除按钮 | 操作区 |\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Prompts/PromptsTable.tsx\n{\n key: 'id',\n label: 'ID',\n align: 'center',\n render: (prompt) => (\n \n {prompt.id}\n \n \n )\n}\n```\n\n#### 表单组件\n\n**通用名称描述表单**：\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Utils/NameAndDescriptionForm.tsx\nexport type NameAndDescriptionFormProps = {\n defaultValues: {\n name?: string\n description?: string\n }\n onSubmit: (data: { name: string; description: string }) => void\n isLoading?: boolean\n allowSubmitDefaults?: boolean\n submitButtonTitle?: string\n}\n\n// 使用 zod 进行表单验证\nconst nameAndDescriptionSchema = z.object({\n name: z.string().min(1),\n description: z.string()\n})\n```\n\n**创建提示词表单**：\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Prompts/Forms/CreatePromptForm.tsx\n// 包含 name 字段验证\n// 禁用条件：isLoading || !isDirty || Object.keys(errors).length > 0\n```\n\n### 4. 组件模块（Widgets）\n\n核心可视化组件系统，负责渲染各类监控面板、告警和洞察信息。\n\n#### Widget 主组件\n\n主组件渲染器，支持标题、内容、详情、告警统计和洞察展示。\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/widgets/Widget.tsx\n// 组件结构\n\n \n \n \n {/* 标题和内容 */}\n \n {title}\n {content}
\n \n \n {/* 告警区域 */}\n {isAlertsExists ? (\n <>\n {alertStats ? : <>}\n {alerts?.map((alert) => )}\n \n ) : <>}\n \n {/* 洞察区域 */}\n {isInsightsExists ? (\n insights?.map((insight) => )\n ) : <>}\n \n \n \n\n```\n\n#### BigTableDetails 大表格详情\n\n支持多部分详情展示和洞察信息渲染。\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/widgets/BigTableWidget/BigTableDetails.tsx\nexport const BigTableDetails: React.FunctionComponent = (props) => {\n return (\n \n {(dashboardContext) => (\n \n {/* 多部分使用 AutoTabs 切换 */}\n {props.details.parts.length > 1 ? (\n ({\n title: part.title,\n tab: RenderPart(dashboardContext, part, props.widgetSize)\n }))}\n />\n ) : (\n RenderPart(dashboardContext, props.details.parts[0], props.widgetSize)\n )}\n \n {/* 洞察块渲染 */}\n {props.details.insights === undefined ? (\n <>\n ) : (\n props.details.insights.map((row) => (\n \n ))\n )}\n \n )}\n \n )\n}\n```\n\n### 5. 通用组件\n\n#### BaseTabs 标签页组件\n\n通用的标签页切换组件，支持手风琴模式。\n\n```tsx\n// 资料来源：ui/packages/evidently-ui-lib/src/components/Tabs/BaseTabs.tsx\n// 属性接口\n{\n tabs: Array<{\n title: string // 标签标题\n tab: ReactNode // 标签内容\n content?: ReactNode // 可选的额外内容\n }>\n activeTab: number // 当前激活索引，-1表示全部显示\n}\n```\n\n#### 工具类组件\n\n| 组件名 | 功能 |\n|--------|------|\n| `TextWithCopyIcon` | 带复制图标的文本展示 |\n| `LoadableView` | 加载状态包装器 |\n| `JsonViewThemed` | 主题化JSON查看器 |\n| `HidedTags` | 折叠标签组件 |\n| `Tooltip` | 提示气泡 |\n| `AlertThemed` | 主题化警告框 |\n\n## 数据流向\n\n```mermaid\ngraph TD\n A[API 数据源] --> B[evidently-ui-lib API 模块]\n B --> C[组件状态管理]\n C --> D[UI 渲染层]\n \n D --> E[DashboardWidgets]\n D --> F[TracesTable]\n D --> G[PromptsTable]\n D --> H[Widget]\n \n E --> I[DrawWidgets]\n F --> J[DialogViewer]\n G --> K[CreatePromptForm]\n H --> L[AlertBlock / InsightBlock]\n```\n\n## 类型定义\n\n核心类型定义位于各组件文件及 `api/index.tsx` 模块中：\n\n```tsx\n// WidgetInfo 类型（示例）\ninterface WidgetInfo {\n id: string\n type: string\n title?: string\n size: 'full' | 'half'\n // ... 其他属性\n}\n\n// Trace 类型（示例）\ninterface Trace {\n id: string\n trace_id: string\n created_at: string\n tags: Record[]\n metadata: object\n origin: string\n spans: Span[]\n}\n\n// Prompt 类型（示例）\ninterface Prompt {\n id: string | null\n name: string\n metadata?: {\n created_at: string\n }\n}\n```\n\n## 依赖关系\n\n| 依赖包 | 版本/用途 |\n|--------|----------|\n| React | 18.x - UI框架 |\n| @mui/material | Material UI组件库 |\n| @emotion/react | 样式解决方案 |\n| dayjs | 日期时间处理 |\n| zod | 表单验证 |\n| react-hook-form | 表单状态管理 |\n\n## 部署模式\n\n组件库支持两种部署模式，通过 `ui/packages/evidently-ui-lib/README.md` 说明：\n\n1. **Service 模式**：作为后端服务的集成UI组件\n2. **Standalone 模式**：独立运行的Web应用\n\n两种模式共享同一套组件库，确保UI一致性和代码复用。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：evidentlyai/evidently\n\n摘要：发现 19 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Update scikit-learn version requirement to support v1.6.0。\n\n## 1. 安装坑 · 来源证据：Update scikit-learn version requirement to support v1.6.0\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update scikit-learn version requirement to support v1.6.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e82e24d201134e7f8dfa0b564d73fce8 | https://github.com/evidentlyai/evidently/issues/1407 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：PromptOptimizer throws OpenAIError when using Vertex AI judge\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：PromptOptimizer throws OpenAIError when using Vertex AI judge\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abf6f9b183ff4892be78fd198f60d8e8 | https://github.com/evidentlyai/evidently/issues/1856 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 运行坑 · 来源证据：IndexError in infer_column_type when column contains only null values\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：IndexError in infer_column_type when column contains only null values\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_44cdd5f2b657432eb8418fb132959ada | https://github.com/evidentlyai/evidently/issues/1764 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_872f2b57cd3a4c61ad5c387c8be3208b | https://github.com/evidentlyai/evidently/issues/1410 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Numpy 2.x support?\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Numpy 2.x support?\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2fc84415b55a43d2be4f7f47cf46d7a1 | https://github.com/evidentlyai/evidently/issues/1557 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v0.7.12\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.12\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fcf994a3bcf94b0d9b2c5d6159816728 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.12 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v0.7.15\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.15\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a9de117bd8e440beab9f7be4af50d710 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.15 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v0.7.20\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.20\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f0d67058bf2a40218adfb0eea1f1665f | https://github.com/evidentlyai/evidently/releases/tag/v0.7.20 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 9. 能力坑 · 来源证据：v0.7.19\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.7.19\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_52e6ab37edca4901a0aa9fe7b5ba12f1 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.19 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 能力坑 · 来源证据：v0.7.21\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.7.21\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fe9f0e6e29564afeb5610928cc9bc834 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.21 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:315977578 | https://github.com/evidentlyai/evidently | README/documentation is current enough for a first validation pass.\n\n## 12. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | last_activity_observed missing\n\n## 13. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:315977578 | https://github.com/evidentlyai/evidently | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:315977578 | https://github.com/evidentlyai/evidently | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Protect this repo from AI-generated PRs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Protect this repo from AI-generated PRs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cfcf13543c3941e88fd7c5f527f95dc3 | https://github.com/evidentlyai/evidently/issues/1879 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：v0.7.17\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.17\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_305e0831e389460096b4d4b908731b41 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.17 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v0.7.18\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.18\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_19a463a1bb2a4fb2bd5bd894c914cc36 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.18 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：evidentlyai/evidently\n\n摘要：发现 19 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Update scikit-learn version requirement to support v1.6.0。\n\n## 1. 安装坑 · 来源证据：Update scikit-learn version requirement to support v1.6.0\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Update scikit-learn version requirement to support v1.6.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e82e24d201134e7f8dfa0b564d73fce8 | https://github.com/evidentlyai/evidently/issues/1407 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：PromptOptimizer throws OpenAIError when using Vertex AI judge\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：PromptOptimizer throws OpenAIError when using Vertex AI judge\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abf6f9b183ff4892be78fd198f60d8e8 | https://github.com/evidentlyai/evidently/issues/1856 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 运行坑 · 来源证据：IndexError in infer_column_type when column contains only null values\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：IndexError in infer_column_type when column contains only null values\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_44cdd5f2b657432eb8418fb132959ada | https://github.com/evidentlyai/evidently/issues/1764 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Update evidently hashlib usage for FIPS-Compliant Systems and Security Best Practices\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_872f2b57cd3a4c61ad5c387c8be3208b | https://github.com/evidentlyai/evidently/issues/1410 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Numpy 2.x support?\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Numpy 2.x support?\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2fc84415b55a43d2be4f7f47cf46d7a1 | https://github.com/evidentlyai/evidently/issues/1557 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v0.7.12\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.12\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fcf994a3bcf94b0d9b2c5d6159816728 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.12 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v0.7.15\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.15\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a9de117bd8e440beab9f7be4af50d710 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.15 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v0.7.20\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.20\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f0d67058bf2a40218adfb0eea1f1665f | https://github.com/evidentlyai/evidently/releases/tag/v0.7.20 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 9. 能力坑 · 来源证据：v0.7.19\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.7.19\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_52e6ab37edca4901a0aa9fe7b5ba12f1 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.19 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 能力坑 · 来源证据：v0.7.21\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v0.7.21\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fe9f0e6e29564afeb5610928cc9bc834 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.21 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:315977578 | https://github.com/evidentlyai/evidently | README/documentation is current enough for a first validation pass.\n\n## 12. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | last_activity_observed missing\n\n## 13. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:315977578 | https://github.com/evidentlyai/evidently | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:315977578 | https://github.com/evidentlyai/evidently | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Protect this repo from AI-generated PRs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Protect this repo from AI-generated PRs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cfcf13543c3941e88fd7c5f527f95dc3 | https://github.com/evidentlyai/evidently/issues/1879 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：v0.7.17\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.17\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_305e0831e389460096b4d4b908731b41 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.17 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v0.7.18\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.18\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_19a463a1bb2a4fb2bd5bd894c914cc36 | https://github.com/evidentlyai/evidently/releases/tag/v0.7.18 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:315977578 | https://github.com/evidentlyai/evidently | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# evidently - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 evidently 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Evidently is \\u200b\\u200ban open-source ML and LLM observability framework. Evaluate, test, and monitor any AI-powered system or data pipeline. From tabular data to Gen AI. 100+ metrics. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目介绍与安装。围绕“项目介绍与安装”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：指标系统 (Metrics)。围绕“指标系统 (Metrics)”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：预设评估 (Presets)。围绕“预设评估 (Presets)”模拟一次用户任务，不展示安装或运行结果。\n5. page-5：描述符系统 (Descriptors)。围绕“描述符系统 (Descriptors)”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目介绍与安装”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“指标系统 (Metrics)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“预设评估 (Presets)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-5\n输入：用户提供的“描述符系统 (Descriptors)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目介绍与安装”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“指标系统 (Metrics)”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“预设评估 (Presets)”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-5：Step 5 必须围绕“描述符系统 (Descriptors)”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/evidentlyai/evidently\n- https://github.com/evidentlyai/evidently#readme\n- README.md\n- pyproject.toml\n- requirements.min.txt\n- src/evidently/__init__.py\n- src/evidently/core/__init__.py\n- src/evidently/core/base_types.py\n- src/evidently/core/report.py\n- src/evidently/legacy/__init__.py\n- src/evidently/metrics/__init__.py\n- src/evidently/metrics/classification.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 evidently 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：evidentlyai/evidently\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install evidently\n```\n\n来源：https://github.com/evidentlyai/evidently#readme\n\n## 来源\n\n- repo: https://github.com/evidentlyai/evidently\n- docs: https://github.com/evidentlyai/evidently#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_fa1c64f5f5114e2b94febefe6ae8510a"
}