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

Учётные данные на соединениях — ключ на каждое соединение и один ключ на обоих концах

Хранилище семантической памяти, которое обращается к двум моделям и предъявляет каждой свой ключ; компилируется в манифесты Kubernetes. Оно читает загруженные материалы с помощью размещённой у провайдера модели и кодирует их с помощью сервера эмбеддингов, работающего рядом с ним в кластере. Ключ, который оно предъявляет размещённой модели, извлекается из хранилища секретов кластера. Сервер эмбеддингов проверяет собственный ключ, и хранилище предъявляет тот же самый ключ — оба конца читают его из одного параметра, поэтому их невозможно записать по-разному.

Это рабочее пространство не определяет ни одной собственной сущности каталога. Каждая сущность Component, Feature и Recipe, которую оно упоминает, поставляется в каталоге стандартной библиотеки; файлы здесь — три Aggregates, один Manifest и три Releases — это всё, что кому-либо приходится писать.

Что собирается

┌── extraction_model ──► llm a hosted model API
│ key on the connection, fetched from a secret store
memory ───┤
│
└── embedding_model ──► embeddings an embedding server that checks a key
key on the connection ═══ the server's own api_key
(both read one parameter)
экземплярсущность Component из каталогачем он является здесь
memorycore/datastore/cogneeвызывающая сторона: хранилище семантической памяти, оба сокета моделей которого объявляют слот credential для ключа, который оно предъявляет по этому соединению
llmcore/ai-model/openaiразмещённая модель с меткой component.aggrega.ai/hosting: managed; к ней обращаются по ссылке, поэтому для неё в кластере ничего не запускается
embeddingscore/ai-model/teiText Embeddings Inference в кластере с меткой self-hosted; он требует ключ от каждой вызывающей стороны и хранит его в собственном слоте api_key

Три релиза используют один Manifest, manifest.yaml, и у каждого есть собственный Aggregate:

релизAggregateчто он показывает
release-matched.yamlaggregate-matched.yamlоба соединения записаны разработчиком, оба конца соединения для эмбеддингов читают один параметр
release-mismatched.yamlaggregate-mismatched.yamlто же самое, но оба конца читают два параметра: сборка проходит успешно, а проверка соглашений выдаёт рекомендацию
release-operator-wired.yamlaggregate-operator-wired.yamlсоединение для извлечения оставлено оператору: сущность Release связывает его и называет его ключ в infra

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

Terminal window
aggrega scaffold --example connection-credentials

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

Terminal window
cd connection-credentials

Сборка

За один запуск собирайте один релиз:

Terminal window
aggrega build --release release-matched.yaml --auto-pull # → dist/matched/
aggrega build --release release-mismatched.yaml --auto-pull # → dist/mismatched/
aggrega build --release release-operator-wired.yaml --auto-pull # → dist/operator-wired/

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

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

Terminal window
aggrega pull --release release-matched.yaml # resolve, then build normally
aggrega build --release release-matched.yaml --auto-pull # or resolve during the build

Рабочее пространство разрешает свои сущности из реестра по умолчанию, который указывает .aggrega-config.yaml, поэтому флаг --catalog не нужен.

Команда pull выводит:

[… omitted: a warning that the declared-sensitive origin of llm.credential reaches the target with no per-key sensitivity marking, because its realization maps it through a valuesMapping]
Pull complete: release-matched.lock (entities=15, source_artifacts=0, external_inputs=0)

а сборка, где <workspace> обозначает папку этого примера, выводит:

[… omitted: the same warning about llm.credential the pull printed]
notice: LINT: Feature "core/referenced-secret" at core/referenced-secret:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: a total build time, which differs per run]
Build completed: 8 files written to <workspace>/dist

