企业官网建设流程全解析

DeepEval Skills：让编码助手按标准工作流为 AI 应用接入评测、数据集与可观测性

【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval

DeepEval 仓库的skills/目录提供了一组「Agent Skills」：教 Claude Code、Cursor 等编码助手如何为你的 LLM 应用、Agent、RAG 管线或多轮聊天机器人添加评测（evals）、生成评测数据集（goldens）、接入 DeepEval 原生 tracing 或裸 OpenTelemetry 导出，并基于评测结果持续迭代。读完本文，你能掌握这三个 Skill 的分工边界、各自的触发条件与前置条件、五种安装方式，以及 Skill 内置的评测模板、CLI 命令与迭代守则背后的源码实现，从而让 Agent 在你项目中产出一套「可复跑、可追溯、可上报 Confident AI」的 pytest 评测套件，而不是一次性脚本。

1. 仓库内 skills/ 目录的组成

skills/下并列放置了三个独立的 Skill，外加一份总览文档 skills/README.md：

每个 Skill 都是标准 Agent Skill 结构：一个带 YAML frontmatter 的SKILL.md（声明name、description、license、metadata），加上一组references/参考文档与templates/代码模板。例如主 Skill 的 frontmatter 声明了：

• description中写明TRIGGER / DO NOT TRIGGER条件——用户想评测 Agent、RAG、多轮聊天机器人、生成 goldens、运行deepeval test run、把结果发到 Confident AI 时触发；而「插桩 tracing」应转给deepeval-tracing、「裸 OTel 导出」应转给deepeval-otel，避免三个 Skill 互相抢活；
• metadata.compatibility写明运行前提：Python 3.9+、目标项目中pip install deepeval、指标计算与数据合成需要模型凭证、上报 Confident AI 需要deepeval login。

三个 Skill 的description都采用了「触发词清单 + 反向排除清单」的写法，这是 Agent Skill 路由的关键：从三份 SKILL.md 的结构看，作者把「何时该用我、何时该转手」写进了元数据本身，而不是留给模型猜测。

2. deepeval 主 Skill：一个可复跑的评测闭环

2.1 工作流七步与核心原则

skills/deepeval/SKILL.md 定义了完整工作流：

1. 检查目标应用与已有的 DeepEval 用法；
2. 询问必需的 intake 问题；
3. 有则复用已有的指标、数据集与模型配置；
4. 用户有数据集就复用，否则用deepeval generate生成 goldens；
5. 使用带 trace 评测时，用deepeval-tracingSkill 完成插桩；
6. 运行deepeval test run；
7. 按用户要求的轮数迭代（默认 5 轮）。

配套的核心原则值得逐条看，因为它们是「让 Agent 写出工程化评测代码」的约束来源：

1. 优先产出最小的、提交进仓库的pytest 评测套件，用户无需 Agent 也能复跑；不要把 goldens 和测试藏在一次性脚本里；
2. 引入新指标前先复用项目已有的指标、阈值、数据集与模型配置；
3. 应用可以插桩时，优先使用带 trace 的单轮评测；
4. 数据集生成用deepeval generate，评测执行用deepeval test run，不要默认退回裸pytest命令；
5. 指标实例统一放在独立的metrics.py模块；
6. 用户提到 traces、生产监控、online evals、dashboard、共享报告时，强烈建议启用 tracing 与 Confident AI；
7. 有意识地迭代：跑评测、看失败与 trace、做针对性修改、再跑。

2.2 用例判定与 intake 问题

主 Skill 要求 Agent 先按「chatbot / 多轮 agent > agent > RAG」的优先级给应用定一个顶层用例类型：RAG 加 agentic 行为按 agent 处理；chatbot 叠加 agent 或 RAG 行为按 chatbot / 多轮 agent 处理。分类细则放在 skills/deepeval/references/choose-use-case.md。

编辑应用代码之前必须完成 intake 询问（见 skills/deepeval/references/intake.md），共五个问题及选项：

