10 分钟搞懂 LiteLLM 插件系统几行代码给 LLM 调用加上日志、监控与审计【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm如果你的 LLM 应用只负责把请求发出去那还算简单。真正麻烦的是周边需求每次调用要留一份日志备查、指标要上 Prometheus 看板、敏感内容要在请求前后做一遍审计……每接一个新工具就重写一遍适配代码维护起来非常痛苦。LiteLLM 的解法是插件系统也叫回调 / hooks 机制内置和自定义的插件统一实现一个接口挂载到 LLM 调用的生命周期上由框架在合适的时机自动触发。也就是说LiteLLM 插件系统的核心就一句话——你只管写发生某件事时做什么剩下的触发和分发交给框架。3 分钟跑起来一个能自己用的最小插件不依赖任何外部服务先看一个完全自包含的 LiteLLM 自定义插件统计每次调用的 token 用量。所有插件都来自对 custom_logger.py 中CustomLogger基类的继承成功事件通过log_success_event回调进来from litellm.integrations.custom_logger import CustomLogger import litellm class TokenCounterLogger(CustomLogger): def __init__(self): super().__init__() self.token_stats {total_tokens: 0, request_count: 0} def log_success_event(self, kwargs, response_obj, start_time, end_time): if hasattr(response_obj, usage): self.token_stats[total_tokens] response_obj.usage.total_tokens self.token_stats[request_count] 1 print(f累计请求: {self.token_stats[request_count]}, f累计Token: {self.token_stats[total_tokens]}) counter TokenCounterLogger() response litellm.completion( modelgpt-3.5-turbo, messages[{role: user, content: Hello World}], callbacks[counter], # 插件在这里注册 )运行后终端就会打印类似累计请求: 1, 累计Token: 25的输出。注意callbacks[counter]这一行——这是把插件挂进调用链的唯一动作。它是怎么工作的注册、挂载、触发三步把上面的例子拆开看LiteLLM 插件的运行逻辑其实就三步插件注册插件类实现CustomLogger定义的接口实例化后通过callbacks参数或全局litellm.callbacks注册钩子挂载框架按事件类型把插件挂到调用生命周期的不同阶段——成功、失败、请求前后等事件触发一次litellm.completion()结束或失败后框架自动调用对应钩子把上下文交给你。核心接口就四个方法同步、异步各一对class CustomLogger: def log_success_event(self, kwargs, response_obj, start_time, end_time): 成功事件日志记录 def async_log_success_event(self, kwargs, response_obj, start_time, end_time): 异步成功事件日志记录 def log_failure_event(self, kwargs, response_obj, start_time, end_time): 失败事件日志记录其中kwargs是本次调用的完整参数model、messages 等response_obj是响应对象start_time/end_time用于计算耗时。只要继承并覆写你需要的方法其余保持默认即可——这是整个 litellm/integrations/ 目录下 20 多种内置集成的共同写法。真实项目里的三种典型用法场景一把调用日志存进 S3log_success_event 最经典的去处是对象存储。S3Logger位于 s3.py会把请求与响应日志写入指定的桶from litellm.integrations.s3 import S3Logger s3_logger S3Logger( s3_bucket_nameyour-bucket, s3_pathlogs/litellm/, s3_region_nameus-east-1, ) response litellm.completion( modelgpt-3.5-turbo, messages[{role: user, content: Hello World}], callbacks[s3_logger], )接入可观测平台是同一套路只是把存储目标换掉下面是 LiteLLM 日志接入第三方平台的实际效果场景二指标自动上 Prometheus监控类插件不关心具体内容只关心调用发生了、花了多久。prometheus_services.py 中的PrometheusServicesLogger会暴露服务延迟等指标from litellm.integrations.prometheus_services import PrometheusServicesLogger litellm.callbacks [PrometheusServicesLogger()] # 全局挂载所有调用生效 response litellm.completion( modelgpt-3.5-turbo, messages[{role: user, content: Hello World}] )注意这里用的是全局litellm.callbacks适合所有请求都要采指标的场景而callbacks[...]适合只对某几次调用生效。场景三请求前后的内容审计审计类需求要挂在调用两侧。CustomGuardrailcustom_guardrail.py通过supported_event_hooks声明自己关心哪些生命周期点from litellm.integrations.custom_guardrail import CustomGuardrail guardrail CustomGuardrail( guardrail_namecontent-filter, supported_event_hooks[pre_call, post_call], )挂载后请求发出前pre_call和响应返回后post_call都会经过你的检查逻辑在 LiteLLM Proxy 中还能看到对应的审计日志写一个自己的 LiteLLM 自定义插件四步清单把前面 3 分钟的例子泛化一下开发流程固定为四步建类继承CustomLogger在__init__里初始化你自己的状态计数器、客户端连接等覆写钩子只覆写你关心的事件——只记成功就写log_success_event还要兜底失败就补log_failure_event注册单次调用传callbacks[...]全局生效用litellm.callbacks [...]验证跑一次真实请求确认插件状态被正确更新再检查异常路径失败事件是否也触发了。钩子函数内部就是普通 Python 代码想接数据库、发消息、写文件都行框架不限制。容易踩的三个坑插件冲突多个插件挂到同一个钩子时执行顺序由注册顺序决定。如果两个插件都改写响应后一个会覆盖前一个的结果挂载前先想清楚先后关系。插件自己成为瓶颈钩子函数是同步执行在请求路径上的慢查询会拖慢每次 LLM 调用。两个缓解手段耗时操作改用async_log_success_event等异步方法高频写入参考 s3_v2.py 的批量上传实现攒一批再写。版本兼容CustomLogger的方法签名会随版本演进插件升级前先读一遍 CONTRIBUTING.md确认目标版本下钩子签名没变再跑回归。照着做今天就能落地最后给一份可以直接执行的清单确认需求属于哪类钩子成功日志 / 失败兜底 / 请求前拦截 / 响应后审计先看 litellm/integrations/ 里有没有现成插件有就直接用没有再继承CustomLogger自己写用最小的真实请求验证钩子触发时机与数据完整性给插件加超时与失败保护避免插件故障拖垮 LLM 调用把插件配置纳入版本管理升级 LiteLLM 时同步回归LiteLLM 插件系统把对接第三方从写适配层变成了实现一个类日志、监控、审计这类高频需求基本都有内置件可挑。如果你手上有现成的 LiteLLM 回调插件或者踩过的坑欢迎在评论区交流。下一篇想写《LiteLLM 多回调共存时如何控制执行顺序》有相关疑问可以先留言。【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考