Un gateway de IA que mantiene los datos personales fuera de sus registros
Un asistente de soporte tiene que trabajar con los nombres y las direcciones de correo de los clientes, así que el modelo al que llama debe verlos. El gateway situado delante de ese modelo guarda registros para auditoría y para depuración, y esos registros no deben conservarlos. Este workspace compila un gateway así a manifiestos de Kubernetes.
Lo que lo hace es un valor del propio gateway, values.log_masking en core/gateway/litellm. Enmascara la copia de cada llamada que el gateway entrega a sus registros, y nada más: el modelo recibe la solicitud exactamente como la envió el llamador, y el llamador recibe la respuesta exactamente como la escribió el modelo. Esa es la diferencia con la Feature core/data-masking, que oculta el texto al propio modelo. Las dos son alternativas, y la sección de abajo sobre cómo elegir entre ellas muestra qué ocurre cuando ambas se establecen en un mismo gateway.
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
| instancia | Component del catálogo | qué es aquí |
|---|---|---|
router | core/gateway/litellm | el gateway de IA: un solo alias publicado, assistant, servido desde el modelo conectado a su socket models |
gpt | core/ai-model/openai | el modelo detrás de ese alias, la propia API de OpenAI, alcanzado como referencia: nada se ejecuta para él en el clúster |
analyzer | core/security/presidio-analyzer | encuentra los fragmentos sensibles de un texto |
anonymizer | core/security/presidio-anonymizer | sustituye los fragmentos que se le entregan |
Tres aristas uses: el socket models del gateway hacia el modelo, que lleva como su credential la clave que el gateway le presenta, y sus sockets pii_analyzer y pii_anonymizer hacia los dos servicios de reconocimiento. El Aggregate vincula esa credencial sin nombrar un secreto, y la Release la nombra en la infra de la vinculación: un Secret que el namespace ya contiene, al que la realización del Manifest hace referencia y que no renderiza. El values.log_masking del gateway enumera qué enmascarar: una expresión regular para los números de ticket de la empresa bajo patterns, y los tipos de entidad PERSON y EMAIL_ADDRESS bajo entities. No hay ninguna lista predeterminada; un gateway que no enumera ni lo uno ni lo otro no enmascara nada en sus registros, y se renderiza exactamente igual que sin el valor.
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:
aggrega scaffold --example ai-gateway-log-maskingDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd ai-gateway-log-maskingCompilación
aggrega build --release release.yaml --auto-pullUna 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:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildEste workspace resuelve las entidades del catálogo desde el registro predeterminado que nombra .aggrega-config.yaml. La propia Recipe del gateway escribe el enmascaramiento de registros, así que la compilación no ejecuta ningún plugin aparte de los que lleva el compilador.
La compilación imprime, con <workspace> en lugar de la carpeta de este ejemplo:
[… omitted: the resolution's summary, a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]Build completed: 9 files written to <workspace>/distCon 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-log-masking`, llama una sola vez a la herramienta `scaffold` con `example` establecido en `ai-gateway-log-masking` y sin `dir`: escribe el ejemplo en una nueva carpeta `ai-gateway-log-masking`. Después llama a la herramienta `build` con `workspace_root` establecido en `ai-gateway-log-masking`, `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-log-masking/dist/`.El árbol renderizado
dist/helm/├── analyzer-default-service.yaml├── analyzer-deployment.yaml├── anonymizer-default-service.yaml├── anonymizer-deployment.yaml├── gpt-service.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yamlEl valor no aporta ningún archivo propio. La Recipe del gateway lo escribe en la configuración del gateway, y añade al ConfigMap del gateway un módulo que esa configuración carga. El modelo renderiza un archivo, gpt-service.yaml, un Service que asigna un nombre interno del clúster al host de la API de OpenAI, api.openai.com; su clave no renderiza ninguno, porque el Secret que la contiene ya existe.
La tabla de enrutamiento, el comienzo del cuerpo de configuración del gateway, tiene una sola entrada, escrita a partir de lo que publica el 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 la 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_KEYLa entrada del guardrail
Este es el cuerpo de configuración del gateway, la clave config.yaml de dist/helm/router/litellm-gateway-config/configmap.yaml, desde su sección litellm_settings en adelante:
[… omitted: the routing table]litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter - log_masking.withhold_failed_calls redact_messages_in_exceptions: trueguardrails: - guardrail_name: "router.log-masking" litellm_params: guardrail: log_masking.LogMasking default_on: true mode: logging_only patterns: - pattern_type: regex name: "ticket" pattern: "\\bTCK-[0-9]{6}\\b" action: MASK pii_entities_config: "PERSON": MASK "EMAIL_ADDRESS": MASKgeneral_settings: disable_error_logs: trueLa Recipe del gateway lo escribe todo a partir de values.log_masking, y da a la entrada el nombre del gateway, aquí router, con un punto donde las entradas de guardrail que escriben las realizaciones de la biblioteca estándar llevan un guion, de modo que ninguna vinculación suya, tenga el nombre que tenga, puede ocupar el lugar de esta entrada. Hay cinco cosas que vale la pena leer en ella.
mode: logging_only es el modo propio del gateway para un guardrail que se ejecuta donde una llamada terminada se entrega a sus registros, y en ningún otro sitio. La clase que carga la entrada se atiene a él nombre lo que nombre una entrada, así que nunca se la llama sobre una solicitud antes de que la solicitud se reenvíe, ni sobre una respuesta antes de que la respuesta se devuelva.
default_on: true lo ejecuta en cada llamada. Un llamador no puede desactivarlo desde la solicitud, ni siquiera con una solicitud que pida deshabilitar los guardrails siempre activos del gateway.
El patrón llega al gateway exactamente como se escribió. Se compara dentro del gateway, sin distinguir mayúsculas de minúsculas, y cada coincidencia se sustituye definitivamente por el nombre del patrón en mayúsculas entre corchetes: [TICKET_REDACTED]. El gateway compila la expresión al arrancar, y una que no compila le impide arrancar — el compilador pasa la cadena sin leerla.
Los tipos de entidad los encuentran los dos servicios de reconocimiento. La entrada no nombra ninguna dirección: el gateway lee ambas de su entorno, que la Recipe del gateway rellena a partir de las dos aristas. De dist/helm/router-deployment.yaml, el env del contenedor del gateway:
env: - name: LITELLM_MODEL_ASSISTANT_API_KEY valueFrom: secretKeyRef: name: openai-api-key key: api-key - name: PRESIDIO_ANALYZER_API_BASE value: http://analyzer-default:3000 - name: PRESIDIO_ANONYMIZER_API_BASE value: http://anonymizer-default:3000La primera es la clave del modelo, referenciada desde el Secret que nombra la Release y nunca escrita en claro; las otras dos son las direcciones de los servicios de reconocimiento. El nombre de una persona se convierte en <PERSON> y una dirección de correo en <EMAIL_ADDRESS>.
Una llamada fallida se retiene en lugar de enmascararse. El gateway no ejecuta ningún guardrail de registro para una llamada que falla, así que el módulo que carga la entrada proporciona también log_masking.withhold_failed_calls, registrado justo después de la guarda de solicitudes, y la Recipe del gateway escribe los dos ajustes junto a él. El callback recibe los datos de una llamada fallida antes que cualquier callback registrado después de él, y sustituye todo texto que haya escrito un llamador o el modelo por [TEXT_WITHHELD], coincida o no, y el texto del error por [ERROR_TEXT_WITHHELD], dejando como estaba lo que envía un intento repetido. disable_error_logs mantiene las llamadas fallidas fuera de los registros de gasto, y redact_messages_in_exceptions mantiene los mensajes de la solicitud fuera de los detalles que el gateway adjunta a un error.
El mismo ConfigMap lleva una segunda clave, log_masking.py: el módulo que nombran el guardrail de la entrada y la segunda entrada de callbacks. La Recipe del gateway añade el módulo, esa entrada de callbacks, la entrada del guardrail y los dos ajustes solo mientras values.log_masking enumere algo, así que un gateway que no enumera nada renderiza el ConfigMap sin ninguno de ellos, byte a byte como un gateway sin el valor.
Lo que ve quien lee los registros, y lo que ve el modelo
Toma un llamador cuya solicitud lleva este texto:
My name is David Johnson and my email is david.johnson@example.com, ticket TCK-104882. Call me on 212-555-0147.El bloque de arriba y los tres de abajo ilustran lo que hace con él el gateway en ejecución; no son salida de la compilación.
El proveedor del modelo recibe la solicitud exactamente como la envió el llamador, y el llamador recibe la respuesta del modelo exactamente como llegó. Una integración de registro a la que el gateway entrega la llamada recibe los mismos mensajes enmascarados:
My name is <PERSON> and my email is <EMAIL_ADDRESS>, ticket [TICKET_REDACTED]. Call me on 212-555-0147.El número de teléfono se registra tal como se envió, porque la vinculación no enumera PHONE_NUMBER y ningún patrón coincide con él. El texto con el que no coincide nada de lo enumerado nunca se enmascara.
Toda copia de una llamada correcta que el gateway entrega a sus registros se enmascara del mismo modo: los mensajes, los mensajes y la respuesta de la carga útil de registro estándar, una respuesta en streaming a medida que el gateway la ensambla, la solicitud y la respuesta tal como las vio el proveedor, la solicitud que conservan los registros de gasto, y la respuesta que recibe cada integración. La respuesta del modelo también se enmascara en esas copias:
Reply for <PERSON> (<EMAIL_ADDRESS>) about [TICKET_REDACTED].Lo que queda sin enmascarar
Enmascarar los registros no oculta el texto a nadie más, y la descripción de values.log_masking lo dice:
- El proveedor del modelo recibe todo sin enmascarar, y lo mismo el gateway y los dos servicios de reconocimiento.
- Una llamada fallida no conserva ningún texto de la solicitud en ningún registro que escriba el gateway, y eso cuesta dos cosas. La línea propia del gateway para una llamada fallida conserva solo el tipo de error, como
An error was logged with its text withheld, as log masking is on: BadRequestError, así que el mensaje del proveedor y su traza salen de ese registro; y las llamadas fallidas salen de los registros de gasto y de los totales de gasto diarios, que solo cuentan las llamadas correctas. Una integración de registro configurada fuera del catálogo todavía puede leer el mensaje de error propio de un proveedor en la excepción que lleva una llamada fallida, y a una registrada antes del callback propio del gateway se le entrega el texto de una llamada fallida tal como llegó. - Solo están cubiertos los registros a través de los cuales escribe el enmascaramiento: no la salida de depuración del gateway, ni los registros propios de un proveedor. Los metadatos de una solicitud, sus definiciones de herramientas y sus cabeceras se registran tal como se enviaron.
- Una llamada cuyas copias no se pueden enmascarar se registra con su texto retenido. Cuando no se puede alcanzar un servicio de reconocimiento, ninguna copia se registra enmascarada en parte: todo texto de toda copia de esa llamada se sustituye por
[TEXT_WITHHELD], y esos datos se entregan a los registros como de costumbre, así que la llamada se sigue contando en los registros de gasto. El registro propio del gateway anota que el texto de la llamada se retuvo. La llamada en sí se responde como de costumbre.
Tal como el catálogo renderiza este gateway, no entrega sus registros a ninguna integración de registro, y sus registros de gasto no conservan ningún texto de solicitud o respuesta ni ninguna llamada fallida. Así que las copias que protege el enmascaramiento son las que recibiría una integración o un registro de gasto que conserve el texto, configurados en el gateway.
Enmascaramiento de registros o enmascaramiento de datos
core/data-masking oculta al modelo el texto enumerado, y en este gateway su realización desactiva el registro del contenido de los mensajes por parte del gateway mientras está vinculada. A su lado, el enmascaramiento de registros no tendría nada sobre lo que actuar, y un lector podría tomar las dos por una sola protección. Así que el gateway rechaza las dos juntas: mientras values.log_masking enumere algo, una vinculación core/data-masking en el gateway detiene la compilación, mediante una aserción del propio Component del gateway. Añadir al gateway una vinculación con el nombre masked, con su realización vinculada en el Manifest, imprime:
[… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][DEVELOPER_ERROR E0033] Component/Feature assertions caused by: Component "core/gateway/litellm" instance "router" assertion "log_masking_not_beside_data_masking": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: "router" lists what to mask in its logs under values.log_masking, and the core/data-masking attachment "masked" is on it too: that attachment's realization turns the gateway's logging of message contents off, so log masking would have nothing left to act on, and a reader could take the two for one protection. Remove values.log_masking to mask what travels, or the "masked" attachment to mask only what is loggedRecurre al enmascaramiento de registros cuando el modelo debe ver los datos y los registros no deben conservarlos; recurre al enmascaramiento de datos cuando el modelo tampoco debe verlos. Ambos leen los mismos patterns y entities, así que una lista significa lo mismo en uno y otro.
Dónde el compilador no interpreta
El compilador enruta el patrón y los tipos de entidad hacia la configuración del gateway como cadenas. No compila la expresión, no sabe qué es un número de ticket o una persona, y no ve el tráfico que transportará el gateway. Cada detención con la que puede encontrarse este workspace — tipos de entidad con un socket de reconocimiento sin conectar, un tipo de entidad que el analizador no reconoce en inglés, enmascaramiento de registros junto a enmascaramiento de datos en un mismo gateway, la conexión al modelo gestionado sin ninguna credencial — la declaran las propias entidades del catálogo, como una aserción del Component del gateway o de su Recipe, y ninguna de ellas se basa en comprensión alguna del texto.
Adaptarlo
- Enmascarar solo patrones. Quita
entitiesdevalues.log_masking, y los dos componentes de reconocimiento con sus aristas y sus entradas en la Release; los patrones se comparan dentro del gateway y no necesitan ninguno de los dos servicios. - Enmascarar más tipos de entidad. Añádelos a
entities, en el vocabulario propio del servicio de reconocimiento; un tipo que el analizador no reconoce en inglés detiene la compilación y nombra los que sí reconoce. - Ocultar el texto también al modelo. Sustituye
values.log_maskingpor una vinculacióncore/data-maskingen el gateway que enumere los mismospatternsyentities, y vincula su realización en el Manifest. - Servir un segundo modelo. Conecta otro componente de modelo al socket
modelsbajo un alias propio, con la clave que el gateway le presenta en esa conexión;values.modelsigue nombrando el alias que publica el gateway. El enmascaramiento se aplica a las llamadas de cada alias que sirve el gateway.