配置扩展程序以调用 Google 服务

借助 Service Extensions，受支持的应用负载平衡器可以通过对 Google 服务的标注来配置扩展程序。本页面介绍如何配置此类扩展程序。

配置流量扩展程序以调用 Model Armor 服务

您可以配置流量扩展程序来调用 Model Armor，以统一对生成式 AI 推理流量强制执行安全政策，这些流量会流向应用负载平衡器，包括 GKE 推理网关。

流量扩展服务会将相关的扩展服务分组到一个或多个链中。您可以在同一扩展链中配置插件和标注。每个扩展程序链都使用通用表达式语言 (CEL) 匹配条件来选择要处理的流量。负载均衡器会按顺序针对每个链的匹配条件评估请求。当请求符合链中定义的条件时，链中的所有扩展程序都会对该请求执行操作。只有一条链与给定的请求匹配。

链中的每个扩展程序都可以有自己的一组支持的事件。扩展程序对请求和响应内容所做的修改对链中的其余扩展程序可见。对于配置为支持响应事件的扩展程序，扩展程序的序列在响应路径上是反向的。

流量扩展程序会附加到使用 Inference Gateway 创建的负载均衡器转发规则。配置资源后，系统会将匹配的请求发送到 Model Armor 服务。

准备工作

确定一个合适的项目，您在该项目中拥有项目 Owner 或 Editor 角色，或者拥有以下 Compute Engine IAM 角色：
- 如需创建实例：Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)
- 如需创建 Cloud Load Balancing 组件，您需要具备 Compute Network Admin (roles/compute.networkAdmin) 角色。
启用所需的 API。
控制台
1. 在 Google Cloud 控制台中，前往启用对 API 的访问权限页面。
  
  前往“启用对 API 的访问权限”部分
2. 按照说明启用所需的 API，包括 Compute Engine API、Model Armor API 和 Network Services API。
gcloud
使用 gcloud services enable 命令：
```
gcloud services enable compute.googleapis.com modelarmor.googleapis.com networkservices.googleapis.com
```
创建所需的 Model Armor 模板。
通过部署推理网关来设置 Google Kubernetes Engine 基础架构。通过发送推理请求来测试模型。

在少数限制的约束下，系统支持以下 OpenAI API 端点：Assistants、Chat Completions、Completions（旧版）、Messages 和 Threads。

配置 OpenAI API 端点时的限制

为 GKE 基础架构配置 OpenAI API 端点时，请考虑以下与清理提示和回答相关的限制：

任何 API 都不支持流式传输 API 响应。如果您同时使用流式传输 API 和非流式传输 API，那么在配置流量扩展程序时，请将 failOpen 设置为 true。Model Armor 会清理非流式回答，并忽略流式回答。
在清理提示和回答时，仅支持以下操作：
- Assistants API：Create、Delete、List、Modify 和 Retrieve
- Chat Completions API：Create、Delete、Get Chat Completion、Get Chat Message、List 和 Update
- Completions（旧版）API：Create
- Messages API：Create、Delete、List、Modify 和 Retrieve
- Threads API：Create、Delete、Modify 和 Retrieve
对于在响应中返回多个选项的 API 调用（例如 POST https://api.openai.com/v1/chat/completions），系统只会清理选项列表中的第一个选项。

配置流量扩展程序

在配置扩展程序之前，通过向负载均衡器发送推理请求并指定负载均衡器公开的 IP 地址来检查行为：

curl -v http://${IP}/v1/chat/completions
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'

尽管敏感数据已发送到 LLM，但请求仍会生成 HTTP 200 OK 状态代码。

为了让 Model Armor 阻止包含敏感数据的提示，请配置流量扩展程序。
控制台
1. 在 Google Cloud 控制台中，前往服务扩展程序页面。
  
  前往 Service Extensions
