Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Un gateway de IA que responde a partir de lo que ya dijo

A un asistente de soporte le hacen las mismas preguntas todo el día con palabras ligeramente distintas. El gateway situado delante de su modelo puede responder a una pregunta a partir de la respuesta que dio a una anterior lo bastante cercana en significado, en lugar de volver a llamar al modelo. Este workspace compila un gateway así a manifiestos de Kubernetes, con el almacén en el que guarda esas respuestas.

La Feature que lo hace es core/semantic-caching. Qué respuestas producidas por la solicitud de un llamador se le pueden servir a otro llamador es la cuestión a la que esta página dedica la mayor parte de su espacio, porque una caché compartida por los llamadores equivocados le entrega a una persona una respuesta generada para otra.

Este workspace no crea ninguna entidad de catálogo propia. Los tres archivos de entidad de aquí — un Aggregate, un Manifest y una Release — son todo lo que se escribe.

Lo que construye

instanciaComponent del catálogoqué es aquí
routercore/gateway/litellmel gateway de IA: un alias de chat, assistant, y un alias de embedding, embedder, cada uno servido desde un modelo conectado a su socket models
chatcore/ai-model/openaiel modelo de chat detrás de assistant, la propia API de OpenAI, alcanzado como referencia: nada se ejecuta para él en el clúster
embeddingscore/ai-model/openai-embeddingel modelo de embedding detrás de embedder, alcanzado del mismo modo
cachecore/datastore/redisel almacén en el que el gateway guarda sus respuestas

Tres aristas uses: dos hacia el socket models del gateway, una hacia cada modelo, cada una de las cuales lleva como su credential la clave que el gateway presenta a ese modelo, y una hacia su socket cache_store, que lleva como su credential la contraseña que la caché presenta al almacén. Dos vinculaciones de Feature en el gateway: api_key, su clave administrativa, y answers, la caché; y una en el almacén, password, la contraseña que exige. Las dos vinculaciones de contraseña leen un mismo parámetro, cache_password, y las dos credenciales de los modelos otro, openai_key; la Release cumple ambos. La vinculación answers nombra el alias de embedding que convierte cada prompt en un vector, cuánto deben parecerse dos prompts — 0.9, como similitud del coseno — y cuánto dura una respuesta almacenada, una hora. Omite scope, así que toma el valor predeterminado, end_user.

Generar el ejemplo

Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.

Escribe el ejemplo en una carpeta nueva con su nombre:

Terminal window
aggrega scaffold --example ai-gateway-semantic-cache

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd ai-gateway-semantic-cache

Compilación

Terminal window
aggrega build --release release.yaml --auto-pull

Una release necesita un lockfile antes de compilarse, y los lockfiles se generan en lugar de distribuirse, así que un clon recién hecho no tiene ninguno. Resuelve uno primero, o deja que la compilación lo rellene:

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

Este workspace resuelve las entidades del catálogo desde el registro predeterminado que nombra .aggrega-config.yaml. La realización de la caché ejecuta un plugin que no se incluye ni en el compilador ni en el catálogo, el paso de configuración del gateway pipeline-step/litellm-gateway-config, que la resolución obtiene del registro que nombra default_registry, hub.aggrega.ai.

La compilación imprime, con <workspace> en lugar de la carpeta de este ejemplo:

