让个人数据不进入日志的 AI 网关
支持助手需要处理客户的姓名和电子邮件地址, 因此它调用的模型必须能看到这些信息。位于该模型前面的网关为审计和调试保留日志, 而这些日志不得保留这些信息。本工作区将这样一个网关 编译为 Kubernetes 清单。
实现这一点的是网关自身的一个值,即 core/gateway/litellm 上的
values.log_masking。它只对网关交给日志的每次调用副本进行掩码,
除此之外不做任何事:模型收到的请求与调用方发送的完全一致,
调用方收到的回复与模型写出的完全一致。这正是它与
Feature core/data-masking 的区别,后者会对模型本身隐藏文本。两者互为替代方案,
下文关于如何在二者之间选择的一节展示了在同一个网关上同时设置两者时会发生什么。
本工作区不编写任何自有的目录实体。这里的三个实体文件 ——一个 Aggregate、一个 Manifest 和一个 Release——就是任何人需要 编写的全部内容。
它构建了什么
| 实例 | 目录中的 Component | 它在此处的角色 |
|---|---|---|
router | core/gateway/litellm | AI 网关:一个已发布的别名 assistant,由连接到其 models 插槽的模型提供服务 |
gpt | core/ai-model/openai | 该别名背后的模型,即 OpenAI 自己的 API,以引用方式访问:集群中不为它运行任何内容 |
analyzer | core/security/presidio-analyzer | 在文本中查找敏感片段 |
anonymizer | core/security/presidio-anonymizer | 替换交给它的片段 |
三条 uses 边:网关的 models 插槽连接到模型,并以网关向模型出示的密钥作为其
credential;网关的 pii_analyzer 和
pii_anonymizer 插槽连接到两个识别服务。该 Aggregate 附加
该凭据时不指明 secret,由 Release 在
附加的 infra 中指明它:一个命名空间中已有的 Secret,Manifest 的
实现引用它,但不渲染它。网关的 values.log_masking
列出要掩码的内容:patterns 下是匹配公司工单号的正则表达式,
entities 下是实体类型 PERSON 和 EMAIL_ADDRESS。
没有默认列表;两者都未列出的网关在其日志中不掩码任何内容,
其渲染结果与不设置该值时完全相同。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example ai-gateway-log-masking然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd ai-gateway-log-masking构建
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 指定的默认注册表解析目录实体。网关自身的 Recipe 负责写入日志脱敏配置,因此除编译器自带的插件外,构建不运行任何其他插件。
构建会输出如下内容,其中 <workspace> 代表本示例的文件夹:
[… 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>/dist借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 的工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `ai-gateway-log-masking` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `ai-gateway-log-masking`,且不提供 `dir`:它会把示例写入一个新的 `ai-gateway-log-masking` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `ai-gateway-log-masking`,`release` 设为 `release.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `ai-gateway-log-masking/dist/` 下。渲染出的目录树
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.yaml该值本身不带来任何文件。网关的 Recipe 将它写入网关的配置,并在网关的 ConfigMap 中添加一个由该配置加载的模块。模型渲染一个文件 gpt-service.yaml,这是一个将集群内名称映射到 OpenAI API 主机 api.openai.com 的 Service;模型的密钥不渲染任何文件,因为保存它的 Secret 已经存在。
路由表是网关配置正文的开头,它只有一个条目,根据模型发布的内容写成——其端点、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护栏条目
下面是网关的配置主体,即 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 - 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: true网关的 Recipe 根据 values.log_masking 写出全部内容,并以网关的名称(此处为 router)为该条目命名,在标准库的实现所写的护栏条目使用连字符的位置改用点号,因此这些实现的任何附加项,无论名称如何,都无法取代该条目。从中有五点值得一读。
mode: logging_only 是网关自身的一种模式,用于只在已完成的调用交给其日志时运行、在其他任何地方都不运行的护栏。 无论条目指定什么,该条目加载的类都遵守这一模式,因此它绝不会在请求被转发之前对请求调用,也不会在回复被返回之前对回复调用。
default_on: true 使它在每次调用时运行。 调用方无法通过请求将其关闭,包括请求禁用网关始终开启的护栏的情况。
模式按编写的原样到达网关。 它在网关内部进行匹配,忽略字母大小写,每个匹配项都会被永久替换为方括号中大写的模式名称:[TICKET_REDACTED]。网关在启动时编译该表达式,无法编译的表达式会使网关无法启动——编译器只是原样传递该字符串,并不读取它。
实体类型由两个识别器服务找出。 该条目不指定任何地址:网关从其环境中读取这两个地址,而网关的 Recipe 根据两条边填充环境。以下摘自 dist/helm/router-deployment.yaml,即网关容器的 env:
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:3000第一个是模型的密钥,从该 Release 指定的 Secret 中引用,绝不会被写出;另外两个是识别器的地址。人名会变为 <PERSON>,电子邮件地址会变为 <EMAIL_ADDRESS>。
失败的调用会被扣留,而不是被掩码。 网关不会对失败的调用运行任何日志护栏,因此该条目加载的模块还提供 log_masking.withhold_failed_calls,紧接在请求守卫之后注册,网关的 Recipe 会在其旁边写入两项设置。该回调会先于在它之后注册的任何回调拿到失败调用的记录,并将调用方或模型写出的每段文本(无论是否匹配)替换为 [TEXT_WITHHELD],将错误的文本替换为 [ERROR_TEXT_WITHHELD],而重试尝试所发送的内容保持不变。disable_error_logs 使失败的调用不进入支出日志,redact_messages_in_exceptions 使请求的消息不出现在网关附加到错误上的详细信息中。
同一个 ConfigMap 还带有第二个键 log_masking.py:即该条目的 guardrail 和第二个 callbacks 条目所指定的模块。只有当 values.log_masking 列出了内容时,网关的 Recipe 才会添加该模块、那个 callbacks 条目、护栏条目和两项设置,因此未列出任何内容的网关渲染出的 ConfigMap 不含其中任何一项,与没有该值的网关逐字节相同。
日志读者看到什么,模型看到什么
假设某个调用方的请求携带以下文本:
My name is David Johnson and my email is david.johnson@example.com, ticket TCK-104882. Call me on 212-555-0147.上面的代码块和下面的三个代码块说明运行中的网关如何处理该文本;它们不是构建的输出。
模型提供方收到的请求与调用方发送的完全一致,调用方收到的模型回复也与返回时完全一致。网关将该调用交给的日志集成收到的是经过掩码处理的相同消息:
My name is <PERSON> and my email is <EMAIL_ADDRESS>, ticket [TICKET_REDACTED]. Call me on 212-555-0147.电话号码按发送时的原样记录,因为该挂接没有列出 PHONE_NUMBER,也没有任何模式与之匹配。未被任何所列项匹配的文本永远不会被掩码。
网关交给其日志的每一份成功调用的副本都以相同方式掩码:消息、标准日志载荷中的消息和回复、网关组装出的流式回复、提供方所见的请求和回复、支出日志保存的请求,以及每个集成收到的回复。模型的回复在这些副本中同样被掩码:
Reply for <PERSON> (<EMAIL_ADDRESS>) about [TICKET_REDACTED].哪些内容不会被掩码
对日志做掩码并不会对其他任何一方隐藏文本,values.log_masking 的描述也说明了这一点:
- 模型提供方收到的所有内容均未经掩码,网关和两个识别器服务也是如此。
- **失败的调用不会在网关写入的任何日志中保留请求文本,这会带来两方面的代价。**网关自身为失败调用记录的那一行只保留错误类型,例如
An error was logged with its text withheld, as log masking is on: BadRequestError,因此提供方的消息及其回溯信息不会出现在该日志中;此外,失败的调用不会出现在支出日志和每日支出总额中,它们只统计成功的调用。在目录之外配置的日志集成仍可以从失败调用所携带的异常中读取提供方自身的错误消息,而注册在网关自身回调之前的日志集成会原样收到失败调用的文本。 - **只有掩码机制所写入的日志受到保护:**网关的调试输出不在此列,提供方自身的日志也不在此列。请求的元数据、工具定义和请求头会按发送时的原样记录。
- 副本无法被掩码的调用,在记录时会隐去其文本。
当某个识别器无法访问时,不会记录只做了部分掩码的副本:该调用每个副本中的每段文本都会被替换为
[TEXT_WITHHELD],记录照常交给日志,因此该调用仍会计入支出日志。 网关自身的日志会记录该调用的文本已被隐去。调用本身照常得到响应。
按照目录渲染这个网关的方式,它不会把日志交给任何日志集成,其支出日志也不保留任何请求或回复文本,不记录失败的调用。因此,掩码所保护的副本,是在网关上配置的日志集成或保留文本的支出日志将会收到的副本。
日志脱敏还是数据脱敏
core/data-masking 对模型隐藏所列出的文本;在这个网关上,它的实现在附加期间会关闭网关对消息内容的日志记录。与它并用时,日志脱敏将无可作用之处,读者却可能把两者当成同一种保护。因此网关拒绝两者同时存在:当 values.log_masking 列有内容时,网关上的 core/data-masking 附加会通过网关自身 Component 的一条断言使构建停止。向网关添加一个名为 masked 的附加,并在 Manifest 中绑定其实现,会输出:
[… 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 logged当模型必须看到数据而日志不得保留它时,使用日志脱敏;当模型也不得看到它时,使用数据脱敏。两者读取相同的 patterns 和 entities,因此同一份列表在两者上含义相同。
编译器不做解释的地方
编译器将模式和实体类型以字符串形式路由到网关的 配置中。它不编译该表达式,不知道 工单号或人是什么,也看不到网关将要 承载的流量。此工作区可能遇到的每一种中止——实体类型的识别器插槽 未连接、分析器在英语中无法识别的实体类型、同一网关上日志脱敏 与数据脱敏并存、到托管模型的连接 未携带凭据——都由目录自身的实体声明,作为 网关的 Component 或其 Recipe 的断言,且其中没有一个依赖于对 文本的任何理解。
改编示例
- 只屏蔽模式。 从
values.log_masking中删除entities,并删除两个识别器组件及其边以及它们在 Release 中的条目;模式在网关内部匹配,不需要这两个服务。 - 屏蔽更多实体类型。 用识别器自身的词汇将它们添加到
entities中;分析器无法在英语中识别的类型会使构建中止,并列出它能识别的类型。 - 同时对模型隐藏文本。 将
values.log_masking替换为网关上的一个core/data-masking附件,列出相同的patterns和entities,并在 Manifest 中绑定其实现。 - 提供第二个模型。 将另一个模型组件以其自己的别名连接到
models插槽,并附上网关在该连接上向它出示的密钥;values.model仍然指定网关发布的别名。 屏蔽作用于网关所提供的每个别名的调用。