一个根据自己已给出的回答来作答的 AI 网关
支持助手整天被问到相同的问题,只是措辞略有不同。位于其模型前面的网关可以 用它先前为一个含义足够接近的问题给出的回复来回答当前问题,而不必再次调用 模型。本工作区将这样一个网关及其用于保存这些回复的存储编译为 Kubernetes manifests。
实现这一功能的 Feature 是 core/semantic-caching。一个调用方可以获得哪些
由另一个调用方的请求所产生的回复,是本页着重讨论的问题,因为一个被错误的
调用方共享的缓存会把为某个人生成的回复交给另一个人。
本工作区不编写任何自有的目录实体。这里的三个实体文件 ——一个 Aggregate、一个 Manifest 和一个 Release——就是任何人需要 编写的全部内容。
它构建了什么
| 实例 | 目录中的 Component | 它在此处的角色 |
|---|---|---|
router | core/gateway/litellm | AI 网关:一个聊天别名 assistant 和一个嵌入别名 embedder,各自由连接到其 models 插槽的模型提供服务 |
chat | core/ai-model/openai | assistant 背后的聊天模型,即 OpenAI 自己的 API,以引用方式访问:集群中不为它运行任何内容 |
embeddings | core/ai-model/openai-embedding | embedder 背后的嵌入模型,以同样的方式访问 |
cache | core/datastore/redis | 网关用于保存其回复的存储 |
三条 uses 边:两条进入网关的 models 插槽,分别连向两个模型,
各自以网关向该模型出示的密钥作为其 credential;
一条进入其 cache_store 插槽,以缓存向存储出示的密码作为其 credential。网关上有两个 Feature 挂载:
api_key,即其管理密钥,以及 answers,即缓存;存储上有一个挂载,
password,即它所要求的密码。两个密码挂载读取同一个
参数 cache_password,两个模型凭据读取另一个参数 openai_key;
由 Release 同时提供这两者。answers 挂载指明了将每条提示转换为向量的嵌入别名、两条提示必须有多相似(0.9,
以余弦相似度计),以及一条已存储的回复保留多久(一小时)。它省略了
scope,因此采用默认值 end_user。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example ai-gateway-semantic-cache然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd ai-gateway-semantic-cache构建
aggrega build --release release.yaml --auto-pullrelease 在构建之前需要一个 lockfile,而 lockfile 是生成的而非随附发布的,因此全新克隆的仓库中没有 lockfile。请先解析出一个,或者让构建来填充它:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the build此工作区从 .aggrega-config.yaml 指定的默认注册表解析目录实体。缓存的实现会运行一个既不随编译器也不随目录发布的插件,即网关配置步骤 pipeline-step/litellm-gateway-config,解析过程会从 default_registry 指定的注册表 hub.aggrega.ai 获取它。
构建会输出如下内容,其中 <workspace> 代表本示例的文件夹:
[… omitted: a line reporting on the gateway configuration step's plugin, five warnings, one per credential attachment, that the declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping, the resolution's summary and a total build time, which differ per run, and a notice that core/referenced-secret declares origin in both of its pillars]Build completed: 13 files written to <workspace>/dist借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 的工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `ai-gateway-semantic-cache` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `ai-gateway-semantic-cache`,且不提供 `dir`:它会把示例写入一个新的 `ai-gateway-semantic-cache` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `ai-gateway-semantic-cache`,`release` 设为 `release.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `ai-gateway-semantic-cache/dist/` 下。渲染出的目录树
dist/helm/├── cache--password--cache-secret-cache-password.yaml├── cache-default-service.yaml├── cache-deployment.yaml├── chat-service.yaml├── embeddings-service.yaml├── router--api-zukey--router-secret-router-api-key.yaml├── router--assistant-zdcredential--router-secret-router-assistant-credential.yaml├── router--embedder-zdcredential--router-secret-router-embedder-credential.yaml├── router--replies-zdcredential--router-secret-router-replies-credential.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yaml缓存挂载本身不带来任何文件。它的作用被写入 网关的配置中。每个模型渲染出一个文件,即一个将集群内名称映射到 OpenAI API 主机的 Service;模型 连接上的每个凭据都会渲染出各自的 Secret,以网关和该 连接的别名命名。
它提供的模型
路由表位于网关配置主体的开头,models 套接字上的每个连接在其中各有一个条目,条目根据每个模型发布的内容写出——其端点、OpenAI 的 API 基础 URL 及其模型名称——并指明网关的 Recipe 用来传递该连接密钥的变量:
model_list: - model_name: "assistant" litellm_params: model: "openai/gpt-4o" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_ASSISTANT_API_KEY - model_name: "embedder" litellm_params: model: "openai/text-embedding-3-small" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_EMBEDDER_API_KEY网关所读取的缓存
以下是网关的配置正文,即
dist/helm/router/litellm-gateway-config/configmap.yaml 中的 config.yaml 键,从其
litellm_settings 开始:
[… omitted: the routing table]litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter cache: true cache_params: host: os.environ/SEMANTIC_CACHE_STORE_HOST port: os.environ/SEMANTIC_CACHE_STORE_PORT redis_semantic_cache_embedding_model: embedder redis_semantic_cache_index_name: router-answers semantic_cache_scope: end_user similarity_threshold: 0.9 supported_call_types: - acompletion - completion - aresponses - responses - aanthropic_messages - anthropic_messages ttl: 3600 type: redis-semantic从中可以读出五点。
其中没有存储的地址。 host 和 port 通过网关自身的间接引用指定两个环境
变量,而网关的 Recipe 根据 cache_store 边设置这两个变量。以下摘自 dist/helm/router-deployment.yaml,即网关容器的
env:
env: - name: LITELLM_MASTER_KEY valueFrom: secretKeyRef: name: router-api-key key: master-key - name: REDIS_PASSWORD valueFrom: secretKeyRef: name: router-replies.credential key: password - name: LITELLM_MODEL_ASSISTANT_API_KEY valueFrom: secretKeyRef: name: router-assistant.credential key: api-key - name: LITELLM_MODEL_EMBEDDER_API_KEY valueFrom: secretKeyRef: name: router-embedder.credential key: api-key - name: SEMANTIC_CACHE_STORE_HOST value: cache-default - name: SEMANTIC_CACHE_STORE_PORT value: "6379"cache-default 是存储自身的 Recipe 生成的 Service,从该
Recipe 发布的内容中读取,6379 是它发布的端口。缓存从 REDIS_PASSWORD 读取存储的
密码,该变量引用 cache_store 边上的 credential 渲染出的 Secret,即 router-replies.credential,而从不读取
密码本身。存储根据同一个
参数 cache-password 渲染自己的 Secret,并以从中读取的 --requirepass 启动,因此
缓存提供的密码与存储要求的密码是同一个值,
只写一次。如果没有 cache_store 边,承载存储地址和密码的三个变量都不会
被渲染,而缓存没有地方保存回复,会使构建中止,如下文所述。第三和第四个条目是
各模型的密钥,每个都引用自其所属连接的
凭据渲染出的 Secret,使用路由表中对应条目指定的变量名;
helm provider 会把从 Secret 读取的每个条目写在普通
条目之前。
嵌入模型是网关自身映射中的一个别名。 网关将
每个提示词发送到 embedder,所经过的映射与调用方请求经过的相同,
因此缓存不持有自己的地址或凭据。如果指定映射
未发布的别名,构建会中止,并列出映射已发布的别名。
生命周期由存储决定。 每条回复写入时以 ttl 作为
过期时间,因此 Redis 会在存储一小时后将其删除。之后针对
该提示词的下一个请求由模型作答,并重新存储。
只列出缓存会读取其提示词的请求类型。 聊天 请求(无论是否流式)以及 responses 和 messages API 会被缓存。 completions 请求不会被缓存,embeddings 请求也不会:如果保留 默认设置,网关会存储每个 embeddings 请求的回复, 为此将每个输入再嵌入一次,却从不返回其中任何一条。
索引以网关和挂接命名,即 router-answers,因此
同一个 Release 中共享一个存储的两个网关会将各自的回复保存在不同的
索引中。
一个缓存条目为谁提供响应
只有当构成其分桶的所有要素都匹配,且提示与它所回答的提示相似度至少为 0.9 时,已存储的回复才会提供给后来的请求:
- 请求出示的密钥(以网关验证的结果为准),以及该密钥的团队和组织;
- 在
end_user下,请求指明的最终用户; - 请求所要求的模型,以及请求的其他参数——不同的 temperature 就是不同的分桶。
网关会把密钥、其团队和组织以及最终用户写入请求本身。对于 chat 请求,网关把它们写入请求的 metadata,覆盖调用方在那里发送的任何值;对于 responses 或 messages 请求,网关把它们与调用方的 metadata 分开保存,从中移除调用方写入的任何团队、组织或最终用户字段,并且其 Recipe 提供的请求守卫会拒绝在那里指明密钥(metadata.user_api_key)的请求,返回指明该字段的 HTTP 400。因此,没有请求能够通过指明某个名称进入另一个密钥的分桶。
请求自身的 metadata 仍可以让它在所出示密钥的各个分桶之间移动。对于 responses 请求,model_group 会在分桶中取代请求所要求的模型。对于 responses 或 messages 请求,caching_groups 让指明同一组模型别名的请求在这些别名之间共享回复。对于 responses 或 chat 请求,redis_namespace 会把指明某个命名空间的请求与未指明命名空间的请求放在不同的分桶中。它们都无法进入另一个密钥的分桶。
此网关的密钥就是其管理密钥,每个调用方都持有它。
该网关未挂接记账数据库,因此不会签发自己的密钥:每个调用方都出示挂接到 api_key 的密钥,没有密钥或密钥并非由网关签发的请求,会在任何查找之前被拒绝。
因此在这里,密钥并不能区分不同的调用方;在默认范围下,使两个调用方彼此隔离的是每个请求指明的最终用户。
在默认的 end_user 下,一个条目会提供给指明同一最终用户的请求。 网关从请求中读取最终用户:x-litellm-end-user-id 或 x-litellm-customer-id 请求头,或者请求体的 user、metadata.user_id、litellm_metadata.user 或 safety_identifier 字段。为 alice 存储的回复会提供给 alice 措辞相似的问题,而不会提供给 bob 的问题。
由此得出两点,二者都是网关的行为,而非配置:
- 网关不会验证这些名称中的任何一个。 持有密钥的人可以指明任意最终用户,并获得为该最终用户存储的内容。请把密钥保留在知道其最终用户是谁的应用中,由应用来指明他们; 不要把密钥交给最终用户本人。
- 未指明最终用户的请求共享同一个缓存。 每个出示相同密钥的此类请求,无论由谁发送, 都从相同的条目获得响应。
在 key 下,每个出示该密钥的调用方都从同一个缓存获得响应。 在挂接的 values 中添加 scope: key 并重新构建:配置的 semantic_cache_scope 变为 key,渲染输出中的其他内容都不变。此时请求头指明的最终用户不再属于分桶的一部分,因此为 alice(在 x-litellm-end-user-id 请求头中指明)存储的回复,会提供给以同样方式指明 bob 的措辞相似的问题,其中的工具调用也包括在内。不过,请求体的 user 字段属于请求的其他参数,因此在那里指明不同最终用户的两个请求仍会落入不同的分桶,就像两个不同的 temperature 一样。这只适合缓存对所有人都相同的答案。
什么会中止构建
以下每一项都是构建打印的一句话,指明需要修改什么:
-
没有管理密钥。 移除
api_key附加项,构建会在任何内容渲染之前停止:[… omitted: a line reporting on the gateway configuration step's plugin, what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][CATALOG_ERROR E0033]Recipe/FeatureRecipe assertionscaused by: FeatureRecipe "semantic-caching-litellm" instance "router" assertion "gateway_checks_the_caller": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "router" needs core/gateway/litellm to check every caller's key before a cached reply is served, but its api_key credential slot is not attached, so the gateway checks no caller and a cache bucket would be made only of what each caller claims. Attach a credential to the api_key slot of "router" -
没有存储。 移除
cache_store边,构建会停止,并指出需要连接的插槽。 -
存储未发布
vector_search。 该插槽接受键值存储,而网关的 Recipe 会在某个存储未声明支持 Redis 查询引擎的向量搜索时停止,缓存正是用这种向量搜索来检索其回复的:8.0 版本之前的 Redis 或 Valkey 会什么都不缓存,而每个请求仍然成功。 -
网关上的第二个
core/semantic-caching附加项,而网关只有一个缓存。 -
同一网关上的
core/data-masking。 二者声明了冲突,因为缓存是在脱敏之后为请求生成键的,所以仅在脱敏所替换内容上有差异的两个请求会共享同一条存储的回复。
存储无法使用时
网关在首次处理请求时连接存储,而不是在启动时连接。如果它无法使用该存储——存储要求一个网关未获得的密码,或拒绝了网关提供的密码——则每次查找都会未命中,也不会存储任何内容,而每个请求仍由模型作答。只有网关自身的日志会说明这一点。正因如此,密码的两端读取同一个参数:存储的 password 槽位,以及 cache_store 边上的 credential。
编译器不做解释的地方
编译器把存储的 Service 名称和端口从存储的 Recipe
以字符串形式传入网关的环境变量,并把别名和数值传入
网关的配置。它不会连接存储,不知道
cache-default:6379 上是否有服务应答,也不知道最终
用户是什么。上文的每一次中止都由目录自身的实体声明:作为
实现或网关 Recipe 中的断言,或作为两个
Features 声明的冲突;其中没有一项依赖于对流量的任何理解。
改编示例
- 每个 key 共享一个缓存。 在每个调用方都应获得相同回复的场合,向
answers附件添加scope: key。 - 在不设密码的情况下运行存储。 同时移除存储的
password附件和cache_store边上的credential,并一并移除 Aggregate 和 Release 中的cache_password参数;此时网关的REDIS_PASSWORD会渲染为空,即不使用密码进行连接。只移除 两个附件中的一个,会导致缓存无法使用该存储。 - 匹配更多或更少的提示。 提高
similarity_threshold以只为更接近的匹配提供回复, 或降低它以提供更多回复;哪个值合适取决于 嵌入模型。