Install modları

Özet

Install modları, bir component'in requirements.txt bağımlılıklarının ne zaman kurulacağına karar verir: publish zamanında, image'a gömülü olarak veya deploy zamanında, container başladığında node üzerinde kurulu olarak. component.yml'deki isteğe bağlı bir anahtar modu seçer — build-zamanı kurulum için atlayın, deploy-zamanı kurulum için install: node ayarlayın.
Build-zamanı kurulum her bağımlılığı yayımlanmış image'a gömer. Deploy'lar saf image çekmeleridir, bu yüzden hızlı ve öngörülebilirdir, ama image bağımlılık kümesiyle büyür — ML yığınları için önemli ölçüde — ve kurulum adımı yüzünden publish daha uzun sürer.
install: node, kaynağı ve requirements.txt'i taşıyan ama kurulu bağımlılığı olmayan bir iskelet image yayımlar. Taze bir node'daki ilk deploy kurulumu o node üzerinde çalıştırır; aynı-node yeniden deploy'ları önbelleğe alınmış kurulumu yeniden kullanır.
İki mod aynı toplam kurulum işini yapar ve yalnızca hangi yaşam döngüsü aşamasının onu ödediği konusunda farklılaşır, bu yüzden seçim deploy hızı, image boyutu ve iterasyon süresi hakkında bir ödünleşmedir.
install: node'u kaldırmak bir mod değişikliğidir, bir temizlik değil. Kurulum maliyetini publish'e geri taşır, image'ı büyütür ve deploy davranışını değiştirir, bu yüzden alanı çevirmeden önce yeni modun iş yüküne uyduğunu doğrulayın.

Zihinsel model — kurulum nereye iner

   Build-zamanı kurulum (varsayılan; install: atlanmış)
   ┌────────────────────────────────────────────────────────────┐
   │ ppl component publish                                      │
   │   build_system image + pip install requirements.txt        │
   │     ─▶ ŞİŞMAN image (ML için çok-GB)                       │
   │                ─▶ registry                                 │
   │                                                            │
   │ ppl backend deploy                                         │
   │   her Node:  ŞİŞMAN image'ı çek  ▶  container başlat        │
   └────────────────────────────────────────────────────────────┘

   install: node
   ┌────────────────────────────────────────────────────────────┐
   │ ppl component publish                                      │
   │   build_system image + Component kaynağı + requirements.txt│
   │     ─▶ İSKELET image (bağımlılık kurulmamış)              │
   │                ─▶ registry                                 │
   │                                                            │
   │ ppl backend deploy                                         │
   │   her Node:                                               │
   │     iskeleti çek  ▶  bağımlılıkları yerel kur              │
   │     (iskelet üzerine katmanlı)  ▶  container başlat        │
   └────────────────────────────────────────────────────────────┘

Toplam kurulum işi aynıdır. Seçim, yaşam döngüsünün hangi aşamasının onu ödediğidir.

İki mod neden var

Build-zamanı kurulum varsayılandır çünkü saf bir image çekmesi hızlı ve öngörülebilirdir. node'a bilinen bir bit kümesi indirir ve container'ı başlatır, deploy zamanında PyPI bağımlılığı, çözünürlük sürprizleri ve node başına kurulum değişkenliği olmadan. O öngörülebilirlik, üretim deployment'larına ve birçok taze node'a inen herhangi bir iş yüküne uygundur.

Maliyet image boyutudur. PyTorch, CUDA, transformers, torchvision ve bir avuç opencv ekstrasına sahip bir ML yığını, çok-gigabaytlık bir image'a gömülür. component'in her yayımlanmış versiyonu o image'ı taşır ve component'i çalıştıran her node onu çeker. ML-ağırlıklı component'ler için image boyutu baskındır: çekmeler dakikalar sürer, registry depolama her versiyonla büyür ve publish-iterasyon döngüsü her değişiklik gömmeyi yeniden çalıştırdığı için yavaşlar.

