İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Bir kimlik bilgisini paylaşmak — tüketici başına, paylaşılan ve ikisi birden

Tek bir OpenAI uyumlu ağ geçidinin arkasında iki CrewAI ajanı. Her ajanın model soketi bir credential yuvası bildirir; böylece bir ajanın eriştiği modele sunduğu anahtar o bağlantıya eklenir. Bu çalışma alanı, tek bir katalog varlığını değiştirmeden yuvayı üç şekilde doldurur: bağlantı başına bir anahtar, her bağlantının gösterdiği tek bir Secret ve bir bağlantının geçersiz kıldığı paylaşılan bir varsayılan.

Asıl mesele iki tüketicidir. Tek bir tüketiciyle üç biçim birbirinden ayırt edilemez — fark, her tüketicinin sonunda hangi Secret’ı gösterdiğidir ve birden fazla tüketici olana kadar bu sorunun bir içeriği yoktur.

Örneği oluşturun

Bu örneği aşağıdaki komutlarla derleyebilir ya da yapay zekâ asistanınıza sizin için derletebilirsiniz.

Örneği, adını taşıyan yeni bir klasöre yazın:

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

Ardından sırada çalıştırılacak komutları yazdırır. İlki yeni klasöre geçer:

Terminal window
cd model-api-key-sharing

Derleme

Her biçim için bir tane olmak üzere üç release. Her çalıştırmada birini derleyin:

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/

Her release kendi dizinine yazar; böylece üç işlenmiş ağacın tümü bir arada bulunur ve birbirleriyle karşılaştırılabilir.

Bir release derlenmeden önce kilit dosyasına ihtiyaç duyar. Yeni bir checkout’ta önce bir tane çözümleyin — ya ayrı bir adım olarak ya da derlemenin onu doldurmasına izin vererek:

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

Release’ler katalog varlıklarını yapılandırılmış katalogdan çözümler; bu nedenle --catalog bayrağına gerek yoktur.

Üçü de bilinçli olarak helm hedefinde derlenir. Üç biçimi birbirinden ayıran gözlemlenebilir şey her ajanın konteynerinin başvurduğu Secret’ın adıdır ve helm, bir kimlik bilgisinin bir konteynerin adıyla başvurduğu adlandırılmış bir Kubernetes Secret’ı olduğu yerdir. İki Manifest kimlik bilgisini bağlar: tüketici başına release için manifest.yaml, ekin taşıdığı değerden bir Secret işleyen k8s-secret-from-parameter’a; paylaşılan ve birleşik release’ler için ise manifest-existing-secret.yaml, hiçbir şey işlemeyen ve her tüketiciyi ad alanında zaten bulunan bir Secret’a yönlendiren k8s-existing-secret’a.

Bir yapay zekâ asistanıyla

Aggrega araçlarıyla kurulmuş bir yapay zekâ asistanı da aynısını yapabilir: bu istemi ona yapıştırın.

Yalnızca Aggrega araçlarını kullanın ve kendiniz klasör oluşturmayın. Çalışma alanı klasöründe henüz `model-api-key-sharing` klasörü yoksa `scaffold` aracını `example` değeri `model-api-key-sharing` olacak şekilde ve `dir` olmadan bir kez çağırın: araç örneği yeni bir `model-api-key-sharing` klasörüne yazar. Ardından `build` aracını her Release için bir kez, şu sırayla — `release-per-consumer.yaml`, `release-shared.yaml` ve `release-composed.yaml` — her seferinde `workspace_root` değeri `model-api-key-sharing`, `release` değeri o dosya, `auto_pull` değeri true ve `write` değeri true olacak şekilde çağırın. Her derlemenin hangi dosyaları yazdığını bana söyleyin; dosyalar `model-api-key-sharing/dist/` altındadır.

Tüketici başına — her bağlantı kendi anahtarını tutar

aggregate-per-consumer.yaml, yuvayı her ajanın bağlantısında, ajan başına farklı bir origin ile doldurur:

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

Bir bağlantıdaki ek, ajanın kendi eklerinden biri olur ve bağlantı ile yuvaya göre adlandırılır — burada gateway.credential — böylece her ajan için bir tane olmak üzere iki Secret üretilir ve her biri o ajanın kendi materyalini taşır:

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"

ve her Deployment kendininkine başvurur:

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

Bir ajanın anahtarını iptal etmek diğerini çalışır durumda bırakır.

Paylaşılan — her bağlantıdan başvurulan tek bir Secret

