AgentOps LiteLLM 集成实战：多提供商 LLM 调用监控与可观测性指南-二趣网

AgentOps LiteLLM 集成实战：多提供商 LLM 调用监控与可观测性指南

【免费下载链接】agentopsPython SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI项目地址: https://gitcode.com/GitHub_Trending/ag/agentops

本文基于仓库中examples/litellm/目录的官方示例（README 与 litellm_example.py）展开，系统讲解如何用 AgentOps SDK 对 LiteLLM 的多提供商 LLM 调用进行自动插桩与监控：从环境准备、API Key 配置、Trace 生命周期的完整代码走读，到agentops.init()全参数解析、SDK 底层拦截机制，以及仓库集成测试与手动测试脚本的验证方式。读完本文，你可以直接复制运行仓库示例，并理解 AgentOps 是如何在源码层面捕获 LiteLLM 的同步、流式与异步调用。

一、背景：LiteLLM 与 AgentOps 各解决什么问题

LiteLLM 是一个统一接口库，允许你用 OpenAI 格式调用 100+ 种 LLM，包括 OpenAI、Llama、Mistral、Claude、Gemini、Gemma、DALL-E、Whisper 等。切换到不同模型时，只需要修改 API Key 和litellm.completion(model="...")中的 model 参数（见示例文件注释）。

AgentOps 则负责可观测性：它会自动插桩（instrument）LiteLLM 调用，为性能、用量模式和模型行为提供洞察（README 中 "AgentOps Integration" 一节）。示例文件的头部注释还指出了一点：LiteLLM 集成将可观测性扩展到了依赖 LiteLLM 的各类 agent 库，使基于这些库构建的 agent 也能被观察。本仓库中这一点有源码佐证——smolagents 的插桩器直接包裹了smolagents.models中的LiteLLMModel.generate/LiteLLMModel.generate_stream（instrumentor.py），并生成形如litellm.{operation} ({model_name})的 span 名称（第 214 行）。

示例目录包含四个文件：

文件	用途
README.md	前置条件、安装命令、示例说明
litellm_example.py	可运行的多提供商 LLM 访问示例
litellm_example.ipynb	同一示例的 Notebook 版本
requirements.txt	依赖清单，仅包含`litellm`（`agentops`与`python-dotenv`需在环境中另行安装，示例注释中给出的安装命令为`pip install -U litellm`/`pip install -U agentops`/`pip install -U python-dotenv`）

二、前置条件与安装

README 声明的运行环境约束与安装步骤如下：

Python 版本：>= 3.10 < 3.13
安装依赖：

pip install agentops litellm

补充两个仓库内可查证的版本事实：

v1 文档（docs/v1/integrations/litellm.mdx）注明 "AgentOps supportslitellm>=1.3.1"；
集成测试的 VCR 录制夹具（test_litellm_provider.yaml）中请求头显示录制时的用户代理为litellm/1.58.1，可以推断当前测试矩阵是在 litellm 1.58.x 上录制的。

三、配置 API Key

示例代码支持两种配置方式（litellm_example.py 第 17–29 行）：

环境变量方式（推荐）：在.env文件或环境中设置AGENTOPS_API_KEY，agentops.init()默认会读取该变量；同时设置所选提供商的 key（如OPENAI_API_KEY）。
参数直传方式：把 key 替换后传给agentops.init(api_key=...)。示例注释明确提醒：不要将 API key 提交到公开仓库。

示例采用的完整写法是先用python-dotenv加载.env，再用os.getenv提供回退值：

import os from dotenv import load_dotenv load_dotenv() os.environ["AGENTOPS_API_KEY"] = os.getenv("AGENTOPS_API_KEY", "your_api_key_here") os.environ["OPENAI_API_KEY"] = os.getenv( "OPENAI_API_KEY", "your_openai_api_key_here" ) # or the provider of your choosing

由于 LiteLLM 是多提供商门面，v2 文档（docs/v2/integrations/litellm.mdx）给出了多提供商 key 的配置形态，按实际使用的提供商设置对应变量即可：

export OPENAI_API_KEY="your_openai_api_key_here" export ANTHROPIC_API_KEY="your_anthropic_api_key_here" export AGENTOPS_API_KEY="your_agentops_api_key_here"

四、完整示例逐行解析

