Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Features и политики

На этой странице объясняется одна идея, присоединение поведения к компоненту и проверка результата политикой, и это не запускаемое рабочее пространство. Политика, которая останавливает сборку, когда данные с ограниченным доступом попадают в управляемую модель без маскирования, показывает и то и другое в рабочем пространстве, которое вы собираете; запишите его в собственную папку командой:

Terminal window
aggrega scaffold --example policy-data-class-route

Затем она выводит команды, которые нужно выполнить дальше:

Terminal window
cd policy-data-class-route
aggrega build --release release-masked.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release-unmasked.yaml --config governance-rego.yaml --auto-pull # halts; exits 1
aggrega build --release release-masking-off-route.yaml --config governance-rego.yaml --auto-pull # halts; exits 1

Сущность Feature присоединяется и реализуется сущностью FeatureRecipe

Сущность Feature — это поведение, которого компонент не несёт сам по себе, — маскирование, резервная копия, ingress, учётные данные, — и которое автор присоединяет к нему в features:. Кто присоединяет сущность Feature, следует из того, кто определяет её входные данные: разработчик присоединяет в сущности Aggregate ту Feature, поведение которой является частью того, чем является приложение; оператор присоединяет в сущности Release ту, все входные данные которой операционные. В любом случае Manifest привязывает каждую Feature к сущности FeatureRecipe, которая решает, как её реализовать для целевой платформы.

В примере разработчик присоединяет core/data-masking из стандартной библиотеки к AI-шлюзу и перечисляет, что маскировать, из aggregate.yaml без комментариев:

masking-gateway:
type: core/gateway/litellm
values:
model: chat
features:
masking:
type: core/data-masking
values:
patterns:
- name: claim_number
regex: '\bCLM-[0-9]{8}\b'
entities: [PERSON, EMAIL_ADDRESS]

Разработчик не указывает ни адреса, ни защитного механизма, ни настройки поставщика. Manifest привязывает core/data-masking к helm/data-masking-litellm, который записывает маскирование в конфигурацию, которую рендерит собственная сущность Recipe шлюза, через шаги конвейера плагинов, завершающего рендеринг, и добавляет рядом модуль, который загружает шлюз. Все остальные файлы, которые записывает сборка, побайтно идентичны файлам сборки без подключения.

То, чего присоединение не делает, описано так же тщательно, как и то, что оно делает: текст, которому не соответствует ни один шаблон и который не обнаруживает распознаватель, проходит без изменений, шлюз и две службы распознавания видят исходный текст, а трафик, не проходящий через шлюз, не затрагивается. Комментарии сущности FeatureRecipe перечисляют, что этот шлюз отклоняет и что пропускает в отправленном виде.

Метки определяют, куда может попасть Feature

Метки — это семантическая идентичность компонента, и они управляют размещением сущностей Feature, селекторами сокетов и политиками без каких-либо изменений в компиляторе. Поле appliesTo сущности Feature — это селектор меток по компоненту, к которому она присоединена. core/data-masking объявляет appliesTo: "dataplane.aggrega.ai/content-masking", голый ключ, который соответствует любому компоненту с этой меткой, каким бы ни было её значение; core/gateway/litellm несёт её со значением entity-recognition. Селектор может также сопоставлять значения, component.aggrega.ai/type in (server, worker), или исключать метку, !model.aggrega.ai/capability; все требования одного селектора, разделённые запятыми, должны выполняться, и Feature присоединяется только к компоненту, которому они соответствуют. Присоединение по меткам приводит полную грамматику селекторов.

Присоединения ограничивают ещё два объявления:

  • Совместимость. Сущность Feature может назвать сущности Features, с которыми она не может делить компонент. core/data-masking объявляет interoperability.conflictsWith: [core/semantic-caching], поэтому сборка, в которой один компонент в итоге несёт обе — прикреплённые к самому компоненту либо к подсистеме или границе, которая его содержит, — останавливается до рендеринга.
  • Обязательное присутствие. Сущность Component может требовать, чтобы присутствовало присоединение заданного типа. example/compute/service из каталога несёт аннотацию features.aggrega.ai/requiredType.monitoring: core/prometheus-exporter, поэтому сборка, в которой его экземпляр ни на каком уровне не несёт core/prometheus-exporter, останавливается с указанием требования monitoring. Чтобы потребовать второй тип, повторите ключ с другим суффиксом; о том, чем обязательное присутствие отличается от слота присоединения, см. раздел «Presence mandates» в entities/component.md.

Feature размещается на компоненте, поведение которого она меняет. core/caller-allowlist присоединяется к серверу моделей, а не к шлюзам, которым разрешено его вызывать; Сервер моделей, который может вызывать только его шлюз, собирает это.

Политика читает построенный граф

Политики подключает оператор в plugins.governance в конфигурации рабочего пространства, каждое подключение — в определённой роли. Политика в роли label-transform добавляет метки в граф; политика в роли ir-verdict оценивает его и может остановить сборку. Обе выполняет движок Rego; он встроен в CLI, а governance/rego — это его сущность Plugin в каталоге стандартной библиотеки.

Первое правило ниже помечает каждый шлюз, который разбирает пересылаемую им полезную нагрузку модели, как точку, где промпты уходят к поставщику модели. На этой роли узлы находятся в input.graph.nodes:

# policies/egress-tagging.rego: attached at the label-transform role
package aggrega.tagging
import rego.v1
labels contains {"node": id, "key": "compliance.aggrega.ai/egress", "value": "model-provider"} if {
some id, node in input.graph.nodes
node.labels["gateway.aggrega.ai/intelligence"] == "semantic"
}

Второе останавливает любой путь через такой шлюз, на котором нет маскирования:

# policies/model-egress.rego: attached at the ir-verdict role
package aggrega.security
import rego.v1
deny contains msg if {
some path in input.precalculated_paths
some egress in path.nodes
input.graph.spec.nodes[egress].labels["compliance.aggrega.ai/egress"] == "model-provider"
not "core/data-masking" in path.attached_features
msg := sprintf(
"BLOCKED: path %v sends model traffic through %v without core/data-masking attached.",
[concat(" -> ", path.nodes), egress]
)
}

Идентификатор узла — это ключ, под которым он находится в input.graph.spec.nodes; attached_features перечисляет типы Feature, прикреплённые к любому узлу пути, поэтому принадлежность проверяется с помощью in; правило проверяет, что маскирование прикреплено, а не то, что оно перечисляет; и решение, собранное в deny, сообщается с уровнем серьёзности halt, который останавливает сборку. Правило по путям видит узел только там, где к нему подходит или от него отходит ребро, поэтому политика, которая должна охватывать и несвязанный узел, читает сами узлы.

Оператор подключает движок по разу на роль, и у каждого подключения свой файл политики; относительный путь в sources разрешается относительно каталога файла конфигурации, а преобразование выполняется до вердикта:

.aggrega-config.yaml
plugins:
governance:
- uri: governance/rego:0.9.0
role: label-transform
with:
sources:
- policies/egress-tagging.rego
- uri: governance/rego:0.9.0
role: ir-verdict
with:
sources:
- policies/model-egress.rego

Страница сокета управления описывает всю поверхность для разработки: полезную нагрузку, которую предоставляет каждая роль, ключи решений и способ задать собственные имена. Пример Политики, формирующие метки подключает политику, формирующую метки, рядом с двумя встроенными плагинами разметки и собирает её.