1. 评测模型：复用已有 DeepEval 配置 / OpenAI / Anthropic / Gemini / 本地或自定义模型 / 由用户提供；
2. 数据集来源：已在工作区 / 需要拖入工作区 / 在 Confident AI 上 / 没有，请生成；
3. 是否加 tracing：Skill 明确推荐「是」，理由是 trace 让失败可检查、能定位断在哪一步、显著加快每轮迭代；
4. 是否上报 Confident AI：Skill 原文说明它免费，提供 hosted 报告、trace、运行历史、dashboard、生产监控与 online evals；
5. 迭代轮数：推荐 5 轮，可选 1 轮 / 3 轮 / 自定义。

intake 文档还规定了数据集分支处理：工作区已有数据集时优先寻找tests/evals/.dataset.json、.dataset.json、dataset.json、.jsonl、.csv；Confident AI 上的数据集应通过其 MCP/API 拉取或导出为本地 goldens 文件；没有数据集时只能用deepeval generate生成，禁止手写或编造 goldens。文档给出量化经验：少于 10 条 goldens 大概率太小，建议扩充；第一批有代表性的生成数据集约30–50 条；生成方法按「docs / 知识库 → 导出的 retrieval contexts → 已有 goldens 扩充 → scratch」的优先级选择，且无论哪种方法都默认按应用用例传入风格化参数；chatbot / 多轮 agent 场景默认生成多轮会话型 goldens。

2.3 评测模板：从仓库直接可复制的代码

主 Skill 的 templates/ 目录提供四份模板，覆盖三种测试形态。

共享指标模块skills/deepeval/templates/metrics.py：

from deepeval.metrics import ( AnswerRelevancyMetric, ContextualRelevancyMetric, StepEfficiencyMetric, TaskCompletionMetric, ) # Keep metrics in one module so eval files stay focused on app execution. # Reuse existing project metrics and thresholds before adding new ones. SINGLE_TURN_TRACE_METRICS = [ TaskCompletionMetric(), StepEfficiencyMetric(), ] SINGLE_TURN_NO_TRACING_METRICS = [ AnswerRelevancyMetric(), ] MULTI_TURN_METRICS = [] # Component-level metrics are span-specific. ... RETRIEVER_SPAN_METRICS = [ ContextualRelevancyMetric(), ] GENERATOR_LLM_SPAN_METRICS = [ AnswerRelevancyMetric(), ]

注意组件级指标的约定：不要为整个应用建一个共享的COMPONENT_METRICS，而是按具体组件/ span 命名（RETRIEVER_SPAN_METRICS、GENERATOR_LLM_SPAN_METRICS、TOOL_SPAN_METRICS、PLANNER_AGENT_SPAN_METRICS），再分别挂到对应 span 上。模板注释给出的挂载方式有二：集成支持的next_agent_span / next_llm_span / next_tool_span / next_retriever_span，或在集成/手动插桩直接创建组件 span 时使用@observe(metrics=[...])。

单轮带 trace 评测skills/deepeval/templates/test_single_turn_tracing.py：

from importlib import import_module import pytest from deepeval import assert_test from deepeval.dataset import EvaluationDataset, Golden from metrics import SINGLE_TURN_TRACE_METRICS ai_app = import_module("ai_app") dataset = EvaluationDataset() dataset.add_goldens_from_json_file(file_path="tests/evals/.dataset.json") @pytest.mark.parametrize("golden", dataset.goldens) def test_single_turn_tracing(golden: Golden): ai_app.run_traced_ai_app(golden.input) assert_test(golden=golden, metrics=SINGLE_TURN_TRACE_METRICS)

形态要点：测试函数里只干两件事——用Golden.input触发已插桩的应用，然后assert_test(golden=golden, metrics=[...])。SKILL.md 明确禁止把带 trace 的单轮评测改写成手工拼LLMTestCase，因为 trace 形态下指标应从 span 结构取数。

单轮无 trace 评测skills/deepeval/templates/test_single_turn_no_tracing.py 只在用户明确拒绝 tracing 或没有任何可行插桩路径时使用，此时手工构造LLMTestCase：

