Backend operasyonları

Özet

Bir backend statik bir dosya değildir — boş bir başlangıç durumuna uygulanan bir tipli mutasyon dizisinin sonucudur. Operasyon log'u gerçeğin kaynağıdır; graf durumu türetilir.
Her yüzey — App, CLI, SDK, REST API — aynı operasyon kümesini konuşur. CLI aracılığıyla yapılan bir değişiklik, App aracılığıyla aynı şekilde görünür; hangi yüzeyin ürettiğinden bağımsız olarak tek bir geçmiş vardır.
Operasyonlar küçük bir tipli kelime dağarcığı oluşturur: add-vertex, connect, change-parameter, add-file, change-endpoint-alias, change-version, delete-vertex, disconnect ve bir avuç başkası. Her biri tersiyle kaydedilir, böylece log incelenebilir ve geri alınabilirdir.
Üç meta-operasyon geçmiş yönetimini kapsar: undo son N operasyonu geri alır, compact log'u aynı son grafı üreten minimum diziye yeniden yazar, operations neler olduğunu gözden geçirir.
Parametre değerleri pipelang literal'leridir (JSON değil), component'in config_schema'sında yaptığı bildirime karşı tipli. Tipi slot'la eşleşmeyen bir değer, deploy zamanında değil düzenleme zamanında reddedilir.

Backend operasyonları nedir

Bir backend, event-sourced bir graftır: boş bir başlangıç durumuna uygulanan küçük tipli operasyonların bir akışı, mevcut graf onları replay ederek türetilir. Operasyon log'u gerçeğin kaynağıdır; graf, projeksiyondur.

Her operasyon dardır — bir vertex, bir edge, bir parametre — ve indiği anda doğrulanır. Platform her operasyonu tersiyle birlikte kaydeder, böylece log hem incelenebilir hem de geri alınabilirdir. Graf, onunla senkron tutulan bir dosya yerine log'un replay'i olduğundan, eşzamanlı düzenlemeler birbirinin üzerine yazmak yerine bağımsız operasyonlar olarak birleşir ve herhangi bir geçmiş noktadaki graf, o noktaya kadarki operasyonların tam olarak ön ekidir.

Bu, standart event-sourcing değiş tokuşudur. Platform mutasyon yüzeyine sahiptir — doğrudan düzenlenecek bant dışı bir dosya yoktur — ve karşılığında her değişiklik inmeden önce doğrulanır, tersiyle kaydedilir ve geri çevrilebilirdir. Undo, kaydedilen operasyonları geri alır; geçmiş, kimin neyi ne zaman değiştirdiğini yanıtlar; "geçen salıdaki graf", bir tahmin yerine somut bir replay'dir.

CLI fiilleri, App'in graf editörü, REST API ve herhangi bir SDK hepsi aynı log'a karşı aynı operasyon satırlarını üretir. Hiçbir yüzeyin onu atlayan ayrı bir düşük seviyeli yolu yoktur. Bu tekdüzelik, başka bir aracın gördüğünü bozmadan bir backend'i bir araçtan düzenlemenizi sağlayan şeydir.

