游戏 AI / 系统课时

用请求日志追踪版本与上下文

用请求日志追踪版本与上下文

玩家问同一句话,NPC 昨天守口如瓶、今天却泄露任务答案,单看回复内容无法判断是模型、提示还是世界状态发生了变化。本课建立可关联且经过脱敏的请求日志,追到每轮回复实际使用的版本、上下文、检索证据、耗时和失败阶段。

学习目标

  • 确定一轮 NPC 请求必须记录的版本、来源与分段耗时。
  • 使用 Python 输出不含玩家原话的结构化 JSON 日志。
  • 利用请求标识排查异常,同时控制敏感数据的访问与留存。

先给每轮请求建立追踪边界

服务端收到对话请求后分配或校验 requestId,在上下文组装、模型调用、输出校验和返回客户端的日志中沿用它。一次请求重试时增加 attempt,新的玩家提问使用新的 requestId。不要只按 sessionId 查找,否则会把多轮对话混在一起。

每个阶段事件记录 stage、status 和时间戳,并约定耗时起点。比如以服务端接收请求为起点,queueMs 表示等候处理的时间,firstTokenMs 表示首段有效回复到达时间,totalMs 表示通过最终校验的完成时间。客户端另记展示时间,避免把 UI 卡顿误判成模型延迟。

记录版本、上下文摘要和检索来源

版本字段必须来自本次实际运行的配置,而非日志采集时读取的最新默认值。至少保留 model、promptVersion、npcProfileVersion、memoryVersion 和 worldSnapshotId;结构化响应协议发生变化时,再加 responseSchemaVersion。采样等生成参数只记录实际传给模型且被接口接受的值。

上下文正文不应默认进入日志。可以白名单记录 questStage=gate_closed、nearbyCount=2 等必要事实摘要,再对规范化上下文计算带密钥的 HMAC 指纹 contextDigest。retrievalRefs 保存文档片段标识与版本,便于核实证据来源;指纹只能判断内容是否一致,不能把原文还原出来。

NPC 请求关联标识与脱敏日志数据流

用 Python 输出一条脱敏日志

下面的程序只依赖 Python 标准库,使用固定的教学数据生成一次成功请求记录。实际项目应当从服务端执行链路采集字段,而不是将示例中的模型名、耗时当成真实服务结果。

python
import hashlib
import hmac
import json

def digest(value, key):
    # 用带密钥的摘要替代可被枚举的玩家标识和上下文原文。
    packed = json.dumps(
        value, ensure_ascii=False, sort_keys=True, separators=(",", ":")
    ).encode("utf-8")
    return hmac.new(key, packed, hashlib.sha256).hexdigest()[:20]

def make_event():
    key = b"demo-key-not-for-production"
    player_id = "player-7"
    context = {"questStage": "gate_closed", "nearbyCount": 2}
    # 摘要只选择允许进入日志的游戏状态字段。
    return {
        "event": "npc.reply.completed",
        "requestId": "demo-21",
        "attempt": 1,
        "npcId": "guard-2",
        "playerToken": digest(player_id, key),
        "model": "example-model",
        "promptVersion": "guard-v3",
        "npcProfileVersion": "guard-npc-v2",
        "memoryVersion": 12,
        "worldSnapshotId": "world-44",
        "contextDigest": digest(context, key),
        "contextSummary": context,
        "retrievalRefs": ["gate-policy@v2#c3"],
        "latencyMs": {"queue": 40, "firstToken": 280, "total": 910},
        "status": "ok",
        "errorCode": None,
    }

if __name__ == "__main__":
    print(json.dumps(make_event(), ensure_ascii=False, sort_keys=True, separators=(",", ":")))

预期输出:

json
{"attempt":1,"contextDigest":"0c891a3b10dc9f9b9442","contextSummary":{"nearbyCount":2,"questStage":"gate_closed"},"errorCode":null,"event":"npc.reply.completed","latencyMs":{"firstToken":280,"queue":40,"total":910},"memoryVersion":12,"model":"example-model","npcId":"guard-2","npcProfileVersion":"guard-npc-v2","playerToken":"05ad7460635e754a03ae","promptVersion":"guard-v3","requestId":"demo-21","retrievalRefs":["gate-policy@v2#c3"],"status":"ok","worldSnapshotId":"world-44"}

example-model、demo-21 和 world-44 均为固定教学标识;真实请求的 ID、时间与耗时会不同。密钥硬编码仅用于演示,生产环境应从受控密钥管理系统读取,并记录摘要密钥版本,以免轮换后误将不同指纹当成上下文变化。

用同一条链路定位错误和性能退化

出现异常时,先按 requestId 聚合各阶段日志,再按 attempt 区分重试。对照正常请求时,先比较 model 与 promptVersion,再检查 worldSnapshotId、memoryVersion、contextDigest 和 retrievalRefs。相同模型却突然答错任务状态,通常应先确认世界快照或记忆是否发生变化,而不是直接修改提示词。

例如预算为 800ms,日志显示 queueMs=40、firstTokenMs=280、totalMs=910,说明最终完成超出预算 110ms,但不能由这三个值直接认定排队是瓶颈。还需增加生成耗时、输出校验耗时和客户端呈现耗时的阶段事件进行判断。

失败事件记录 status=error、failedStage、应用自定义的 errorCode 和是否重试;外部接口错误先映射为超时、限流、认证等受控类别,避免把包含玩家内容的原始异常对象直接写入日志。本例只有一条完成事件,线上应把同一标识贯穿所有阶段事件。

控制隐私边界并保留复现能力

默认不记录玩家原话、完整对话历史、召回片段正文、访问密钥或可能夹带提示文本的异常堆栈。带密钥的玩家伪名仍然可能关联到个人,必须限制查询权限、设置保留期并审计访问;只做哈希不等于彻底匿名。

如果需要逐字重放故障,应在单独授权的测试环境保存去标识的回放样例和对应版本快照,不能指望通过日志指纹恢复内容。验收时挑一条请求,确认能找到实际版本、证据来源和每段耗时,同时检索不到玩家敏感原文,这条追踪链路才算可用。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用请求日志追踪版本与上下文

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通