StandardLoggingPayload 规范

位于 kwargs["standard_logging_object"]。这是一个标准载荷，记录每一次成功和失败的响应。

StandardLoggingPayload

字段	类型	描述
`id`	`字符串`	唯一标识符
`trace_id`	`字符串`	追踪属于同一整体请求的多个 LLM 调用
`call_type`	`字符串`	调用类型
`response_cost`	`float`	以美元 ($) 计算的响应成本
`cost_breakdown`	`Optional[CostBreakdown]`	详细的成本明细对象
`response_cost_failure_debug_info`	`StandardLoggingModelCostFailureDebugInformation`	成本跟踪失败时的调试信息
`status`	`StandardLoggingPayloadStatus`	载荷状态
`status_fields`	`StandardLoggingPayloadStatusFields`	用于轻松过滤和分析的类型化状态字段
`total_tokens`	`整数`	Token 总数
`prompt_tokens`	`整数`	提示词 (prompt) token 数量
`completion_tokens`	`整数`	补全 (completion) token 数量
`startTime`	`float`	调用开始时间
`endTime`	`float`	调用结束时间
`completionStartTime`	`float`	流式请求的首字响应时间
`response_time`	`float`	总响应时间。如果为流式请求，则为首字响应时间
`model_map_information`	`StandardLoggingModelInformation`	模型映射信息
`model`	`字符串`	请求中发送的模型名称
`model_id`	`Optional[str]`	所用部署的模型 ID
`model_group`	`Optional[str]`	请求使用的 `model_group`
`api_base`	`字符串`	LLM API 基础 URL
`metadata`	`StandardLoggingMetadata`	元数据信息
`cache_hit`	`Optional[bool]`	是否命中缓存
`cache_key`	`Optional[str]`	可选的缓存键
`saved_cache_cost`	`float`	通过缓存节省的成本
`request_tags`	`列表`	请求标签列表
`end_user`	`Optional[str]`	可选的终端用户标识符
`requester_ip_address`	`Optional[str]`	可选的请求者 IP 地址
`messages`	`Optional[Union[str, list, dict]]`	请求中发送的消息
`response`	`Optional[Union[str, list, dict]]`	LLM 响应
`error_str`	`Optional[str]`	可选的错误字符串
`error_information`	`Optional[StandardLoggingPayloadErrorInformation]`	可选的错误信息
`model_parameters`	`dict`	模型参数
`hidden_params`	`StandardLoggingHiddenParams`	隐藏参数

成本明细

cost_breakdown 字段提供补全请求的详细成本明细，作为包含以下内容的 CostBreakdown 对象：

input_cost：输入/提示词 token 的成本，包括缓存创建 token
output_cost：输出/补全 token 的成本（如果适用，包括推理 token）
tool_usage_cost：内置工具使用成本（例如，网页搜索、代码解释器）
total_cost：输入 + 输出 + 工具使用的总成本

注意：此字段适用于所有调用类型。对于非补全调用，input_cost 和 output_cost 可能为 0。

总成本关系为：response_cost = cost_breakdown.total_cost

CostBreakdown 类型

class CostBreakdown(TypedDict, total=False):
    input_cost: float        # Cost of input/prompt tokens in USD
    output_cost: float       # Cost of output/completion tokens in USD (includes reasoning)
    tool_usage_cost: float   # Cost of built-in tools usage in USD
    total_cost: float        # Total cost in USD

StandardLoggingUserAPIKeyMetadata

字段	类型	描述
`user_api_key_hash`	`Optional[str]`	LiteLLM 虚拟密钥的哈希值
`user_api_key_alias`	`Optional[str]`	API 密钥的别名
`user_api_key_org_id`	`Optional[str]`	与密钥关联的组织 ID
`user_api_key_team_id`	`Optional[str]`	与密钥关联的团队 ID
`user_api_key_user_id`	`Optional[str]`	与密钥关联的用户 ID
`user_api_key_team_alias`	`Optional[str]`	与密钥关联的团队别名

StandardLoggingMetadata

继承自 StandardLoggingUserAPIKeyMetadata 并添加以下内容：

字段	类型	描述
`spend_logs_metadata`	`Optional[dict]`	用于支出日志的键值对
`requester_ip_address`	`Optional[str]`	请求者的 IP 地址
`requester_metadata`	`Optional[dict]`	附加的请求者元数据
`vector_store_request_metadata`	`Optional[List[StandardLoggingVectorStoreRequest]]`	向量数据库请求元数据
`requester_custom_headers`	Dict[str, str]	客户端发送到代理的任何自定义 (`x-`) 标头。
`prompt_management_metadata`	`Optional[StandardLoggingPromptManagementMetadata]`	提示词管理和版本控制元数据
`mcp_tool_call_metadata`	`Optional[StandardLoggingMCPToolCall]`	MCP（模型上下文协议）工具调用信息和成本跟踪
`applied_guardrails`	`Optional[List[str]]`	已应用的安全护栏 (guardrail) 名称列表
`usage_object`	`Optional[dict]`	来自 LLM 提供商的原始使用量对象
`cold_storage_object_key`	`Optional[str]`	用于冷存储检索的 S3/GCS 对象键
`guardrail_information`	`Optional[list[StandardLoggingGuardrailInformation]]`	安全护栏信息