2. 点击创建扩展程序。系统会打开一个向导，引导您完成一些初始步骤。
3. 对于产品，选择负载均衡。然后，点击继续。系统会显示支持的应用负载平衡器列表。
4. 选择负载均衡器类型。
5. 将区域指定为 us-central1。点击继续。
6. 对于扩展程序类型，选择流量扩展程序，然后点击继续。
7. 如需打开创建扩展程序表单，请点击继续。在创建扩展程序表单中，请注意，之前的选择无法修改。
8. 在基本信息部分，执行以下操作：
  1. 为扩展程序指定一个唯一名称。
    
    名称必须以小写字母开头，后面最多可跟 62 个小写字母、数字或连字符，但不能以连字符结尾。
  2. 可选：输入简短的扩展程序说明，最多可输入 1,024 个字符。
  3. 可选：在标签部分中，点击添加标签。然后，在显示的行中，执行以下操作：
    
    在键中，输入键名称。
    
    对于值，输入该键的值。
    
    如需添加更多键值对，请点击添加标签。您最多可以添加 64 个键值对。
    
    如需详细了解标签，请参阅为项目创建和更新标签。
9. 在转发规则字段中，选择要与扩展程序关联的一个或多个转发规则。选择在部署推理网关时生成的转发规则。已与其他扩展服务相关联的转发规则无法选择，并且会显示为不可用。
10. 对于扩展程序链，请添加一个或多个要针对匹配请求执行的扩展程序链。
  
  如需添加扩展链，请执行以下操作，然后点击完成：
  - 对于新的扩展程序链名称，请指定一个唯一的名称。
    
    名称必须符合 RFC-1034 的要求，仅限使用小写字母、数字和连字符，且长度上限为 63 个字符。此外，第一个字符必须是字母，最后一个字符必须是字母或数字。
  - 若要匹配执行扩展程序链的请求，请为匹配条件指定通用表达式语言 (CEL) 表达式，例如 request.path == "/v1/chat/completions"。
    
    如需详细了解 CEL 表达式，请点击获取语法帮助或参阅 CEL 匹配器语言参考文档。
  - 添加一个或多个要针对匹配请求执行的扩展程序。
    
    对于每个扩展服务，请在扩展服务下执行以下操作，然后点击完成：
    
    对于扩展程序名称，请指定一个唯一的名称。
    
    名称必须符合 RFC-1034 的要求，仅限使用小写字母、数字和连字符，且长度上限为 63 个字符。此外，第一个字符必须是字母，最后一个字符必须是字母或数字。
    
    对于可编程性类型，选择 Google 服务，然后选择一个 Model Armor 服务端点，例如 modelarmor.us-central1.rep.googleapis.com。
    
    对于超时，请指定一个介于 10 到 1000 毫秒之间的值，该值表示数据流上消息的超时时间。请注意，Model Armor 的延迟时间约为 250 毫秒。
    
    对于事件，选择所有 HTTP 事件类型。
    
    对于转发标头，点击添加标头，然后添加要转发到扩展程序的 HTTP 标头（从客户端或后端）。如果未指定标头，则系统会发送所有标头。
    
    可选：如果扩展服务超时或失败，并且您希望继续处理请求或响应，请为故障开放选择已启用。链中的后续扩展程序也会执行。
    
    默认情况下，系统未选择故障时打开选项。在这种情况下，如果发生错误，请求或响应处理会停止。如果响应标头尚未传递给下游客户端，系统会向客户端返回通用 HTTP 500 状态代码。如果响应标头已传递，则会重置到客户端的 HTTP 数据流。
    
    如果优先考虑安全性或完整性，建议采用默认选项，即不选择应急开启。启用故障开放（尤其是对于非关键操作）有助于优先考虑可用性。
    
    对于元数据，点击添加元数据以指定用于过滤与特定模型对应的提示和回答的 Model Armor 模板。
    
    对于密钥，指定 model_armor_settings。对于值，请以 JSON 字符串的形式指定模板，例如：
    
    [{ "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" }]
    
    替换以下内容：
    
    MODEL_NAME：通过 InferenceModel 资源配置的模型名称，例如 meta-llama/Llama-3.1-8B-Instruct
    
    TEMPLATE_PROJECT_ID：Model Armor 模板的项目 ID
    
    LOCATION：Model Armor 模板的位置，例如 us-central1
    
    RESPONSE_TEMPLATE：供模型使用的回答模板
    
    PROMPT_TEMPLATE：供模型使用的提示模板
    
    此外，还可以指定一个默认模板，以便在请求与模型不完全匹配时使用。如需配置默认模板，请将 MODEL_NAME 指定为 default。
    
    如果您不想过滤提示或回答流量，请创建并添加一个空过滤模板。
    
    metadata 的总大小必须小于 1 KiB。元数据中的键总数必须小于 20。每个键的长度必须小于 64 个字符。每个值的长度必须小于 1,024 个字符。所有值都必须是字符串。
    
    当请求被屏蔽时，Model Armor 会返回标准 403 Forbidden 状态代码。您可以在 Model Armor 模板的安全政策中定义自定义响应设置（包括自定义状态代码和消息），以替换默认状态。如需了解详情，请参阅 TemplateMetadata。
