Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Спільне використання облікових даних — для кожного споживача, спільні та обидва варіанти одночасно

Два агенти CrewAI за одним OpenAI-сумісним шлюзом. Сокет model кожного агента оголошує слот credential, тож ключ, який агент пред’являє моделі, до якої звертається, прикріплюється на цьому з’єднанні. Цей робочий простір заповнює слот трьома способами, не змінюючи жодної сутності каталогу: ключ на кожне з’єднання, один Secret, на який вказують усі з’єднання, і спільне значення за замовчуванням, яке перевизначає одне з’єднання.

Суть саме у двох споживачах. З одним споживачем три форми не відрізнити — різниця полягає в тому, на який Secret зрештою вказує кожен споживач, а це питання не має змісту, доки споживач лише один.

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

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

Terminal window
aggrega scaffold --example model-api-key-sharing

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:

Terminal window
cd model-api-key-sharing

Збирання

Три релізи, по одному на форму. Збирайте по одному за запуск:

Terminal window
aggrega build --release release-per-consumer.yaml --auto-pull # → dist/per-consumer/
aggrega build --release release-shared.yaml --auto-pull # → dist/shared/
aggrega build --release release-composed.yaml --auto-pull # → dist/composed/

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

Перед збиранням релізу потрібен його lock-файл. У свіжому checkout спершу розв’яжіть його — окремим кроком або дозвольте збиранню заповнити його:

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

Релізи розв’язують свої сутності каталогу з налаштованого каталогу, тож прапорець --catalog не потрібен.

Усі три збираються під ціль helm, і це навмисно. Спостережувана ознака, що розрізняє три форми, — це ім’я Secret, на який посилається контейнер кожного агента, а саме в helm облікові дані є іменованим Kubernetes Secret, на який контейнер посилається за іменем. Облікові дані прив’язують дві сутності Manifest: manifest.yaml до k8s-secret-from-parameter, що генерує Secret зі значення, яке несе прикріплення, для релізу з ключем на кожного споживача; і manifest-existing-secret.yaml до k8s-existing-secret, що нічого не генерує і спрямовує кожного споживача на Secret, який уже є в просторі імен, для спільного і комбінованого релізів.

З ШІ-асистентом

ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.

Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека робочого простору ще не містить теки `model-api-key-sharing`, викличте один раз інструмент `scaffold`, задавши для `example` значення `model-api-key-sharing`, без `dir`: він запише приклад у нову теку `model-api-key-sharing`. Потім викличте інструмент `build` один раз для кожного файлу Release у такому порядку — `release-per-consumer.yaml`, `release-shared.yaml` і `release-composed.yaml` — щоразу задаючи для `workspace_root` значення `model-api-key-sharing`, для `release` — цей файл, для `auto_pull` — true і для `write` — true. Скажіть, які файли записала кожна збірка; вони розташовані в `model-api-key-sharing/dist/`.

Для кожного споживача — кожне з’єднання має власний ключ

aggregate-per-consumer.yaml заповнює слот на з’єднанні кожного агента, з різним origin для кожного агента:

researcher:
type: core/ai-agent/crewai
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: researcher-key-change-me

Прикріплення на з’єднанні стає одним із власних прикріплень агента й отримує ім’я за з’єднанням і слотом — тут gateway.credential — тож генеруються два Secret, по одному на агента, кожен із власним матеріалом цього агента:

dist/per-consumer/helm/researcher--gateway-zdcredential--researcher-secret-researcher-gateway-credential.yaml
[… omitted: the apiVersion and the Secret kind]
metadata:
name: researcher-gateway.credential
[… omitted: the labels and annotations every rendered document carries]
stringData:
OPENAI_API_KEY: "researcher-key-change-me"
# dist/per-consumer/helm/writer--gateway-zdcredential--writer-secret-writer-gateway-credential.yaml
[… omitted: the apiVersion and the Secret kind]
metadata:
name: writer-gateway.credential
[… omitted: the labels and annotations every rendered document carries]
stringData:
OPENAI_API_KEY: "writer-key-change-me"

і кожен Deployment посилається на свій:

dist/per-consumer/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: researcher-gateway.credential
key: OPENAI_API_KEY
# dist/per-consumer/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: writer-gateway.credential
key: OPENAI_API_KEY

Відкликання ключа одного агента не зупиняє іншого.

Спільні — один Secret, на який посилається кожне з’єднання