Zihinsel model

   boş
     │  add-vertex          v1  (release X'e sabitlenmiş)
     │  add-vertex          v2  (release Y'ye sabitlenmiş)
     │  add-vertex          v3  (release Z'ye sabitlenmiş)
     │  connect             v1.out0 → v2.in0
     │  connect             v2.out0 → v3.in0
     │  change-parameter    v2.threshold = 0.7
     │  add-file            v2.weights  = <file_id>
     │  change-endpoint-alias  v3.image_out → preview
     ▼
   mevcut backend grafı

Her satır bir kaydedilmiş operasyondur. App'in render ettiği graf, ppl backend get'in döndürdüğü graf ve deploy adımının doğruladığı graf hepsi o log'un replay'idir. Aynı backend'i CLI'dan, UI'dan veya bir script'ten düzenlemek aynı log'a yeni satırlar yazar; bir değişikliği başlatan yüzey özel olarak kaydedilmez.

Doğrulama, bir operasyon inmeden önce gerçekleşir. Kaynak ve hedef tipleri birleşmeyen bir connect reddedilir ve kaydedilmez; graf inşa gereği geçerli kalır. Literal değeri bildirilen tiple eşleşmeyen bir change-parameter çağrıda reddedilir. Dosya tipi slot'la eşleşmeyen bir add-file reddedilir. Log yalnızca platformun kabul ettiği operasyonları içerir, bu yüzden "mevcut graf geçerli mi" ile "log'a ne indi" aynı sorudur.

Log'un ürettiği graf için Backend'ler ve doğrulama sözleşmesi için Tipler sayfalarına bakın.

Operasyon kelime dağarcığı

Bunu "hangi fiiller var" kataloğu olarak kullanın.

Operasyon kümesi kasıtlı olarak küçüktür. Neredeyse her backend düzenlemesi aşağıdaki fiillerden birine uyar ve platform bu kelime dağarcığının dışında her şeyi reddeder.

Graf topolojisi — hangi vertex'lerin var olduğunu ve nasıl wire'landıklarını değiştiren operasyonlar. add-vertex grafa bir component instance ekler (belirli bir release sürümünü sabitleyerek). delete-vertex bir vertex kaldırır ve disconnect'leri cascade eder. connect, (from-vertex, from-output)'u (to-vertex, to-input)'a wire'lar. disconnect, belirli bir input'taki inbound edge'i kaldırır — input'lar en fazla bir upstream edge kabul eder, bu yüzden disconnect hedefi alır. change-version, bir vertex'i aynı component'in farklı bir release'ine taşır, yeni release'in tipleri uyumlu olduğu sürece mevcut bağlamalarını korur.

Vertex bağlamaları — bir vertex'in yapılandırmasını değiştiren operasyonlar. change-parameter, bir tipli config parametresini bir pipelang literal'ine ayarlar. add-file, bir dosyayı vertex'in file_schema slot'larından birine bağlar (--file "" iletmek bağlamayı temizler). add-constraint, tip çıkarımı kendi başına karar veremediğinde bir vertex'in generic-type bağlamalarını sabitler veya iyileştirir.

Vertex metadata'sı — vertex'in nasıl adlandırıldığını veya render edildiğini etkileyen operasyonlar. change-alias vertex'in display alias'ını yeniden adlandırır. change-layout, graf-görünümü araçlarında (x, y, w, h) pozisyonunu ayarlar. change-metadata serbest biçimli bir metadata anahtarı ayarlar.

Endpoint açma — harici çağıranların vertex'e nasıl ulaştığını etkileyen operasyonlar. change-endpoint-alias, bir component-tarafından-bildirilmiş endpoint adını, application'ın runtime'da çözdüğü kararlı bir rol dizesine eşler. change-host-port-binding, doğrudan erişim için bir container port'unu bir host port'una eşler. change-volume-mount, container'a bir volume mount eder.

Runtime override'ları — deploy edildiğinde bir vertex'in nasıl çalıştığını ayarlayan operasyonlar. change-service-config, bir vertex'in depends_on bildirimlerindeki bir (service, key) değerini override eder (örn. bir serving service'inin model adını veya pull stratejisini değiştir). Bunlar, component'in varsayılanlarının backend seviyesinde override edilmesi gereken durumlar için kaçış kapaklarıdır.

Her operasyon log'da bir satırdır. Platformun reddettiği operasyonlar (tip-uyumsuz bir connect, yanlış tipte bir parametre literal'i, component'in bildirmediği bir endpoint'te bir alias) hiç kaydedilmez — geçersiz operasyonlar asla inmediği için graf geçerli kalır.

Undo, compact, gözden geçir

Bu üç fiili, graf üzerinde değil log'un kendisi üzerinde işlem yapmak için kullanın.

ppl backend undo <bid> <count> son N operasyonu ters sırada geri alır. Undo'nun kendisi yeni operasyonlar olarak kaydedilir, böylece neyin yapıldığı, geri alındığı ve yeniden yapıldığı izi yeniden yazılmak yerine korunur. Onu daha eskileri rahatsız etmeden en son düzenlemeleri geri yürümek için kullanın.

ppl backend compact <bid> kaydedilen log'u aynı son grafı üreten minimum operasyon dizisine yeniden yazar. Yerini alan parametre değerleri düşürülür, geri alınan değişiklikler düşürülür ve connect/disconnect dalgalanması gerçekten var olan edge'lere daralır; grafın kendisi değişmez. Compact'ten sonra, daha eski operasyonlar artık log'da değildir, bu yüzden undo onların içinden geriye uzanamaz. Compact, uzun düzenleme geçmişi biriktirmiş ve göz atılamayacak kadar gürültülü bir log'u olan bir backend'e uyar — son graf korunur, yerini alan operasyonlar düşürülür.

ppl backend operations <bid> log'u gözden geçirir: kimin neyi ne zaman değiştirdiği, kaç operasyonu geri alacağı ve bir backend'in neden olduğu gibi göründüğü.

Yaygın bir birleşik desen: yakın zamanda neler olduğunu görmek için operations, kötü düzenlemeleri geri yürümek için undo, düzeltilmiş durumdan düzenlemeye devam et.

Patch ile batch mutasyonları

Birçok küçük operasyonun birlikte inmesi veya hiç inmemesi gerektiğinde bunu kullanın.

ppl backend patch <bid> --file ./changes.json, bir JSON operasyon batch'ini tek bir işlem olarak uygular. İlk hata iptal eder ve tüm batch geri alınır, böylece ya düzenlemelerin hepsi iner ya da hiçbiri inmez. --dry-run (veya dosyada dry_run: true) eklemek, commit etmeden sonucu önizler — batch otomasyonla üretildiğinde ve çağıran gerçek için göndermeden önce type-check edip etmeyeceğini bilmek istediğinde yararlıdır.

İşlemsel şekil önemlidir çünkü her operasyonu kendi CLI çağrısı olarak vermenin atomiklik garantisi yoktur. On iki operasyonu birer birer veren ve onuncuda başarısız olan bir script, backend'i dokuzu uygulanmış halde bırakır; patch ya on ikisinin de uygulanmasını ya da hiçbirinin uygulanmamasını sağlar.

Parametre literal'leri nasıl çalışır

change-parameter makul görünen bir değeri reddettiğinde bu çerçeveyi kullanın.

Parametre değerleri JSON değil, pipelang literal'leridir. --type bayrağı değerin hangi tiple eşleşmesi gerektiğini bildirir; --value pipelang söziziminde literal'dir. Platform, literal'in tipe karşı ayrıştırıldığını ve tipin component'in config_schema'sından bildirilen parametre tipiyle eşleştiğini doğrular.

Gramer küçük ve özeldir: dizeler çift tırnaklı, tuple'lar parantez içinde, listeler köşeli parantez içinde, kayıtlar süslü parantez içinde, küçük harf boolean'lar, ondalık float'lar. "true" (tırnaklı bir dize) veya 1 (bir Double beklenirken bir tamsayı) gibi JSON görünümlü değerler change-parameter çağrısında reddedilir. Tam gramer Tip sözizimi referansı içinde yaşar.

Shell tırnaklaması da önemlidir. Shell, pipelang ayrıştırıcısı görmeden önce parantezleri, köşeli parantezleri veya tırnakları yememesi için shell çağrılarında tam literal'i tek tırnağa alın:

ppl backend change-parameter <bid> --vertex 2 --name threshold \    --type Double --value '0.7'

Doğrulamanın karşı çalıştığı tip sistemi için Tipler sayfasına bakın.

Log'un yapmanıza izin verdikleri

Hangi yeteneklerin event-sourced tasarımın aşağı akış sonuçları olduğunu anlamak için bu çerçeveyi kullanın.

Event-sourced şekil, birçok başka platform yeteneğini mümkün kılan şeydir. Undo bunlardan biridir. Yeniden üretilebilirlik başka biridir: aynı log her seferinde replay'de aynı grafı üretir. Denetim bir üçüncüdür: log, kimin yaptığı ve ne zaman dahil olmak üzere her değişikliğin yetkili kaydıdır. Test-and-verify döngüleri buna bağlıdır, çünkü sabitlenmiş operasyon geçmişi olan bir backend "dün test edilen sürümü" adreslenebilir kılar. Bir backend'i ppl backend create --source <bid> ile fork etmek log'u yeni bir nesneye kopyalar; fork özdeş başlar ve kendi sonraki operasyonları aracılığıyla ayrışır.

Tasarım, her değişikliğin bir operasyondan geçmesini gerektirir. Grafı el ile düzenlemek için bant dışı bir yol yoktur ve log'u atlamanın bir yolu yoktur. Karşılığında, log neyin değiştiğine bakılacak tek yerdir ve her aşağı akış yeteneği o özelliğe dayanır.

Bunun yeri

Backend operasyonları, platformun atomik düzenleme alfabesidir. Her üst düzey iş akışı — bir graf monte etmek, bir model değiştirmek, yeni bir endpoint açmak, bir değişikliği geri almak, paralel ortamlar için fork etmek — bu tipli operasyonların bir dizisine ayrışır. Kelime dağarcığı bir kez öğrenilecek kadar küçük ve işi ifade edecek kadar büyüktür ve event-sourced log neyin olduğunun yetkili kaydıdır.

İlgili

Backend'ler — bu operasyonların inşa ettiği kavramsal katman.
Tipler — connect ve change-parameter'ın neye karşı doğruladığı.
Dosya bağlama — add-file'ın neyi bağladığı ve taşıdığı config.
Çözümler — vertex'lerin ve edge'lerin nasıl sevk edilmiş bir ürün olduğu.
Secret'ler — bir secret: true parametresini bir workspace secret'ine bağlama.
Deployment'lar — runtime tarafı; log girdidir, deployment çıktıdır.
Tip sözizimi referansı — tam pipelang literal grameri.