redis-expert

Redis 专家

目的

提供涵盖八个领域的 Redis 全方位专业知识：数据建模与键命名、客户端连接、集群与复制、Redis Search、可观测性、安全、语义缓存和 Agent 记忆。只要代码、配置或设计决策涉及 Redis，就使用这项技能。详细信息位于 references/<domain>/；请根据具体领域和主题加载相应文件，而不是凭猜测作答。对于上游材料中有依据的内容，保留其技术指导；对于汇总内容必须区分 Redis 版本、模块、客户端或部署模式的情况，则加以限定说明。

核心原则

1. 只要代码、配置或设计决策涉及 Redis，就使用这项技能，不要等到用户提及 Redis 才使用。
2. 根据访问模式选择数据结构，而不是根据数据的形状。
3. 加载任务涉及的每个领域。生产环境中的搜索部署会同时涉及核心、搜索、安全和可观测性。
4. 根据目标版本、模块、客户端库和部署模式验证 Redis 专属指导。一般的数据库经验在这里经常会导致错误判断，因此并不可靠。
5. 明确说明与版本相关的行为，因为维度不匹配可能会被拒绝，而度量标准不匹配则可能只会在无提示的情况下降低相关性。
6. 优先使用增量式 SCAN 系列命令和连接池，而不是只适用于小规模场景的捷径。
7. 优先使用遵循最小权限原则的应用专属 ACL，而不是共享凭据。
8. 生成的指导中不要使用 em dash。

授权模型

Redis 相关工作大多只是提供建议。只有涉及访问实时系统的操作才需要授权：

用户指令	授权范围
“该用哪种数据结构？”	推理和建议，无需连接
“该如何为此建立索引？”	架构和查询设计，不会创建索引
“这很慢”	根据你提供的指标、SLOWLOG 和 FT.PROFILE 输出进行诊断
“应用此配置”	将配置变更作为提案，仅在用户要求应用时才实际应用
“连接到生产环境”	需要另行授权并指明目标；连接前报告风险
“清空缓存”	必须明确且具体。绝不能将其作为完成其他任务的步骤。

绝不要为了方便回答问题而连接实时部署、运行破坏性命令或更改安全设置。

步骤 0：主动触发

只要代码、配置或设计决策涉及 Redis，就使用这项技能，不要等到用户提到“Redis”才使用。完整的触发列表、置信度规则以及应保持静默的情况，请阅读 references/proactive-trigger.md。

步骤 1：选择合适的领域

工作内容	领域	参考文件夹
选择数据结构、命名键、建模实体	核心	references/core/
配置客户端、连接池、流水线、超时、客户端缓存、避免慢命令	连接	references/connections/
分片、哈希标签、CROSSSLOT 错误、只读副本	集群	references/clustering/
搜索索引设计、FT.SEARCH/FT.AGGREGATE/FT.HYBRID、向量搜索、RAG	搜索	references/search/
指标、SLOWLOG、INFO、事件分诊、Redis Insight	可观测性	references/observability/
身份验证、ACL、TLS、网络暴露、生产环境加固	安全	references/security/
使用 LangCache 缓存大模型响应的语义内容	语义缓存	references/semantic-cache/
Agent 会话事件、长期记忆、使用 Iris 在后台提升记忆	Agent 记忆	references/iris/

一项任务通常会涉及多个领域（生产环境中的搜索部署会同时涉及核心、搜索、安全和可观测性）。请加载每个相关领域的文件，而不是只选择一个。

核心：数据建模与键命名

选择与访问模式相符的 Redis 类型，而不只是看数据的形状：原子计数器用 String，字段可独立更新的对象用 Hash，队列用 List，成员检查用 Set，排名用 Sorted Set，嵌套数据用 JSON，事件日志用 Stream，相似性搜索用 Vector Set。经典反模式是将扁平对象塞进序列化字符串中，导致每次更新字段都必须先读取、解析、修改再重写；应改用 Hash。

键名：使用小写字母，以冒号分隔，层级稳定（user:1001:profile），简短易读；多租户场景下按租户添加前缀（tenant:42:user:7:cart）。

参见 references/core/choose-data-structure.md 和 references/core/key-naming.md。

连接：高效访问 Redis

