aiproxy/core/relay/plugin/cache/README.zh.md

Cache Plugin 配置指南

概述

Cache Plugin 是一个高性能的 AI API 请求缓存解决方案，通过存储和重用相同请求的响应来帮助减少延迟和成本。它支持内存缓存和 Redis，适用于分布式部署。

功能特性

• 双重存储：支持内存缓存和 Redis，提供灵活的部署选项
• 自动降级：Redis 不可用时自动降级到内存缓存
• 基于内容的缓存：使用请求体的 SHA256 哈希值生成缓存键
• 可配置 TTL：为缓存项设置自定义生存时间
• 大小限制：可配置最大项目大小以防止内存问题
• 缓存头部：可选的头部信息来指示缓存命中
• 零拷贝设计：通过缓冲池实现高效的内存使用

配置示例

{
    "model": "gpt-4",
    "type": 1,
    "plugin": {
        "cache": {
            "enable": true,
            "ttl": 300,
            "item_max_size": 1048576,
            "add_cache_hit_header": true,
            "cache_hit_header": "X-Cache-Status"
        }
    }
}

配置字段说明

插件配置

字段	类型	必填	默认值	说明
enable	bool	是	false	是否启用 Cache 插件
ttl	int	否	300	缓存项的生存时间（秒）
item_max_size	int	否	1048576 (1MB)	单个缓存项的最大大小（字节）
add_cache_hit_header	bool	否	false	是否添加指示缓存命中的头部
cache_hit_header	string	否	"X-Aiproxy-Cache"	缓存命中头部的名称

工作原理

缓存键生成

插件基于以下内容生成缓存键：

1. 请求模式（如 chat completions）
2. 请求体的 SHA256 哈希值

这确保了相同的请求会命中缓存，而不同的请求不会相互干扰。

缓存存储

插件使用两层缓存策略：

1. Redis（如果可用）：分布式缓存的主要存储
2. 内存：备用存储或未配置 Redis 时的主要存储

请求流程

1. 请求阶段：

   • 插件检查是否启用缓存
   • 从请求体生成缓存键
   • 查找缓存（先查 Redis，再查内存）
   • 如果命中，立即返回缓存的响应
   • 如果未命中，继续请求上游 API

2. 响应阶段：

   • 捕获响应体和头部
   • 如果响应成功，存储到缓存
   • 遵守大小限制以防止内存问题

使用示例

{
    "plugin": {
        "cache": {
            "enable": true,
            "ttl": 60,
            "item_max_size": 524288,
            "add_cache_hit_header": true
        }
    }
}

响应头部示例

当 add_cache_hit_header 启用时：

缓存命中：

X-Aiproxy-Cache: hit

缓存未命中：

X-Aiproxy-Cache: miss