StandardLoggingVectorStoreRequest

字段	类型	描述
vector_store_id	Optional[str]	向量数据库 ID
custom_llm_provider	Optional[str]	向量数据库关联的自定义 LLM 提供商（例如：bedrock, openai, anthropic）
query	Optional[str]	向量数据库查询
vector_store_search_response	Optional[VectorStoreSearchResponse]	OpenAI 格式的向量数据库搜索响应
start_time	Optional[float]	向量数据库请求开始时间
end_time	Optional[float]	向量数据库请求结束时间

StandardLoggingAdditionalHeaders

字段	类型	描述
`x_ratelimit_limit_requests`	`整数`	请求速率限制
`x_ratelimit_limit_tokens`	`整数`	Token 速率限制
`x_ratelimit_remaining_requests`	`整数`	剩余请求额度
`x_ratelimit_remaining_tokens`	`整数`	剩余 Token 额度

StandardLoggingHiddenParams

字段	类型	描述
`model_id`	`Optional[str]`	可选的模型 ID
`cache_key`	`Optional[str]`	可选的缓存键
`api_base`	`Optional[str]`	可选的 API 基础 URL
`response_cost`	`Optional[str]`	可选的响应成本
`additional_headers`	`Optional[StandardLoggingAdditionalHeaders]`	附加标头
`batch_models`	`Optional[List[str]]`	仅针对批处理 API 设置。列出用于成本计算的模型
`litellm_model_name`	`Optional[str]`	请求中发送的模型名称

StandardLoggingModelInformation

字段	类型	描述
`model_map_key`	`字符串`	模型映射键
`model_map_value`	`Optional[ModelInfo]`	可选的模型信息

StandardLoggingModelCostFailureDebugInformation

字段	类型	描述
`error_str`	`字符串`	错误字符串
`traceback_str`	`字符串`	回溯字符串
`model`	`字符串`	模型名称
`cache_hit`	`Optional[bool]`	是否命中缓存
`custom_llm_provider`	`Optional[str]`	可选的自定义 LLM 提供商
`base_model`	`Optional[str]`	可选的基础模型
`call_type`	`字符串`	调用类型
`custom_pricing`	`Optional[bool]`	是否使用了自定义定价

StandardLoggingPayloadErrorInformation

字段	类型	描述
`error_code`	`Optional[str]`	可选的错误代码（例如 "429"）
`error_class`	`Optional[str]`	可选的错误类（例如 "RateLimitError"）
`llm_provider`	`Optional[str]`	返回错误的 LLM 提供商（例如 "openai"）

StandardLoggingPayloadStatus

具有两个可能值的字面量类型

"success"
"failure"

StandardLoggingGuardrailInformation

字段	类型	描述
`guardrail_name`	`Optional[str]`	安全护栏名称
`guardrail_provider`	`Optional[str]`	安全护栏提供商
`guardrail_mode`	`Optional[Union[GuardrailEventHooks, List[GuardrailEventHooks]]]`	安全护栏模式
`guardrail_request`	`Optional[dict]`	安全护栏请求
`guardrail_response`	`Optional[Union[dict, str, List[dict]]]`	安全护栏响应
`guardrail_status`	`Literal["success", "guardrail_intervened", "guardrail_failed_to_respond"]`	安全护栏执行状态：`success` = 未检测到违规，`blocked` = 因策略违规导致内容被拦截/修改，`failure` = 技术错误或 API 失败
`start_time`	`Optional[float]`	安全护栏开始时间
`end_time`	`Optional[float]`	安全护栏结束时间
`duration`	`Optional[float]`	安全护栏持续时间（秒）
`masked_entity_count`	`Optional[Dict[str, int]]`	掩码实体计数

StandardLoggingPayloadStatusFields

用于轻松过滤和分析的类型化状态字段。

字段	类型	描述
`llm_api_status`	`StandardLoggingPayloadStatus`	LLM API 调用状态：`"success"` 表示成功完成，`"failure"` 表示报错
`guardrail_status`	`GuardrailStatus`	安全护栏执行状态（见下文）

StandardLoggingPayloadStatus

具有两个可能值的字面量类型

"success" - LLM API 请求成功完成
"failure" - LLM API 请求失败

GuardrailStatus

具有四个可能值的字面量类型

"success" - 安全护栏已运行并允许内容通过（未检测到违规）
"guardrail_intervened" - 安全护栏因策略违规拦截或修改了内容
"guardrail_failed_to_respond" - 安全护栏发生技术故障或 API 错误
"not_run" - 此请求未运行安全护栏

使用示例

过滤安全护栏介入的请求日志

{
  "status_fields": {
    "guardrail_status": "guardrail_intervened"
  }
}

查找安全护栏技术故障

{
  "status_fields": {
    "guardrail_status": "guardrail_failed_to_respond"
  }
}