install: node, image-boyutu maliyetinin deploy-zamanı kurulum maliyetinden ağır bastığı iş yüklerine uyar. Yayımlanmış image bir iskelettir — runtime base, component kaynağı ve requirements.txt, kurulu bağımlılık olmadan. Taze bir node'daki ilk deploy o node üzerinde, iskeletin üstüne katmanlanmış şekilde pip install çalıştırır; aynı node'daki sonraki deploy'lar önbelleğe alınmış kurulumu yeniden kullanır ve neredeyse anında başlar.

install: node, bağımlılık kümesi büyük olduğunda, aynı node'lar birçok deploy boyunca yeniden kullanıldığında ve publish döngüsünün iterasyon hızı önemli olduğunda kendini öder. Büyük bir ML component'i üzerinde iterasyon yapan bir yazar, hızlı yayımlanan ve kurulum maliyetini yalnızca node başına ilk deploy'da ödeyen çok daha küçük bir iskelet image kazanır. Tersi durum — küçük bir bağımlılık kümesi, geçici node'lar, seyrek deploy'lar — fayda sağlamaz, çünkü deploy-zamanı kurulum mekanizması gömmenin maliyetinden daha pahalıdır.

CUDA wheel varyantı build sisteminin işidir, install modunun değil

Bir component CUDA-, CPU-özellik- veya mimari-özel bağımlılıklar çektiğinde bunu okuyun.

Bazı Python wheel'leri donanım arasında taşınabilir değildir. torch+cu126, torch+cu128'den farklı bir wheel'dir, AVX-512'li OpenCV genel CPU build'inden farklı bir binary'dir ve bitsandbytes CUDA-versiyonu başına wheel'ler gönderir. Bir component'in aldığı wheel, install modu tarafından değil, build_system anahtarı tarafından belirlenir: her CUDA-aromalı build sistemi kendi yığınını (CUDA 12.6 yığınında torch+cu126, CUDA 12.8 yığınında torch+cu128) ve kendi paket-index URL'lerini sabitler. O aynı sabitlenmiş template, deploy-zamanı node kurulumunun yeniden kullandığı şeydir.

install: node, node'un GPU sınıfını, CPU özelliklerini veya CUDA versiyonunu incelemez ve indiği donanım için bir wheel'i otomatik seçmez. Deploy-zamanı node build'i yalnızca iskelet image'ı ve build sisteminin sabit install-template'ini alır; build-zamanı yolunun çözeceği aynı wheel'leri çözer. Belirli bir CUDA versiyonunu hedeflemek için eşleşen build_system'i seçin — install modunu değiştirmek hangi wheel'in kurulacağını değiştirmez.

İzlenecek yol — modu çevir

# component.yml (build-zamanı kurulum — varsayılan)name: "..."language: pybuild_system: 2-cuda12.8-torch2.8-onnxrtgpu1.22# component.yml (Node üzerinde deploy-zamanı kurulum)name: "..."language: pybuild_system: 2-cuda12.8-torch2.8-onnxrtgpu1.22install: node

ppl component publish -m "<msg>"ppl component promote

