mcpField
D
deepeval-otel

deepeval-otel

github.com/confident-ai开发19.2k42 次安装1 天前更新
代码仓库

关于 deepeval-otel

deepeval-otel 是为 AI 应用配置供应商无关的 OpenTelemetry，并将追踪数据发送到 Confident AI Observatory 的技能。它指导设置 HTTP 导出器和 `confident.*` 属性，无需安装 `deepeval` 包。

主要功能

  1. 01通过 OTLP/HTTP 导出追踪
  2. 02配置 Confident AI 端点与认证
  3. 03设置追踪和跨度属性
  4. 04将 AI 跨度与其他遥测隔离
  5. 05提供 Python 导出器模板

适用场景

  1. 01将 LLM 应用追踪发送到 Observatory
  2. 02为 Agent、检索和工具跨度添加观测
  3. 03调整现有 OpenTelemetry 导出器
  4. 04避免导出非 AI 遥测数据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/confident-ai/deepeval --skill deepeval-otel

安装后在 Claude Code 中输入/deepeval-otel确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

LICENSE
references/
endpoint-and-exporter.md
gen-ai-fallbacks.md
span-attributes.md
trace-attributes.md
templates/
confident_otel_setup.py

详细介绍

DeepEval OpenTelemetry 导出

使用此技能，通过原始 OpenTelemetry 为AI 应用（大模型应用、Agent、RAG 流水线或聊天机器人）添加检测，使其跟踪数据进入 Confident AI 的 Observatory。无需安装 deepeval 包——任何支持 OTLP 的 OpenTelemetry SDK 都能使用。只需完成两件事：导出到正确的 Confident AI OTLP 端点，并设置 Confident AI 会从每个 span 中读取的 confident.* 属性。

适用范围：仅限 AI 应用

此技能仅为 AI 应用添加检测。confident.* 属性和 span 类型——agent、llm、retriever、tool——用于描述 AI 组件，而 Confident AI 的 Observatory 专为评估和监控 AI 行为而构建。

仅为系统中的 AI 部分添加检测：Agent 循环和规划、大模型调用、检索／向量搜索以及工具调用。不要将 confident.* 属性应用于非 AI 软件（Web 服务、CRUD 后端、数据库层、基础设施），也不要应用于 AI 应用中的非 AI span——这些数据不属于 Confident AI，也无法在其中得到有意义的呈现。如果目标没有大模型、Agent、检索或工具调用组件，则不适用此技能。

何时使用此技能，何时使用 deepeval 技能

当用户需要以与供应商无关的方式通过 OTLP 导出到 Confident AI 时，使用此技能——将 OpenTelemetry 导出器指向 Confident AI，并设置 confident.* 属性。

当用户想要构建 Python pytest 评估套件、生成数据集或标准答案、编写指标、运行 deepeval test run，或使用 deepeval SDK 的 @observe 装饰器添加检测时，使用 deepeval 技能。这两种技能相辅相成，而非互为替代。

前提条件

  • 拥有 Confident AI 账户和 CONFIDENT_API_KEY。
  • 应用所用语言的 OpenTelemetry SDK。对于 Python： opentelemetry-sdk 和 opentelemetry-exporter-otlp-proto-http。
  • Confident AI OTLP 端点仅接受 HTTP——绝不能使用 gRPC。

工作原理

Confident AI 提供 OTLP/HTTP 跟踪端点。将任意 OpenTelemetry span 导出器指向该端点，并附上 x-confident-api-key 请求头。随后，Confident AI 的导出器会读取每个 span 上的 confident.* 属性，以构建跟踪和 span 结构。父子嵌套关系来自原生 OpenTelemetry span 上下文，而非任何属性。

工作流

  1. 确认目标是 AI 应用（具有大模型调用、Agent 循环、检索或工具调用）。如果这些都没有，请停止——此技能不适用。然后检查是否已有 OpenTelemetry 配置（TracerProvider、span 导出器或 OpenTelemetry Collector），并优先调整现有配置的指向，而不是添加并行流水线。
  2. 根据 API 密钥的区域前缀选择端点。阅读 references/endpoint-and-exporter.md。
  3. 配置（或调整）OTLP/HTTP span 导出器，并添加 x-confident-api-key 请求头。对于 Python，请从 templates/confident_otel_setup.py 开始。
  4. 如果进程还运行其他 OpenTelemetry 检测或 APM Agent （例如 HTTP／DB 自动检测、Datadog 等），请隔离 Confident AI 导出流程，确保只有 AI span 会发送到该端点——可以使用专用流水线或 span 筛选器。阅读 references/endpoint-and-exporter.md 中的“仅导出 AI Span”。
  5. 在 span 上设置 confident.span.* 属性；对于整个跟踪的字段，设置 confident.trace.*。阅读 references/span-attributes.md 和 references/trace-attributes.md。
  6. 遵守 OTLP 数据类型规则：将字典／元数据编码为 JSON，字符串列表使用原生数组。请参阅 span-attributes.md 中的数据类型规则。
  7. 如果应用已发出 OpenTelemetry GenAI 语义约定，请先阅读 references/gen-ai-fallbacks.md，再添加重复属性。
  8. 确认跟踪数据已显示在 Confident AI Observatory 中。

核心原则

  1. 仅对 AI 组件进行埋点——Agent、大模型、检索器和工具 Span。 切勿对非 AI 软件或非 AI Span 应用 confident.* 属性。
  2. 仅导出 AI Span。如果进程中有其他 OpenTelemetry 埋点或 APM Agent，请隔离 Confident AI 管道（使用专用 Provider 或 Span 过滤器），确保非 AI Span——HTTP 请求、数据库查询、基础设施相关 Span——绝不会导出到 Confident AI。
  3. 优先调整现有 OTLP 导出器的指向，而不是额外添加并行导出器。
  4. confident.* 属性键就是完整的约定——所有语言中都相同，因此语言选择无关紧要。
  5. 始终使用 OTLP/HTTP。Confident AI 的端点不接受 gRPC。
  6. 遵循 OTLP 数据类型规则：属性值必须是原始类型或同质原始类型列表；字典和元数据应使用 JSON 编码。
  7. 如果已知，请显式设置 confident.span.type；仅在无法确定时才依赖 gen_ai.* 推断。
  8. 切勿将密钥、凭证或未经处理的敏感数据放入 Span 属性中。

参考资料

主题文件
端点、区域选择、身份验证、导出器配置references/endpoint-and-exporter.md
Trace 级 confident.trace.* 属性references/trace-attributes.md
Span 级 confident.span.* 属性和数据类型规则references/span-attributes.md
标准 OTel gen_ai.* 回退行为references/gen-ai-fallbacks.md

模板

用途模板
最精简的 Python OTLP 导出器配置及示例 Tracetemplates/confident_otel_setup.py

评论

支持 Markdown