本教程介绍如何使用 Azure 托管 Redis 作为大型语言模型(LLM)应用程序中语义缓存的 Redis 终结点。 语义缓存是应用程序或网关模式,而不是单独的 Azure Managed Redis 托管功能。 Azure托管 Redis 提供 Redis 终结点和 RediSearch 矢量搜索功能,用于存储和搜索缓存的提示、嵌入、元数据和响应。
本教程中,您将学习如何:
- 确定语义缓存应在应用程序或Azure API 管理中运行。
- 配置Azure托管 Redis、RediSearch、嵌入、TLS 和身份验证的先决条件。
- 使用 RedisVL 实现Python语义缓存。
- 使用Azure API 管理策略配置网关级语义缓存。
- 面向生产环境优化阈值、TTL、分区、版本和可观测性。
- 了解成本、性能和产品契合度方面的考量。
语义缓存的工作原理
当新提示足够接近缓存提示时,语义缓存会重复使用以前的 LLM 响应。 典型的请求流为:
- 从应用程序或 API 使用者处接收提示。
- 使用缓存使用的同一嵌入模型为提示生成嵌入。
- 在 Azure 托管 Redis 中按向量相似度搜索缓存的提示嵌入。
- 如果最近的缓存条目位于配置的阈值内,并且与所需的租户、用户、模型和提示版本分区匹配,则返回缓存的响应。
- 如果没有可接受的匹配项,请调用 LLM 并存储 Redis 中的提示、响应、嵌入、元数据和 TTL。
Azure托管 Redis 可以支持此模式,因为 RediSearch 支持 Redis 数据结构的矢量相似性搜索、元数据筛选和矢量索引。 有关详细信息,请参阅Azure Managed Redis 中的向量搜索和Redis 向量搜索概念。
选择实现路径
| 路径 | 何时使用 | 缓存逻辑运行位置 |
|---|---|---|
| 使用 RedisVL 的应用级语义缓存 | 你拥有应用程序代码,需要自定义阈值、分区、元数据或模型调用逻辑。 | 应用程序使用 Azure Managed Redis 作为 Redis 终结点,并配合 RedisVL SemanticCache。 RedisVL SemanticCache 支持提示查找、响应存储、TTL、元数据、筛选器和 Redis COSINE 距离阈值。 有关详细信息,请参阅 RedisVL SemanticCache API。 |
| 借助 Azure API 管理 实现网关级语义缓存 | 您需要为通过 Azure API 管理 的 LLM API 提供集中式语义缓存。 | Azure API 管理 在后端调用之前使用llm-semantic-cache-store,并在后端响应之后使用llm-semantic-cache-lookup。 Azure 托管 Redis 被配置为外部缓存。 有关详细信息,请参阅Azure API 管理中为 LLM API 启用语义缓存。 |
Prerequisites
- 一份 Azure 订阅。
- 支持 RediSearch 的层上的Azure托管 Redis 实例。 Azure Managed Redis 模块一文按层列出了模块的可用性。
- 创建 Azure 托管 Redis 实例时会启用 RediSearch 模块。 必须在创建时启用模块,并且无法手动将模块添加到现有Azure托管 Redis 实例。 有关详细信息,请参阅将 Redis 模块与 Azure 托管 Redis 配合使用。
- 使用适用于 RediSearch 的企业(
EnterpriseCluster)或非群集(NoCluster)群集策略的 Azure 托管 Redis 配置。 OSS(OSSCluster)群集策略不支持 RediSearch,如 RediSearch 模块要求中所述。 - 嵌入模型或部署。 为每个语义缓存索引使用一个嵌入模型和矢量维度。 Redis 矢量索引要求查询向量具有与索引矢量字段相同的维度,如 Redis 矢量搜索概念中所述。
- 已为客户端配置 TLS 和身份验证。 使用 TLS(
rediss://或ssl=True)以及Microsoft Entra ID或批准的机密存储。 不要硬编码访问密钥。 有关详细信息,请参阅用于身份验证的 Microsoft Entra ID和 TLS 配置。 - 对于 RedisVL 路径:Python、
redisvl、redis,以及嵌入和 Redis 身份验证方法所需的任何包。 - 对于 Azure API 管理 方案:具有 LLM API 的 API 管理实例、嵌入后端、到嵌入后端的托管标识身份验证,以及配置为外部 Redis 兼容缓存的 Azure Managed Redis。 这些先决条件在 Azure API 管理 中为 LLM API 启用语义缓存中所述。
路径 1:使用 RedisVL 构建应用级语义缓存
当应用程序应控制缓存查找、未命中处理、模型调用、元数据和缓存存储时,请使用此路径。 RedisVL SemanticCache 连接到 Redis,并为语义上类似的提示提供 check 和 store 操作。
该值使用 Redis COSINE 距离单位,范围从 distance_threshold 到 0;根据 2,较低的值表示更严格的匹配。
安装所需的Python包:
pip install openai redis redis-entraid redisvl
在环境中设置AZURE_MANAGED_REDIS_HOST、AZURE_OPENAI_ENDPOINT、OPENAI_API_VERSION、AZURE_OPENAI_API_KEY、AZURE_OPENAI_EMBEDDING_DEPLOYMENT和AZURE_OPENAI_CHAT_DEPLOYMENT。 如果实例不使用端口 AZURE_MANAGED_REDIS_PORT,还可以设置 10000。
以下示例将配置的 Redis 客户端传递到 RedisVL,以便可以使用Azure托管 Redis TLS 和Microsoft Entra ID身份验证:
import os
from openai import AzureOpenAI
from redis import Redis
from redis_entraid.cred_provider import create_from_default_azure_credential
from redisvl.extensions.cache.llm import SemanticCache
from redisvl.utils.vectorize import AzureOpenAITextVectorizer
credential_provider = create_from_default_azure_credential(
("https://redis.azure.com/.default",)
)
redis_client = Redis(
host=os.environ["AZURE_MANAGED_REDIS_HOST"],
port=int(os.getenv("AZURE_MANAGED_REDIS_PORT", "10000")),
ssl=True,
credential_provider=credential_provider,
)
vectorizer = AzureOpenAITextVectorizer(
model=os.environ["AZURE_OPENAI_EMBEDDING_DEPLOYMENT"],
api_config={
"azure_endpoint": os.environ["AZURE_OPENAI_ENDPOINT"],
"api_version": os.environ["OPENAI_API_VERSION"],
# Load from a secret store or managed configuration. Don't hard-code keys.
"api_key": os.environ["AZURE_OPENAI_API_KEY"],
},
)
openai_client = AzureOpenAI(
api_key=os.environ["AZURE_OPENAI_API_KEY"],
api_version=os.environ["OPENAI_API_VERSION"],
azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
)
cache = SemanticCache(
name="semcache_support_promptv1",
redis_client=redis_client,
vectorizer=vectorizer,
distance_threshold=0.15, # Redis COSINE distance [0-2]; lower is stricter.
ttl=3600,
)
def call_llm(prompt: str) -> str:
completion = openai_client.chat.completions.create(
model=os.environ["AZURE_OPENAI_CHAT_DEPLOYMENT"],
messages=[{"role": "user", "content": prompt}],
)
response = completion.choices[0].message.content
if response is None:
raise RuntimeError("The chat completion didn't contain a response.")
return response
def answer(prompt: str) -> str:
hits = cache.check(prompt=prompt, num_results=1)
if hits:
return hits[0]["response"]
response = call_llm(prompt)
cache.store(
prompt=prompt,
response=response,
metadata={
"model_id": os.environ["AZURE_OPENAI_CHAT_DEPLOYMENT"],
"prompt_version": "support-v1",
},
)
return response
对于生产,不要在所有调用方之间共享一个未分区的缓存。 为租户、用户、模型 ID 和提示版本使用单独的缓存索引或 RedisVL 可筛选字段。 Redis 支持与元数据筛选器相结合的矢量搜索,如 Redis 矢量搜索概念中所述。
路径 2:使用Azure API 管理构建网关级语义缓存
当 LLM 流量流经 Azure API 管理 并且你希望使用集中式策略缓存时,请使用此路径。 Azure API 管理语义缓存使用配置的外部缓存和嵌入后端。 查找策略在转发到 LLM 后端之前检查语义上类似的缓存响应,存储策略会在后端返回后缓存符合条件的响应。 有关完整设置步骤,请参阅Azure API 管理中为 LLM API 启用语义缓存。
策略 llm-semantic-cache-lookup 在入站部分中运行,需要嵌入后端。 根据 llm-semantic-cache-lookup 策略参考,score-threshold 的范围从 0.0 到 1.0;较低的值需要更高的语义相似性。 根据
<policies>
<inbound>
<base />
<llm-semantic-cache-lookup
score-threshold="0.05"
embeddings-backend-id="embeddings-backend"
embeddings-backend-auth="system-assigned"
ignore-system-messages="true"
max-message-count="10">
<vary-by>@(context.Subscription.Id)</vary-by>
</llm-semantic-cache-lookup>
<rate-limit calls="10" renewal-period="60" />
</inbound>
<outbound>
<llm-semantic-cache-store duration="300" />
<base />
</outbound>
</policies>
使用 <vary-by> 按订阅、租户、用户组或其他可防止跨用户数据暴露的边界对缓存的响应进行分区。 Azure API 管理 策略参考建议使用 vary-by 来控制 llm-semantic-cache-lookup 策略中的缓存条目的跨用户访问。
建议的设计选择
优化相似性阈值
从严格的阈值开始,评估结果,只有当测试集表明缓存的响应仍然正确时,才放宽阈值。 RedisVL distance_threshold 使用 Redis COSINE 距离单位 [0-2],其中较低的值更严格。
Azure API 管理 score-threshold使用 0.0 到 1.0 的范围,其中较低的值也需要更高的语义相似性。 请勿在未验证其单位和行为之前,在 RedisVL 和 Azure API 管理 之间复制阈值。 有关 RedisVL 阈值的详细信息,请参阅 RedisVL SemanticCache API。 有关Azure API 管理阈值的详细信息,请参阅llm-semantic-cache-lookup。
按用例设置 TTL
为易失性或高风险内容设置较短的 TTL,并为稳定内容设置更长的 TTL。 例如:
| 用例 | 示例 TTL |
|---|---|
| 产品可用性、定价或操作状态 | 秒到分钟 |
| 政策、合规性或法律援助 | 分钟到小时数,进行额外评审 |
| 产品常见问题解答或公开文档中的解答 | 从小时到天 |
Azure API 管理 存储策略使用duration属性设置 TTL,如llm-semantic-cache-store所述。 RedisVL SemanticCache 支持默认 ttl 和每条目 TTL 替代,如 RedisVL SemanticCache API 中所述。
对缓存条目进行分区和版本控制
在重用响应之前,按租户、用户组或订阅对缓存条目进行分区。 还包括模型 ID、嵌入模型 ID、提示模板版本、工具配置版本以及缓存索引名称、元数据、密钥前缀或 API 管理 vary-by 值中的安全策略版本。 在模型或提示模板更改后重用缓存条目可能会返回过时或不兼容的响应。
确定何时不缓存
不要对高度个性化、监管、安全关键、时间敏感或依赖于工具或事务的副作用的提示或响应使用语义缓存。 由于语义缓存基于相似性而不是完全提示相等性返回响应,因此Azure API 管理警告说,缓存的响应对于当前请求可能不正确、过时或不安全,并且应仔细评估工作负荷。 有关详细信息,请参阅 llm-semantic-cache-lookup 使用情况说明。
监视缓存行为
跟踪缓存命中率、未命中率、查找延迟、后端 LLM 延迟、令牌和成本降低、阈值距离分布、过时响应报告、安全升级处理、Redis 内存使用、密钥计数、写入失败和缓存操作错误。 对于网关级缓存,请使用Azure API 管理跟踪和指标。 对于应用级缓存,记录查找结果、阈值、距离或分数(如果可用)、分区 ID、模型版本、提示版本以及响应是否来自缓存。
了解成本、性能和产品拟合
当语义缓存工作良好时,它可以通过返回相同或语义上类似的提示的存储响应来减少重复的后端 LLM 调用、令牌处理和端到端响应延迟。 RedisVL 将语义缓存描述为一种通过避免冗余 LLM 调用来降低 API 成本和延迟的方法。 Azure API 管理语义缓存还旨在降低带宽和后端处理要求,降低 API 使用者的延迟。 对于反复、稳定的问题和响应(例如产品常见问题解答、策略指南、支持分诊、文档助理以及针对稳定输入生成摘要)的工作负荷,其收益最高。
语义缓存还会给每个符合条件的请求带来额外开销。 应用程序或网关仍需要为传入提示创建嵌入、执行 Redis 矢量查找、应用分区和阈值规则,以及存储缓存未命中。 在缓存命中时,将避免 LLM 调用。 未命中时,请求会承担缓存查找开销和正常的模型调用。 规划额外的嵌入成本、Redis 内存、索引大小和查找延迟,并使用生产遥测来衡量净效果,而不是假设仅从缓存命中率中节省成本。
语义缓存与 LLM 无关,因为 Redis 存储提示嵌入、响应和元数据,而不是依赖于一个聊天模型提供程序。 缓存可以位于不同的 LLM API 前面,包括通过 Microsoft Foundry 或其他与 API 兼容的提供程序公开的模型 API。 但是,语义缓存索引必须对存储的提示和查找提示使用相同的嵌入模型、矢量维度和距离行为。 此外,通过聊天模型、提示模板、工具行为和安全策略对缓存进行分区或版本控制,因此在一个协定下生成的响应不会在另一个协定下重复使用。
在你控制模型调用边界的地方使用语义缓存:
| Microsoft AI 产品领域 | 适用于 Azure 托管 Redis 的语义缓存 |
|---|---|
| 智能 Microsoft 365 Copilot 副驾驶®和低代码/无代码Copilot Studio代理 | 通常不适合应用级别的 RedisVL 缓存,因为这些体验强调托管编排和低代码创作。 如果代理调用你自己的 API,请考虑在该 API 边界后进行缓存,而不是在 Copilot 创作体验中缓存。 |
| 位于 LLM API 前面的 Azure API 管理 | 如果想要集中的基于策略的语义缓存,而无需更改应用程序代码,则非常适合使用。 将 llm-semantic-cache-lookup 和 llm-semantic-cache-store 与 Azure Managed Redis 一起用作外部缓存。 |
| Microsoft Foundry 自定义应用和代理 | 在代码中构建自定义 AI 应用程序、代理、工具或编排并需要控制阈值、TTL、分区、模型版本、遥测和安全规则时,通常最合适。 在应用层中使用 RedisVL,或在 API 边界使用Azure API 管理。 |
在生产之前验证
在为生产流量启用语义缓存之前:
- 生成一组应匹配的提示和不能匹配的提示。
- 通过所选缓存路径运行测试集。
- 查看误报、过期答案、延迟和令牌节省。
- 根据需要收紧阈值、分区、TTL 或无缓存规则。
- 每当嵌入模型、聊天模型、提示模板、工具行为或安全策略更改时重复验证。