[… 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

Con un asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.

Usa solo las herramientas de Aggrega y no crees ninguna carpeta tú mismo. Si la carpeta del espacio de trabajo aún no contiene una carpeta `ai-gateway-semantic-cache`, llama una sola vez a la herramienta `scaffold` con `example` establecido en `ai-gateway-semantic-cache` y sin `dir`: escribe el ejemplo en una nueva carpeta `ai-gateway-semantic-cache`. Después llama a la herramienta `build` con `workspace_root` establecido en `ai-gateway-semantic-cache`, `release` establecido en `release.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `ai-gateway-semantic-cache/dist/`.

El árbol renderizado

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

La vinculación de la caché no aporta ningún archivo propio. Lo que hace se escribe en la configuración del gateway. Cada modelo renderiza un archivo, un Service que asigna un nombre interno del clúster al host de la API de OpenAI, y cada credencial en una conexión de modelo renderiza un Secret propio, con el nombre del gateway y del alias de la conexión.

Los modelos que sirve

La tabla de enrutamiento, el comienzo del cuerpo de configuración del gateway, tiene una entrada por cada conexión en el socket models, escrita a partir de lo que publica cada modelo — su endpoint, la URL base de la API de OpenAI, y su nombre de modelo — y que nombra la variable bajo la que la Recipe del gateway entrega la clave de esa conexión:

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

La caché, tal como la lee el gateway

Este es el cuerpo de configuración del gateway, la clave config.yaml de dist/helm/router/litellm-gateway-config/configmap.yaml, desde su litellm_settings en adelante:

[… 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

Hay cinco cosas que vale la pena leer en él.

La dirección del almacén no está en él. host y port nombran dos variables de entorno mediante la indirección propia del gateway, y la Recipe del gateway las establece a partir de la arista cache_store. De dist/helm/router-deployment.yaml, el env del contenedor del gateway:

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 es el Service que emite la propia Recipe del almacén, leído de lo que publica esa Recipe, y 6379 el puerto que publica. La caché lee la contraseña del almacén de REDIS_PASSWORD, una referencia al Secret que renderiza la credential de la arista cache_store, router-replies.credential, y nunca la contraseña en sí. El almacén renderiza un Secret propio a partir del mismo parámetro, cache-password, y arranca con --requirepass leído de él, así que la contraseña que presenta la caché y la que exige el almacén son un único valor, escrito una sola vez. Sin una arista cache_store no se renderiza ninguna de las tres variables bajo las que llegan la dirección y la contraseña del almacén, y la caché, sin dónde guardar sus respuestas, detiene la compilación, como se ve más abajo. La tercera y la cuarta entrada son las claves de los modelos, cada una referenciada desde el Secret que renderiza la credencial de su propia conexión, bajo la variable que nombra su entrada en la tabla de enrutamiento; el proveedor helm escribe cada entrada que lee de un Secret antes que las simples.

El modelo de embedding es un alias del propio mapa del gateway. El gateway envía cada prompt a embedder a través del mismo mapa por el que pasa la solicitud de un llamador, así que la caché no guarda ninguna dirección ni credencial propia. Nombra un alias que el mapa no publique y la compilación se detiene, enumerando los que sí publica.

La duración es la del almacén. Cada respuesta se escribe con ttl como caducidad, así que Redis la elimina una hora después de almacenarla. La siguiente solicitud para ese prompt la responde el modelo, y la respuesta se almacena de nuevo.

Solo se nombran los tipos de solicitud cuyo prompt lee la caché. Las solicitudes de chat, en streaming o no, y las API responses y messages se almacenan en caché. Una solicitud completions no, y tampoco una solicitud de embeddings: con su propio valor predeterminado, el gateway almacenaría la respuesta a cada solicitud de embeddings, calculando para ello por segunda vez el embedding de cada entrada, y no devolvería ninguna.

El índice lleva el nombre del gateway y de la vinculación, router-answers, así que dos gateways de una misma Release que comparten un almacén guardan sus respuestas en índices separados.

A quién se sirve desde una entrada de la caché

Una respuesta almacenada se sirve a una solicitud posterior solo cuando todo lo que compone su compartimento coincide, y el prompt tiene una similitud de al menos 0.9 con aquel al que respondió:

  • la clave que presenta la solicitud, tal como la verificó el gateway, con el equipo y la organización de esa clave;
  • con end_user, el usuario final que nombra la solicitud;
  • el modelo que pide la solicitud, y los demás parámetros de la solicitud — una temperatura distinta es un compartimento distinto.

El gateway escribe la clave, su equipo y su organización y el usuario final en la propia solicitud. En una solicitud de chat los escribe en los metadata de la solicitud, por encima de cualquier valor que el llamador haya enviado ahí; en una solicitud responses o messages los mantiene aparte de los metadata del llamador, elimina de ellos cualquier campo de equipo, organización o usuario final que haya escrito el llamador, y la guarda de solicitudes que entrega su Recipe rechaza una solicitud que nombre ahí la clave, metadata.user_api_key, con HTTP 400 nombrando el campo. Así que ninguna solicitud puede entrar en el compartimento de otra clave con solo nombrarla.

Los propios metadata de una solicitud aún pueden moverla entre los compartimentos de la clave que presenta. En una solicitud responses, model_group ocupa en su compartimento el lugar del modelo que pide la solicitud. En una solicitud responses o messages, caching_groups permite que las solicitudes que nombran el mismo grupo de alias de modelo compartan respuestas entre ellos. En una solicitud responses o de chat, redis_namespace mantiene las solicitudes que nombran un namespace en compartimentos aparte de las que no nombran ninguno. Ninguno de ellos llega al compartimento de otra clave.

La clave de este gateway es su clave administrativa, y todo llamador la tiene. No tiene vinculada ninguna base de datos de gestión, así que no emite claves propias: todo llamador presenta la clave vinculada a api_key, y una solicitud sin clave, o con una clave que el gateway no emitió, se rechaza antes de buscar nada. Así que aquí la clave no separa a ningún llamador de otro, y con el ámbito predeterminado lo que mantiene separados a dos llamadores es el usuario final que nombra cada solicitud.

Con end_user, el valor predeterminado, una entrada se sirve a las solicitudes que nombran el mismo usuario final. El gateway lee el usuario final de la solicitud: un encabezado x-litellm-end-user-id o x-litellm-customer-id, o el campo user, metadata.user_id, litellm_metadata.user o safety_identifier del cuerpo. Una respuesta almacenada para alice se sirve para la pregunta de alice formulada de forma parecida, y no para la de bob.

De ello se siguen dos cosas, y ambas son comportamiento del gateway y no configuración:

  • El gateway no verifica ninguno de esos nombres. Quien tenga la clave puede nombrar a cualquier usuario final y recibe lo que se almacenó para ese usuario final. Mantén la clave en la aplicación que sabe quiénes son sus usuarios finales, y deja que sea ella quien los nombre; no entregues la clave a los propios usuarios finales.
  • Las solicitudes que no nombran ningún usuario final comparten una sola caché. Toda solicitud de ese tipo que presente la misma clave se sirve desde las mismas entradas, la haya enviado quien la haya enviado.

Con key, todo llamador que presente la clave se sirve desde una sola caché. Añade scope: key a los valores de la vinculación y vuelve a compilar: el semantic_cache_scope de la configuración dice key, y nada más cambia en la salida renderizada. El usuario final que nombra un encabezado deja entonces de formar parte del compartimento, así que una respuesta almacenada para alice, nombrada en un encabezado x-litellm-end-user-id, se sirve para la pregunta de bob formulada de forma parecida que lo nombra del mismo modo, incluidas las llamadas a herramientas que contenga. El campo user del cuerpo es, sin embargo, uno de los demás parámetros de la solicitud, así que dos solicitudes que nombran ahí usuarios finales distintos siguen cayendo en compartimentos distintos, como ocurre con dos temperaturas. Eso conviene a una caché de respuestas que son las mismas para todos, y a nada más.

Qué detiene la compilación

Cada uno de estos casos es una frase que imprime la compilación, y que nombra qué cambiar:

  • Ninguna clave administrativa. Quita la vinculación api_key y la compilación se detiene antes de renderizar nada:

    [… 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 assertions
    caused 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"
  • Ningún almacén. Quita la arista cache_store y la compilación se detiene nombrando el socket que hay que conectar.

  • Un almacén que no publica ningún vector_search. El socket admite los almacenes clave-valor, y la Recipe del gateway se detiene con uno que no declare que sirve la búsqueda vectorial del motor de consultas de Redis, con la que la caché busca entre sus respuestas: un Redis anterior a la versión 8.0, o Valkey, no almacenaría nada mientras todas las solicitudes seguirían teniendo éxito.

  • Una segunda vinculación core/semantic-caching en el gateway, que tiene una sola caché.

  • core/data-masking en el mismo gateway. Las dos declaran un conflicto, porque una caché calcula la clave de una solicitud después del enmascaramiento, así que dos solicitudes que solo difieren en lo que sustituye el enmascaramiento compartirían una única respuesta almacenada.

Cuando no se puede usar el almacén

El gateway se conecta al almacén cuando sirve su primera solicitud, no cuando arranca. Si no puede usar el almacén — el almacén pide una contraseña que no se le dio al gateway, o rechaza la que se le dio —, todas las búsquedas fallan y no se almacena nada, mientras el modelo sigue respondiendo a todas las solicitudes. Solo el registro propio del gateway lo indica. Por eso los dos extremos de la contraseña leen un mismo parámetro: el slot password del almacén y la credential de la arista cache_store.

Dónde el compilador no interpreta

El compilador canaliza el nombre del Service y el puerto del almacén desde la Recipe del almacén hacia el entorno del gateway como cadenas, y el alias y los números hacia la configuración del gateway. No se conecta al almacén, no sabe si algo responde en cache-default:6379, y no sabe qué es un usuario final. Cada detención de arriba la declaran las propias entidades del catálogo, como una aserción en la realización o en la Recipe del gateway o como el conflicto que declaran las dos Features, y ninguna de ellas se basa en comprensión alguna del tráfico.

Adaptarlo

  • Compartir una caché por clave. Añade scope: key a la vinculación answers, donde a todo llamador se le deban servir las mismas respuestas.
  • Ejecutar el almacén sin contraseña. Quita a la vez la vinculación password del almacén y la credential de la arista cache_store, junto con el parámetro cache_password en el Aggregate y en la Release; el REDIS_PASSWORD del gateway se renderiza entonces vacío, lo que conecta sin contraseña. Quitar solo una de las dos vinculaciones deja a la caché sin poder usar el almacén.
  • Hacer coincidir más o menos prompts. Sube similarity_threshold para servir solo coincidencias más cercanas, o bájalo para servir más; qué valor conviene depende del modelo de embedding.