缓存（简单与语义）

语义缓存适用于生产和企业用户。

简单缓存适用于所有计划。

通过将过去的响应存储在Portkey缓存中，加速并节省您的LLM请求费用。缓存模式有2种：

• 简单：逐字匹配请求。非常适合重复的、相同的提示。适用于所有模型，包括图像生成模型。

• **语义：针对语义相似的请求匹配响应。适合去噪请求，处理多余的介词、代词等。适用于/chat/completions或/completions**路由上的任何模型。

Portkey缓存处理请求速度可达20倍，并且更便宜。

在配置中启用缓存

要启用 Portkey 缓存，只需将 cache 参数添加到您的 config object 中。

简单缓存

"cache": { "mode": "simple" }

工作原理

简单缓存对输入提示执行精确匹配。如果再次收到完全相同的请求，Portkey 将直接从缓存中检索响应，绕过模型执行。

语义缓存

"cache": { "mode": "semantic" }

工作原理

语义缓存考虑输入请求之间的上下文相似性。它使用余弦相似度来确定输入与缓存请求之间的相似性是否超过特定阈值。如果满足相似性阈值，Portkey 将从缓存中检索响应，从而节省模型执行时间。有关我们如何做到这一点的更多详细信息，请查看这篇 博客。

语义缓存是两个缓存的“超集”。将缓存模式设置为“语义”也适用于简单的缓存命中情况。

为了优化准确的缓存命中率，语义缓存仅适用于输入标记少于 8,191 的请求，并且消息数量（人类、助手、系统合计）小于或等于 4。

在语义缓存中忽略第一条消息

在使用 /chat/completions 端点时，Portkey 至少需要在 messages 数组中包含 两个 消息对象。第一个消息对象通常用于 system 消息，在确定语义相似性以进行缓存时不予考虑。

例如：

messages = [
        { "role": "system", "content": "You are a helpful assistant" },
        { "role": "user", "content": "Who is the president of the US?" }
]

在这种情况下，仅使用 user 消息的内容（"Who is the president of the US?"）来查找缓存中的语义匹配。system 消息（"You are a helpful assistant"）被忽略。

这意味着即使您在保持 user 消息语义相似的情况下更改 system 消息，Portkey 仍然会返回语义缓存命中。

这使您能够修改助手的行为或上下文，而不会影响类似用户查询的缓存命中。

了解如何在配置中设置缓存.

---

设置缓存年龄

您可以通过此设置来设置缓存响应的年龄（或“ttl”）。缓存年龄也在您的 Config 对象中设置：

"cache": { 
    "mode": "semantic",
    "max_age": 60
}

在此示例中，您的缓存将在 60 秒后自动过期。缓存年龄以 秒 为单位。

• 最小 缓存年龄为 60 秒

• 最大 缓存年龄为 90 天（即 7776000 秒）

• 默认 缓存年龄为 7 天（即 604800 秒）

---

强制刷新缓存

确保即使您的请求存在现有的缓存响应，也能获取并存储新的响应。缓存强制刷新只能在发起请求时进行，并且不属于您的配置。

您可以通过以下请求头启用缓存强制刷新：

"x-portkey-cache-force-refresh": "True"

REST API

curl https://api.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-virtual-key: open-ai-xxx" \
  -H "x-portkey-config: cache-config-xxx" \
  -H "x-portkey-cache-force-refresh: true" \
  -d '{
    "messages": [{"role": "user","content": "Hello!"}]
  }'

Python

Node

• 只有在请求中同时传递缓存配置时，缓存强制刷新才会被激活。（仅将cacheForceRefresh设置为true而不传递相关的缓存配置将不会产生任何效果）

• 对于具有先前语义命中的请求，强制刷新将在您请求的所有语义匹配项上执行。

---

缓存命名空间：简化缓存分区

Portkey 通常沿着请求头中传递的所有值对缓存进行分区。使用自定义缓存命名空间，您现在可以忽略元数据和其他头信息，仅基于您发送的自定义字符串对缓存进行分区。

这使您能够更精细地控制缓存数据，并优化缓存命中率。

工作原理

要使用缓存命名空间，只需在您的 API 请求中包含 x-portkey-cache-namespace 头，后面跟上任何自定义字符串值。Portkey 将使用此命名空间字符串作为划分缓存的唯一依据，忽略所有其他头，包括元数据。

例如，如果您发送以下头：

"x-portkey-cache-namespace: user-123"

Portkey 将在命名空间 user-123 下缓存响应，忽略与请求相关的任何其他头或元数据。

Node

import Portkey from 'portkey-ai';

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY",
    config: "pc-cache-xxx",
    virtualKey: "open-ai-xxx"
})

async function main(){
    const response = await portkey.chat.completions.create({
        messages: [{ role: 'user', content: 'Hello' }],
        model: 'gpt-4',
    }, {
        cacheNamespace: 'user-123'
    });
}

main()

在这个例子中，响应将在命名空间 user-123 下缓存，忽略任何其他头或元数据。

Python

REST

---

分析中的缓存

Portkey 在分析页面上为您提供强大的缓存使用统计信息。只需前往缓存标签，您将看到：

• 您的缓存命中总数以及每日缓存命中率

• 从缓存交付结果的平均延迟以及为您节省的时间

• 缓存为您节省了多少资金

日志中的缓存

在日志页面，缓存状态会在状态列中更新。当您未使用缓存时，您将看到 Cache Disabled，而根据缓存命中状态，您可能会看到 Cache Miss、Cache Refreshed、Cache Hit 或 Cache Semantic Hit。更多信息请阅读 here。

对于每个请求，我们还会计算并显示缓存响应时间，以及您通过每次命中节省了多少费用。

---

缓存如何与配置一起工作

您可以在两个级别设置缓存：

• 顶级，适用于所有目标。

• 目标级别，当特定目标被触发时有效。

设置顶级缓存

{
  "cache": {"mode": "semantic", "max_age": 60},
  "strategy": {"mode": "fallback"},
  "targets": [
    {"virtual_key": "openai-key-1"},
    {"virtual_key": "openai-key-2"}
  ]
}

设置目标级别缓存

您也可以在**两个级别（顶级和目标）**设置缓存。

在这种情况下，目标级别缓存设置将优先于 顶级缓存设置。您应该从第二个请求开始为该特定目标获取缓存命中。

如果您的任何目标具有**override_params，则该目标上的缓存将无法工作，直到该特定参数组合也与缓存一起存储。 如果该目标没有override_params**，那么即使该目标没有被触发过一次，缓存也将处于活动状态。