Два других релиза выводят те же строки: каждый pull называет собственный lock-файл, и каждая сборка записывает восемь файлов. Строка notice: относится к сущности Feature для учётных данных, которую использует каждое вложение здесь: core/referenced-secret принимает имя своего секрета, origin, либо из values разработчика, либо из infra оператора, и это уведомление сообщает, что один лист объявлен в обоих разделах. Оно не меняет ни один вердикт и ни один сгенерированный байт; в разделе Credential Features объясняется, почему лист находится в обоих.

Там, где эта страница показывает результат сборки, блок скопирован из реального запуска — см. Чтение вывода на этих страницах, где описаны соглашение и метка, которой обозначаются пропущенные строки.

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочей области ещё нет папки `connection-credentials`, вызовите инструмент `scaffold` один раз, задав `example` равным `connection-credentials` и не указывая `dir`: он запишет пример в новую папку `connection-credentials`. Затем вызовите инструмент `build` один раз для каждой сущности Release в следующем порядке — `release-matched.yaml`, `release-mismatched.yaml`, `release-operator-wired.yaml` — каждый раз задавая `workspace_root` равным `connection-credentials`, `release` равным этому файлу, `auto_pull` равным true и `write` равным true. Сообщите мне, какие файлы записала каждая сборка; они находятся в `connection-credentials/dist/`.

Сгенерированное дерево

dist/matched/helm/
├── embeddings-default-service.yaml
├── embeddings-headless-service.yaml
├── embeddings-statefulset.yaml
├── llm-service.yaml
├── memory--llm-zdcredential--memory-externalsecret-memory-memory-llm-credential.yaml
├── memory-default-service.yaml
├── memory-headless-service.yaml
└── memory-statefulset.yaml

Один файл добавлен вложением, а не собственным Recipe компонента: это ExternalSecret, который получает ключ, предъявляемый хранилищем размещённой модели. Имя файла содержит компонент, к которому он прикреплён, memory, и имя вложения, llm.credential, записанное как llm-zdcredential, потому что точка входит в одну строку с собственным именем файла; см. Именование сгенерированного ресурса. Ни один файл не содержит ключ эмбеддингов: он хранится в Secret, который уже есть в пространстве имён, как показано в разделах ниже.

Какой документ что написал

  • Каталог объявляет точки привязки. Сущность Component хранилища объявляет слот credential на каждом из двух своих сокетов моделей; сущность Component сервера эмбеддингов объявляет api_key на себе самой; каждый Recipe решает, в какой переменной передаётся ключ.
  • Сущность Aggregate — разработчик — указывает, к каким моделям обращается хранилище, учётные данные на каждом соединении, ключ, который проверяет сервер, и единственный параметр, который читают оба конца соединения эмбеддингов.
  • Сущность Manifest — маршрутизация оператора для этой целевой платформы — решает, чем становятся учётные данные в Kubernetes: ссылкой на Secret, который уже есть в пространстве имён, для каждого вложения core/referenced-secret, кроме вложения на соединении с размещённой моделью, которое извлекается из кластерного хранилища секретов.
  • Сущность Release — документ оператора для одного окружения — задаёт параметры, помещает границу в пространство имён и, в релизе с подключением оператором, подключает соединение извлечения и указывает ключ, предъявляемый на нём.

Ключ на каждое соединение

Хранилище обращается к двум моделям через два сокета, которые объявляет его сущность каталога, — extraction_model и embedding_model, и каждый сокет объявляет слот credential. Поэтому ключ, который предъявляет хранилище, находится на том соединении, на котором он предъявляется, и каждое соединение несёт свой собственный. Из aggregate-matched.yaml:

memory:
type: core/datastore/cognee
values:
# The width of the vectors the embedding model above returns.
embedding_dimensions: 384
uses:
extraction_model:
llm:
target: llm
features:
credential: # the key presented to the hosted model
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.provider_key_entry }}"
embedding_model:
embeddings:
target: embeddings
features:
credential: # the key presented to the embedding server
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.embedding_key_secret }}"

