Opik × LiteLLM 集成指南为多模型 LLM 应用接入端到端可观测性【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm本篇指南以 Opik 的 LiteLLM 官方集成模板为骨架讲解如何在一个基于 LiteLLM 网关的多模型 LLM 应用中接入 Opik 的追踪Tracing、日志与评估能力。读完本文你将掌握通过OpikLogger回调实现零侵入的 LLM 调用自动日志、在track装饰器函数内传递current_span_data建立完整 Span 层级、以及如何借助track_completion装饰器对litellm.completion/litellm.acompletion含流式做细粒度追踪——无论你调用的是 OpenAI、Anthropic、Groq 还是任意 LiteLLM 支持的上百个 Provider。背景为什么需要为 LiteLLM 应用加一层可观测性LiteLLM 的价值在于把几十家 LLM Provider 的统一成一套 OpenAI 兼容的 API 接口让应用层可以用litellm.completion(modelgroq/llama3-8b-8192)这样的写法无缝切换模型。但统一网关也带来了新问题调用到底发给了哪个 Providerprompt、输出、token 用量和成本是多少在多步骤 Agent 流程里哪一次子调用拖慢了整体响应这些问题单靠 LiteLLM 自身无法回答需要一套独立的追踪层来记录每一次调用的输入、输出、元数据与成本——这正是 Opik 所承担的角色。在 Opik 仓库中LiteLLM 集成分为两条互补的路径集成源码目录回调式集成本文主体通过litellm.callbacks注册OpikLoggerLiteLLM 每次完成调用后自动把请求与响应发给 Opik装饰器式集成track_completion通过 opik_tracker.py 暴露的track_completion包装litellm.completion/litellm.acompletion在 Opik 一侧主动拦截并记录调用适合需要精确控制 Span 结构的场景。账号与环境准备选择 Opik 部署形态Opik 平台有两种运行方式集成代码完全一致只需配置不同的端点与密钥Comet 托管版Cloud在 Comet 平台注册账号并获取 API Key开箱即用自托管版Self-hosted参考 自托管安装说明通过 Docker Compose 一键拉起完整的 Opik 后端含 ClickHouse 存储同时 docker-compose 编排文件 与 Helm Chart 提供了两种生产部署路径。安装依赖LiteLLM 集成需要同时安装opik与litellm两个 Python 包pip install opik litellm集成所需的 Python SDK 源码位于 sdks/python/src/opik/integrations/litellm/opik 包会将其作为官方库内集成随包发布。如果你要参与集成开发仓库在 sdks/python/tests/library_integration/litellm/ 与 sdks/python/tests/e2e_library_integration/litellm/ 提供了配套的单元与端到端测试。配置 Opik 客户端针对你的部署形态用任一方式配置 Opik Python SDKCLI 配置终端执行opik configure按提示选择 Cloud 或自托管并填入 API Key 与 Base URL代码配置调用opik.configure()可在运行时动态传入参数环境变量设置OPIK_API_KEY、OPIK_URL_OVERRIDE等环境变量详见 SDK 配置文档 SDK 配置指南。配置 LiteLLM 的 Provider API Key在调用具体 Provider 之前需要先配置对应的 API Key。以 Groq 为例可将密钥写入环境变量export GROQ_API_KEYYOUR_API_KEY对于不同 Provider环境变量名各不相同如OPENAI_API_KEY、ANTHROPIC_API_KEY。更稳妥的方式是在代码中安全地读取密钥并同时设定 Opik 的项目名保证日志落到统一项目下import os import getpass if GROQ_API_KEY not in os.environ: os.environ[GROQ_API_KEY] getpass.getpass(Enter your Groq API key: ) # 为本次集成演示设置项目名所有 trace 会归入该项目 os.environ[OPIK_PROJECT_NAME] groq-integration-demo方式一通过 OpikLogger 回调自动记录 LLM 调用这是最省事的接入方式创建OpikLogger实例并注册进litellm.callbacks此后所有通过 LiteLLM 发出的调用都会被自动记录业务代码零改动from litellm.integrations.opik.opik import OpikLogger import litellm import os opik_logger OpikLogger() litellm.callbacks [opik_logger] # 设置项目名便于在 Opik UI 中按项目聚合 os.environ[OPIK_PROJECT_NAME] groq-integration-demo response litellm.completion( modelgroq/llama3-8b-8192, # 替换为实际模型名如 openai/gpt-4o messages[ {role: user, content: Why is tracking and evaluation of LLMs important?} ] )执行后在 Opik 的 Trace 列表中即可看到一条完整的调用记录chat.completion级别的 trace 与对应 span携带输入 messages、输出 choices、token usage 与created_from: litellm元数据。这一行为有仓库端到端测试作为依据test_opik_logging.py 中的test_litellm_opik_logging__happyflow以litellm.callbacks [opik]触发一次真实调用后断言 Opik 侧恰好生成 1 条 trace 与 1 条 span且trace 名称为chat.completionspan 名称以模型名如gpt-5-nano开头两者元数据均包含{created_from: litellm}输入严格等于原始messages数组span 类型为llmtags 中包含 Provider 名测试中为openai。回调集成的工作原理OpikLogger回调本身定义在 LiteLLM 一侧但 Opik 与之对应的底层能力由 litellm_completion_decorator.py 的LiteLLMCompletionTrackDecorator实现可以从源码确认其记录行为输入过滤记录输入时仅保留messages、functions、function_call、tools、tool_choice、response_format、stop等业务参数见源码中KWARGS_KEYS_TO_LOG_AS_INPUTS敏感信息脱敏api_key、aws_secret_access_key、azure_ad_token、vertex_credentials等 21 项密钥类参数会被显式排除绝不落盘见SENSITIVE_PARAMS_TO_EXCLUDEProvider 识别通过litellm.get_llm_provider(model_name)解析模型前缀如groq/、openai/再经LITELLM_PROVIDER_MAPPING映射为 Opik 统一的LLMProvider枚举写入 span 的provider字段成本计算调用litellm.completion_cost()计算单次调用的费用并随 span 记录total_cost供 Opik 侧做成本聚合usage 归一化把 LiteLLM 返回的 usage 数据转换为 Opik 统一的OpikUsage结构见 opik_usage.py 与 litellm_provider_mapping.py。方式二在 track 函数内记录调用并维护 Span 层级当 LiteLLM 调用发生在 Opiktrack装饰的函数内部时若不额外处理LiteLLM 侧回调产生的 trace 与外层函数不在同一调用树中。解决办法是在litellm.completion的metadata中显式传入opik_context.get_current_span_data()把当前 Span 作为元数据带给 LiteLLM使内层调用挂载到外层函数对应的 Span 之下from opik import track, opik_context import litellm track def generate_story(prompt): response litellm.completion( modelgroq/llama3-8b-8192, # 替换为实际模型名 messages[{role: user, content: prompt}], metadata{ opik: { current_span_data: opik_context.get_current_span_data(), }, }, ) return response.choices[0].message.content track def generate_topic(): prompt Generate a topic for a story about Opik. response litellm.completion( modelopenai/gpt-4o, # 可与上方不同模型 messages[{role: user, content: prompt}], metadata{ opik: { current_span_data: opik_context.get_current_span_data(), }, }, ) return response.choices[0].message.content track def generate_opik_story(): topic generate_topic() story generate_story(topic) return story generate_opik_story()运行后Opik 中会呈现一棵清晰的调用树generate_opik_storyTrace→generate_topic/generate_storySpan→ 各自的litellm.completionLLM Span方便你在 Trace 详情页逐层下钻定位延迟与失败节点。方式三track_completion 装饰器精确追踪含流式如果不想依赖 LiteLLM 全局回调可以直接用 Opik 内置的track_completion装饰器包装调用函数。它支持同步与异步、流式与非流式四种组合并通过 opik_tracker.py 暴露import litellm from opik.integrations.litellm import track_completion tracked_completion track_completion(project_namemy-project)(litellm.completion) response tracked_completion(modelgpt-3.5-turbo, messages[{role: user, content: Hello}])track_completion接收两个可选参数参数类型说明project_namestr | None日志写入的 Opik 项目名缺省时使用 SDK 默认项目sourceTraceSource | NoneTrace 来源标识如sdk、optimization用于区分数据产生方流式调用的聚合原理流式场景下LiteLLM 返回的是CustomStreamWrapper无法一次性拿到完整响应。Opik 通过 stream_patchers.py 对包装器的__next__/__anext__进行打补丁逐个累积 chunk流结束后由 completion_chunks_aggregator.py 的aggregate把全部 chunk 拼装为一条完整的ModelResponse从每个 chunk 的delta中提取增量content与role并拼接成完整消息聚合首尾 chunk 中的usagetoken 统计与finish_reason若流中途抛异常通过error_info_collector收集错误信息写入 span保证失败调用也可追溯。对应测试位于 test_litellm_streaming.py覆盖了同步/异步流式 chunk 聚合与错误路径。三种方式的选型建议接入方式侵入性适用场景litellm.callbacks [OpikLogger()]最低全局生效快速接入、全量记录所有 Provider 调用最契合官方模板的默认路径trackmetadata[opik][current_span_data]中多步骤 Agent / 编排链需要把 LLM 调用挂入业务函数的 Span 层级track_completion装饰器低中按调用点生效需要按函数粒度控制项目归属与来源、或对流式输出有精细追踪诉求常见问题与排查回调未生效确认litellm.callbacks [opik_logger]在首次litellm.completion之前执行若使用 e2e 测试中的字符串形式litellm.callbacks [opik]需要确保opik已安装且其 LiteLLM 回调入口可被 LiteLLM 动态加载。API Key 泄露风险集成内置脱敏机制但仍应避免在metadata或消息内容中放置密钥自托管场景建议配合 docker-compose 的配置 限制后端网络访问。成本字段为空litellm.completion_cost()依赖模型定价表若 Provider/模型不在 model_prices_and_context_window.json 所对应的定价体系中total_cost会以None落库不影响其余日志字段。Provider 识别失败litellm.get_llm_provider对未识别前缀会抛异常装饰器会静默返回Nonespan 的provider字段为空属预期行为。结语通过本文的三种接入方式你已经可以为任何基于 LiteLLM 的应用建立完整的 Opik 可观测链路从一次最简单的litellm.completion自动日志到多模型 Agent 编排中的 Span 树再到流式输出的逐 chunk 聚合与成本核算。更深层的实现细节敏感参数过滤清单、usage 归一化、流式打补丁均可在 sdks/python/src/opik/integrations/litellm/ 中直接阅读源码配套测试为你的接入行为提供了可复现的验证基准。【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考