LiteLLM 计费与价格系统全链路文档

本系列文档完整描述 LiteLLM 代理服务中价格数据的流动路径，从 JSON 价格文件的下载、PostgreSQL 的读写、UI 展示与编辑，到最终路由层的计费计算，涵盖所有关键节点、代码位置与已知陷阱。

---

文档目录

文件	内容
01-model-cost-map.md	价格 JSON 文件的下载、初始化、本地 backup、热重载与局限
02-pgsql-lifecycle.md	PostgreSQL 中价格数据的存储、加密、启动加载、轮询更新
03-ui-pricing.md	UI 的价格展示来源、字段优先级、编辑保存的 API 路径与写 DB 行为
04-billing-flow.md	路由层计费的触发、custom_pricing 判断、UUID/JSON 两条路径、cache 计算
05-cache-pricing-bugs.md	Anthropic cache 计费的已知 bug、根因与修复方法
06-s3-cost-map.md	从 S3 兼容存储签名读取 model cost map：环境变量、加载优先级、启动摘要、热重载

---

整体架构一览

flowchart TD
    subgraph 初始化阶段
        A[import litellm] --> B{LITELLM_LOCAL_MODEL_COST_MAP?}
        B -- true --> C[读 backup JSON\nlitellm/model_prices_and_context_window_backup.json]
        B -- false --> S{S3 四变量齐全?}
        S -- 是 --> D1[boto3 SigV4 从 S3 读取\ns3://S3_BUCKET_NAME/MODEL_COST_MAP_S3_KEY]
        S -- 否 --> D2[GET GitHub 远程 JSON\n超时5s, 失败 fallback 到 backup]
        C --> E[litellm.model_cost dict\n进程级全局对象]
        D1 --> E
        D2 --> E
    end

    subgraph 启动阶段
        F[proxy_startup_event] --> G[add_deployment\nproxy_server.py:5714]
        G --> H[读 DB LiteLLM_ProxyModelTable]
        H --> I[decrypt litellm_params]
        I --> J[Router._create_deployment\nrouter.py:6173]
        J --> K[litellm.register_model UUID entry\nrouter.py:6204]
        K --> E
    end

    subgraph 30s 轮询
        L[APScheduler\n每30秒] --> M[add_deployment]
        M --> N[upsert_deployment\nrouter.py:6744]
        N -- litellm_params 有变化 --> J
        N -- 无变化 --> O[skip]
    end

    subgraph UI 保存
        P[PATCH /model/id/update] --> Q[update_db_model\n加密写 DB]
        Q --> R[clear_cache\n立即重载]
        R --> J
    end

    subgraph 请求计费
        S[LLM 请求完成] --> T[calculate_request_cost\nlitellm_logging.py:1381]
        T --> U{use_custom_pricing_for_model?}
        U -- True\nlitellm_params 有价格字段 --> V[用 UUID 查\nlitellm.model_cost UUID]
        U -- False\n无价格字段 --> W[用 model name 5步 fallback\n查 litellm.model_cost]
        V --> X[generic_cost_per_token\nllm_cost_calc/utils.py:580]
        W --> X
        X --> Y[calculate_cache_writing_cost\n5m vs 1hr 分拆计算]
    end

    E -.被查询.-> V
    E -.被查询.-> W

---

两条计费路径速查

	UUID 路径（custom_pricing=True）	JSON 路径（custom_pricing=False）
触发条件	litellm_params 中有任意 _CUSTOM_PRICING_KEYS 字段非 None	litellm_params 中无任何价格字段
价格来源	litellm.model_cost[UUID]，由 _create_deployment() 写入	litellm.model_cost[model_name]，由 JSON 文件初始化
何时更新	UI 保存后立即（clear_cache），或 30s 轮询检测到参数变化	重启或热重载 /reload/model_cost_map
cache 字段	来自 DB litellm_params，字段缺失时静默为 0	来自 JSON 文件对应 key
典型陷阱	cache_creation_input_token_cost_above_1hr 缺失 → 1hr cache 免费	JSON key 必须与 provider/model 格式匹配