11. 点击创建扩展程序。
gcloud
1. 在 YAML 文件中定义调用，并将其与部署推理网关时生成的转发规则相关联。使用提供的示例值。
  cat >traffic_callout_service.yaml <<EOF name: traffic-ext forwardingRules: - https://www.googleapis.com/compute/v1/projects/LB_PROJECT_ID/regions/us-central1/forwardingRules/FORWARDING_RULE loadBalancingScheme: INTERNAL_MANAGED extensionChains: - name: "chain1-model-armor" matchCondition: celExpression: 'request.path == "/v1/chat/completions"' extensions: - name: extension-chain-1-model-armor service: modelarmor.us-central1.rep.googleapis.com failOpen: true supportedEvents: - REQUEST_HEADERS - REQUEST_BODY - REQUEST_TRAILERS - RESPONSE_HEADERS - RESPONSE_BODY - RESPONSE_TRAILERS timeout: 1s metadata: model_armor_settings: '[ { "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" } ]' EOF
  替换以下内容：
  - TEMPLATE_PROJECT_ID：Model Armor 模板的项目 ID
  - LB_PROJECT_ID：负载均衡器转发规则的项目 ID
  - FORWARDING_RULE：要与扩展程序关联的一个或多个转发规则。选择在部署推理网关时生成的转发规则。
    
    已与其他扩展服务相关联的转发规则无法选择，并且会显示为不可用。
  - MODEL_NAME：通过 InferenceModel 资源配置的模型名称，例如 meta-llama/Llama-3.1-8B-Instruct
  - LOCATION：Model Armor 模板的位置，例如 us-central1
  - RESPONSE_TEMPLATE：供模型使用的回答模板
  - PROMPT_TEMPLATE：供模型使用的提示模板
  在 metadata 字段中，指定在过滤与特定模型对应的提示和回答时要使用的 Model Armor 设置和模板。
  
  此外，还可以指定一个默认模板，以便在请求与模型不完全匹配时使用。如需配置默认模板，请将 MODEL_NAME 指定为 default。
  
  如果您不想过滤提示或回答流量，请创建并添加一个空过滤模板。
  
  metadata 的总大小必须小于 1 KiB。元数据中的键总数必须小于 16。每个键的长度必须小于 64 个字符。每个值的长度必须小于 1,024 个字符。所有值都必须是字符串。
  
  当请求被屏蔽时，Model Armor 会返回标准 403 Forbidden 状态代码。您可以在 Model Armor 模板的安全政策中定义自定义响应设置（包括自定义状态代码和消息），以替换该状态。如需了解详情，请参阅 TemplateMetadata。
