提示词缓存动态字段怎么配置或排查

提示词缓存里的“动态字段”如果指的是 Hugging Face Transformers 的动态 KV 缓存，核心配置不是给提示词拼一个特殊参数，而是让 DynamicCache 保存已经计算过的 key/value 状态，并随着生成 token 增长。它适合输入长度不断变化的生成和多轮对话；如果缓存完全不增长，先查 use_cache、past_key_values 是否真的传入，再看模型本身是否使用滑动窗口或分块注意力。

官方文档：https://huggingface.co/docs/transformers/main/kv_cache

最稳妥的排查顺序是：先确认缓存开关，再确认缓存对象与模型配置匹配，最后观察序列长度、窗口上限和显存。缓存长度不一定无限增长，这并不自动代表配置失败。

先把“提示词缓存”和 DynamicCache 分开

提示词是文本或消息模板，DynamicCache 保存的是模型注意力计算产生的 KV 状态，两者不是同一份数据。Transformers 官方文档把 DynamicCache 作为默认缓存类，特点是容量会随 key/value 增加而增长；generate() 也可以通过 use_cache=False 明确关闭缓存。

配置时最容易混淆三个入口：use_cache 是总开关，past_key_values 是把已有缓存交给模型的状态对象，cache_implementation 是让生成流程选择 dynamic、static 或 offloaded 等实现。先决定要不要复用上下文，再决定缓存实现，排查会简单很多。

用 DynamicCache 配置一次可复用生成

下面的示例只演示配置边界，不绑定某个必须下载的模型。重点是缓存对象由模型配置初始化，生成时显式传入；调试阶段打印序列长度，能快速确认动态字段是否真的变化。

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from transformers.cache_utils import DynamicCache

# 使用公开模型标识；实际项目应换成已经验证过的模型和 dtype。
model_id = "Qwen/Qwen3-0.6B"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, device_map="auto")

# 动态缓存会随生成过程追加 KV 状态，不预先固定一个大长度。
past_key_values = DynamicCache(config=model.config)
prompt = "请用三句话解释 KV cache 的作用。"
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

# 只有显式打开缓存并传入对象，后续调用才有可复用的状态。
outputs = model.generate(
    **inputs,
    past_key_values=past_key_values,
    use_cache=True,
    do_sample=False,
    max_new_tokens=64,
)

# 输出包含本轮输入；从输入长度之后截取新生成内容。
new_tokens = outputs[0, inputs["input_ids"].shape[1]:]
print(tokenizer.decode(new_tokens, skip_special_tokens=True))
print("缓存长度:", past_key_values.get_seq_length())

如果打印的长度没有变化，先不要改模型。确认对象没有在每次循环内重新创建，确认生成调用没有被配置文件覆盖，并检查模型是否支持该缓存接口。若只想比较关闭缓存的基线，可以临时设置 use_cache=False，但不要把这个基线配置留在生产路径。

迭代对话中，动态字段要跟着新增片段走

多轮对话的关键是状态一致：messages 保存完整历史，缓存保存已经送进模型的上下文，而本轮输入只应是相对缓存末尾新增的 token。把完整历史再次传入，同时又复用旧缓存，会造成重复上下文或长度不匹配。

messages = []
cache = DynamicCache(config=model.config)

for user_text in ["我在做客服机器人。", "请把上一句改成更短的系统提示。"]:
    # 消息历史用于生成聊天模板，缓存对象在循环外保持同一个实例。
    messages.append({"role": "user", "content": user_text})
    rendered = tokenizer.apply_chat_template(
        messages, add_generation_prompt=True, tokenize=False
    )
    encoded = tokenizer(rendered, return_tensors="pt").to(model.device)

    # 生产代码应只编码缓存之后的新片段；此处用长度日志暴露是否重复编码。
    before = cache.get_seq_length()
    result = model.generate(
        **encoded,
        past_key_values=cache,
        use_cache=True,
        do_sample=False,
        max_new_tokens=48,
    )
    answer = tokenizer.decode(
        result[0, encoded["input_ids"].shape[1]:], skip_special_tokens=True
    )
    messages.append({"role": "assistant", "content": answer})
    print("缓存长度:", before, "->", cache.get_seq_length())

这段代码用于说明状态关系，真正接入已有对话时要根据聊天模板切出未缓存的后缀，并让 attention_mask 覆盖缓存长度加新输入长度。多模态对话还要特别注意：新图片或音频必须再次经过 processor 编码，不能把新的媒体当成普通文本后缀。

按现象排查动态缓存

排查时把“动态”拆成四个可观察值：缓存对象是否存在、当前序列长度、模型的注意力窗口、GPU/CPU 的存储位置。下面的检查表适合先做最小复现。

官方说明中，滑动窗口或分块注意力模型的缓存可能在达到窗口或块大小后停止增长。显存紧张时，offloaded 缓存会把部分 KV 状态移到 CPU，代价是数据搬运；它是资源取舍，不是把动态字段“修好”的万能开关。

什么时候改用 StaticCache

DynamicCache 对长度变化友好，但缓存尺寸不固定，通常不能直接享受大多数 JIT/编译优化。StaticCache 会预分配最大缓存长度，官方文档说明它更适合长度相近、愿意用额外显存换编译收益的场景；长度差异很大时，短请求会为未使用的 token 付出注意力计算成本。

# 长度比较稳定、需要固定形状时再选择 static；它不是默认排障方案。
result = model.generate(
    **inputs,
    cache_implementation="static",
    do_sample=False,
    max_new_tokens=64,
)

因此，动态字段排查的结论应落在业务约束上：对话长度变化明显就保留 DynamicCache；批量请求长度相近、编译后的解码收益明确，再用 StaticCache 做基准比较。不要只比较模型文件大小，还要同时记录首 token 延迟、总延迟、显存和长对话失败率。

相关问题

DynamicCache 为什么不一直增长？

可能是模型使用滑动窗口或分块注意力，也可能是缓存被重新创建或发生了裁剪。先打印缓存对象生命周期和 get_seq_length()，再查模型配置。

关闭 use_cache 会影响输出正确性吗？

它主要改变是否复用 KV 状态，通常会影响速度和显存，不应被当作修复提示词内容的办法。关闭后可作为慢速基线，确认问题是否来自缓存状态。

长上下文一定要换 StaticCache 吗？

不一定。StaticCache 以固定最大长度换编译机会，长短请求混杂时可能浪费显存和计算；先用 DynamicCache 测量，再按长度分布决定。