使用连接池或多路复用，绝不要每次请求都新建连接——这是最常见、影响最大的客户端错误。将互不依赖的命令通过管道合并为一次往返。生产环境中，绝不要调用扫描整个键空间的命令（KEYS、针对大型集合的 SMEMBERS、针对大型哈希的 HGETALL），而应使用增量式的 SCAN/SSCAN/HSCAN 变体。为热门且很少写入的键启用 RESP3 客户端缓存。根据应用的实际故障模型设置明确的连接和读取超时，不要依赖客户端默认值。

参见 references/connections/（连接池、管道、阻塞、客户端缓存、超时）。

集群：分片与复制

Redis Cluster 会将每个键哈希到 16,384 个槽之一。任何多键命令（MGET、SDIFF、事务、管道、多键 Lua）都要求所有键位于同一槽，否则会因 CROSSSLOT 而失败。哈希标签（{ 和 } 之间的部分）可强制将键放在同一位置；标签应限定为有意义的实体（{user:1001}），不要给过多键添加标签，否则会造成热点。对于读密集型工作负载，可将读取路由到副本，但副本最终才会保持一致；绝不要从副本读取刚写入的数据，也绝不要将副本读取用于任何要求严格新鲜度的场景。

参见 references/clustering/hash-tags.md 和 references/clustering/read-replicas.md。

搜索：索引、查询、向量与 RAG

三种查询命令：FT.SEARCH 用于直接检索文档（默认选择），FT.AGGREGATE 用于分面和分析流水线，FT.HYBRID（Redis 8.4+）用于在一次融合查询中结合词法（BM25）和向量相似性。FT.CREATE 始终需要显式指定 PREFIX，并应使用 DIALECT 2。根据访问模式选择最精确的字段类型；用于精确匹配筛选的 TAG 大约比误用 TEXT 快 10 倍。对于向量字段，DIM 必须与嵌入模型匹配，距离度量必须与检索设计相符。根据 Redis、模块和客户端的版本，维度不匹配可能在索引或查询时被拒绝，而度量或模型不匹配则可能在没有明显应用错误的情况下导致相关性下降。生产规模的近似搜索使用 HNSW，小型精确匹配语料使用 FLAT。零停机架构变更应通过索引别名进行，绝不要让应用查询直接指向原始索引名称。

完整说明参见 references/search/：架构与字段类型、查询语法、聚合与游标、向量和混合搜索、原生向量集合、RAG 模式、索引管理、使用 FT.EXPLAIN/FT.PROFILE 调试，以及各客户端示例（references/search/clients/），涵盖 redis-py、Jedis 和 RedisVL。

可观测性：监控与事件分流

将 INFO 中的 used_memory、connected_clients、blocked_clients、 instantaneous_ops_per_sec、keyspace_hits/keyspace_misses（命中率）和 rejected_connections 导出到监控系统。临时诊断时： 使用 SLOWLOG GET 查找超过慢命令阈值的操作，使用 MEMORY DOCTOR 获取内存压力的通俗摘要，使用 CLIENT LIST 查看连接状态， 使用 FT.PROFILE 分析缓慢的搜索查询。Redis Insight 是用于交互式探索的官方 GUI，不能替代导出的指标。

参见 references/observability/metrics.md 和 references/observability/commands.md。

安全：生产环境加固

对于生产部署，应根据托管服务或可自托管拓扑进行身份验证并使用 TLS。没有身份验证的生产 Redis 是常见的安全漏洞模式。相比所有应用共用一个 requirepass，更建议为每个应用配置独立的 ACL 用户，仅允许其实际需要的最少命令和键模式，这样即使凭据泄露，影响范围也有限。使用 bind、protected-mode yes 和防火墙规则限制网络暴露，仅允许应用子网访问。使用 bind 0.0.0.0 并设置 protected-mode no 会使整个网络都能访问 Redis。对于破坏性命令（FLUSHALL、DEBUG、 CONFIG），优先使用 ACL 限制和网络控制。如果还使用了命令重命名或禁用功能，请验证其与客户端及运维工具的兼容性，因为这可能导致预期的命令名称无法使用。

参见 references/security/auth.md、references/security/acls.md 和 references/security/network.md。

语义缓存：使用 LangCache 缓存大模型响应

在任何大模型调用前使用旁路缓存模式：先按提示词相似度搜索缓存；命中时返回存储的响应；未命中时调用大模型并存储结果。相似度阈值取决于工作负载和嵌入模型，是启发式设置，不能直接套用为通用默认值。建议从较保守的阈值开始，然后使用评估集进行校准，同时考虑隐私、租户隔离、TTL、失效和投毒风险。 切勿让互不相关的任务类型共用一个缓存（代码问题和密码重置问题在语义上截然不同，即使格式相似），应为每种任务使用独立的缓存 ID 或基于属性的过滤。

