1. 为什么 AI Agent 绕不开 Redis 这层缓存做过 AI Agent 项目的人大概都有过这种体验本地跑个 demo 顺风顺水一旦把并发量拉起来或者把会话状态放到多实例部署的环境里整个系统就开始变得又慢又乱。模型调用本身已经够贵了结果每次用户发一句话Agent 还要重新去查一遍历史对话、重新拼一遍工具调用结果、重新算一遍向量检索的中间态——这些重复劳动堆在一起延迟和成本直接失控。这就是 Redis 在 AI Agent 架构里真正的位置。它不是顺便加个缓存而是 Agent 的短期记忆层和状态协调层。一个典型的 Agent 循环是这样的接收用户输入 → 规划Planning→ 调用工具Tool Calling→ 观察结果Observation→ 再规划 → 输出。这个循环里每一步产生的中间状态如果都靠数据库或者内存变量扛着多轮对话一长、并发一高系统就会崩。Redis 的定位就是把这些高频读写、生命周期短、结构灵活的数据接过来。我先把这篇要讲清楚的东西摆出来AI Agent 场景下 Redis 到底缓存什么、怎么设计 key、怎么处理缓存一致性、分布式锁怎么用、序列化怎么选、线上常见的超时和失效问题怎么排查。适合正在搭 Agent 后端、或者已经把 Agent 跑起来但被性能和状态问题折磨的开发者。如果你只是想让 Agent 跑通一个 demo那 Redis 可以先放一放但只要涉及多轮会话、多实例部署、工具调用结果复用这层缓存基本躲不掉。有一点要先说明白AI Agent 和传统 Web 后端的缓存需求不完全一样。传统缓存大多是读多写少、结果稳定比如商品详情、用户资料。而 Agent 的缓存对象往往是会话态、工具调用结果、规划中间态这些东西变化快、和具体会话强绑定、还经常需要设置较短的 TTL。用传统那套缓存整个接口响应的思路来做 Agent 缓存很容易踩坑。下面我按实际项目里的顺序一层层拆。2. Agent 里到底哪些数据该进 Redis很多人一上来就问Redis 缓存怎么配但更该先问的是我到底要缓存什么。选错了缓存对象后面 key 设计、过期策略、一致性方案全是白费功夫。我按 Agent 运行时实际产生的数据分几类说。2.1 会话上下文最核心也最容易失控的部分多轮对话的上下文是 Agent 缓存的第一大头。用户和 Agent 聊了 20 轮第 21 轮进来时你需要把前面的对话历史喂给模型。如果每次都从数据库全量拉取再拼接延迟会随着轮次线性增长。常见的做法是把会话上下文以列表结构存在 Redis 里比如用List或者Stream。每轮对话追加一条读取时按需截取最近 N 轮。这里有个关键决策是缓存完整历史还是只缓存最近窗口。我的经验是Redis 里只保留热窗口——比如最近 10 到 20 轮更早的历史落库需要时再按需回捞。原因很简单模型的上下文窗口是有限的你缓存再多它也吃不下反而白白占内存。import redis import json r redis.Redis(hostlocalhost, port6379, decode_responsesTrue) def append_turn(session_id, role, content): key fagent:ctx:{session_id} turn json.dumps({role: role, content: content}, ensure_asciiFalse) r.rpush(key, turn) # 只保留最近 20 轮控制内存 r.ltrim(key, -20, -1) r.expire(key, 3600) # 1 小时不活跃就回收 def get_context(session_id): key fagent:ctx:{session_id} turns r.lrange(key, 0, -1) return [json.loads(t) for t in turns]这段代码看着简单但ltrim那行是精髓。我见过太多项目忘了裁剪结果一个长会话把 Redis 内存吃满最后触发淘汰策略把别的 key 挤掉引发连锁故障。2.2 工具调用结果省下的是真金白银Agent 调用外部工具搜索、数据库查询、第三方 API往往又慢又贵。同一个会话里用户可能反复问相关的问题触发相同的工具调用。这时候把工具调用结果按工具名 参数指纹缓存起来命中一次就省一次外部调用。这里要注意的是参数指纹怎么算。不能简单用参数的 JSON 字符串因为字段顺序、空格差异会导致同样的语义算出不同的 key。稳妥的做法是对参数做规范化排序后再哈希。import hashlib def tool_cache_key(tool_name, params: dict): normalized json.dumps(params, sort_keysTrue, ensure_asciiFalse) digest hashlib.sha256(normalized.encode()).hexdigest()[:16] return fagent:tool:{tool_name}:{digest}TTL 设置上工具结果的新鲜度要求不同。搜索类结果可能几分钟就过时设 300 秒而一些静态查询比如汇率换算的固定公式结果可以设几小时。别一刀切。2.3 规划中间态与向量检索缓存Agent 的 Planning 阶段经常会产生一些中间结构比如任务分解列表、候选工具排序。这些数据生命周期极短可能就几秒到几十秒但读写频率很高。用 Redis 的String存 JSON 或者Hash存字段都行关键是 TTL 要短。向量检索这块要单独提一句。RAG 场景下同一个 query 的 embedding 和检索结果可以缓存。embedding 计算是 CPU/GPU 密集操作缓存命中能显著降延迟。但要注意embedding 缓存对 query 的精确匹配要求高稍微改一个字就是另一个 key所以命中率取决于用户提问的重复度。实际项目里我会给 embedding 缓存设较长的 TTL比如 24 小时因为语义相近的 query 复用价值高。缓存对象推荐结构典型 TTL备注会话上下文List / Stream30min - 2h需裁剪窗口工具调用结果String (JSON)5min - 数小时按工具特性定规划中间态String / Hash10s - 60s极短生命周期EmbeddingString (二进制)数小时 - 24h注意内存占用限流计数String (INCR)与窗口对齐配合过期3. Key 设计与序列化那些看起来不重要却天天出事的地方缓存对象定了接下来是 key 怎么设计、value 怎么序列化。这两件事在 demo 阶段无所谓上了生产就是天天出问题的地方。3.1 Key 命名要有层级感和可扫描性我推荐用冒号分隔的层级命名比如agent:ctx:{session_id}、agent:tool:{tool}:{hash}。好处是可以用SCAN按前缀批量操作也方便在监控里按前缀统计内存占用。但有个坑必须提醒不要用KEYS agent:ctx:*去扫线上 Redis。KEYS是 O(N) 操作会阻塞整个实例。线上要用SCAN游标迭代。我见过有人写了个定时任务用KEYS清理过期会话结果每次执行 Redis 就卡顿几秒Agent 请求大面积超时。def scan_keys(pattern, batch100): cursor 0 while True: cursor, keys r.scan(cursorcursor, matchpattern, countbatch) for k in keys: yield k if cursor 0: break另外key 里如果包含用户可控的内容比如 session_id 直接来自前端一定要做校验或哈希防止有人构造超长 key 或者恶意 key 撑爆内存。3.2 序列化选型JSON、MessagePack 还是 Pickle序列化这块我的排序是JSON 优先MessagePack 次之Pickle 尽量别用。JSON 的好处是可读、跨语言、调试方便。缺点是体积大、数字精度有损。对于会话上下文这种需要人肉排查的数据JSON 是首选。MessagePack 体积能压到 JSON 的 60% 左右序列化速度也快适合工具调用结果这种量大且不需要人读的场景。代价是调试时得额外解码。Pickle 我基本不用。一是跨语言不友好二是反序列化有安全风险三是 Python 版本升级容易出兼容问题。Agent 项目经常要和其他语言的服务比如 Rust 写的推理服务交互Pickle 直接出局。import msgpack def set_tool_result(key, data, ttl300): packed msgpack.packb(data, use_bin_typeTrue) r.set(key, packed, exttl) def get_tool_result(key): raw r.get(key) if raw is None: return None return msgpack.unpackb(raw, rawFalse)提示如果 value 里包含二进制数据比如 embedding 向量别硬塞进 JSON用 MessagePack 或者直接存 bytes。JSON 处理二进制会先 base64 编码体积膨胀 33%。3.3 大 key 与热 key 的预防Agent 场景特别容易产生大 key。比如把整个会话的所有工具调用结果塞进一个 Hash聊得越久这个 Hash 越大。大 key 的危害是读写慢、删除时阻塞、集群模式下数据倾斜。预防手段有几个一是拆分把工具结果按调用 ID 单独存 key会话里只存引用二是限制单个 value 大小超过阈值就落库三是监控用redis-cli --bigkeys或者MEMORY USAGE定期排查。热 key 则是另一个极端某个 key 被高频访问把单个分片的 CPU 打满。Agent 里常见的热 key 是全局配置或者热门工具的结果。解决办法是本地缓存加一层或者给 key 加随机后缀做分片读。4. 缓存一致性Agent 状态和数据库怎么不打架这是最容易出事故的部分。Agent 的会话状态既在 Redis 又在数据库两边不同步就会出现用户看到的历史和实际存的不一样这种诡异问题。4.1 先搞清楚你的读写模式一致性方案没有银弹得先看你的读写模式。Agent 场景大致分两种写少读多比如工具调用结果、embedding写一次读很多次。这种用 Cache-Aside 就行读时先查缓存没有再查库并回填。写多读多比如会话上下文每轮都在写。这种如果还用 Cache-Aside每次写都要更新库再删缓存延迟高。更实际的做法是以 Redis 为主存储异步落库。也就是说会话的实时状态以 Redis 为准后台任务定期把数据同步到数据库做持久化。def save_turn(session_id, turn): # 先写 Redis保证实时性 append_turn(session_id, turn[role], turn[content]) # 异步落库不阻塞主流程 async_persist_queue.put({session_id: session_id, turn: turn})这个方案的风险是 Redis 挂了会丢最近的数据。所以关键会话要么用 Redis 的 AOF 持久化要么接受最多丢最近几轮的业务容忍度。这个取舍必须和产品方对齐不能自己拍脑袋。4.2 删除缓存还是更新缓存经典问题。我的结论是优先删除缓存而不是更新缓存。原因是更新缓存容易在并发下产生脏数据——两个请求同时更新后写的可能先到缓存里就留下了旧值。删除缓存则让下次读自然回源逻辑更简单。但删除也有坑就是删除后瞬间大量请求回源造成缓存击穿。Agent 场景里如果某个热门会话的缓存被删紧接着几十个请求同时回源查库数据库可能扛不住。这时候要用互斥锁或者逻辑过期来兜底。4.3 延迟双删与最终一致如果业务对一致性要求高可以用延迟双删更新库 → 删缓存 → 延迟几百毫秒再删一次。第二次删是为了清掉在更新库到第一次删缓存这个窗口内被其他请求回填的旧值。不过说实话Agent 场景里大部分数据对强一致的要求没那么高。会话上下文差一两轮、工具结果稍微旧一点用户基本无感。真正需要强一致的是计费、配额、权限这类数据这些我建议直接走数据库或者用 Redis 的原子操作别掺和缓存那一套。5. 分布式锁Agent 并发下的状态保护Agent 多实例部署后同一个会话可能被多个实例同时处理。比如用户快速发了两条消息两个实例同时读到同一份上下文各自追加最后就丢了一条。这时候需要分布式锁。5.1 用 SET NX EX 实现基础锁Redis 分布式锁最基础的实现就是SET key value NX EX ttl。NX 保证只有第一个请求能设置成功EX 保证锁会自动过期避免死锁。import uuid def acquire_lock(lock_key, ttl10): token str(uuid.uuid4()) ok r.set(lock_key, token, nxTrue, exttl) return token if ok else None def release_lock(lock_key, token): # 用 Lua 保证判断 token 再删除的原子性 lua if redis.call(get, KEYS[1]) ARGV[1] then return redis.call(del, KEYS[1]) else return 0 end r.eval(lua, 1, lock_key, token)释放锁必须用 Lua 脚本先比对 token 再删除。否则可能出现A 的锁过期了B 拿到了锁这时 A 执行完来删锁把 B 的锁删了。这个 bug 非常隐蔽线上排查起来很痛苦。5.2 锁的粒度别锁太大也别锁太小锁的粒度是个经验活。锁整个会话agent:lock:session:{id}能保证同一会话串行处理但会降低并发。锁单个操作比如只锁追加消息这一步并发高但可能保护不全。我的做法是会话级的写操作锁整个会话读操作不加锁。因为读多写少锁写不锁读能兼顾一致性和吞吐。如果会话内还有更细的并发点比如多个工具并行调用再单独加细粒度锁。5.3 锁超时与续期锁的 TTL 设多长是个难题。设短了业务没执行完锁就过期别的请求进来乱套设长了万一持锁进程崩了锁要等很久才释放。稳妥方案是看门狗续期持锁期间起一个后台线程每隔 TTL/3 的时间检查业务是否还在执行是就续期。Redisson 这类客户端内置了这个机制。如果自己实现要注意续期和释放的竞态别续期续到一个已经被别人拿走的锁上。注意分布式锁不是万能的。如果业务本身能设计成幂等很多场景根本不需要锁。加锁之前先问自己这个操作重复执行会怎样如果无害就别加锁省得引入复杂度和性能损耗。6. 线上高频故障超时、失效与内存告警前面讲的都是设计这一节讲线上真会遇到的故障。我把最常见的几类列出来附上排查思路。6.1 command timed out别急着怪 RedisRedis command timed out; nested exception is io.lettuce.core.RedisCommandTimeoutException这个报错很多人第一反应是Redis 挂了。实际上大部分情况是客户端侧的问题。排查顺序我一般这样走先看 Redis 服务端慢日志SLOWLOG GET确认有没有慢命令。再看客户端连接池配置是不是连接数不够导致排队。检查有没有大 key 操作比如HGETALL一个几万字段的 Hash。看网络尤其是跨机房访问RTT 高的时候默认超时很容易触发。Lettuce 默认命令超时是 60 秒但很多框架会覆盖成更短的值。Agent 场景里如果某个工具调用结果特别大序列化反序列化耗时也会算进超时。我遇到过一次就是工具返回了几 MB 的 JSON反序列化慢导致偶发超时。后来改成只缓存必要字段就好了。6.2 缓存失效引发的雪崩如果大量 key 在同一时刻过期请求会同时涌向数据库。Agent 场景里如果所有会话的 TTL 都是固定 1 小时且用户集中在某个时段活跃就可能在整点附近触发雪崩。解决办法是给 TTL 加随机抖动import random def set_with_jitter(key, value, base_ttl): jitter random.randint(0, int(base_ttl * 0.1)) r.set(key, value, exbase_ttl jitter)这样过期时间就分散开了。另外热点数据可以用逻辑过期value 里存一个过期时间戳物理上不过期读到逻辑过期时异步刷新避免大量请求同时回源。6.3 内存告警与淘汰策略Redis 内存满了会触发淘汰。Agent 场景下如果淘汰策略设成allkeys-lru可能把正在用的会话上下文淘汰掉导致用户失忆。如果设成noeviction写入直接报错。我的建议是会话上下文这类不能丢的数据单独放一个实例或用单独的 DB配置volatile-lru只淘汰设了过期时间的 key。而工具结果、embedding 这类可重建的数据可以容忍淘汰。物理隔离比在一个实例里靠策略区分更可靠。故障现象常见根因排查入口command timed out连接池不足 / 大 key / 网络 RTTSLOWLOG、连接池监控缓存雪崩TTL 集中过期检查 TTL 是否加抖动用户会话丢失内存淘汰 / key 被误删淘汰策略、内存监控数据不一致双写时序问题检查删除/更新顺序锁失效TTL 过短 / 未续期锁监控、业务耗时统计6.4 主从与集群下的坑如果用了主从或者集群有几个坑要提前知道。主从复制是异步的主节点写入后还没同步到从节点就宕机锁可能丢失。集群模式下涉及多个 key 的操作比如 Lua 脚本里操作多个 key要求这些 key 在同一个 slot否则会报 CROSSSLOT 错误。解决办法是用 hash tag比如agent:ctx:{session123}:turns和agent:ctx:{session123}:meta大括号里的内容相同就会落到同一个 slot。7. 我踩过的几个真实坑和对应经验理论讲完了说几个我自己项目里真踩过的坑这些在文档里基本看不到。第一个坑用 List 存会话读取时全量拉取。一开始图省事LRANGE key 0 -1把整个会话拉出来。会话短的时候没事聊到几十轮后每次读取都要传输几百 KB延迟肉眼可见地涨。后来改成只拉最近 N 轮更早的按需回捞延迟立刻降下来。教训是缓存读取要按需别图省事全量拉。第二个坑工具结果缓存没做参数规范化。同样的查询前端传参字段顺序不一样算出来的 key 就不一样缓存命中率极低。加了sort_keysTrue之后命中率从 20% 涨到 70% 多。这个改动一行代码收益巨大。第三个坑分布式锁 TTL 设太短。有个工具调用偶尔要跑 15 秒锁 TTL 设了 10 秒结果锁提前过期两个请求同时写会话数据错乱。后来加了续期机制才解决。教训是锁 TTL 要大于业务 P99 耗时且要有续期兜底。第四个坑监控缺失。上线初期没做缓存命中率监控出了问题只能靠猜。后来加了命中率、平均耗时、大 key 数量这几个指标排查效率完全不一样。Agent 缓存这种动态性强的场景没有监控基本等于盲开。第五个坑把 embedding 向量用 JSON 存。一个 1536 维的向量JSON 序列化后体积膨胀好几倍内存消耗远超预期。改成二进制存储后内存占用直接砍半。涉及数值数组的场景一定要用二进制序列化。8. 一套可落地的 Agent 缓存分层方案最后把我实际项目里用的分层方案整理出来可以直接参考。第一层本地缓存进程内。存全局配置、工具元数据这类几乎不变的数据。用 LRU 结构容量小命中快不占 Redis 资源。第二层Redis 热数据。存会话上下文、工具结果、规划中间态。按数据类型分 DB 或分实例配置不同的淘汰策略和 TTL。第三层数据库持久化。会话历史、重要工具结果落库作为最终真相来源。Redis 里的数据丢了可以从这里重建。读写路径上读优先本地再 Redis最后数据库写以 Redis 为主异步落库。锁只在会话级写操作上加读不加锁。TTL 全部加抖动热点数据用逻辑过期。这套方案不是最优解但在多实例、中等并发、成本敏感的 Agent 项目里跑得比较稳。具体参数还得根据你的 QPS、数据量、一致性要求去调。我个人的体会是Agent 缓存治理这件事设计阶段多想一步比上线后救火省十倍力气。尤其是 key 设计和 TTL 策略改起来牵一发动全身一开始就定好规矩后面会轻松很多。