2. 导入流量扩展程序。使用 gcloud service-extensions lb-traffic-extensions import 命令和以下示例值。
  gcloud service-extensions lb-traffic-extensions import traffic-ext \ --source=traffic_callout_service.yaml \ --location=us-central1
kubectl
1. 如果您使用的 GKE 版本低于 v1.32.2-gke.1182001，请安装流量扩展 CRD：
  kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml
2. 在 YAML 文件中定义扩展程序。此自定义资源会将推理网关与 Model Armor 服务相关联。使用提供的示例值。
  cat >traffic_callout_service.yaml <<EOF apiVersion: networking.gke.io/v1 kind: GCPTrafficExtension metadata: name: traffic-ext spec: targetRefs: - group: "gateway.networking.k8s.io" kind: Gateway name: inference-gateway extensionChains: - name: "chain1-model-armor" matchCondition: celExpressions: - celMatcher: 'request.path == "/v1/chat/completions"' extensions: - name: extension-chain-1-model-armor googleAPIServiceName: modelarmor.us-central1.rep.googleapis.com failOpen: true supportedEvents: - RequestHeaders - RequestBody - RequestTrailers - ResponseHeaders - ResponseBody - ResponseTrailers timeout: 1s metadata: model_armor_settings: '[ { "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" } ]' EOF
  替换以下内容：
  - MODEL_NAME：通过 InferenceModel 资源配置的模型名称，例如 meta-llama/Llama-3.1-8B-Instruct
  - TEMPLATE_PROJECT_ID：Model Armor 模板的项目 ID
  - LOCATION：Model Armor 模板的位置，例如 us-central1
  - RESPONSE_TEMPLATE：供模型使用的回答模板
  - PROMPT_TEMPLATE：供模型使用的提示模板
  在 metadata 字段中，指定在过滤与特定模型对应的提示和回答时要使用的 Model Armor 设置和模板。
  
  此外，还可以指定一个默认模板，以便在请求与模型不完全匹配时使用。如需配置默认模板，请将 MODEL_NAME 指定为 default。
  
  如果您不想过滤提示或回答流量，请创建并添加一个空过滤模板。
  
  metadata 的总大小必须小于 1 KiB。元数据中的键总数必须小于 16。每个键的长度必须小于 64 个字符。每个值的长度必须小于 1,024 个字符。所有值都必须是字符串。
  
  当请求被屏蔽时，Model Armor 会返回标准 403 Forbidden 状态代码。您可以在 Model Armor 模板的安全政策中定义自定义响应设置（包括自定义状态代码和消息），以替换该状态。如需了解详情，请参阅 TemplateMetadata。
3. 将 traffic_callout_service.yaml 文件中定义的配置应用到您的 GKE 集群。此命令会创建 GCPTrafficExtension 资源，用于将推理网关关联到 Model Armor 服务。
  kubectl apply -f traffic_callout_service.yaml

向服务扩展服务账号授予所需角色。使用 gcloud projects add-iam-policy-binding 命令：

gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/container.admin
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

替换以下内容：

TEMPLATE_PROJECT_ID：Model Armor 模板的项目 ID
LB_PROJECT_NUMBER：负载均衡器的项目编号

Google Cloud 控制台中与您项目对应的“项目信息”面板中列出了这些值。

如需验证流量扩展服务是否按预期工作，请运行相同的 curl 命令：

curl -v http://${IP}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'
  ```

配置服务扩展程序后，如果请求包含敏感数据，则会生成 HTTP 403 Forbidden 状态代码，记录模板中配置的错误消息，并关闭连接。

如果请求安全，则生成 HTTP 200 OK 状态代码，并将 LLM 响应返回给用户。

如需监控扩展程序的行为，请使用日志浏览器。在查询窗格中，根据推理网关配置，按相应的负载均衡器资源类型进行过滤。

应用负载平衡器日志条目包含有助于调试 HTTP 或 HTTPS 流量的信息。

如需更详细地分析安全评估，请启用 Model Armor 审核日志记录。

后续步骤

管理扩展程序