以下是 litellm_example.py 的核心逻辑（安装与 import 步骤省略）：

import litellm import agentops agentops.init(auto_start_session=False, trace_name="LiteLLM Example") tracer = agentops.start_trace( trace_name="LiteLLM Example", tags=["litellm-example", "agentops-example"], ) # 注意：必须用 litellm.completion() 的模块级调用方式（详见下一节） messages = [{"role": "user", "content": "Write a 12 word poem about secret agents."}] response = litellm.completion(model="gpt-4o-mini", messages=messages) print(response.choices[0].message.content) agentops.end_trace(tracer, end_state="Success") # 编程化校验 span 是否被正确记录 try: agentops.validate_trace_spans(trace_context=tracer) print("Success! All LLM spans were properly recorded in AgentOps.") except agentops.ValidationError as e: print(f"Error validating spans: {e}") raise

各步骤说明：

agentops.init(...)：初始化 SDK 单例客户端。auto_start_session=False表示不自动开启会话，改为手动用start_trace管理；trace_name指定默认 trace 的名称。从源码看（agentops/init.py 第 141–146 行），init()内部还会探测当前是否运行在 Jupyter Notebook（ZMQInteractiveShell）中，是则自动将auto_start_session置为False——这正是 Notebook 场景需要手动start_trace/end_trace的原因，示例脚本与该行为保持一致。
agentops.start_trace(trace_name=..., tags=...)：开启一个新的 trace（根 span）并返回TraceContext，支持多个并发、用户管理的 trace；tags会附加到 trace span 上，便于后续在控制台按litellm-example等标签检索（start_trace 实现）。
litellm.completion(model=..., messages=...)：一次普通的 LiteLLM 补全调用。AgentOps 会自动为其生成 LLM span，无需显式埋点。
agentops.end_trace(tracer, end_state="Success")：结束 trace 并标记终态（end_trace 实现）。
agentops.validate_trace_spans(trace_context=tracer)：编程化自检。该函数与ValidationError异常在 agentops/validation.py 中定义，并由包级 agentops/init.py 第 38 行导出。示例用它验证 LLM 调用确实产生了 span，适合写进 CI 或冒烟脚本。

关键陷阱：必须用`litellm.completion()`，而不是`from litellm import completion`

示例代码用整段注释强调了这一要求（litellm_example.py 第 34–47 行）：

# 错误（AgentOps 无法拦截）： from litellm import completion completion() # 正确（AgentOps 可拦截）： import litellm litellm.completion()

原因是 AgentOps 通过包裹litellm模块上的函数来完成插桩；from litellm import completion拿到的是原始未包裹的函数引用，插桩会失效。v1 集成文档（docs/v1/integrations/litellm.mdx）也把这一点列为正式警告："AgentOps requires a minor adjustment to how you call LiteLLM. This is because of other existing integrations that use thecompletionfunction."

另需注意：v2 文档（docs/v2/integrations/litellm.mdx）演示了另一条接入路径——通过 LiteLLM 自身的回调机制litellm.success_callback = ["agentops"]挂接 AgentOps。两套写法分别来自 v1/v2 文档，实际接入时以你所用 SDK 版本的文档为准；仓库examples/litellm/目录给出的权威可运行示例采用的是litellm.completion()模块级调用方式。

五、`agentops.init()`参数速查

完整示例只用了两个参数，但init()支持更多配置（签名与文档字符串），下表覆盖与 LiteLLM 场景相关的常用项：

参数	说明 / 默认值
`api_key`	AgentOps API Key；不传则读取`AGENTOPS_API_KEY`环境变量
`endpoint`	服务端点；不传则读取`AGENTOPS_API_ENDPOINT`，默认`https://api.agentops.ai`
`app_url`	控制台地址；不传则读取`AGENTOPS_APP_URL`，默认`https://app.agentops.ai`
`max_wait_time`	队列刷新前最长等待时间（毫秒），默认 5000
`max_queue_size`	事件队列最大长度，默认 512
`default_tags`	会话/trace 默认标签，用于分组排序（旧参数`tags`已弃用，传入会触发弃用告警）
`trace_name`	默认 trace 名称，缺省为`"default"`
`instrument_llm_calls`	是否对 LLM 调用插桩并发出 LLM 事件
`auto_start_session`	客户端创建时是否自动开启会话
`auto_init`	是否在 import 时自动初始化客户端，默认 True
`skip_auto_end_session`	不根据框架决策自动结束会话（例如由 Crew 判断任务完成时机）
`env_data_opt_out`	是否关闭环境数据采集
`log_level`	客户端日志级别，默认`CRITICAL`
`fail_safe`	出错时是否抑制异常并继续执行
`log_session_replay_url`	是否向控制台打印会话回放 URL，默认 True
`exporter_endpoint`	导出器端点；不传则读取`AGENTOPS_EXPORTER_ENDPOINT`

