LiteLLM 错误排查指南从诊断到预防的完整解决方案【免费下载链接】litellmCall all LLM APIs using the OpenAI format. Use Bedrock, Azure, OpenAI, Cohere, Anthropic, Ollama, Sagemaker, HuggingFace, Replicate (100 LLMs)项目地址: https://gitcode.com/GitHub_Trending/li/litellm在现代 LLM 应用开发中错误处理与调试能力直接决定了系统的稳定性和用户体验。本文提供一套系统化的 LiteLLM 故障排查方法论涵盖认证失败、超时错误等六大核心故障类型通过问题诊断→解决方案→预防策略三阶框架帮助开发者快速定位问题根源并实施长效预防机制。我们将结合实战案例、监控指标和最佳实践构建全方位的错误应对体系确保您的 LLM 应用始终保持最佳运行状态。认证错误AuthenticationError密钥与权限问题诊断 问题诊断认证错误通常表现为 API 调用时的 401/403 响应状态码主要源于密钥配置或权限设置问题。典型错误信息包括Invalid API key或Permission denied。故障预警指标应用启动时无法加载环境变量首次 API 调用即失败无成功历史记录密钥轮换后立即出现认证失败诊断要点检查密钥格式是否符合提供商要求如 OpenAI 密钥以sk-开头验证环境变量加载路径与应用访问权限确认密钥是否具有目标模型的访问权限️ 解决方案✅ 推荐方案环境变量与密钥验证机制import os import litellm from litellm.exceptions import AuthenticationError def validate_api_keys(): 验证所有必要的API密钥是否已正确配置 required_keys { OPENAI_API_KEY: os.environ.get(OPENAI_API_KEY), ANTHROPIC_API_KEY: os.environ.get(ANTHROPIC_API_KEY) } missing_keys [k for k, v in required_keys.items() if not v] if missing_keys: raise AuthenticationError(f缺少必要的API密钥: {, .join(missing_keys)}) # 可选添加密钥格式验证 for key, value in required_keys.items(): if key OPENAI_API_KEY and not value.startswith(sk-): raise AuthenticationError(fOpenAI密钥格式无效: {value[:4]}...) # 在应用初始化阶段调用 try: validate_api_keys() print(所有API密钥验证通过) except AuthenticationError as e: print(f密钥验证失败: {str(e)}) # 处理初始化失败逻辑替代方案对比 | 方案 | 适用场景 | 优点 | 缺点 | |------|----------|------|------| | 环境变量 | 生产环境 | 安全符合云原生实践 | 配置管理复杂 | | 配置文件 | 开发环境 | 集中管理易于修改 | 密钥泄露风险 | | 密钥管理服务 | 企业级应用 | 高度安全支持自动轮换 | 集成复杂度高 | 预防策略密钥管理最佳实践使用.env文件配合python-dotenv管理开发环境密钥生产环境采用 Kubernetes Secrets 或云服务商密钥管理服务实施密钥定期轮换机制建议每 90 天更新一次权限最小化原则为不同环境创建专用 API 密钥开发/测试/生产针对特定模型和功能配置细粒度权限定期审计密钥使用记录撤销未使用的凭证预启动验证流程在应用启动脚本中添加密钥验证步骤实现密钥健康检查接口便于监控系统定期检测请求超时错误Timeout性能瓶颈分析与优化 问题诊断超时错误表现为 API 调用在指定时间内未收到响应通常与网络状况、服务负载或请求复杂度相关。LiteLLM 中典型的超时错误会包含timeout关键字及具体超时时间。故障预警指标响应时间中位数P50持续上升95% 响应时间P95超过 5 秒间歇性超时无明显规律图LiteLLM 代理服务器性能监控面板红框标注了响应时间中位数和每秒请求数(RPS)指标诊断要点区分客户端超时与服务端超时检查网络延迟和稳定性分析请求大小与复杂度️ 解决方案✅ 推荐方案智能超时与重试策略import litellm from litellm import completion from litellm.exceptions import Timeout import time from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type # 配置全局超时单位秒 litellm.timeout 10 # 默认超时时间 retry( stopstop_after_attempt(3), # 最多重试3次 waitwait_exponential(multiplier1, min2, max10), # 指数退避策略 retryretry_if_exception_type(Timeout), # 仅对超时错误重试 before_sleeplambda retry_state: print(f请求超时将在 {retry_state.next_action.sleep} 秒后重试...) ) def llm_completion_with_retry(model, messages, **kwargs): 带超时重试机制的LLM调用函数 # 动态调整超时时间根据模型和请求大小 adjusted_timeout calculate_dynamic_timeout(model, messages) try: response completion( modelmodel, messagesmessages, timeoutadjusted_timeout, **kwargs ) return response except Timeout as e: print(f请求超时: {str(e)}) raise # 触发重试机制 def calculate_dynamic_timeout(model, messages): 根据模型类型和消息长度动态计算超时时间 base_timeout 10 token_count estimate_token_count(messages) # 对长请求增加超时时间 if token_count 2000: base_timeout token_count // 1000 # 每1000 tokens增加1秒 # 对已知响应较慢的模型增加超时 slow_models [gpt-4, claude-2] if any(model.startswith(m) for m in slow_models): base_timeout * 1.5 return min(base_timeout, 30) # 最大超时不超过30秒 def estimate_token_count(messages): 估算消息的token数量 # 实现token估算逻辑可使用tiktoken库 return sum(len(str(msg)) // 4 for msg in messages) # 简化估算高级优化技巧请求分割将大型请求拆分为多个小请求实现增量处理流式响应使用streamTrue选项获取流式响应减少感知延迟模型降级在高负载时自动切换到响应更快的轻量模型 预防策略性能基准建立为每个模型建立响应时间基准线设置关键指标告警阈值如 P95 8 秒定期进行负载测试识别性能拐点网络优化选择与 LLM 服务地理位置接近的部署区域配置连接池复用 HTTP 连接实施请求压缩减少网络传输时间智能流量管理实现请求队列和背压机制基于时间段调整请求频率避开服务高峰期对敏感操作实施超时预警提前通知用户可能的延迟模型未找到错误NotFoundError模型配置与兼容性问题 问题诊断模型未找到错误通常发生在请求了 LiteLLM 不支持或配置不正确的模型时错误信息通常包含Model not found或Unsupported model。故障预警指标新添加的模型首次调用失败模型名称包含特殊字符或版本号最近更新了 LiteLLM 版本诊断要点验证模型名称是否符合 LiteLLM 规范检查模型是否在支持列表中确认模型配置是否正确特别是自定义模型️ 解决方案✅ 推荐方案模型验证与回退机制import litellm from litellm.exceptions import NotFoundError import json import os def load_supported_models(): 加载支持的模型列表 try: # 从 LiteLLM 配置文件加载支持的模型 with open(model_prices_and_context_window.json, r) as f: model_data json.load(f) return {model.lower() for model in model_data.keys()} except Exception as e: print(f加载模型列表失败: {str(e)}) # 返回默认支持的模型列表作为 fallback return {gpt-3.5-turbo, gpt-4, claude-2, llama-2-70b-chat} SUPPORTED_MODELS load_supported_models() def get_fallback_model(model): 获取模型的降级方案 fallback_map { gpt-4-turbo: gpt-4, gpt-4: gpt-3.5-turbo, claude-3-opus: claude-2, claude-3-sonnet: claude-2, # 添加更多模型的降级映射 } return fallback_map.get(model, gpt-3.5-turbo) # 默认降级到gpt-3.5-turbo def safe_llm_completion(model, messages, **kwargs): 安全的LLM调用函数包含模型验证和降级机制 # 标准化模型名称移除版本号转为小写 normalized_model model.split(:)[0].lower() # 检查模型是否支持 if normalized_model not in SUPPORTED_MODELS: print(f模型 {model} 不受支持尝试降级...) fallback_model get_fallback_model(normalized_model) print(f将使用降级模型: {fallback_model}) model fallback_model try: response litellm.completion( modelmodel, messagesmessages, **kwargs ) return response except NotFoundError as e: print(f模型 {model} 未找到: {str(e)}) # 尝试最终降级方案 final_fallback gpt-3.5-turbo print(f尝试最终降级模型: {final_fallback}) return litellm.completion( modelfinal_fallback, messagesmessages, **kwargs )自定义模型配置 对于自托管或自定义部署的模型需在 LiteLLM 配置文件中正确定义# proxy_model_config.yaml 示例 model_list: - model_name: custom-llama-7b litellm_params: model: ollama/llama2 api_base: http://localhost:11434 max_tokens: 4096 - model_name: custom-mistral litellm_params: model: huggingface/mistralai/Mistral-7B-Instruct-v0.1 api_key: your-hf-token api_base: https://api-inference.huggingface.co/models 预防策略模型管理规范维护项目级别的模型白名单实施模型版本控制避免频繁变更新模型上线前进行兼容性测试配置验证机制应用启动时验证所有模型配置定期同步 LiteLLM 最新支持的模型列表为自定义模型添加健康检查端点文档与培训维护项目支持的模型文档开发人员培训了解模型命名规范提供模型选择决策树帮助选择合适模型速率限制错误RateLimitError流量控制与资源优化 问题诊断速率限制错误发生在 API 调用频率超过服务提供商限制时错误信息通常包含Rate limit exceeded或Too many requests。故障预警指标单位时间内请求量突增错误率随请求量同步上升间歇性错误集中在高峰期诊断要点确认速率限制的具体类型请求数/令牌数/并发数分析请求模式识别峰值时段检查是否有异常流量或不当使用️ 解决方案✅ 推荐方案智能路由与流量控制from litellm import Router from litellm.exceptions import RateLimitError import time from collections import defaultdict # 记录每个API密钥的使用情况 api_key_metrics defaultdict(lambda: { requests: 0, tokens: 0, last_reset: time.time() }) # 配置API密钥池 model_list [ {model_name: gpt-3.5-turbo, api_key: sk-123, max_requests_per_minute: 300}, {model_name: gpt-3.5-turbo, api_key: sk-456, max_requests_per_minute: 300}, {model_name: gpt-3.5-turbo, api_key: sk-789, max_requests_per_minute: 300}, ] # 初始化路由器 router Router( model_listmodel_list, routing_strategyleast_busy, # 选择最空闲的API密钥 timeout60, retry2, # 重试次数 fallbacks[claude-2, llama-2-70b-chat] # 最终降级方案 ) def rate_limited_completion(messages, **kwargs): 带速率限制控制的LLM调用 try: # 检查并重置每分钟计数器 current_time time.time() for key_data in api_key_metrics.values(): if current_time - key_data[last_reset] 60: # 超过1分钟 key_data[requests] 0 key_data[tokens] 0 key_data[last_reset] current_time # 使用路由器进行调用 response router.completion( modelgpt-3.5-turbo, messagesmessages, **kwargs ) # 更新使用指标 api_key response[api_key_used] api_key_metrics[api_key][requests] 1 api_key_metrics[api_key][tokens] response[usage][total_tokens] return response except RateLimitError as e: print(f速率限制错误: {str(e)}) # 实施动态退避策略 current_load sum(data[requests] for data in api_key_metrics.values()) avg_load current_load / len(api_key_metrics) if api_key_metrics else 0 # 根据负载动态计算等待时间 wait_time min(60, max(2, avg_load * 0.1)) print(f所有密钥均达到速率限制等待 {wait_time:.2f} 秒后重试...) time.sleep(wait_time) # 递归重试 return rate_limited_completion(messages, **kwargs)流量控制策略对比 | 策略 | 实现方式 | 适用场景 | 效果 | |------|----------|----------|------| | 令牌桶算法 | 控制请求发放速率 | 稳定流量 | 平滑流量避免突发 | | 漏桶算法 | 固定速率处理请求 | 突发流量 | 严格控制输出速率 | | 优先级队列 | 按请求重要性排序 | 混合业务场景 | 保障核心功能可用 | | 动态限流 | 基于实时负载调整 | 波动流量 | 资源利用率最大化 | 预防策略流量规划实施请求流量预测提前扩容为不同API密钥设置差异化限流策略核心业务与非核心业务分离处理监控与告警实时监控速率限制指标设置预警阈值建立多级别告警机制警告、严重、紧急监控各API密钥使用均衡度弹性扩展建立API密钥自动扩容机制实现多云/多提供商容灾方案非关键功能自动降级机制上下文窗口超限错误ContextWindowExceededError令牌管理与优化 问题诊断上下文窗口超限错误发生在请求的令牌数超过模型最大上下文限制时错误信息通常包含context window exceeded或maximum context length。故障预警指标对话历史持续增长单次请求包含超长文本模型响应逐渐变慢然后失败诊断要点计算输入令牌数是否超过模型限制分析令牌分布提示/历史/响应检查是否有不必要的上下文信息️ 解决方案✅ 推荐方案智能上下文管理系统import litellm from litellm.exceptions import ContextWindowExceededError import tiktoken # 用于令牌计数 # 模型上下文窗口限制tokens MODEL_CONTEXT_LIMITS { gpt-3.5-turbo: 4096, gpt-3.5-turbo-16k: 16384, gpt-4: 8192, gpt-4-32k: 32768, claude-2: 100000, # 添加更多模型 } # 初始化令牌编码器 def get_encoder(model): 获取适合模型的令牌编码器 try: return tiktoken.encoding_for_model(model) except KeyError: # 回退到默认编码器 return tiktoken.get_encoding(cl100k_base) def count_tokens(text, encoder): 计算文本的令牌数 return len(encoder.encode(text)) def calculate_message_tokens(messages, encoder): 计算消息列表的总令牌数 total_tokens 0 for message in messages: # 每条消息的基础令牌数role content分隔符 total_tokens 4 for key, value in message.items(): total_tokens count_tokens(str(value), encoder) # 系统消息额外令牌 total_tokens 2 return total_tokens def optimize_context(messages, model, response_token_estimate500): 优化上下文确保不超过模型限制 context_limit MODEL_CONTEXT_LIMITS.get(model, 4096) encoder get_encoder(model) # 计算当前消息的令牌数 current_tokens calculate_message_tokens(messages, encoder) available_tokens context_limit - current_tokens - response_token_estimate if available_tokens 0: # 有足够空间无需优化 return messages, current_tokens # 需要优化计算需要减少的令牌数 tokens_to_reduce -available_tokens print(f上下文超限需要减少 {tokens_to_reduce} tokens) # 创建消息副本进行操作 optimized_messages messages.copy() # 策略1: 移除中间历史消息保留系统消息和最近的对话 if len(optimized_messages) 3: # 至少保留系统消息和最近两轮对话 # 从最早的非系统消息开始移除 system_msg None user_messages [] for msg in optimized_messages: if msg.get(role) system: system_msg msg else: user_messages.append(msg) # 只保留最近的N条消息 while user_messages and tokens_to_reduce 0: removed_msg user_messages.pop(0) removed_tokens calculate_message_tokens([removed_msg], encoder) tokens_to_reduce - removed_tokens # 重新构建消息列表 optimized_messages [] if system_msg: optimized_messages.append(system_msg) optimized_messages.extend(user_messages) # 检查是否仍然超限 current_tokens calculate_message_tokens(optimized_messages, encoder) available_tokens context_limit - current_tokens - response_token_estimate if available_tokens 0: return optimized_messages, current_tokens # 策略2: 总结早期对话历史 # (实现对话摘要逻辑此处省略) # 策略3: 截断最长的消息 # (实现消息截断逻辑此处省略) return optimized_messages, current_tokens def safe_completion(model, messages, **kwargs): 安全的Completion调用包含上下文优化 try: # 估算响应令牌数默认500可根据需求调整 response_token_estimate kwargs.pop(response_token_estimate, 500) # 优化上下文 optimized_messages, token_count optimize_context( messages, model, response_token_estimate ) print(f优化后上下文令牌数: {token_count}) # 调用LLM return litellm.completion( modelmodel, messagesoptimized_messages, **kwargs ) except ContextWindowExceededError as e: print(f上下文窗口超限错误: {str(e)}) # 尝试使用更大上下文的模型 larger_model get_larger_model_alternative(model) if larger_model: print(f尝试使用更大上下文的模型: {larger_model}) return safe_completion(larger_model, messages, **kwargs) raise # 无法处理向上抛出异常 def get_larger_model_alternative(model): 获取更大上下文窗口的替代模型 model_upgrades { gpt-3.5-turbo: gpt-3.5-turbo-16k, gpt-4: gpt-4-32k, # 添加更多模型升级路径 } return model_upgrades.get(model) 预防策略令牌管理最佳实践实施实时令牌计数在UI中显示令牌使用情况为不同模型设置安全阈值如最大限制的90%建立对话分段机制自动拆分长对话智能上下文策略实现对话摘要功能压缩历史对话基于语义重要性筛选上下文信息采用渐进式上下文加载按需添加历史信息用户体验优化提前警告用户接近上下文限制提供清理历史对话的选项自动建议切换到更大上下文模型服务不可用错误ServiceUnavailableError高可用架构与容灾方案 问题诊断服务不可用错误表示 LLM 服务暂时无法处理请求通常与服务维护、过载或网络问题相关。错误信息通常包含Service unavailable或503 Error。故障预警指标错误率突然上升响应时间显著增加特定提供商的请求集中失败️ 解决方案✅ 推荐方案多提供商容灾架构import litellm from litellm.exceptions import ServiceUnavailableError, APIError import time import logging from typing import List, Dict, Any # 配置日志 logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) # 多提供商配置 PROVIDER_CONFIG { primary: [ {model: gpt-3.5-turbo, api_key: os.environ.get(OPENAI_API_KEY)}, {model: gpt-4, api_key: os.environ.get(OPENAI_API_KEY)}, ], secondary: [ {model: claude-2, api_key: os.environ.get(ANTHROPIC_API_KEY)}, {model: claude-instant-1, api_key: os.environ.get(ANTHROPIC_API_KEY)}, ], tertiary: [ {model: llama-2-70b-chat, api_base: https://api.ollama.com, api_key: os.environ.get(OLLAMA_API_KEY)}, ] } # 服务健康状态跟踪 provider_health { openai: {healthy: True, last_failure: 0, retry_after: 0}, anthropic: {healthy: True, last_failure: 0, retry_after: 0}, ollama: {healthy: True, last_failure: 0, retry_after: 0}, } def get_provider(model: str) - str: 从模型名称获取提供商 if model.startswith((gpt-, davinci-, curie-, babbage-, ada-)): return openai elif model.startswith((claude-,)): return anthropic elif model.startswith((llama-, mistral-)): return ollama # 添加更多提供商判断 return unknown def is_provider_healthy(provider: str) - bool: 检查提供商是否健康 if not provider_health[provider][healthy]: # 检查是否过了重试等待时间 if time.time() - provider_health[provider][last_failure] provider_health[provider][retry_after]: # 尝试恢复健康状态 provider_health[provider][healthy] True logger.info(fProvider {provider} marked as healthy again after cooldown) else: return False return True def mark_provider_unhealthy(provider: str, retry_after: int 60): 标记提供商为不健康状态 provider_health[provider][healthy] False provider_health[provider][last_failure] time.time() provider_health[provider][retry_after] retry_after logger.warning(fProvider {provider} marked as unhealthy. Retry after {retry_after} seconds) def get_available_models(preferred_model: str) - List[Dict[str, Any]]: 获取可用的模型列表考虑健康状态和优先级 available [] # 首先尝试首选模型 for tier in [primary, secondary, tertiary]: for config in PROVIDER_CONFIG[tier]: if config[model] preferred_model: provider get_provider(preferred_model) if is_provider_healthy(provider): available.insert(0, config) # 放在最前面 return available # 按优先级添加所有健康的模型 for tier in [primary, secondary, tertiary]: for config in PROVIDER_CONFIG[tier]: provider get_provider(config[model]) if is_provider_healthy(provider): available.append(config) return available def high_availability_completion(preferred_model: str, messages: List[Dict[str, str]], **kwargs): 高可用的Completion调用支持多提供商故障转移 available_models get_available_models(preferred_model) if not available_models: raise ServiceUnavailableError(所有LLM提供商当前都不可用) last_error None for model_config in available_models: model model_config[model] provider get_provider(model) try: logger.info(f尝试调用模型: {model} (提供商: {provider})) response litellm.completion( modelmodel, messagesmessages, api_keymodel_config.get(api_key), api_basemodel_config.get(api_base), **kwargs ) # 调用成功记录并返回 logger.info(f成功使用模型 {model} 完成请求) return response except (ServiceUnavailableError, APIError) as e: last_error e logger.error(f模型 {model} 调用失败: {str(e)}) mark_provider_unhealthy(provider) except Exception as e: last_error e logger.error(f模型 {model} 发生意外错误: {str(e)}) # 非服务不可用错误不标记提供商为不健康 # 所有模型都失败 raise ServiceUnavailableError( f所有可用模型调用失败。最后错误: {str(last_error)} ) 预防策略多提供商架构至少配置2-3个不同的LLM提供商实施流量分配策略如70%主提供商30%备用定期测试故障转移机制健康检查系统实施主动健康检查每30秒建立多层级告警机制自动恢复流程与人工干预升级路径容量规划监控各提供商的服务状态和性能建立流量预测模型提前扩容非关键功能降级机制主动监控体系构建 LiteLLM 可观测性平台有效的监控是预防和解决 LiteLLM 错误的关键。建立完善的监控体系可以帮助您在问题影响用户之前发现并解决它们。关键监控指标性能指标请求延迟P50/P95/P99请求吞吐量RPS成功率与错误率令牌使用量输入/输出/总令牌资源指标API 密钥使用情况模型调用分布提供商健康状态并发请求数监控工具集成图LiteLLM 与 Langfuse 集成的监控界面展示了完整的请求追踪、性能指标和成本分析推荐监控工具链LangfuseLLM 应用专用观测平台支持请求追踪、性能分析和成本监控Prometheus Grafana开源监控解决方案适合自定义指标和告警LiteLLM 内置监控proxy 模式下提供的原生监控界面集成示例# Langfuse 集成示例 import litellm from langfuse import Langfuse from langfuse.callback import CallbackHandler # 初始化 Langfuse langfuse Langfuse( public_keypk-lf-..., secret_keysk-lf-..., hosthttps://cloud.langfuse.com ) # 创建回调处理器 langfuse_handler CallbackHandler( langfuselangfuse, trace_namelitellm-completion, user_iduser-123 ) # 使用回调进行监控 response litellm.completion( modelgpt-3.5-turbo, messages[{role: user, content: Hello, world!}], callbacks[langfuse_handler] )告警策略关键告警阈值错误率 1%警告 5%严重P95 延迟 5 秒警告 10 秒严重令牌使用量超出日预算 80%警告100%严重特定提供商错误率 10%警告告警渠道Slack/Teams 即时消息通知邮件详细报告PagerDuty 紧急告警生产环境严重错误故障速查表常见问题与解决方案摘要错误类型诊断要点快速解决方案预防措施认证错误密钥无效或权限不足检查密钥格式和环境变量使用密钥管理服务定期轮换超时错误响应时间长网络问题增加超时时间实现重试监控响应时间优化网络模型未找到模型名称错误或不支持验证模型名称检查配置维护模型白名单版本控制速率限制请求频率超过限制使用多密钥路由实施限流流量控制错峰调用上下文超限令牌数超过模型限制优化上下文截断历史实时令牌计数自动摘要服务不可用提供商服务中断切换备用提供商多提供商架构健康检查总结与最佳实践成功的 LiteLLM 错误处理需要综合诊断、解决和预防三个层面的策略。通过本文介绍的方法您可以建立一个健壮的错误处理体系分层防御实施前端验证、中间层限流和后端容错的多层防御机制数据驱动基于监控数据不断优化错误处理策略持续学习记录和分析错误模式持续改进预防措施自动化尽可能自动化错误检测、诊断和恢复流程记住最有效的错误处理是预防。通过建立完善的监控体系、实施合理的资源管理策略和采用多提供商架构您可以显著减少 LiteLLM 错误对应用的影响提供更可靠的 LLM 服务体验。无论您是在开发初期还是维护成熟的生产系统本文介绍的方法和最佳实践都将帮助您构建更健壮、更可靠的 LLM 应用。【免费下载链接】litellmCall all LLM APIs using the OpenAI format. Use Bedrock, Azure, OpenAI, Cohere, Anthropic, Ollama, Sagemaker, HuggingFace, Replicate (100 LLMs)项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考