实用指南：AI智能体的语义缓存——如何优化你的LLM应用

可将此文档视为《AI智能体的语义缓存：如何让您的LLM应用更快更省成本》中内容的操作员版重构版本：包含清晰的阶段划分、有序的代码模块以及可在交接时保留的恢复说明。在扩大范围之前，最好将“概览”阶段视为一个可量化的基准，记录一份最佳案例、一个故障实例以及对应的回滚说明。应将此阶段视为输入与经过验证的输出之间的契约，为相关成果命名、明确成功标准，并杜绝默许的半完成状态。

语义缓存的工作原理

在“语义缓存的工作原理”阶段，应在修改代码之前明确输入内容、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。当下一步操作是编写代码或调用工具时，优先选择具有架构验证的结构化输出，而非自由形式的文字描述。

从零开始构建语义缓存

在“构建语义缓存”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个流程即可进行审计。 当下一步是代码执行或工具调用时，优先使用具有架构验证的结构化输出，而非自由形式的文本。

from sentence_transformers import SentenceTransformer
import numpy as np

model = SentenceTransformer("all-mpnet-base-v2")# Embed your FAQ dataset
faq_questions = ["How do I get a refund?", "Where is my order?", ...]
faq_embeddings = model.encode(faq_questions)def cosine_distance(a, b):
    return 1 - np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))def check_cache(query: str, threshold: float = 0.3):
    query_embedding = model.encode(query)
    distances = [cosine_distance(query_embedding, e) for e in faq_embeddings]
    best_idx = np.argmin(distances)
    best_distance = distances[best_idx]

    if best_distance < threshold:
        return faq_answers[best_idx]  # Cache hit
    return None  # Cache miss

使用 Redis 进入生产环境

在“进入生产环境”阶段，修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 当下一步操作为代码编写或工具调用时，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文本。 在“进入生产环境”阶段，修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入参数与经过验证的输出之间的契约。需为相关成果命名，明确成功判定标准，并杜绝无声的半完成状态。

from redisvl.extensions.cache.llm import SemanticCache
from redisvl.utils.vectorize import HFTextVectorizer

# Load a cache-optimized embedding model
vectorizer = HFTextVectorizer("redis/langcache-embed-v1")# Create the cache
cache = SemanticCache(
    name="customer_support_cache",
    vectorizer=vectorizer,
    redis_client=redis_client,
    distance_threshold=0.3
)# Set TTL (time to live) — keeps cache fresh
cache.set_ttl(86400)  # 24 hours

衡量已构建的内容

在“衡量已构建内容”阶段，首先需写下相关约定：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。 缓存稳定的系统指令和工具结构。重复发送相同的开头信息是导致资源浪费的常见原因。

1. 缓存命中率

在处理“1 缓存命中率”阶段时，首先写下相关规范：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改不会出错。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放，这样操作人员无需查看整个系统结构即可进行审计。 缓存系统中稳定的指令和工具架构。重复发送相同的前置数据是导致资源浪费的常见原因。

2. 精度

在完成“2精度”阶段时，首先需写下规范：所需的输入参数、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都属于产品功能的一部分，而非后续的优化工作。 缓存系统中稳定的指令和工具结构。重复发送相同的报文头是导致资源浪费的常见原因。 在完成“2精度”阶段时，首先需写下规范：所需的输入参数、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 将此阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝无声的半完成状态。

3. 回忆

将“3次召回阶段”视为可测量的指标时效果最佳。在扩大范围之前，先记录一份理想的输出结果、一个失败案例以及回滚说明。在功能结果旁同时记录处理时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外账单。为每轮对话和每次会话设定令牌预算。智能工具往往会大量消耗上下文资源，设置上限能防止演示环境变成令人意外的收费来源。

4. 延迟优化

将“4个延迟优化阶段”视为可测量的指标体系时，其效果最佳。在扩大范围之前，先记录一份理想的处理结果、一个故障案例以及回滚说明。 应将配置与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。 为每轮对话和每次会话设定令牌预算。智能工具往往会大量消耗上下文资源，设置上限可避免演示过程突然产生额外费用。

With-Cache Latency = (avg_llm_latency × (1 - hit_rate)) + (avg_cache_latency × hit_rate)

混淆矩阵视图