此外，agentops.configure(**kwargs)（第 176–224 行）允许在运行中更新上述大部分配置，并对无效参数发出告警。

六、底层机制：AgentOps 从哪里拦截 LiteLLM 调用

LiteLLM 以 OpenAI 兼容格式转发请求，因此从源码结构看，AgentOps 的 LLM 提供商插桩集中在 agentops/instrumentation/providers/openai/ 目录下，其中 wrappers/ 子目录按 OpenAI 接口面拆分为chat.py、completion.py、embeddings.py、image_gen.py、responses.py，另有stream_wrapper.py专门处理流式响应。插桩器与配置分别由 instrumentor.py 和 config.py 承载。这解释了第四节的调用方式约束：只有litellm模块属性上的函数被包裹后，litellm.completion()调用才会进入插桩路径。

对于构建在 LiteLLM 之上的 agent 框架，仓库同样提供了直接插桩。以 smolagents 为例，instrumentor.py 第 96–97 行用wrap_function_wrapper包裹smolagents.models模块的LiteLLMModel.generate与LiteLLMModel.generate_stream，声明的依赖为smolagents >= 1.0.0与litellm（第 67 行），span 名称模板为litellm.{operation} ({model_name})。这与示例注释中"LiteLLM 集成使依赖 LiteLLM 的 agent 库可被观察"的说法相互印证。

七、用仓库测试与手动脚本验证

仓库为 LiteLLM 链路提供了三层验证手段：

集成测试：tests/integration/test_llm_providers.py 第 287–307 行的test_litellm_provider依次覆盖三类调用——同步completion、stream=True的流式补全、异步acompletion，正好对应生产代码中最常见的三种 LiteLLM 使用形态。
夹具与录制：tests/fixtures/providers.py 第 87–98 行的litellm_client夹具会注入litellm.openai_key、litellm.anthropic_key、litellm.openrouter_key，支撑多提供商测试；对应的 VCR 录制文件为 tests/fixtures/recordings/test_litellm_provider.yaml，其中还包含对x-litellm-api-key请求头的脱敏处理（见 tests/fixtures/vcr.py 第 67 行）。
手动 Canary 脚本：tests/core_manual_tests/providers/litellm_canary.py 是一个端到端手工验证脚本：agentops.init(default_tags=["litellm-provider-test"])之后依次发起同步、流式、异步（acompletion）调用，再调用agentops.stop_instrumenting()停止插桩并发起一次"未追踪"的completion调用，最后end_session(end_state="Success")。脚本尾部注释说明其用途是验证一次会话只产生一个 LLM 事件。这个脚本是排查"插桩是否生效、停止插桩后是否不再记录"这类问题的现成模板。

示例自带的agentops.validate_trace_spans自检（见第四节）则是日常开发中最轻量的验证方式。

八、延伸阅读与文件索引

官方 Notebook 版本示例：examples/litellm/litellm_example.ipynb
v1 集成文档（含安装步骤与会话控制台观察指引）：docs/v1/integrations/litellm.mdx
v2 集成文档（含success_callback接法、流式与多提供商示例）：docs/v2/integrations/litellm.mdx
SDK 入口与 Trace API：agentops/init.py
OpenAI 兼容面插桩实现：agentops/instrumentation/providers/openai/
smolagents/LiteLLM 框架级插桩：agentops/instrumentation/agentic/smolagents/instrumentor.py
集成测试与夹具：tests/integration/test_llm_providers.py、tests/fixtures/providers.py

注意事项小结：Python 版本须落在 3.10–3.12；调用必须使用import litellm后的模块级litellm.completion()写法以确保被插桩；API key 一律走环境变量并避免入库；多提供商场景下只需按提供商补充对应的 key 环境变量，其余代码保持不变。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析