Bir bağlantıdaki kimlik bilgisi o bağlantıya yazılır: başka bir yere eklenen hiçbir şey onu doldurmaz. Bu nedenle birkaç tüketici tek bir kimlik bilgisini yazarak paylaşır: her bağlantının kimlik bilgisi aynı değeri okur ve bu değer tek bir Secret’ı adlandırır.

aggregate-shared.yaml tek bir parametre bildirir ve onu her iki bağlantıda okur:

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

Release, kimlik bilgisini origin’i ad alanında zaten var olan bir Secret’ın adı olarak okuyan k8s-existing-secret’a bağlar. Hiç Secret işlemez — yalnızca ağ geçidinin Service’i ve iki Deployment yazılır — ve her iki Deployment da parametrenin adlandırdığı tek Secret’a başvurur:

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

Bu, Release’in dışında, onu dağıtan kişi tarafından oluşturulan ve her tüketici tarafından okunan tam olarak tek bir fiziksel Secret’tır. Anahtarın materyali hiçbir zaman yazılmış bir dosyadan veya işlenmiş bir yapıttan geçmez.

Parametrenin ne taşıdığı, Manifest’in bağladığı gerçekleştirmeye bağlıdır. k8s-existing-secret altında bir Secret’ın adıdır. Bunun yerine k8s-secret-from-parameter’a bağlansaydı, tek bir parametreyi okuyan aynı iki bağlantı anahtarın kendisini taşırdı ve derleme, her biri aynı materyali tutan, tüketici başına bir Secret işlerdi: işleme bileşen başına çalışır ve o gerçekleştirme, işlediği Secret’ı tüketen bileşenin ve bağlantının adıyla adlandırır. Tüketicilerin birbirinden uzaklaşmasını önleyen tek parametredir; onu hangi gerçekleştirmenin okuduğu ise bir kaynağı paylaşıp paylaşmadıklarını belirler. Kümede üretilen bir kimlik bilgisi de aynı şekilde paylaşılır — tek istek ve çok sayıda başvuru; bkz. Kimlik bilgisi modeli.

Birleşik — paylaşılan varsayılan, bir bağlantı geçersiz kılıyor

aggregate-composed.yaml, paylaşılan parametreyi varsayılan olarak tutar ve bir bağlantının kendine ait bir Secret adlandırmasına izin verir:

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

Geçersiz kılma, o tek bağlantının yazdığı şeydir; ona hiçbir şey basamaklanmaz ve writer paylaşılan Secret’ı olduğu gibi korur:

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

Bir bağlantının kimlik bilgisi kendine ait eksiksiz bir ektir; bu nedenle bir geçersiz kılma ihtiyaç duyduğu her alanı yeniden belirtir — burada Feature türü, key ve origin — ve varsayılandan hiçbirini devralmaz.

Yuvanın kazandırdıkları

core/ai-agent/crewai yuvayı model soketinde bir kez bildirir ve üç biçimin tümü Aggregate’te yapılan seçimlerdir:

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]

Yuva isteğe bağlıdır; bu nedenle dördüncü bir şekil hiçbir şey eklememektir: her iki bağlantıdan features: bloğunu kaldırın; işlenmiş ağaç her OPENAI_API_KEY env girdisini kaybeder ve geriye iki Deployment ile ağ geçidi Service’i kalır. Boşluğu doldurmak için hiçbir şey uydurulmaz. Katalog varlığı her durumda aynıdır; kararı yazar verir.

Bu derlenir, çünkü buradaki ağ geçidi core/ai-model/openai-compatible, component.aggrega.ai/hosting etiketi taşımaz. Kataloğun managed olarak etiketlediği bir hedefe — örneğin core/ai-model/openai — kimlik bilgisi olmadan erişen bir bağlantı, bağlantı values içinde hedefin kimlik bilgisi almadığını, unauthenticated: true, belirtmedikçe derlemeyi ajanın kendi doğrulamasında durdurur.

Yuva ayrıca aileden bağımsızdır (feature.aggrega.ai/kind=secret her iki kimlik bilgisi ailesini de kabul eder); aynı ajanın helm’de başvurulabilir bir Secret, compose’da ise değer enjekte eden bir kimlik bilgisi almasını sağlayan budur. Kimlik bilgisi teslimi — uçtan uca secretKeyRef bu sağlayıcı ayrımını işler ve onun negatif release’i, başvurulamayan bir kimlik bilgisinden bir başvuruyu karşılaması istendiğinde ne olduğunu gösterir.

Determinizm

Üç release’in tümü, her düğümü iki kez işleyen ve üretilen baytları karşılaştıran --verify-determinism altında derlenir:

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

Üçünden herhangi birini temiz bir ağaçtan yeniden derlemek, işlenmiş çıktısını bayt bayt yeniden üretir.