install: serbest-biçimli bir string'tir. Yalnızca node kurulumu deploy zamanına erteler; alanı atlamak — veya başka herhangi bir değer — build-zamanı gömmeyi kullanır. Özel bir install: build literal'i yoktur. node dışındaki bir değer hâlâ build zamanında gömer, ama daha yüksek bir build katmanı gerektirir (platform stok builder'ın üstüne ekstra bir kurulum adımı katmanlar) ve yalnızca o katmanı hak eden planlarda kabul edilir.

Varyasyonlar — hangi modun seçileceği

install: node'u şu durumda seçin:

Bağımlılık kümesi, gömülü image boyutunun çekme süresi ve registry depolamada baskın olacağı kadar büyük. Gömmek israftır.
İterasyon hızı deploy hızından daha önemli. Geliştirme sırasında daha hızlı publish döngüsü — küçük bir iskelet hızlı yayımlanır ve kurulum yalnızca node başına ilk deploy'da çalışır.

Varsayılanı (build-zamanı kurulum) şu durumda seçin:

Bağımlılık kümesi küçük. Deploy-zamanı kurulum mekanizması gömmekten daha pahalıdır.
Deploy'lar birçok taze Node'a iner. İlk-dokunuş kurulumu baskın olurdu.
Her deploy garantili-hızlı bir çekme olmalı — deploy zamanında PyPI bağımlılığı yok.

CUDA wheel varyantı (torch+cu126 vs torch+cu128, vb.) install modu tarafından değil, build_system anahtarı tarafından ayarlanır; install: node, Node'un donanımı için bir wheel'i otomatik seçmez. Hedeflediğiniz CUDA versiyonu için eşleşen build_system'i seçin.

Dockerfile-base'i install: node ile karıştırmak işe yarar, ama Dockerfile-base publish zamanında çalışırken kurulum deploy zamanında çalışır. Buna göre sıralayın.

Referans anlık görüntüsü

YAML alanı

install: node    # VEYA build-zamanı kurulum için tamamen atla

Modu algıla

grep '^install:' component.yml

Satır mevcut ve install: node okuyor → Node üzerinde deploy-zamanı kurulum.
Satır yok, yorumlanmış veya node dışında herhangi bir değer → build-zamanı kurulum (bağımlılıklar yayımlanmış image'a gömülü).

Image-boyutu ipucu

İskelet image (install: node): runtime base'i artı kaynak, kurulu bağımlılık olmadan.
Build-zamanı-kurulmuş image: aynısı, artı tüm bağımlılık kümesi gömülü — bir ML yığını için önemli ölçüde daha büyük.

Yaygın hatalar

Hata	Neden yanlış
"Deploy yavaş — `install: node`'u bırakayım."	Tersi. Onu kaldırmak `publish`'i yavaşlatır ve image'ı şişirir; toplam iş değişmez.
Küçük bir component'e `install: node` eklemek.	Deploy-zamanı kurulum mekanizması küçük bir bağımlılık kümesini gömmekten daha pahalıdır.
`requirements.txt`'i düzenleyip canlı bir deployment'ta yerinde yeniden kurulum beklemek.	Hiçbir mod çalışan bir deployment'a karşı yeniden kurmaz; yeni bir versiyon yayımlamanız ve yeniden deploy etmeniz gerekir.

Bunun yeri

Install modları, build-deploy yaşam döngüsünün neresinde bağımlılık kurulumunun ineceğine karar verir. Doğru yanıt iş yüküne bağlıdır: image-gömme maliyeti vs deploy-zamanı kurulum maliyeti, iterasyon hızı vs üretim güvenilirliği, registry depolama vs ilk-deploy gecikmesi. Platform, her component'i tek bir tasarıma zorlamak yerine, makul bir varsayılan ve belirtilmiş ödünleşmelerle seçimi component yazarına bırakır. build_system anahtarı bu seçimin yanında durur — kuratörlü base image'ı seçer ve bağımlılık yığınını (CUDA wheel varyantı dahil) kurulumun ne zaman çalıştığından bağımsız olarak sabitler (Build sistemleri'ne bakın).

Disiplin, varsayılanı kopyalamak yerine iş yüküne uyan modu seçmektir. install: node, büyük bir bağımlılık kümesine sahip iterasyon-ağırlıklı bir ML component'ine uyar; build-zamanı kurulum, mütevazı bir bağımlılık kümesine sahip küçük bir yardımcı program component'ine uyar. Yanlış seçim, ekibin daha sonra deploy hızında, image boyutunda veya iterasyon süresinde ödediği bir maliyet üretir.

İlgili

Build sistemleri — build_system: küratörlü yığını install:'ten bağımsız seçer.
Component'ler — requirements.txt / xmake_packages'ın yazıldığı yer.
Deployment'lar — bir install: node deploy'u taze bir node'a indiğinde neyin değiştiği.
Yayımlama semantiği — kurulumun içinde çalıştığı publish + promote döngüsü.