LLM 请求怎样记录 token 用量而不泄露正文

LLM 请求可以记录 token 用量，但不应该把 prompt、回答原文、Authorization 或完整请求体一起写进普通应用日志。比较稳妥的边界是：请求进入时生成短期 request_id，只记录模型、提供商、耗时、状态和 token 计数；正文仍在受控链路中处理，日志只保留经过脱敏的摘要或长度。

官方地址：https://huggingface.co/docs/inference-providers/tasks/chat-completion

非流式响应直接读取 usage 对象；流式响应要打开 include_usage，并只接收最后的用量块。日志字段采用白名单，正文默认不落盘。

先把可记录字段和正文分开

Hugging Face 的 Chat Completion 兼容响应包含 usage，常见字段是 prompt_tokens、completion_tokens 和 total_tokens。这些字段适合做按模型、租户或时间窗口的聚合。相反，消息数组、工具参数、完整回答和鉴权头都不应作为默认日志字段。

可以先定义一份窄日志结构，遇到新字段也不会因为“方便调试”而自动扩散：

# 只把白名单元数据写入日志，不记录 messages 和完整 choices
def usage_event(response, request_id, model, elapsed_ms, status):
    usage = response.get("usage") or {}
    return {
        "request_id": request_id,       # 便于关联链路，但不使用正文作 ID
        "model": model,
        "elapsed_ms": elapsed_ms,
        "status": status,
        "prompt_tokens": usage.get("prompt_tokens"),
        "completion_tokens": usage.get("completion_tokens"),
        "total_tokens": usage.get("total_tokens"),
    }

这里的 None 是正常分支：某些代理、错误响应或尚未结束的流式片段可能暂时没有 usage。不要为了补齐字段而把原始响应整体打印出来。

非流式和流式用量要分开处理

非流式请求在响应结束时读取一次 usage 即可。流式请求则不同：每个增量只代表部分文本，不能把每个片段的 token 数累加成最终账单。按 Hugging Face 文档，流式调用应设置 stream_options.include_usage，在结束前接收一个包含整体 usage 的额外块。

# 流式响应只在 usage 存在时记录一次最终用量
def consume_stream(chunks, request_id):
    final_usage = None
    for chunk in chunks:
        if chunk.get("usage") is not None:
            final_usage = chunk["usage"]  # 结束块提供整次请求统计
        # 业务层可继续转发 delta，但不要把 delta 原文写入日志
    if final_usage is None:
        return {"request_id": request_id, "usage_status": "missing"}
    return {"request_id": request_id, "usage_status": "complete", **final_usage}

如果上游没有返回 usage，记录 usage_status=missing 并保留请求状态即可。不要用字符数或本地估算值冒充供应商返回的 token 计数。

在应用边界做脱敏，而不是事后清洗

日志拦截器应在序列化前完成字段白名单。对确实需要定位问题的场景，只保留正文长度、模板版本、哈希化的业务对象标识或固定长度的脱敏摘要；不要记录可逆的 Base64，也不要把 API key、工具参数和用户输入藏在异常对象里。

# 对可选诊断信息做固定长度脱敏，默认不返回原文
def redact_text(text, limit=24):
    if not text:
        return {"present": False, "length": 0}
    return {
        "present": True,
        "length": len(text),
        "preview": "[REDACTED]",  # 固定占位，避免日志泄露正文
        "truncated": len(text) > limit,
    }

保留策略也要写进规范：例如生产日志只保留 7 天的用量明细，聚合报表保留更久；访问日志、应用日志和成本报表分别设置权限。Hugging Face Inference Endpoints 的安全文档对其服务端 payload 和 tokens 的处理有明确说明，但这不等于应用自己的日志、APM 和异常平台会自动安全，调用方仍需独立设置边界。

上线前用一张字段清单收口

最后检查三件事：非流式是否只在结束时读 usage；流式是否等待 include_usage 的最终块；异常和重试路径是否复用了同一套脱敏器。做到这三点，token 统计和正文保护就不会互相冲突。

常见问题

为什么 total_tokens 为空？上游可能返回错误、代理未透传 usage，或流还没结束。记录缺失状态，不要打印原始响应补查。

能否只记录 prompt_tokens？可以，但成本和输出效率分析会缺少 completion_tokens；应在字段协议中明确缺失含义。

哈希后的正文就一定安全吗？不一定。短文本、低熵标识或可枚举内容可能被反推，生产日志优先记录长度、模板版本和业务关联 ID。