参见 references/semantic-cache/langcache-usage.md 和 references/semantic-cache/best-practices.md。LangCache 目前在 Redis Cloud 上处于预览阶段，行为可能会发生变化。

Agent 记忆：使用 Iris 管理会话记忆和长期记忆

由托管的 Redis Agent Memory 数据平面提供两层记忆：每次对话追加写入会话事件（成本低、有序，写入路径上不调用大模型），以及可进行语义搜索的长期记忆（默认 TTL 为 1 年）。后台晋升工作器以 5 分钟为去重时间窗口，从会话中提取持久事实，因此每次写入后，长期记忆最终会保持一致。

每轮对话都使用一个稳定的 session_id 和带时区的 UTC 时间戳进行追加；写入时使用 owner_id、namespace、topics 和 memory_type 对长期记录进行范围限定；在服务端使用结构化过滤条件和相似度阈值进行搜索，而不是在客户端过滤。

参见 references/iris/setup-and-auth.md、references/iris/session-memory.md、 references/iris/long-term-memory.md 和 references/iris/promotion.md。

故障处理

当 Redis 指导所依赖的事实无法确认时：

1. 说明该指导所依据的版本、模块或客户端假设
2. 区分硬性拒绝和静默降级，因为后者更加危险
3. 如果最佳实践因工作负载或版本而异，不要将其说成普遍适用
4. 如果正确做法是进行测量，例如校准相似度阈值，请明确说明
5. 切勿为了消除自身的不确定性而连接到实时部署、重新配置它或清空它

错误的相似度阈值会悄无声息地降低效果。未经验证的相关说法也一样。

反模式

• 将扁平、独立更新的对象存储为序列化字符串，而不是 Hash
• 对需要精确匹配筛选的字段使用 TEXT，而不是 TAG
• 在生产数据上调用 KEYS、不设上限的 SMEMBERS 或不设上限的 HGETALL， 而不是使用增量式的 SCAN 系列命令
• 每次请求都新建连接，而不是使用连接池或多路复用
• 在集群部署中执行多键操作，却没有使用哈希标签将键放置在同一节点
• 对任何要求严格新鲜度的数据（余额、幂等状态）从副本读取
• VECTOR 字段的 DIM 或 DISTANCE_METRIC 与实际嵌入模型不匹配
• 生产环境中的 Redis 没有密码、没有 TLS，或绑定到 0.0.0.0 且关闭了受保护模式
• 多种互不相关的任务类型共用一个语义缓存
• 用长期记忆代替会话事件，充当对话缓冲区
• 假设会话写入后，提升的记忆可以立即同步搜索
• 凭一般数据库经验猜测 Redis 特定的最佳实践，而不是查阅相关参考资料。Redis 有许多特定行为（CROSSSLOT、向量维度不匹配时的静默处理、RESP3 要求），依赖其他数据库的经验经常会导致错误判断

随附参考资料

按领域整理，与上游官方技能及 Iris Agent 记忆领域相对应：

• references/proactive-trigger.md：何时应主动使用此技能，以及置信度规则。
• references/core/：数据结构选择、键命名约定。
• references/connections/：连接池、流水线、阻塞命令、客户端缓存、超时。
• references/clustering/：哈希标签、只读副本。
• references/search/：架构和字段类型、查询语法与优化、聚合和游标、向量与混合搜索、原生向量集合、RAG 模式、方言、索引管理与调试，以及 references/search/clients/ 中各客户端的示例。
• references/observability/：要监控的指标、内置调试命令。
• references/security/：身份验证与 TLS、ACL、网络限制。
• references/semantic-cache/：LangCache 的使用和调优最佳实践。
• references/iris/：Agent Memory 存储设置与身份验证、会话记忆、长期记忆、后台提升。

非参考类随附内容

• 此聚合内容未随附评估套件。在将 Redis 特定指导视为权威实现契约之前，请根据目标 Redis 版本、模块、客户端库和部署模式进行验证。
• Cursor 插件打包配置位于项目级别（.cursor-plugin/plugin.json），涵盖此仓库中的所有技能，而非仅此技能。

目标 Redis 版本和部署文档仍是运行时行为的权威依据。