Çözümler

Özet

• Bir çözüm, sevk edilmiş bir Pipelogic ürününün tüm yığınıdır: bir component (yeniden kullanılabilir tipli yetenek) bir backend'e (tipli graf) sabitlenir, bu bir deployment olarak çalışır ve doğrudan çağıranlar tarafından ya da bir application (kararlı alias'larla deploy edilmiş endpoint'lere bağlı UI) aracılığıyla erişilir.
• Bir driver, bir application'ın sabitlediği adlandırılmış, yeniden kullanılabilir sözleşmedir. Application ikisine referans verir: needs_driver (canlı wire sözleşmesi — UX ihtiyacı başına transport) ve taps_driver (capture ve replay sözleşmesi — her zaman HTTP, her iki yön). Bir backend, endpoint alias'ları driver'ın bildirdiği her gerekli endpoint ile hizalandığında bir driver'ı karşılar — backend'de hiçbir driver_id yaşamaz, hizalama örtüktür.
• Bir çözümü inşa etme işi çoğunlukla kompozisyondur, kodlama değil. Katalogdaki component'ler backend'lere wire'lanır; backend'ler deployment'lara dönüşür; deployment'lar endpoint'leri açar; application'lar bu endpoint'lere bağlanır. Özel kod yalnızca kataloğun zaten yeteneği kapsamadığı yerlerde ortaya çıkar.
• Endpoint alias'ları bir application'ı vertex kimliklerinden ayrı tutar. Bir backend (vertex, endpoint-name)'i kararlı bir rol dizesine eşler; application, belirli bir vertex'in endpoint'ini sabitlemek yerine upload alias'ını deployment'a karşı çözer.
• Çoğu ürün çalışması için operasyon sırası build'den önce değiştir, değiştirmeden önce yeniden kullan'dır: Solutions katalogundaki yayımlanmış bir backend veya component'ten başlayın, rol uyduğu ama implementasyon değişmesi gerektiği zaman bir sağlayıcı değiştirin ve yalnızca hiçbir katalog girişi yeteneği kapsamadığında özel kod yazın.
• Bir çözüm, grafın yalnızca var olduğunda değil, beklenen davranış canlı runtime'da gözlemlenebilir olduğunda hazırdır — akan çıktılar, sağlıklı container log'ları, olmaları gereken yerde üretilen dosyalar.

"Çözüm" burada ne anlama gelir

Bir çözüm, dört katmanın tümünün — component, backend, deployment, application (veya doğrudan çağıran) — bir son kullanıcının etkileşime girdiği bir ürüne kompozisyonudur. Terim, herhangi bir tek primitive'i değil tüm yığını adlandırır.

Sözleşme kesindir çünkü katmanlar çoktan-çoğadır: aynı component onlarca çözümün içinde oturabilir, aynı backend birden fazla ürün yüzeyine hizmet verebilir ve aynı deployment birden fazla application'ın endpoint bağlamasını barındırabilir. Monte edilen ürün için tek bir sözcük, "bu ürün" hakkında bir konuşmanın hangi component sürümlerine, hangi backend revizyonuna, hangi deployment'a ve hangi application build'ine atıfta bulunduğunu sıralamak zorunda olmaması demektir. Sözcük, platformun uyguladığı alias ve bağlama sözleşmeleriyle birleştirilmiş tüm bunları ifade eder.

Her katman bir işi yapar. Component'ler genel kalır, backend'ler onları oluşturur, deployment'lar onları çalıştırır ve application'lar onları yüzeye çıkarır. Sınırlar katıdır: bir component onu hangi backend'in kullandığını bilmez, bir backend onu hangi deployment'ın çalıştırdığını bilmez ve bir deployment hangi application'ın endpoint'lerini çözdüğünü bilmez. Bu ayrım, aynı primitive'leri birçok çözüm boyunca yeniden kullanılabilir kılan şeydir.

Zihinsel model — dört katman

   ┌─────────────────────────────────────────────────────┐
   │  Application        UI; endpoint alias'larını çözer      │
   ├─────────────────────────────────────────────────────┤
   │  Deployment    bir runtime üzerinde çalışan backend │
   ├─────────────────────────────────────────────────────┤
   │  Backend       tipli graf + vertex başına bağlamalar│
   ├─────────────────────────────────────────────────────┤
   │  Component     yeniden kullanılabilir tipli yetenek │
   └─────────────────────────────────────────────────────┘

Aşağıdan yukarıya okuyarak: bir component, bildirilmiş input slot'ları, output slot'ları, yapılandırma parametreleri ve isteğe bağlı dosya slot'ları olan yeniden kullanılabilir tipli bir yetenektir. Bir backend, component release'lerini vertex olarak sabitleyen, parametrelerini ve dosyalarını bağlayan, tipli stream'lerini bağlayan ve harici çağıranların erişeceği endpoint'lere kararlı rol adları veren ürüne özel graftır. Bir deployment, o backend'i bir runtime üzerinde çalıştırır, grafı container'lar olarak materyalleştirir ve her endpoint alias'ı için çözülmüş URL'ler yayımlar. Bir application, alias ile deployment'a bağlı UI'dır — upload ve events ister ve şu anda arkasında hangi vertex veya release olduğunu hiç bilmeden canlı URL'leri geri alır.