Вложение, записанное на соединении, становится одним из собственных вложений хранилища и получает имя из псевдонима соединения, точки и слота: llm.credential и embeddings.credential. Ниже приведены первые две и последние четыре записи env контейнера хранилища из dist/matched/helm/memory-statefulset.yaml:

- name: LLM_API_KEY
valueFrom:
secretKeyRef:
name: memory-llm.credential
key: api-key
- name: EMBEDDING_API_KEY
valueFrom:
secretKeyRef:
name: embedding-server-key
key: api-key
[… omitted: the store's own settings, HTTP_PORT to EMBEDDING_DIMENSIONS]
- name: EMBEDDING_ENDPOINT
value: http://embeddings-default:8080/v1
- name: EMBEDDING_MODEL
value: BAAI/bge-small-en-v1.5
- name: LLM_ENDPOINT
value: https://api.openai.com/v1
- name: LLM_MODEL
value: gpt-4o-mini

Первые две записи — это ключи, каждый из учётных данных на своём соединении, под переменной, которую Recipe хранилища назначает этой стороне: LLM_API_KEY для извлечения, EMBEDDING_API_KEY для эмбеддингов. Обе являются ссылками, а не значениями, и провайдер helm записывает записи, читаемые из Secret, перед обычными. Последние четыре пришли с двух соединений: каждая модель публикует свой адрес и имя модели, а Recipe хранилища читает их для каждого сокета.

Сущность Component хранилища также объявляет слот ключа на себе самой — model_api_key. Её Recipe читает этот слот только для неподключённого сокета, когда хранилище обращается к провайдеру по собственному адресу провайдера и нет соединения, которое несло бы ключ. Здесь подключены оба сокета, поэтому слот не читается.

Один ключ на обоих концах

Сервер эмбеддингов проверяет ключ. Он хранит этот ключ в слоте своей сущности Component, api_key, и его Recipe передаёт всё, что заполняет слот, как API_KEY — переменную, которую Text Embeddings Inference читает при запуске. Из aggregate-matched.yaml:

embeddings:
type: core/ai-model/tei
values:
model: BAAI/bge-small-en-v1.5
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.embedding_key_secret }}"

Это одно вложение на сервере. Ключ, который предъявляет хранилище, — другое, на соединении хранилища, показанном выше. Заполнение слота на одном конце ничего не заполняет на другом, поэтому объявление ключа на обоих концах — это минимум, а не дублирование. Два ключа остаются одним ключом потому, что оба читают один параметр, embedding_key_secret, который объявляет Aggregate и выполняет Release:

parameters:
provider_key_entry: ai/openai-api-key
embedding_key_secret: embedding-server-key

Manifest привязывает core/referenced-secret к k8s-existing-secret, который читает origin как имя секрета Secret, уже имеющегося в пространстве имён, и ничего не рендерит. Поэтому оба конца ссылаются на этот один Secret. В env контейнера сервера, из dist/matched/helm/embeddings-statefulset.yaml:

- name: API_KEY
valueFrom:
secretKeyRef:
name: embedding-server-key
key: api-key

и в контейнере хранилища, из dist/matched/helm/memory-statefulset.yaml:

- name: EMBEDDING_API_KEY
valueFrom:
secretKeyRef:
name: embedding-server-key
key: api-key

Secret создаётся вне сущности Release тем, кто её развёртывает, поэтому материал ключа никогда не проходит через написанный файл или отрендеренный артефакт.

Почему сервер никогда не видит ключей вызывающих сторон

Вложение на соединении достаётся только вызывающей стороне. Две учётные записи хранилища — это вложения хранилища: то, что они отрисовывают, находится рядом с хранилищем, и контейнер хранилища ссылается на это. Ничто из них не доходит до компонента, на который указывает соединение, поэтому цель отрисовывается одинаково, что бы ни несли достигающие её соединения.

Размещённая модель показывает это наглядно. Она отрисовывает один файл — Service, сопоставляющий внутрикластерное имя с хостом провайдера, — весь spec из dist/matched/helm/llm-service.yaml:

spec:
type: ExternalName
externalName: api.openai.com
ports:
- port: 443

Ключ, который хранилище ей предъявляет, извлекается рядом с хранилищем, как показывает следующий раздел. Сервер эмбеддингов показывает это через сравнение: несовпадающий релиз ниже меняет ключ на соединении хранилища с эмбеддингами и не трогает ключ сервера, и три файла сервера в dist/mismatched/ отличаются от файлов в dist/matched/ только меткой aggrega.ai/aggregate-name, которая называет сущность Aggregate, из которой собран каждый из них.

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

Один ключ на сервер

Text Embeddings Inference проверяет один ключ. Каждый вызывающий предъявляет один и тот же ключ, вызывающему с любым другим ключом отказывается в доступе, а сервер не может отличить одного вызывающего от другого, поэтому отзыв доступа у одного вызывающего означает смену ключа, который предъявляют все вызывающие. Сколько бы соединений к нему ни вело, его слот api_key содержит один ключ. Это ограничение самого сервера, и его разделяют core/ai-model/vllm и core/ai-model/tgi из каталога. Это не ограничение соединения: вызывающий, обращающийся к нескольким серверам, хранит по одному ключу на соединение, как хранилище здесь хранит два.

Ключ одного соединения из хранилища секретов

Manifest привязывает каждое вложение core/referenced-secret по его типу, а одно из них — по имени. Из manifest.yaml:

features:
# One realization for every core/referenced-secret attachment: the Secret
# already exists in the namespace, and origin is its name.
type:
core/referenced-secret:1.0.0: helm/k8s-existing-secret:1.0.0
# One attachment bound differently, by its name. An attachment written on
# a connection is named for the connection's alias, a dot and the slot,
# so the memory store's credential on its llm connection is
# llm.credential. That key is fetched from the store, and origin is the
# store entry to fetch.
name:
llm.credential: helm/k8s-external-secret:1.0.0

k8s-external-secret читает origin как запись хранилища, которую нужно получить. origin соединения — это параметр provider_key_entry, заполненный значением ai/openai-api-key, поэтому вложение отрисовывает ExternalSecret, который оператор хранилища секретов в кластере согласует в Secret. Весь spec из dist/matched/helm/memory--llm-zdcredential--memory-externalsecret-memory-memory-llm-credential.yaml:

spec:
refreshInterval: "1h"
secretStoreRef:
name: platform-secret-store
kind: ClusterSecretStore
target:
name: memory-llm.credential
creationPolicy: Owner
data:
- secretKey: api-key
remoteRef:
key: "ai/openai-api-key"

Secret, который он заполняет, memory-llm.credential, назван по хранилищу и соединению, и именно на это имя ссылается LLM_API_KEY хранилища выше. Реализация читает из ClusterSecretStore с именем platform-secret-store.

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

Где два конца разрешают секрет

Целевая платформа разрешает секрет по ссылке внутри области видимости секретов: границы, в пределах которой один ресурс может ссылаться на другой. Если оба конца соединения находятся в одной области, оба ссылаются на один ресурс секрета. Если они находятся в разных областях, каждый конец содержит собственный ресурс секрета, реализованный из одной и той же записи хранилища. Manifest выбирает реализацию для каждого конца — по типу Feature для всех вложений этого типа или для одного вложения по его имени.

Каждая целевая платформа определяет область в своих терминах. В Kubernetes, для которого собирается это рабочее пространство, это пространство имён: рабочая нагрузка может ссылаться на Secret только в своём собственном. Каждый релиз здесь размещает свою единственную границу в одном пространстве имён, aggrega.ai/namespace: memory, и каждый сгенерированный документ содержит его — заголовок обоих StatefulSet:

dist/matched/helm/memory-statefulset.yaml
metadata:
name: memory
namespace: memory
# dist/matched/helm/embeddings-statefulset.yaml
metadata:
name: embeddings
namespace: memory

Поэтому оба конца ссылаются на один Secret, показанный выше. Если сервер эмбеддингов находится в собственном пространстве имён, Manifest привязывает учётные данные обоих концов по имени — api_key и embeddings.credential — к k8s-external-secret, Release заполняет параметр записью хранилища, и каждый конец содержит ExternalSecret в своём пространстве имён, причём оба получают одну и ту же запись. Тогда хранилище обращается к серверу через границы пространств имён, что описано в cross-boundary-networking. На других целевых платформах областью служат проект Compose, корневая конфигурация Terraform и стек CloudFormation; каждую из них описывает модель учётных данных.

Оператор подключает соединение

aggregate-operator-wired.yaml описывает соединение с сервером эмбеддингов и оставляет сокет extraction_model хранилища несвязанным: его объявляет каталожная сущность хранилища, а разработчик оставляет его оператору. Сущность Release подключает его к размещённой модели, которую объявляет сущность Aggregate. Из release-operator-wired.yaml:

memory:
uses:
# A connection the Aggregate does not write, into a socket the
# store's catalog entity declares, to a component the Aggregate
# declares. A Release writes no values, so the credential on it
# names its secret in infra.
extraction_model:
llm:
target: llm
features:
credential:
type: core/referenced-secret
infra:
origin: ai/openai-api-key

Сущность Release может подключить соединение к сокету, который объявляет каталожная сущность и оставляет несвязанным сущность Aggregate, — к компоненту, который объявляет Aggregate. Она не добавляет компонентов и никогда не перенаправляет соединение, описанное в Aggregate. Она не записывает values, поэтому учётные данные на этом соединении указывают свой секрет в infra: core/referenced-secret берёт origin из values разработчика или из infra оператора, ровно из одного из двух, и сборка останавливается на вложении, которое содержит оба или ни одного.

Вложение называется llm.credential в точности как в согласованном релизе, поэтому уровень имён в сущности Manifest связывает его так же. Помимо метки с именем сущности Aggregate, dist/operator-wired/ и dist/matched/ различаются двумя строками. Поле data ресурса ExternalSecret:

data:
- secretKey: value
remoteRef:
key: "ai/openai-api-key"

и ссылка хранилища на заполняемый им Secret в dist/operator-wired/helm/memory-statefulset.yaml:

- name: LLM_API_KEY
valueFrom:
secretKeyRef:
name: memory-llm.credential
key: value

Ключ данных — value, а не api-key, потому что key — это лист values, который записывает только Aggregate, поэтому вложение, созданное одной лишь сущностью Release, читает значение по умолчанию сущности Feature. Реализация публикует этот ключ, а хранилище читает его из опубликованного, так что обе стороны по-прежнему согласованы.

Размещённая модель помечена как managed, поэтому соединение, ведущее к ней, несёт учётные данные или указывает в собственных values, что модель их не требует, — unauthenticated: true. Это верно независимо от того, какой документ описал соединение. Удалите блок features: из соединения в сущности Release — и сборка остановится. Остановка — это E0033, неудавшееся утверждение сущности Component хранилища, и её сообщение заканчивается собственной фразой правила: the extraction_model connection llm of “memory” reaches “llm”, whose component.aggrega.ai/hosting label is managed, with no credential: attach one under credential on that connection, or set unauthenticated: true in its values (соединение extraction_model llm сущности «memory» ведёт к «llm», метка component.aggrega.ai/hosting которой — managed, без учётных данных: прикрепите их в credential на этом соединении или задайте unauthenticated: true в его values).

Когда два конца не согласуются

aggregate-mismatched.yaml задаёт ключу сервера и ключу хранилища два разных параметра:

parameters:
provider_key_entry:
type: string
description: >
The store entry holding the key the memory store presents to the hosted
model provider.
embedding_key_secret:
type: string
description: The Secret holding the key the embedding server verifies.
# The fault: a second parameter for what is meant to be the same key.
memory_embedding_key_secret:
type: string
description: The Secret holding the key the memory store presents to the embedding server.

