LiteLLM 内部文档索引¶
本目录收录部署、运维、配置相关的补充文档，内容均为上游仓库未覆盖的项目定制细节。
chat-completions — 下游请求参数全景¶
面向下游应用开发人员，解释 /v1/chat/completions 到底能传哪些字段。
- README — 入口与关键结论：代理层不做 pydantic 校验、四类字段分类、drop_params 兜底机制
- 01-openai-standard-params — OpenAI 标准字段逐个解释 + provider 兼容矩阵
- 02-messages-and-content-blocks — messages 完整结构：6 种 role、9 种 content block type
- 03-tools-and-structured-output — tools / tool_choice / response_format 详解
- 04-litellm-specific-params — LiteLLM 特有 body 字段：metadata、guardrails、tags 等
- 05-provider-passthrough-and-drop-params — 未知字段的处理：extra_body 透传、drop_params
- 06-streaming-usage-field — streaming 场景下 usage 字段的返回时机与格式
billing-and-pricing — 计费与价格系统¶
- README — 整体架构图与两条计费路径速查
- 01-model-cost-map — 价格 JSON 文件的下载、初始化、本地 backup、热重载与局限
- 02-pgsql-lifecycle — PostgreSQL 价格数据的存储、加密、启动加载、30s 轮询
- 03-ui-pricing — UI 价格展示来源、字段优先级、编辑保存 API
- 04-billing-flow — 路由层计费触发、custom_pricing 判断、UUID/JSON 路径
- 05-cache-pricing-bugs — Anthropic cache 计费已知 bug、根因与修复配置方法
- 06-s3-cost-map — 从 S3 兼容存储签名读取 model cost map
trace-id — 全链路追踪（Trace ID / Session ID）¶
面向接入方与运维：trace_id 怎么传、流到哪里、UI 怎么搜、出问题怎么排。
- README — 整体架构图：双通道链路，速查表与入口导航
- 01-input-channels — trace_id 的 4 种输入入口及优先级
- 02-output-destinations — trace_id 的 6 个出口
- 03-ui-session-search — UI Logs 页 Session ID 前缀过滤
- 04-debugging — 验证脚本、SQL 速查、常见故障定位 checklist
health-check — 心跳与模型健康巡检¶
面向运维与开发：proxy 后台对每个上游模型 deployment 的周期性真实推理调用如何工作、怎么压成本、怎么排障。
- README — 整体架构图、配置项速查、决策树
- 01-mechanism — 启动入口、主循环、SharedHealthCheckManager 决策流程
- 02-config-reference — YAML / 环境变量 / model_info 字段全集
- 03-cost-reduction — 心跳成本三因子 + 推荐组合 + 常见误区
- 04-troubleshooting — 排障路径、多 Pod fallback 放大 bug、实战案例
prompt-caching — 上游 Prompt Cache 与路由黏性¶
- README — 总览：两套同名机制澄清、硬约束速查表
- 01-mechanism — 注册流程、cache key、路由命中、TTL、多 Pod 共享
- 02-config-reference — YAML 字段全集、环境变量、幻觉字段清单
- 03-provider-matrix — 各 provider 的 cache_control 格式与响应字段映射
- 04-billing-and-cost — 分级定价、拆分计费、已知 bug
- 05-best-practices — 启用决策清单、中转站验证、调试方法
cooldown — 冷却期与路由避让¶
- README — 总览架构图、触发路径速查、决策树
- 01-mechanism — 触发调用点、白名单、V1/V2 路径、Redis key、TTL 恢复
- 02-config-reference — YAML / 环境变量 / 单 deployment 配置 / Prometheus 指标
- 03-best-practices — 推荐 cooldown_time、跟 retry/fallback 叠加、常见误区
- 04-troubleshooting — 排障路径、状态观测、故障复现验证
errors — 错误体系全链路¶
面向运维与开发：25 个异常类的语义、上游 status_code 映射、Router 决策、症状反查。和 cooldown/ 互补。
- README — 总览架构图、异常→Router 决策→客户端→可观测性
- 01-exception-catalog — 全部 25 个异常类目录，按分类整理
- 02-provider-mapping — 跨 provider 映射矩阵、7 处已知不一致、接入新 provider checklist
- 03-router-behavior — Router 决策五步走、retry/fallback/cooldown 反应链
- 04-where-to-see — 一次失败的痕迹分布：客户端、日志、监控、S3
- 05-troubleshooting-by-symptom — 按症状反查根因、Case Study、工具命令速查
rate-limiting — 限流与额度（quota）¶
- README — 限流总链路图、四类限流器速查
- 01-limiter-types — max_budget / TPM / RPM / max_parallel_requests 四类限流器
- 02-pre-call-flow — Pre-call 阶段的限流检查链
- 03-spend-update-flow — Post-call 阶段：cost 计算 → DB spend 累加
- 04-cache-pricing-trap — cache 价格漏配导致 budget 限不住
- 05-skip-budget-checks-bug — _is_model_cost_zero 旁路跳过所有 budget 检查
- 06-user-request-limiter — 按用户请求数限流，Redis ZSET 滑动窗口