Bir backend aynı anda en fazla bir deployment barındırır — bağlantı tasarım gereği 1:1'dir, böylece şu anda neyin çalıştığı kesindir. İki ortamı paralel çalıştırmak için (staging ve üretim, A ve B, mavi ve yeşil), önce backend'i fork edin ve her fork'u bağımsız olarak deploy edin. Her ortam böylece kendi operasyon geçmişiyle kendi nesnesidir, bu da ortam başına davranışı denetlemeyi basit tutar.

Her katmanın ayrıntısı için Component'ler, Backend'ler, Deployment'lar, Application'lar sayfalarına bakın.

Endpoint alias'ları — graf ile yüzey arasındaki ayrışma

Bir UI veya harici çağıran kararlı bir URL'e ihtiyaç duyduğunda bu çerçeveyi kullanın.

Bir component, çalıştığında vertex'inin açtığı endpoint'leri bildirir. input_image_http component'i, image yüklemelerini kabul eden bir ingress endpoint'i bildirir; output_json_http, her tipli değeri JSON olarak yayan bir egress endpoint'i bildirir; bir LLM component'i, üretilen token'ları bir server-sent-events transport'u üzerinden akıtan bir egress endpoint'i bildirir. Her endpoint'in component-local bir adı, bir port'u, bir türü (ingress veya egress) ve onu taşıyan bir veya daha fazla transport'u (HTTP, WebSocket, SSE, WebRTC, multipart) vardır.

Component-local ad, bir çözüm boyunca kararlı değildir. Bir backend'deki vertex 1, başka bir backend'de vertex 7 olabilir. Bir component'in içsel olarak kullandığı endpoint adı, application için hiçbir anlam ifade etmeyebilir. Backend katmanı bunu, ppl backend change-endpoint-alias aracılığıyla (vertex, endpoint-name)'i kararlı bir rol dizesine eşleyerek düzeltir. Application, vertex'lere değil rollere konuşur.

   ┌─────────────────────┐                       ┌────────────────────┐
   │ vertex 1  (ingress) │                       │ application POST'lar    │
   │ "image_input"       │───────────── upload ─▶│ image'i buraya     │
   └─────────────────────┘                       └────────────────────┘

   ┌─────────────────────┐                       ┌────────────────────┐
   │ vertex 3  (egress)  │                       │ application abone olur  │
   │ "output_json_http"  │───────────── events ─▶│ event'lere burada  │
   └─────────────────────┘                       └────────────────────┘

Deployment ayağa kalktığında, her alias için çözülmüş URL'i yayımlar. Application, upload ve events'i deployment'a karşı çözer ve vertex kimliklerinden, component release'lerinden ve runtime yerleştirmesinden ayrı kalır. Alttaki component release'ini değiştirmek, vertex'i yeniden numaralandırmak veya implementasyonu tamamen değiştirmek, alias hala var olduğu sürece application'ı çalışır halde bırakır.

Bu dolaylılık, bir application'ın backend değişikliklerinden sağ çıkmasını sağlayan şeydir: alias sözleşmedir ve arkasındaki vertex bir implementasyon ayrıntısıdır. Bir vertex'e dokunan bir backend mutasyonu, çözdüğü alias yerinde kaldığı sürece UI'ı bozmaz.

Yeniden kullan, değiştir, build et — bu sırayla

Yeni bir çözüm planlarken bu çerçeveyi kullanın.

Önce yeniden kullan. Solutions katalogunu açın ve çözümün ihtiyaç duyduğu sonuca uyan bir yayımlanmış backend arayın. Biri uyuyorsa, onu workspace'e fork edin ve oradan iterasyon yapın — graf montajı zaten yapılmış; geriye kalan parametre ayarı, dosya bağlama ve belki bir application'dır.

Rol doğru ama sağlayıcı değişmeli olduğunda değiştir. Belirli bir rol etrafında wire'lanmış bir backend — bir OCR component'i, bir image classifier'ı veya bir LLM — genellikle o tek vertex'teki component release'ini değiştirerek aynı roldeki farklı bir sağlayıcıya yeniden hedeflenebilir. Tip sistemi bunu yönlendirir: platform, yeni release'e karşı hala type-check olan her parametreyi, dosya bağlamasını ve edge'i korur ve artık olmayan her şeyi düşürür. Neyin tam olarak düşürüleceğini görmek için swap'i önce plan modunda çalıştırın; apply adımı bir şey kaybedilecek olduğunda varsayılan olarak reddeder, böylece bozucu bir swap asla sessizce inmez — commit'ten önce düşmeleri açıkça onaylarsınız.