将“混淆矩阵视图”阶段视为可度量的对象来使用效果最佳。在扩大范围之前，先记录一份理想状态下的转录内容、一个故障案例以及回滚说明。同时文档化正常流程与恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。为每轮对话和每次会话设定token预算——智能工具往往会过度消耗上下文，设置上限可避免演示过程变成意外的费用账单。将“混淆矩阵视图”阶段视为输入与已验证输出之间的契约：为相关文档命名，明确成功标准，绝不允许出现无声的、不完整的处理结果。

提升缓存准确度的四种技巧

在提升“四项技术”阶段时，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。当下一步操作是编写代码或调用工具时，优先选择具有架构验证的结构化输出，而非自由形式的文字描述。

1. 阈值扫描

在“1 阈值扫描”阶段，修改代码之前需先明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审核。 当下一步操作为代码执行或工具调用时，宜使用具有架构验证的结构化输出，而非自由形式的文本。

2. 交叉编码器重排序

在第二个交叉编码器重排序阶段，修改代码之前需明确输入内容、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都是产品功能的一部分，而非后续需要补充的内容。 当下一步操作为代码编写或工具调用时，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文本。 在第二个交叉编码器重排序阶段，修改代码之前需明确输入内容、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入与经过验证的输出之间的契约。需为相关输出文件命名，明确成功判定标准，并杜绝无声的半完成状态。

3. 以大语言模型作为评判者

在完成“LLM作为裁判”的三个阶段时，首先需写下合同条款：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及token或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外费用。 缓存稳定的系统指令和工具架构。重复发送相同的开头信息是导致资源浪费的常见原因。

4. 作为预过滤器的模糊匹配

在实施四步模糊匹配流程时，首先需明确相关约定：所需的输入参数、成功标志，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合预期。 应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 需缓存系统中稳定的指令和工具架构。重复发送相同的前置数据是导致资源浪费的常见原因。

真正的收益：在 AI 智能体中实现缓存

在处理“真正有价值的缓存”阶段时，首先需明确相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误消息处理都是产品功能的一部分，而非后续需要补充的内容。 缓存系统中稳定的指令和工具结构。重复发送相同的报文是导致资源浪费的常见原因。 在处理“真正有价值的缓存”阶段时，首先需明确相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 将此阶段视为输入与经过验证的输出之间的契约。为相关产物命名，定义成功判定标准，杜绝无声的半完成状态。

实际应用验证：沃尔玛的waLLMartCache

在将沃尔玛的测试环境视为可量化评估基准时，其实际应用验证效果最佳。在扩大测试范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外账单。为每轮操作和每次会话设定令牌预算。智能工具往往会大量消耗上下文资源，设置上限能防止演示过程变成意外收费的源头。

入门指南

将“入门阶段”视为可衡量的指标会更有助于其有效开展。在扩大范围之前，先记录一份优秀的测试案例、一个失败案例以及回滚说明。 应将配置与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放，这样操作人员无需查看整个系统结构即可进行审计。 为每轮对话和每次会话设定预算额度。智能工具往往会大量消耗上下文资源，设置上限可避免演示过程变成意外的费用账单。

结论

将“结论阶段”视为可度量的工作面时，其效果最佳。在扩大范围之前，需记录一份理想案例、一个失败案例以及回滚说明。 同时记录正常流程与恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的一部分，而非后续需要补充的内容。 为每轮对话和每次会话设定token预算。智能工具会大量消耗上下文，设置上限可避免演示过程变成意外的费用账单。 将“结论阶段”视为输入与已验证输出之间的契约。为相关文档命名，明确成功标准，绝不允许出现无声的、不完整的处理结果。

操作检查清单

在处理操作检查清单阶段时，首先写下合同条款：所需的输入参数、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。

优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应能指向单一的责任模块，而非复杂的流程链。

缓存系统中稳定的指令和工具结构。重复发送相同的开头信息是导致资源浪费的常见原因。

保持图结构的扁平化与类型化。嵌套的数据结构会掩盖哪个节点修改了哪个字段，还会在中断后导致程序无法继续运行。

只要预算允许，就在持续集成过程中使用测试数据而非真实的付费 API，添加用于检测关键路径的冒烟测试。

将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，这样操作人员无需查看全部架构即可进行审计。

在升级技术栈之前，先冻结版本，为关键流程记录标准日志，并明确回滚步骤。共享环境需要设置速率限制、租户验证机制，以及负责密钥轮换的明确责任人。与其追求花哨的一次性演示，不如注重扎实的可靠性。

针对 576e7f2969bf 的批量说明：请勿将提供商密钥放入代码仓库，为每个会话设置令牌使用上限，并将日志与评估用固定文件一同存储，以便后续模型更换时保持数据可比性。