Облікові дані на з’єднанні записуються на цьому з’єднанні: ніщо, прикріплене в іншому місці, їх не заповнює. Тож кілька споживачів спільно використовують одні облікові дані через авторство: облікові дані кожного з’єднання читають те саме значення, і це значення називає один Secret.

aggregate-shared.yaml оголошує один параметр і читає його на обох з’єднаннях:

parameters:
team_model_key:
type: string
default: team-model-key
components:
researcher:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: "{{ .parameters.team_model_key }}"
writer: { ... } # the same credential, reading the same parameter

Реліз прив’язує облікові дані до k8s-existing-secret, який читає origin як ім’я Secret, що вже існує в просторі імен. Він не генерує жодного Secret — записуються лише Service шлюзу і два Deployment — і обидва Deployment посилаються на один Secret, названий параметром:

dist/shared/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY
# dist/shared/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY

Це рівно один фізичний Secret, створений поза сутністю Release тим, хто її розгортає, і прочитаний кожним споживачем. Матеріал ключа ніколи не проходить через авторський файл чи згенерований артефакт.

Те, що несе параметр, залежить від реалізації, яку прив’язує Manifest. За k8s-existing-secret це ім’я Secret. Якби натомість було прив’язано k8s-secret-from-parameter, ті самі два з’єднання, що читають один параметр, несли б сам ключ, і збирання згенерувало б по одному Secret на споживача, кожен з тим самим матеріалом: генерування виконується для кожного компонента, а ця реалізація називає Secret, який генерує, за компонентом-споживачем і з’єднанням. Один параметр не дає споживачам розійтися; а те, яка реалізація його читає, визначає, чи спільний у них ресурс. Облікові дані, згенеровані в кластері, спільно використовуються так само — один запит і багато посилань; див. Модель облікових даних.

Комбіновані — спільне значення за замовчуванням, одне з’єднання його перевизначає

aggregate-composed.yaml залишає спільний параметр як значення за замовчуванням і дозволяє одному з’єднанню назвати власний Secret:

researcher:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: researcher-model-key # this connection's own Secret
writer:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: "{{ .parameters.team_model_key }}" # the shared default

Перевизначення — це те, що пише саме це з’єднання; ніщо на нього не каскадується, а writer зберігає спільний Secret без змін:

dist/composed/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: researcher-model-key
key: OPENAI_API_KEY
# dist/composed/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY

Облікові дані з’єднання — це ціле окреме прикріплення, тож перевизначення повторює кожне потрібне поле — тут тип Feature, key і origin — і не успадковує жодного від значення за замовчуванням.

Що дає слот

core/ai-agent/crewai оголошує слот один раз, на своєму сокеті model, і всі три форми — це вибір, зроблений в Aggregate:

usesSchema:
model:
selector: "component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api"
required: true
inject: [env, file]
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

Слот необов’язковий, тож четвертий варіант — нічого не прикріплювати: приберіть блок features: з обох з’єднань, і згенероване дерево втратить усі записи env OPENAI_API_KEY, залишивши два Deployment і Service шлюзу. Ніщо не вигадується, щоб заповнити прогалину. Сутність каталогу однакова в кожному випадку; вирішує автор.

Це збирається, бо шлюз тут, core/ai-model/openai-compatible, не має мітки component.aggrega.ai/hosting. З’єднання з ціллю, яку каталог позначає managed — скажімо, core/ai-model/openai, — без облікових даних зупиняє збирання на власній перевірці агента, якщо тільки з’єднання не вказує у своїх values, що ціль їх не потребує, unauthenticated: true.

Слот також агностичний щодо сімейства (feature.aggrega.ai/kind=secret допускає будь-яке сімейство облікових даних), і саме це дозволяє тому самому агентові приймати Secret, на який можна послатися, у helm і облікові дані з вбудованим значенням у compose. Доставка облікових даних — secretKeyRef наскрізно розбирає цей поділ між провайдерами, а її негативний реліз показує, що стається, коли від облікових даних, на які не можна послатися, вимагають задовольнити посилання.

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

Усі три релізи збираються з --verify-determinism, що генерує кожен вузол двічі й порівнює виведені байти:

Terminal window
aggrega build --release release-shared.yaml --auto-pull --verify-determinism

Повторне збирання будь-якого з трьох із чистого дерева відтворює його згенерований результат байт у байт.