En son build et. Yalnızca hiçbir katalog girişi çözümün ihtiyaç duyduğu yeteneği kapsamadığında veya mantık genel bir component'in yanlış soyutlama olacağı kadar ürüne özgü olduğunda özel bir component yazın. Katalog kategoriye ve modaliteye göre indexlenir, böylece "ihtiyacım olan şey zaten burada mı" bir arama kadar uzaktadır; build, aramanın ortaya çıkardığı boşlukları doldurur.

Sıra, her hareketin ne kadar iş aldığını yansıtır. Bir backend'i yeniden kullanmak monte edilmiş bir grafı yeniden kullanır; bir component'i değiştirmek bir vertex'i değiştirir; bir component build etmek yazılacak, yayımlanacak ve sabitlenecek yeni kod ekler. Build'den önce yeniden kullanmaya ve değiştirmeye uzanmak, rol izin verdiği sürece bir çözümü kataloğun test edilmiş yüzeyinde tutar.

Harici API'ler nasıl uyar

Çözüm bir model sunucusuna, bir veritabanına, bir webhook'a, bir donanım cihazına veya üçüncü taraf bir hizmete konuşması gerektiğinde bu çerçeveyi kullanın.

Harici API'ler Pipelogic'te özel bir kategori değildir. Tipli input'ları ve output'larıyla normal component'ler olarak görünürler ve kimlik doğrulama, retry, transport ve oran sınırları işlemleri component'in içinde yaşar. Backend grafının bakış açısından, bir barındırılan model API'sine konuşan bir vertex ile yerel bir ONNX modeli çalıştıran bir vertex aynı görünür: tipli giriş, tipli çıkış, bağlanmış parametreler ve secret'ler, container olarak deploy edilmiş.

Bu tekdüzelik, ayrı bir plugin API olmadığı anlamına gelir. Pipelogic'in ayrı bir model-sağlayıcı SDK'sı, veritabanı konnektör çerçevesi veya mesaj-broker entegrasyon katmanı yoktur — her şey bir component'tir, her component aynı sözleşmeye sahiptir ve her çözüm onları aynı şekilde oluşturur. Entegrasyon yazarları sağlayıcı kaydetmek yerine küçük component'ler yazar ve çözüm yazarları, her component'in neye konuştuğundan bağımsız olarak onları tek bir soyutlama aracılığıyla oluşturur.

Referans anlık görüntüsü — katman sınırları

Katman	Sahip	Sahip değil
Component	tipli I/O, kod, parametreler, varsayılanlar, release metadata	içinde çalıştığı backend, herhangi bir vertex'teki bağlamalar
Backend	graf, vertex başına parametre ve dosya bağlamaları, endpoint alias'ları, runtime override'ları	component implementasyonu, runtime, application
Deployment	tek bir backend için canlı runtime, alias başına çözülmüş URL'ler	backend graf tanımı, application UI
Application	UI, driver pin'leri (needs_driver, taps_driver), bir deployment'a karşı alias çözümü	backend grafı, deployment yaşam döngüsü, component kodu
Driver	her backend'in ve application'ın hizalandığı adlandırılmış sözleşme (gerekli endpoint'ler, gerekli worker promise'leri, gerekli fill'ler)	herhangi bir alias'ın arkasındaki implementasyon, runtime'daki transport

Component release'leri değiştirilemezdir. Bir component'in daha yeni bir release'i, daha eski birini sabitleyen bir backend'i rahatsız etmez — yeniden bağlama açık bir backend düzenlemesidir, asla bir promote'un yan etkisi değil.

Bir çözüm ne zaman "tamamlanmış"tır

Grafın var olması ölçü değildir. Bir çözüm, beklenen davranış canlı runtime'da gözlemlenebilir olduğunda tamamlanmıştır: temsili girdiler doğru çıktıları üretir, container log'ları temizdir, üretilen dosyalar olmaları gereken yere iner ve application (varsa) manuel kurtarma olmadan render eder. O gözlem kanıt döngüsüdür ve Davranışı kanıtla içinde anlatılan aynı döngüdür.

Kanıt adımı, bir promote kararının arkasındaki kanıtı sağlayan şeydir. Üretime hazır, grafın monte edildiği değil, o kanıtın var olduğu anlamına gelir.

Bunun yeri

Çözümler, bir bütün olarak sevk edilen ürün için platformun kelime dağarcığıdır. Dört katmanlı ayrım, o ürünü monte edilebilir, değiştirilebilir, yeniden deploy edilebilir ve yeniden kullanılabilir kılan şeydir. Primitive'ler — tipli component'ler, event-sourced backend'ler, ayrılmış deployment'lar, alias'a bağlı application'lar — bu özelliklerin her birine bağlanacak somut bir nesne verir.

İlgili

• Component'ler — yeniden kullanılabilir tipli yapı taşları.
• Backend'ler — tipli graf + bağlamalar.
• Deployment'lar — çalışan backend'ler + alias başına çözülmüş URL'ler.
• Application'lar — alias'ları deployment'lara karşı çözen UI'lar.
• Tipler — tüm katmanlar boyunca uygulanan sözleşme.
• Çözüm yayımlama — bir çözümü herkese açık paylaşma.
• Quickstart — ilk göreviniz için rota seçici.