获取成功的 LLM 请求

{
  "status_fields": {
    "llm_api_status": "success"
  }
}

查找安全护栏成功运行且未介入的请求

{
  "status_fields": {
    "guardrail_status": "success",
    "llm_api_status": "success"
  }
}

查找未运行安全护栏的请求

{
  "status_fields": {
    "guardrail_status": "not_run"
  }
}

StandardLoggingPromptManagementMetadata

用于跟踪提示词版本控制和管理信息。

字段	类型	描述
`prompt_id`	`字符串`	必填。提示词模板或版本的唯一标识符
`prompt_variables`	`Optional[dict]`	提示词模板中使用的变量/参数（例如：`{"user_name": "John", "context": "support"}`）
`prompt_integration`	`字符串`	必填。管理提示词的集成或系统（例如：`"langfuse"`, `"promptlayer"`, `"custom"`）

StandardLoggingMCPToolCall

用于跟踪 LiteLLM 请求中的模型上下文协议 (MCP) 工具调用。这为外部工具集成提供了详细的日志记录。

字段	类型	描述
`name`	`字符串`	必填。正在调用的工具名称（例如：`"get_weather"`, `"search_database"`）
`arguments`	`dict`	必填。作为键值对传递给工具的参数
`result`	`Optional[dict]`	工具执行返回的响应/结果（由自定义日志记录钩子填充）
`mcp_server_name`	`Optional[str]`	处理工具调用的 MCP 服务器名称（例如：`"weather-service"`, `"database-connector"`）
`mcp_server_logo_url`	`Optional[str]`	MCP 服务器 Logo 的 URL（用于 LiteLLM 仪表板的 UI 显示）
`namespaced_tool_name`	`Optional[str]`	包含服务器前缀的完全限定工具名称（例如：`"deepwiki-mcp/get_page_content"`, `"github-mcp/create_issue"`）
`mcp_server_cost_info`	`Optional[MCPServerCostInfo]`	工具调用的成本跟踪信息

MCPServerCostInfo

MCP 服务器工具调用的成本跟踪结构

字段	类型	描述
`default_cost_per_query`	`Optional[float]`	对此 MCP 服务器的任何工具调用的默认美元成本
`tool_name_to_cost_per_query`	`Optional[Dict[str, float]]`	用于精细定价的每工具成本映射（例如：`{"search": 0.01, "create": 0.05}`）

用法

# Basic MCP tool call metadata
mcp_tool_call = {
    "name": "search_documents",
    "arguments": {
        "query": "machine learning tutorials",
        "limit": 10,
        "filter": "type:pdf"
    },
    "mcp_server_name": "document-search-service",
    "namespaced_tool_name": "docs-mcp/search_documents",
    "mcp_server_cost_info": {
        "default_cost_per_query": 0.02,
        "tool_name_to_cost_per_query": {
            "search_documents": 0.02,
            "get_document": 0.01
        }
    }
}

# optional result field (via custom logging hooks)
mcp_tool_call_with_result = {
    "name": "search_documents",
    "arguments": {
        "query": "machine learning tutorials",
        "limit": 10,
        "filter": "type:pdf"
    },
    "result": {
        "documents": [...],
        "total_found": 42,
        "search_time_ms": 150
    },
    "mcp_server_name": "document-search-service",
    "namespaced_tool_name": "docs-mcp/search_documents",
    "mcp_server_cost_info": {
        "default_cost_per_query": 0.02,
        "tool_name_to_cost_per_query": {
            "search_documents": 0.02,
            "get_document": 0.01
        }
    }
}

StandardLoggingPayload​

成本明细​

CostBreakdown 类型​

StandardLoggingUserAPIKeyMetadata​

StandardLoggingMetadata​

StandardLoggingVectorStoreRequest​

StandardLoggingAdditionalHeaders​

StandardLoggingHiddenParams​

StandardLoggingModelInformation​

StandardLoggingModelCostFailureDebugInformation​

StandardLoggingPayloadErrorInformation​

StandardLoggingPayloadStatus​

StandardLoggingGuardrailInformation​

StandardLoggingPayloadStatusFields​

StandardLoggingPayloadStatus​

GuardrailStatus​

使用示例​

StandardLoggingPromptManagementMetadata​

StandardLoggingMCPToolCall​

MCPServerCostInfo​

用法​

StandardLoggingPayload

成本明细

CostBreakdown 类型

StandardLoggingUserAPIKeyMetadata

StandardLoggingMetadata

StandardLoggingVectorStoreRequest

StandardLoggingAdditionalHeaders

StandardLoggingHiddenParams

StandardLoggingModelInformation

StandardLoggingModelCostFailureDebugInformation

StandardLoggingPayloadErrorInformation

StandardLoggingPayloadStatus

StandardLoggingGuardrailInformation

StandardLoggingPayloadStatusFields

StandardLoggingPayloadStatus

GuardrailStatus

使用示例

StandardLoggingPromptManagementMetadata

StandardLoggingMCPToolCall

MCPServerCostInfo

用法