@pytest.mark.parametrize("golden", dataset.goldens) def test_single_turn_no_tracing(golden: Golden): actual_output = ai_app.run_ai_app(golden.input) test_case = LLMTestCase( input=golden.input, actual_output=actual_output, expected_output=getattr(golden, "expected_output", None), context=getattr(golden, "context", None), retrieval_context=getattr(golden, "retrieval_context", None), ) assert_test(test_case=test_case, metrics=SINGLE_TURN_NO_TRACING_METRICS)

多轮端到端评测skills/deepeval/templates/test_multi_turn_e2e.py 用ConversationSimulator模拟用户与 chatbot 对话，把模拟出的会话参数化为 pytest 用例：

simulator = ConversationSimulator(model_callback=ai_app.chatbot_callback) dataset = EvaluationDataset() dataset.add_goldens_from_json_file(file_path="tests/evals/.dataset.json") @pytest.mark.parametrize( "test_case", simulator.simulate( conversational_goldens=dataset.goldens, max_user_simulations=MAX_TURNS, # 模板中为 10 ), ) def test_multi_turn(test_case): assert_test(test_case=test_case, metrics=MULTI_TURN_METRICS)

2.4 运行命令与deepeval test run的参数细节

SKILL.md「Common Commands」一节给出三条核心命令：

# 1) 无现成数据集时，从文档自举单轮 goldens deepeval generate --method docs --variation single-turn \ --documents ./docs --output-dir ./tests/evals --file-name .dataset # 2) 运行评测套件 deepeval test run tests/evals/test_<app>.py \ --num-processes 5 --identifier "iterating-on-<purpose>-round-1" # 3) 开启 Confident AI 时打开最新 hosted 报告 deepeval view

这些参数在仓库 CLI 源码中有对应实现，可以对照确认取值与含义（见 deepeval/cli/test/command.py）：

命令实现上deepeval test run基于 typer 包装 pytest，并开启了allow_extra_args与ignore_unknown_options（deepeval/cli/test/command.py），意味着额外透传的 pytest 参数也能生效——这解释了为什么 Skill 强调用它而非裸pytest：既拿到评测框架的结果聚合与上报能力，又不丢失 pytest 原生选项。

2.5 迭代循环与护栏

skills/deepeval/references/iteration-loop.md 规定每一轮的动作：跑deepeval test run（带--identifier "iterating-on-<purpose>-round-N"，<purpose>取retrieval、tool-use、prompting、conversation-flow等当前迭代焦点）→ 读失败与分数 → 有 trace 时检查失败用例的 trace → 找最小可能的应用改动 → 改 prompt、检索、工具说明、解析或应用逻辑 → 重跑 → 总结变化与分数是否改善。

同样重要的是它的Guardrails（Agent 迭代时的红线）：

• 不允许为讨好当前生成的例子而做让应用整体更不正确的改动；
• 不允许单纯降阈值让失败消失，除非指标确实失准且用户同意；
• 不允许无理由删除困难 goldens；
• 不允许擅自更换框架或模型供应商（例如 OpenAI 换 LiteLLM/Anthropic/Gemini）；同一供应商内换模型名（文档举例 OpenAIgpt-5.4→gpt-5.5）在评测失败或用户目标支持时是允许的。

当失败原因在输出中解释不清时，Skill 要求先补最小必要的 trace 上下文再改应用——推荐补充的上下文包括检索到的文档 ID、工具名与输入输出、planner 步骤或选中路由、prompt 版本与变量、解析器输入输出；并再次强调不 trace 密钥与敏感原始数据。若多轮迭代后分数不动，Skill 给出明确话术与动作：把测试报告存到 Confident AI，对 pass/fail 结果做人工标注，估算假阳/假阴率，判断指标是否与人判断脱节或阈值失准。

3. deepeval-tracing Skill：DeepEval SDK 插桩

skills/deepeval-tracing/SKILL.md 的职责边界一句话：只负责产出结构良好的 trace，不跑评测——挂指标、跑 eval 是deepevalSkill 的事，裸 OTel 导出是deepeval-otelSkill 的事。

其工作流为：确认目标是 AI 应用（有 LLM 调用、agent 循环、检索或工具调用；否则此 Skill 不适用）→ 检测框架、模型供应商、agent SDK 与向量库 → 查 references/integrations.md 选择原生集成（SKILL.md 的触发描述点名了 LangGraph、LangChain、OpenAI Agents、LlamaIndex、Pydantic AI、CrewAI 等）→ 无合适集成则回退到手动@observe（详见 references/tracing.md）→ 给每个 span 有意义的type（llm/retriever/tool/agent）并捕获输入输出 → 加 trace 级 tags 与 metadata → 用deepeval login或导出的CONFIDENT_API_KEY（CI 与非交互场景优先后者）验证 trace 出现在 Confident AI Observatory。

核心原则包括：只插桩 AI 组件；原生集成优先、手动@observe是回退手段；写插桩代码前先读对应集成文档；span 名默认取函数名，除非有强理由覆盖；绝不 trace 密钥、凭证或敏感用户原始数据。

4. deepeval-otel Skill：不装 deepeval，用裸 OTel 导出到 Confident AI

skills/deepeval-otel/SKILL.md 面向语言无关的场景：Confident AI 暴露一个OTLP/HTTP traces endpoint，任何 OTLP 能力齐全的 OpenTelemetry SDK 只要把 exporter 指过去、带x-confident-api-key请求头，Confident AI 侧就会读取每个 span 上的confident.*属性来重建 trace/span 结构；父子嵌套来自原生 OTel span context，与属性无关。

关键约束（SKILL.md 反复强调）：

• 只做 OTLP/HTTP，endpoint 不接受 gRPC；
• confident.*属性键就是完整契约，所有语言一致；
• 只插桩 AI 组件（agent / LLM / retriever / tool），不要把confident.*用到 Web 服务、CRUD 后端、DB 层等 span 上；
• 若进程里还有别的 OpenTelemetry 插桩或 APM agent（Datadog、HTTP/DB 自动插桩等），要用独立 pipeline 或 span filter 隔离，保证只有 AI span 被导出；
• 已有 exporter 优先「改指向」而不是加一条并行管线；
• 数据类型规则：属性值必须是基本类型或同构基本类型列表；dict/metadata 必须JSON 编码成字符串（OTLP 没有 map 类型）；字符串列表用原生 OTLP 数组；
• confident.span.type已知时显式设置，只在回退时依赖gen_ai.*语义约定推断（见 references/gen-ai-fallbacks.md）。

属性契约细节分别放在 references/span-attributes.md（span 级confident.span.*与数据类型规则）、references/trace-attributes.md（trace 级confident.trace.*）和 references/endpoint-and-exporter.md（endpoint、区域选择、鉴权、exporter 接线与「只导出 AI span」的隔离方案）。

最小可运行模板 skills/deepeval-otel/templates/confident_otel_setup.py 演示了完整接线，依赖opentelemetry-sdk与opentelemetry-exporter-otlp-proto-http：

def pick_endpoint(api_key: str) -> str: """按 API key 区域前缀选择 Confident AI OTLP endpoint。 仅 confident_eu_... 走 EU endpoint，其余走默认。""" if api_key.startswith("confident_eu_"): return "https://eu.otel.confident-ai.com" return "https://otel.confident-ai.com" def configure_tracing() -> trace.Tracer: api_key = os.environ.get("CONFIDENT_API_KEY") endpoint = pick_endpoint(api_key) provider = TracerProvider() provider.add_span_processor( BatchSpanProcessor( OTLPSpanExporter( # endpoint 必须带 /v1/traces 后缀；仅接受 OTLP/HTTP，不接受 gRPC endpoint=f"{endpoint}/v1/traces", headers={"x-confident-api-key": api_key}, ) ) ) trace.set_tracer_provider(provider) return trace.get_tracer(__name__)

模板随后发出一个「agent 根 span 包 llm 子 span」的示例 trace，展示了属性用法：根 span 设confident.span.type=agent、confident.agent.name、confident.span.input；trace 级confident.trace.name/input/output、confident.trace.tags（原生数组）、confident.trace.metadata（json.dumps编码）；子 LLM span 设confident.llm.model、confident.llm.input_token_count/output_token_count、confident.span.metadata；异常时走原生 OTelStatus(StatusCode.ERROR)与record_exception，而不是confident.*属性。进程退出前调用trace.get_tracer_provider().shutdown()让 BatchSpanProcessor 把缓冲区刷完。

5. 安装方式：五种途径

skills/README.md 给出五种安装途径，本文按其顺序完整说明：

5.1 Claude.ai（Web）

1. 从本仓库下载skills/deepeval文件夹；
2. 压缩为 zip；
3. 在 Claude.ai 中进入Settings > Capabilities > Skills；
4. 点击Upload skill，选择 zip 包上传。

5.2 Claude Code（本地 CLI）

把skills/deepeval文件夹下载或克隆后，放进本地项目的 skills 目录：

mkdir -p .claude/skills/ cp -r path/to/downloaded/deepeval .claude/skills/

5.3 Cursor 插件

README 说明本仓库自带指向./skills/的 Cursor 插件清单，以插件安装后 Cursor 可直接发现deepevalskill。仓库里确实存在该清单 ​.cursor-plugin/plugin.json，其中"skills": "./skills/"字段即声明 Skill 目录位置；仓库同时带有 ​.claude-plugin/plugin.json（字段一致），说明同一套skills/目录被 Claude Code 与 Cursor 两份插件清单共同引用。

5.4 skills CLI

使用 skills 兼容的命令行安装器：

npx skills add confident-ai/deepeval --skill "deepeval"

5.5 手动拷贝

直接把skills/deepeval拷贝或软链（symlink）到你所用 agent 的 skills 目录即可——三个子 Skill 目录都是自包含的（SKILL.md+references/+templates/），任何支持 SKILL.md 约定的工具都能消费。

6. 前置条件

skills/README.md 的 Prerequisites 一节区分了本地评测与托管能力两层：

# 本地评测：在目标项目中安装 DeepEval pip install -U deepeval

# 托管报告、traces、生产监控或 online evals：连接 Confident AI deepeval login

结合三个 SKILL.md 的compatibility元数据，完整前提可以归纳为：

• deepeval主 Skill：Python 3.9+，目标项目pip install deepeval；指标计算与数据合成需要模型凭证；Confident AI 上报、hosted traces、online evals 需要deepeval login；
• deepeval-tracing：Python 项目pip install deepeval；trace 到达 Confident AI 需要deepeval login，或导出CONFIDENT_API_KEY（CI 与非交互场景推荐）；
• deepeval-otel：任意语言的 OTel SDK（Python 示例假设opentelemetry-sdk与opentelemetry-exporter-otlp-proto-http）+ Confident AI 账号与CONFIDENT_API_KEY；endpoint 仅 HTTP。

7. 三个 Skill 的路由纪律（何时选谁）

三个 SKILL.md 的description互相引用，形成明确的路由表：

这种「Skill 即文档、文档即契约」的组织方式，使得同一仓库既是 DeepEval 框架本体，也是面向编码助手的可安装知识包：Agent 读取SKILL.md获得工作流与红线，读取references/获得分支细节（intake、用例选择、数据集、合成数据、指标、pytest E2E、带 trace 评测、Confident AI、产物契约、迭代循环），读取templates/获得可直接替换占位符运行的起点代码。

8. 小结

• skills/是 DeepEval 仓库内面向编码助手的三个自包含 Agent Skill：deepeval（评测闭环）、deepeval-tracing（SDK 插桩）、deepeval-otel（裸 OTLP 导出），边界由各自 SKILL.md 的 TRIGGER/DO-NOT-TRIGGER 描述精确切分；
• 主 Skill 产出的评测套件遵循固定形态：metrics.py独立指标模块 + 单轮 trace / 单轮无 trace / 多轮 E2E 三类 pytest 模板 +deepeval generate生成 30–50 条 goldens +deepeval test run带--identifier迭代（参数与 deepeval/cli/test/command.py 源码一致）；
• OTel Skill 的完整契约是：OTLP/HTTP-only endpoint（按 key 前缀区分 US/EU，必须带/v1/traces后缀）、x-confident-api-key头、confident.span.*/confident.trace.*属性、dict 必须 JSON 编码、只导出 AI span；
• 所有能力的前置条件只有两层：pip install -U deepeval（本地评测）与deepeval login/CONFIDENT_API_KEY（Confident AI 托管能力）。

【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval