Перейти до вмісту
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 не потрібен.

Отримання виводить:

[… 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

Два інші релізи виводять ті самі рядки: кожне отримання називає власний 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

і в контейнерному env сховища, з 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

Ключ, який сховище їй пред’являє, отримується поруч зі сховищем, як показує наступний розділ. Сервер ембедингів показує це через порівняння: невідповідний релiз нижче змінює ключ на з’єднанні сховища з сервером ембедингів і не чіпає ключ сервера, а три файли сервера в 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. Модель, що лежить в основі всього цього, — модель облікових даних.