DeepEval Skills让编码助手按标准工作流为 AI 应用接入评测、数据集与可观测性【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepevalDeepEval 仓库的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.mdSkill定位来自各 SKILL.md 的 frontmatter分类deepeval为 AI 应用添加端到端评测闭环接入应用、复用或生成数据集、提交可复跑的 pytest 评测套件、运行评测、迭代修复失败用例。覆盖 Python SDK、pytest 评测、CLI 生成、带 trace 的评测、Confident AI 上报与 Agent 驱动的改进循环llm-evaluationdeepeval-otel不依赖deepeval包用裸 OpenTelemetryOTLP/HTTP将任意语言的 AI 应用 trace 导出到 Confident AI Observatory核心是confident.*属性契约与 OTLP endpoint 配置observabilitydeepeval-tracing用 DeepEval 原生 tracingobserve、框架/模型/向量库集成给 AI 应用插桩让执行过程以 span 粒度在 Confident AI 可见observability每个 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 定义了完整工作流检查目标应用与已有的 DeepEval 用法询问必需的 intake 问题有则复用已有的指标、数据集与模型配置用户有数据集就复用否则用deepeval generate生成 goldens使用带 trace 评测时用deepeval-tracingSkill 完成插桩运行deepeval test run按用户要求的轮数迭代默认 5 轮。配套的核心原则值得逐条看因为它们是「让 Agent 写出工程化评测代码」的约束来源优先产出最小的、提交进仓库的pytest 评测套件用户无需 Agent 也能复跑不要把 goldens 和测试藏在一次性脚本里引入新指标前先复用项目已有的指标、阈值、数据集与模型配置应用可以插桩时优先使用带 trace 的单轮评测数据集生成用deepeval generate评测执行用deepeval test run不要默认退回裸pytest命令指标实例统一放在独立的metrics.py模块用户提到 traces、生产监控、online evals、dashboard、共享报告时强烈建议启用 tracing 与 Confident AI有意识地迭代跑评测、看失败与 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共五个问题及选项评测模型复用已有 DeepEval 配置 / OpenAI / Anthropic / Gemini / 本地或自定义模型 / 由用户提供数据集来源已在工作区 / 需要拖入工作区 / 在 Confident AI 上 / 没有请生成是否加 tracingSkill 明确推荐「是」理由是 trace 让失败可检查、能定位断在哪一步、显著加快每轮迭代是否上报 Confident AISkill 原文说明它免费提供 hosted 报告、trace、运行历史、dashboard、生产监控与 online evals迭代轮数推荐 5 轮可选 1 轮 / 3 轮 / 自定义。intake 文档还规定了数据集分支处理工作区已有数据集时优先寻找tests/evals/.dataset.json、.dataset.json、dataset.json、.jsonl、.csvConfident 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.pyfrom 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.pyfrom 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_pathtests/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(goldengolden, metricsSINGLE_TURN_TRACE_METRICS)形态要点测试函数里只干两件事——用Golden.input触发已插桩的应用然后assert_test(goldengolden, metrics[...])。SKILL.md 明确禁止把带 trace 的单轮评测改写成手工拼LLMTestCase因为 trace 形态下指标应从 span 结构取数。单轮无 trace 评测skills/deepeval/templates/test_single_turn_no_tracing.py 只在用户明确拒绝 tracing 或没有任何可行插桩路径时使用此时手工构造LLMTestCasepytest.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( inputgolden.input, actual_outputactual_output, expected_outputgetattr(golden, expected_output, None), contextgetattr(golden, context, None), retrieval_contextgetattr(golden, retrieval_context, None), ) assert_test(test_casetest_case, metricsSINGLE_TURN_NO_TRACING_METRICS)多轮端到端评测skills/deepeval/templates/test_multi_turn_e2e.py 用ConversationSimulator模拟用户与 chatbot 对话把模拟出的会话参数化为 pytest 用例simulator ConversationSimulator(model_callbackai_app.chatbot_callback) dataset EvaluationDataset() dataset.add_goldens_from_json_file(file_pathtests/evals/.dataset.json) pytest.mark.parametrize( test_case, simulator.simulate( conversational_goldensdataset.goldens, max_user_simulationsMAX_TURNS, # 模板中为 10 ), ) def test_multi_turn(test_case): assert_test(test_casetest_case, metricsMULTI_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选项短选项默认源码 help--identifier-idNone为该次 test run 打标识便于在 Confident AI 区分迭代轮次--num-processes-nNonepytest 并发进程数Skill 建议非小数据集时取 5受限机器上可省略--ignore-errors-iFalse是否忽略执行错误继续跑--skip-on-missing-params-sFalse参数缺失的用例直接跳过--display-dall结束时展示全部用例还是部分--exit-on-first-failure-xFalse首个失败即退出--official-oFalse将该次运行标记为 Confident AI 上的官方基线命令实现上deepeval test run基于 typer 包装 pytest并开启了allow_extra_args与ignore_unknown_optionsdeepeval/cli/test/command.py意味着额外透传的 pytest 参数也能生效——这解释了为什么 Skill 强调用它而非裸pytest既拿到评测框架的结果聚合与上报能力又不丢失 pytest 原生选项。2.5 迭代循环与护栏skills/deepeval/references/iteration-loop.md 规定每一轮的动作跑deepeval test run带--identifier iterating-on-purpose-round-Npurpose取retrieval、tool-use、prompting、conversation-flow等当前迭代焦点→ 读失败与分数 → 有 trace 时检查失败用例的 trace → 找最小可能的应用改动 → 改 prompt、检索、工具说明、解析或应用逻辑 → 重跑 → 总结变化与分数是否改善。同样重要的是它的GuardrailsAgent 迭代时的红线不允许为讨好当前生成的例子而做让应用整体更不正确的改动不允许单纯降阈值让失败消失除非指标确实失准且用户同意不允许无理由删除困难 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 SkillDeepEval 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 有意义的typellm/retriever/tool/agent并捕获输入输出 → 加 trace 级 tags 与 metadata → 用deepeval login或导出的CONFIDENT_API_KEYCI 与非交互场景优先后者验证 trace 出现在 Confident AI Observatory。核心原则包括只插桩 AI 组件原生集成优先、手动observe是回退手段写插桩代码前先读对应集成文档span 名默认取函数名除非有强理由覆盖绝不 trace 密钥、凭证或敏感用户原始数据。4. deepeval-otel Skill不装 deepeval用裸 OTel 导出到 Confident AIskills/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/HTTPendpoint 不接受 gRPCconfident.*属性键就是完整契约所有语言一致只插桩 AI 组件agent / LLM / retriever / tool不要把confident.*用到 Web 服务、CRUD 后端、DB 层等 span 上若进程里还有别的 OpenTelemetry 插桩或 APM agentDatadog、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.mdspan 级confident.span.*与数据类型规则、references/trace-attributes.mdtrace 级confident.trace.*和 references/endpoint-and-exporter.mdendpoint、区域选择、鉴权、exporter 接线与「只导出 AI span」的隔离方案。最小可运行模板 skills/deepeval-otel/templates/confident_otel_setup.py 演示了完整接线依赖opentelemetry-sdk与opentelemetry-exporter-otlp-proto-httpdef 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 endpointf{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.typeagent、confident.agent.name、confident.span.inputtrace 级confident.trace.name/input/output、confident.trace.tags原生数组、confident.trace.metadatajson.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.aiWeb从本仓库下载skills/deepeval文件夹压缩为 zip在 Claude.ai 中进入Settings Capabilities Skills点击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 deepeval5.5 手动拷贝直接把skills/deepeval拷贝或软链symlink到你所用 agent 的 skills 目录即可——三个子 Skill 目录都是自包含的SKILL.mdreferences/templates/任何支持 SKILL.md 约定的工具都能消费。6. 前置条件skills/README.md 的 Prerequisites 一节区分了本地评测与托管能力两层# 本地评测在目标项目中安装 DeepEval pip install -U deepeval# 托管报告、traces、生产监控或 online evals连接 Confident AI deepeval login结合三个 SKILL.md 的compatibility元数据完整前提可以归纳为deepeval主 SkillPython 3.9目标项目pip install deepeval指标计算与数据合成需要模型凭证Confident AI 上报、hosted traces、online evals 需要deepeval logindeepeval-tracingPython 项目pip install deepevaltrace 到达 Confident AI 需要deepeval login或导出CONFIDENT_API_KEYCI 与非交互场景推荐deepeval-otel任意语言的 OTel SDKPython 示例假设opentelemetry-sdk与opentelemetry-exporter-otlp-proto-http Confident AI 账号与CONFIDENT_API_KEYendpoint 仅 HTTP。7. 三个 Skill 的路由纪律何时选谁三个 SKILL.md 的description互相引用形成明确的路由表你的需求用哪个 Skill建 pytest 评测套件、生成数据集/goldens、写指标、deepeval test run、迭代deepevalPython 应用、想用 DeepEval SDKobserve、框架集成产 tracedeepeval-tracing裸 OpenTelemetry / OTLP 导出或应用不是 Pythondeepeval-otel三者都不是非 AI 软件Web 服务、CRUD、基础设施一律不适用——confident.*属性与 span 类型只为 AI 组件设计这种「Skill 即文档、文档即契约」的组织方式使得同一仓库既是 DeepEval 框架本体也是面向编码助手的可安装知识包Agent 读取SKILL.md获得工作流与红线读取references/获得分支细节intake、用例选择、数据集、合成数据、指标、pytest E2E、带 trace 评测、Confident AI、产物契约、迭代循环读取templates/获得可直接替换占位符运行的起点代码。8. 小结skills/是 DeepEval 仓库内面向编码助手的三个自包含 Agent Skilldeepeval评测闭环、deepeval-tracingSDK 插桩、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_KEYConfident AI 托管能力。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DeepEval Skills：让编码助手按标准工作流为 AI 应用接入评测、数据集与可观测性
DeepEval Skills让编码助手按标准工作流为 AI 应用接入评测、数据集与可观测性【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepevalDeepEval 仓库的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.mdSkill定位来自各 SKILL.md 的 frontmatter分类deepeval为 AI 应用添加端到端评测闭环接入应用、复用或生成数据集、提交可复跑的 pytest 评测套件、运行评测、迭代修复失败用例。覆盖 Python SDK、pytest 评测、CLI 生成、带 trace 的评测、Confident AI 上报与 Agent 驱动的改进循环llm-evaluationdeepeval-otel不依赖deepeval包用裸 OpenTelemetryOTLP/HTTP将任意语言的 AI 应用 trace 导出到 Confident AI Observatory核心是confident.*属性契约与 OTLP endpoint 配置observabilitydeepeval-tracing用 DeepEval 原生 tracingobserve、框架/模型/向量库集成给 AI 应用插桩让执行过程以 span 粒度在 Confident AI 可见observability每个 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 定义了完整工作流检查目标应用与已有的 DeepEval 用法询问必需的 intake 问题有则复用已有的指标、数据集与模型配置用户有数据集就复用否则用deepeval generate生成 goldens使用带 trace 评测时用deepeval-tracingSkill 完成插桩运行deepeval test run按用户要求的轮数迭代默认 5 轮。配套的核心原则值得逐条看因为它们是「让 Agent 写出工程化评测代码」的约束来源优先产出最小的、提交进仓库的pytest 评测套件用户无需 Agent 也能复跑不要把 goldens 和测试藏在一次性脚本里引入新指标前先复用项目已有的指标、阈值、数据集与模型配置应用可以插桩时优先使用带 trace 的单轮评测数据集生成用deepeval generate评测执行用deepeval test run不要默认退回裸pytest命令指标实例统一放在独立的metrics.py模块用户提到 traces、生产监控、online evals、dashboard、共享报告时强烈建议启用 tracing 与 Confident AI有意识地迭代跑评测、看失败与 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共五个问题及选项评测模型复用已有 DeepEval 配置 / OpenAI / Anthropic / Gemini / 本地或自定义模型 / 由用户提供数据集来源已在工作区 / 需要拖入工作区 / 在 Confident AI 上 / 没有请生成是否加 tracingSkill 明确推荐「是」理由是 trace 让失败可检查、能定位断在哪一步、显著加快每轮迭代是否上报 Confident AISkill 原文说明它免费提供 hosted 报告、trace、运行历史、dashboard、生产监控与 online evals迭代轮数推荐 5 轮可选 1 轮 / 3 轮 / 自定义。intake 文档还规定了数据集分支处理工作区已有数据集时优先寻找tests/evals/.dataset.json、.dataset.json、dataset.json、.jsonl、.csvConfident 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.pyfrom 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.pyfrom 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_pathtests/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(goldengolden, metricsSINGLE_TURN_TRACE_METRICS)形态要点测试函数里只干两件事——用Golden.input触发已插桩的应用然后assert_test(goldengolden, metrics[...])。SKILL.md 明确禁止把带 trace 的单轮评测改写成手工拼LLMTestCase因为 trace 形态下指标应从 span 结构取数。单轮无 trace 评测skills/deepeval/templates/test_single_turn_no_tracing.py 只在用户明确拒绝 tracing 或没有任何可行插桩路径时使用此时手工构造LLMTestCasepytest.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( inputgolden.input, actual_outputactual_output, expected_outputgetattr(golden, expected_output, None), contextgetattr(golden, context, None), retrieval_contextgetattr(golden, retrieval_context, None), ) assert_test(test_casetest_case, metricsSINGLE_TURN_NO_TRACING_METRICS)多轮端到端评测skills/deepeval/templates/test_multi_turn_e2e.py 用ConversationSimulator模拟用户与 chatbot 对话把模拟出的会话参数化为 pytest 用例simulator ConversationSimulator(model_callbackai_app.chatbot_callback) dataset EvaluationDataset() dataset.add_goldens_from_json_file(file_pathtests/evals/.dataset.json) pytest.mark.parametrize( test_case, simulator.simulate( conversational_goldensdataset.goldens, max_user_simulationsMAX_TURNS, # 模板中为 10 ), ) def test_multi_turn(test_case): assert_test(test_casetest_case, metricsMULTI_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选项短选项默认源码 help--identifier-idNone为该次 test run 打标识便于在 Confident AI 区分迭代轮次--num-processes-nNonepytest 并发进程数Skill 建议非小数据集时取 5受限机器上可省略--ignore-errors-iFalse是否忽略执行错误继续跑--skip-on-missing-params-sFalse参数缺失的用例直接跳过--display-dall结束时展示全部用例还是部分--exit-on-first-failure-xFalse首个失败即退出--official-oFalse将该次运行标记为 Confident AI 上的官方基线命令实现上deepeval test run基于 typer 包装 pytest并开启了allow_extra_args与ignore_unknown_optionsdeepeval/cli/test/command.py意味着额外透传的 pytest 参数也能生效——这解释了为什么 Skill 强调用它而非裸pytest既拿到评测框架的结果聚合与上报能力又不丢失 pytest 原生选项。2.5 迭代循环与护栏skills/deepeval/references/iteration-loop.md 规定每一轮的动作跑deepeval test run带--identifier iterating-on-purpose-round-Npurpose取retrieval、tool-use、prompting、conversation-flow等当前迭代焦点→ 读失败与分数 → 有 trace 时检查失败用例的 trace → 找最小可能的应用改动 → 改 prompt、检索、工具说明、解析或应用逻辑 → 重跑 → 总结变化与分数是否改善。同样重要的是它的GuardrailsAgent 迭代时的红线不允许为讨好当前生成的例子而做让应用整体更不正确的改动不允许单纯降阈值让失败消失除非指标确实失准且用户同意不允许无理由删除困难 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 SkillDeepEval 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 有意义的typellm/retriever/tool/agent并捕获输入输出 → 加 trace 级 tags 与 metadata → 用deepeval login或导出的CONFIDENT_API_KEYCI 与非交互场景优先后者验证 trace 出现在 Confident AI Observatory。核心原则包括只插桩 AI 组件原生集成优先、手动observe是回退手段写插桩代码前先读对应集成文档span 名默认取函数名除非有强理由覆盖绝不 trace 密钥、凭证或敏感用户原始数据。4. deepeval-otel Skill不装 deepeval用裸 OTel 导出到 Confident AIskills/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/HTTPendpoint 不接受 gRPCconfident.*属性键就是完整契约所有语言一致只插桩 AI 组件agent / LLM / retriever / tool不要把confident.*用到 Web 服务、CRUD 后端、DB 层等 span 上若进程里还有别的 OpenTelemetry 插桩或 APM agentDatadog、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.mdspan 级confident.span.*与数据类型规则、references/trace-attributes.mdtrace 级confident.trace.*和 references/endpoint-and-exporter.mdendpoint、区域选择、鉴权、exporter 接线与「只导出 AI span」的隔离方案。最小可运行模板 skills/deepeval-otel/templates/confident_otel_setup.py 演示了完整接线依赖opentelemetry-sdk与opentelemetry-exporter-otlp-proto-httpdef 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 endpointf{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.typeagent、confident.agent.name、confident.span.inputtrace 级confident.trace.name/input/output、confident.trace.tags原生数组、confident.trace.metadatajson.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.aiWeb从本仓库下载skills/deepeval文件夹压缩为 zip在 Claude.ai 中进入Settings Capabilities Skills点击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 deepeval5.5 手动拷贝直接把skills/deepeval拷贝或软链symlink到你所用 agent 的 skills 目录即可——三个子 Skill 目录都是自包含的SKILL.mdreferences/templates/任何支持 SKILL.md 约定的工具都能消费。6. 前置条件skills/README.md 的 Prerequisites 一节区分了本地评测与托管能力两层# 本地评测在目标项目中安装 DeepEval pip install -U deepeval# 托管报告、traces、生产监控或 online evals连接 Confident AI deepeval login结合三个 SKILL.md 的compatibility元数据完整前提可以归纳为deepeval主 SkillPython 3.9目标项目pip install deepeval指标计算与数据合成需要模型凭证Confident AI 上报、hosted traces、online evals 需要deepeval logindeepeval-tracingPython 项目pip install deepevaltrace 到达 Confident AI 需要deepeval login或导出CONFIDENT_API_KEYCI 与非交互场景推荐deepeval-otel任意语言的 OTel SDKPython 示例假设opentelemetry-sdk与opentelemetry-exporter-otlp-proto-http Confident AI 账号与CONFIDENT_API_KEYendpoint 仅 HTTP。7. 三个 Skill 的路由纪律何时选谁三个 SKILL.md 的description互相引用形成明确的路由表你的需求用哪个 Skill建 pytest 评测套件、生成数据集/goldens、写指标、deepeval test run、迭代deepevalPython 应用、想用 DeepEval SDKobserve、框架集成产 tracedeepeval-tracing裸 OpenTelemetry / OTLP 导出或应用不是 Pythondeepeval-otel三者都不是非 AI 软件Web 服务、CRUD、基础设施一律不适用——confident.*属性与 span 类型只为 AI 组件设计这种「Skill 即文档、文档即契约」的组织方式使得同一仓库既是 DeepEval 框架本体也是面向编码助手的可安装知识包Agent 读取SKILL.md获得工作流与红线读取references/获得分支细节intake、用例选择、数据集、合成数据、指标、pytest E2E、带 trace 评测、Confident AI、产物契约、迭代循环读取templates/获得可直接替换占位符运行的起点代码。8. 小结skills/是 DeepEval 仓库内面向编码助手的三个自包含 Agent Skilldeepeval评测闭环、deepeval-tracingSDK 插桩、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_KEYConfident AI 托管能力。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考