api_key сервера читает embedding_key_secret, а соединение хранилища читает memory_embedding_key_secret; сущность Release заполняет их двумя разными Secret. Сборка проходит успешно и записывает восемь файлов: компилятор вычисляет каждое переданное ему вложение и ничего не сравнивает между двумя концами. Сервер по-прежнему ссылается на embedding-server-key, а хранилище теперь предъявляет другой, из dist/mismatched/helm/memory-statefulset.yaml:

- name: EMBEDDING_API_KEY
valueFrom:
secretKeyRef:
name: embedding-client-key
key: api-key

После развёртывания сервер принимает запросы хранилища, только если в этих двух Secret случайно окажется один и тот же ключ.

Это выявляет проверка соглашений о публикации для сущности Release:

Terminal window
aggrega lint --release release-mismatched.yaml
release-mismatched.yaml:
warn: E0329 connection-credential-matches-target-key: connection "embeddings" on socket "embedding_model" of component "memory" carries a credential in its credential slot and its target "embeddings" holds a key in its api_key slot, but the two ends write their secret's locator differently, so they may name different secrets and the target would refuse the key this caller presents. The locators are compared as written, and neither is shown here. Reading one parameter at both ends keeps them one key; that agreement is the standard-catalog convention, and the build does not check it.
conventions checked: 10 entities, 1 advisory finding(s)

Та же проверка согласованного релиза ничего не сообщает:

Terminal window
aggrega lint --release release-matched.yaml
conventions checked: 10 entities, 0 advisory finding(s)

как и проверка релиза, связанного оператором.

Правило находит два конца по именам, которые им даёт стандартный каталог, — api_key цели и credential соединения — и сравнивает origin, который записывает каждый конец, в том виде, как он записан: два конца, читающие один параметр, считаются равными, и ничего не разрешается. Правило никогда не цитирует ни одно из значений, поскольку записанное там может быть самим секретом. Оно не оценивает цель с меткой managed, чей api_key, если она его объявляет, — это ключ, предъявляемый её поставщику, а не ключ, который предъявляют её вызывающие; поэтому соединение с llm не вызывает замечаний ни в одном из трёх релизов. Замечание носит рекомендательный характер: aggrega lint завершается с кодом 0, а рабочее пространство, в котором два конца намеренно различаются, отключает проверку с помощью allow_connection_credential_mismatches. Редактор, задающий демону тот же вопрос, aggrega/lint с указанием сущности Release, получает то же замечание с кодом connection-credential-matches-target-key и кратким кодом E0329. Правило и то, что оно читает, описаны в разделе Правила дисциплины.

Детерминированность

Все три релиза собираются с --verify-determinism, который рендерит каждый узел дважды и сравнивает выданные байты:

Terminal window
aggrega build --release release-matched.yaml --verify-determinism

Повторная сборка любого из трёх с чистого дерева воспроизводит его отрендеренный вывод байт в байт.

Адаптация примера

  • Добавьте второго вызывающего для сервера эмбеддингов. Учётные данные его соединения тоже читают embedding_key_secret. Сервер хранит один ключ для всех вызывающих, поэтому второй вызывающий предъявляет тот же ключ.
  • Получайте ключ эмбеддингов тоже из хранилища. Привяжите api_key и embeddings.credential по имени к k8s-external-secret и заполните embedding_key_secret записью хранилища вместо имени объекта Secret. Оба конца меняются вместе, потому что оба читают этот параметр.
  • Обращайтесь к модели, которая не проверяет ключ. Не указывайте учётные данные в соединении. Если цель помечена как managed, укажите это в соединении с помощью unauthenticated: true в его values.

О совместном использовании одного ключа в соединениях нескольких вызывающих см. model-api-key-sharing. О маршрутизаторе, который хранит ключи провайдеров от имени своих вызывающих, см. ai-agent-and-model-router. Модель, лежащая в основе всего этого, — модель учётных данных.