游戏 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 保存文档片段标识与版本,便于核实证据来源;指纹只能判断内容是否一致,不能把原文还原出来。

用 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=(",", ":")))预期输出:
{"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 和是否重试;外部接口错误先映射为超时、限流、认证等受控类别,避免把包含玩家内容的原始异常对象直接写入日志。本例只有一条完成事件,线上应把同一标识贯穿所有阶段事件。
控制隐私边界并保留复现能力
默认不记录玩家原话、完整对话历史、召回片段正文、访问密钥或可能夹带提示文本的异常堆栈。带密钥的玩家伪名仍然可能关联到个人,必须限制查询权限、设置保留期并审计访问;只做哈希不等于彻底匿名。
如果需要逐字重放故障,应在单独授权的测试环境保存去标识的回放样例和对应版本快照,不能指望通过日志指纹恢复内容。验收时挑一条请求,确认能找到实际版本、证据来源和每段耗时,同时检索不到玩家敏感原文,这条追踪链路才算可用。