DeepEval 追踪集成选择指南从 CallbackHandler 到 deepeval.instrument 的完整实践【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval本文基于 DeepEval 官方技能参考文档 integrations.md 展开系统讲解为 LLM 应用添加追踪tracing时如何挑选正确的集成方式先识别应用使用的框架、模型供应商与向量数据库优先使用 DeepEval 提供的原生集成如 LangGraph 的CallbackHandler、OpenAI 的客户端补丁仅对不受支持的组件才回退到手写observe。读完本文你将掌握 DeepEval 全部集成文档的索引、四种集成机制的底层差异以及两套可直接复制的实战示例代码。核心原则先选原生集成手写 observe 只是兜底integrations.md 开篇即给出明确的选型规则优先使用 DeepEval 官方支持的原生集成手动observe仅在没有原生集成的应用代码或框架边界处作为后备。该文档给出的四步选择流程是识别应用中已存在的框架、模型供应商、Agent SDK、向量数据库以及任何已有的 OpenTelemetry 设置如果存在对应的集成文档先阅读该文档再写追踪代码优先使用集成的原生追踪面native tracing surface仅在外部应用函数或不受支持的组件周围才使用手动observe严格遵循对应集成文档中的追踪配置方式。文档以 LangGraph 为例做了强调LangGraph 应用应当先使用 LangGraph/LangChain 回调集成CallbackHandler而不是第一选择就加手动observe——手动observe适合包裹外层应用函数或不支持的组件而不是图graph本身。此外该文档还划定了一个重要的命名约定当后续评测eval把指标挂到某个组件 span 上时这些指标列表应当以它们所评估的组件/span 命名例如RETRIEVER_SPAN_METRICS、GENERATOR_LLM_SPAN_METRICS而不是搞一个全局列表。文档同时明确职责边界把指标挂到 span 上是评测活动由deepeval技能负责而本技能deepeval-tracing只负责产出结构良好的 trace。集成文档全索引integrations.md 维护了三类共 36 篇集成文档的索引全部位于 docs/content/integrations/ 目录下。框架集成Frameworks框架集成文档LangGraphlanggraph.mdxLangChainlangchain.mdxOpenAI Agentsopenai-agents.mdxLlamaIndexllamaindex.mdxPydantic AIpydanticai.mdxCrewAIcrewai.mdxGoogle ADKgoogle-adk.mdxStrandsstrands.mdxAgentCoreagentcore.mdxOpenAI SDKopenai.mdxAnthropic SDKanthropic.mdxHugging Facehuggingface.mdx模型供应商集成Models供应商集成文档OpenAIopenai.mdxAzure OpenAIazure-openai.mdxAnthropicanthropic.mdxGeminigemini.mdxAmazon Bedrockamazon-bedrock.mdxVertex AIvertex-ai.mdxGrokgrok.mdxOpenRouteropenrouter.mdxLiteLLMlitellm.mdxOllamaollama.mdxvLLMvllm.mdxLM Studiolmstudio.mdxPortkeyportkey.mdxDeepSeekdeepseek.mdxMoonshotmoonshot.mdx向量数据库集成Vector Databases向量库集成文档Chromachroma.mdxElasticsearchelasticsearch.mdxPGVectorpgvector.mdxQdrantqdrant.mdxWeaviateweaviate.mdxCogneecognee.mdxOpenTelemetry 的分工边界integrations.md 最后专门澄清了一个容易混淆的边界如果你想用厂商中立的 OpenTelemetry SDK而非 DeepEval SDK做插桩包括非 Python 应用、裸 OTLP 导出的场景应改用deepeval-otel技能。当前技能deepeval-tracing覆盖的是 DeepEval 原生observe追踪与上述列出的所有集成。这一分工与 deepeval-tracing 技能主文档 中的三技能划分一致deepeval-tracing——用 DeepEval SDKobserve、框架集成给应用插桩使 trace 进入 Confident AIdeepeval——构建 pytest 评测套件数据集、指标、traced evals、deepeval test run对已插桩的应用跑评测deepeval-otel——用厂商中立的 OpenTelemetry SDK 插桩裸 OTLP含非 Python 应用。四种集成机制源码视角的实现差异integrations.md 只给出文档索引而具体的机制实现差异在 deepeval/integrations/README.md 的集成矩阵中有完整记载。该 README 将每种集成归入四种机制之一Native client wrapper原生客户端包装——厂商 SDK 客户端类的即插即用替代品如用deepeval.openai.OpenAI替换openai.OpenAIspan 直接通过trace_manager构建摩擦最小但只覆盖经过该客户端的调用Callback handler / event listener回调处理器 / 事件监听器——注册到框架自身的回调或事件 APILangChainBaseCallbackHandler、LlamaIndexBaseEventHandler、CrewAIBaseEventListener等覆盖框架经该面派发的所有调用无需替换客户端Trace processor追踪处理器——面向本身已有追踪流水线的框架OpenAI Agents SDK以处理器身份接入并把事件翻译为 DeepEval spanOpenTelemetry——向全局TracerProvider注册 OTelSpanProcessor框架或社区 instrumentor 产出 OTel spanDeepEval 将其翻译为 Confident span 属性并经 OTLP 发送。从源码结构看README 中的能力矩阵显示所有集成在四个使用面上Bare 直接调用、observe/with trace(...)包裹、dataset.evals_iterator(...)、deepeval test run均已拉齐其中 Pydantic AI、AgentCore、Google ADK、Strands 四个 OTel 模式集成走的是同一套SpanInterceptorContextAwareSpanProcessor模式处理器在有 DeepEval trace 上下文激活或评测进行中时自动切到 REST 路由其余情况走 OTLP从而保证混合使用OTel 集成嵌套在observe内时两端数据落到同一条 trace 上。两个可从源码直接验证的机制细节LangChain/LangGraph 集成的入口是 deepeval/integrations/langchain/init.py仅导出CallbackHandler与tool两个符号——这正是文档中“每调用传一次回调”的 per-call 模式的来源OpenAI 集成在 deepeval/openai/init.py 中导入官方OpenAI/AsyncOpenAI类后调用patch_openai_classes()就地打补丁并先检查openai包是否安装、缺失时抛出ModuleNotFoundError——说明“换一行 import”背后是运行时 monkey-patch而非 API 重写。实战一LangGraph 应用用 CallbackHandler 追踪按 integrations.md 的选型规则LangGraph 应用应走 LangChain 回调集成。langgraph.mdx 给出了完整可复制的 Python 示例安装pip install -U deepeval langgraph langchain-openai后把CallbackHandler(...)传入图运行的 config 即可每次invoke产生的 agent 节点、模型调用、工具调用都会成为可检查的 span。from langchain.chat_models import init_chat_model from langgraph.graph import StateGraph, MessagesState, START, END from langgraph.prebuilt import ToolNode, tools_condition from deepeval.integrations.langchain import CallbackHandler from deepeval.dataset import EvaluationDataset, Golden from deepeval.metrics import TaskCompletionMetric def get_weather(city: str) - str: Return the weather in a city. return fIts always sunny in {city}! llm init_chat_model(openai:gpt-4o-mini).bind_tools([get_weather]) def chatbot(state: MessagesState): return {messages: [llm.invoke(state[messages])]} graph ( StateGraph(MessagesState) .add_node(chatbot) .add_node(tools, ToolNode([get_weather])) .add_edge(START, chatbot) .add_conditional_edges(chatbot, tools_condition) .add_edge(tools, chatbot) .compile() ) # Goldens 是你要评测的输入 dataset EvaluationDataset(goldens[Golden(inputWhat is the weather in Paris?)]) # TaskCompletionMetric 传入 evals_iterator for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): graph.invoke( {messages: [{role: user, content: golden.input}]}, config{callbacks: [CallbackHandler()]}, )该集成产生的 trace 树形结构为引自 langgraph.mdxTrace ← 用户观察到的端到端单元 └── Agent: weather_graph ← 一次 graph invoke(...) 调用 ├── Node: chatbot ← 模型选择工具 │ └── LLM: gpt-4o-mini ├── Node: tools ← ToolNode 执行工具 │ └── Tool: get_weather └── Node: chatbot ← 模型写出最终答案 └── LLM: gpt-4o-mini文档还强调CallbackHandler支持name、tags、metadata、thread_id、user_id等 trace 级 kwargs以及通过next_agent_span/next_llm_span/next_retriever_span/next_tool_span把组件级字段暂存到回调将打开的下一个 span 上部署到 LangGraph server 时则把回调烘焙进编译后的图.with_config(callbacks[CallbackHandler()])让服务端执行的每个请求都被追踪。实战二OpenAI 客户端补丁追踪对于直接使用 OpenAI SDK 的应用openai.mdx 的集成方式是替换 import把from openai import OpenAI换成from deepeval.openai import OpenAI之后每次client.chat.completions.create(...)和client.responses.create(...)都自动成为携带输入、输出与tools_called的 LLM span无需改写调用方式源码机制见上文 deepeval/openai/init.py 的补丁说明。from deepeval.dataset import EvaluationDataset, Golden from deepeval.tracing import trace, LlmSpanContext from deepeval.metrics import AnswerRelevancyMetric from deepeval.openai import OpenAI client OpenAI() # Goldens 是你要评测的输入 dataset EvaluationDataset(goldens[Golden(inputWhats the capital of France?)]) for golden in dataset.evals_iterator(): with trace(llm_span_contextLlmSpanContext(metrics[AnswerRelevancyMetric()])): client.chat.completions.create( modelgpt-4o, messages[ {role: system, content: Be concise.}, {role: user, content: golden.input}, ], )LlmSpanContext可接受metrics、prompt、expected_output、expected_tools、context、retrieval_context等字段在下一个 LLM span 创建时被读取。多个 OpenAI 调用同属一个逻辑单元如 planner 调用 回答调用时用with trace(nameplan_then_respond):括起来各 LLM span 便作为兄弟 span 挂在同一 root 下。同步与异步客户端OpenAI/AsyncOpenAI均受支持。通用 OTel 后端deepeval.instrument对于通过 OpenInference 等社区 instrumentor 产出 OTel span 的场景integrations/README.md 说明仓库在顶层暴露了deepeval.instrument(...)可与任意 OpenInference instrumentor 直接配对import deepeval from openinference.instrumentation.google_adk import GoogleADKInstrumentor deepeval.instrument(namemy-app, environmentdevelopment) GoogleADKInstrumentor().instrument()该入口配置TracerProvider、挂载 DeepEval 的 OpenInference span interceptor把openinference.span.kind、llm.input_messages.{idx}、llm.token_count.*等语义属性翻译为confident.span.*并经ContextAwareSpanProcessor决定走 REST 还是 OTLP。instrument_google_adk(...)只是对以上两步的便捷封装而 AgentCore、Strands、Pydantic AI 各有自己的SpanInterceptor分别读取 OTel GenAI 语义属性或 logfire 风格属性但共享同一套处理器路由逻辑。与手动 observe 的边界integrations.md 反复强调手动observe的定位它服务于“没有原生集成的应用代码或框架边界”。配套的 tracing.md 规定了手动插桩的规范——用有意义的type值llm、retriever、tool、agent帮助后续指标选择、尽量以消息数组形式捕获输入输出、不给 trace 名随意起自定义name、以及在 trace 级用 tags/metadata 做分组而不追踪密钥与敏感数据。换句话说集成负责框架内部组件的 spanobserve负责应用自有的外层边界两者叠加后得到的 trace 才能既完整又干净。最后重申职责边界本指南所指的集成与插桩工作“到产出结构良好的 trace 为止”——把指标挂到 span 上如RETRIEVER_SPAN_METRICS、GENERATOR_LLM_SPAN_METRICS这类按组件命名的指标列表并运行评测属于deepeval技能的范畴裸 OpenTelemetry/OTLP 导出则属于deepeval-otel技能。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考