Build sistemleri

Özet

Her component, component.yml'de build_system: <key> bildirir. Anahtar, küratörlü bir image çifti seçer: kaynağı derleyen bir build image ve onu üretimde çalıştıran bir runtime image. Yaygın durumlar için elle yazılmış Dockerfile yok.
runtime image zaten pipelogic'i artı çekirdek bağımlılıklarını (numpy, opencv, pyyaml, protobuf, pika, C++ ML SDK) içerir. component yazarı yalnızca component'e özgü olanı yazar — requirements.txt'te ek Python paketleri, xmake_packages üzerinden ek C++ paketleri.
ppl component publish, build'i yazarın makinesinde değil, bir uzak build kümesinde çalıştırır. Yerel Docker yok, yerel CUDA sürücüleri yok, yerel toolchain yok. Build ya uzaktan başarılı olur (ve yayımlanabilir bir artifact üretir) ya da uzaktan başarısız olur (her diğer yazarın göreceği aynı hatayla).
component'e özgü her şeyi == ile tam olarak sabitleyin. Sabitlenmemiş bağımlılıklar, kayıt defterinin build günü döndürdüğü her ne ise ona çözülür, böylece dün işe yarayan bir build yarın farklı bir ağaç çözebilir.
Küratörlü anahtarlar, platformun sürdürdüğü bir katalogdur. Yeni yığınlar, yaygın olarak yararlı olduklarında eklenir; tek seferlik ihtiyaçlar xmake_packages veya Dockerfile-base ile karşılanır, custom build katmanı hakkı veren planlarda kullanılabilen tam custom bir Dockerfile (küratörlü bir build_system_base üzerine inşa edilmiş) ile.

Zihinsel model — `build_system` anahtarı tüm build'i sürer

   component.yml                   ppl component publish
   ┌───────────────────────────┐   ┌───────────────────────────────────┐
   │ language: py              │   │ Build aşaması (build_system img)  │
   │ build_system:             │──▶│   pip wheel <requirements.txt>    │
   │   2-cuda12.8-torch2.8-    │   │   xmake xmake_packages'a karşı    │
   │   onnxrtgpu1.22           │   ├───────────────────────────────────┤
   │ requirements.txt:         │   │ Runtime aşaması (build_system img)│
   │   transformers==4.44.2    │   │   wheel kur / binary kopyala      │
   │   huggingface-hub==0.24.6 │   │   image'da zaten pipelogic +      │
                                   │   numpy + opencv + pyyaml + …     │
   └───────────────────────────┘   └───────────────────────────────────┘
                                                     │
                                                     ▼
                                               worker image

Platform, küratörlü image'ların sahibidir, onları güncel tutar ve her anahtarın arkasında çalışan bir sistem kütüphaneleri, dil runtime'ları ve ML framework'leri yığını garanti eder. component yazarı kaynağın ve component başına requirements.txt'in (veya xmake_packages'ın) sahibidir.

Keyfi Dockerfile'lar yerine neden küratörlü build image'ları

build_system anahtarı iki amaca hizmet eder: component oluşturmayı kolaylaştırır — yazar yaygın durum için asla bir Dockerfile yazmaz — ve tüm katalog genelinde image şişkinliğinden kaçınır. Küratörlü bir base bir kez inşa edilir ve yeniden kullanılır; her component farklı bir base kullansaydı, her biri gigabaytlarca yinelenmiş katman gönderirdi.

Boyut boyutu somuttur. Bir GPU yığını — CUDA, cuDNN, PyTorch, ONNX Runtime — herhangi bir component kodu eklenmeden önce birkaç gigabayttır. component'ler bir base'i paylaştığında, o yığın bir kez inşa edilir: kayıt defteri paylaşımlı katmanları tek bir kez depolar ve bir component'i zaten çekmiş bir node onları bir sonraki için önbelleğe alır. Her component farklı bir base seçtiğinde, hiçbir şey paylaşılmaz. Her component, neredeyse aynı sistem kütüphanelerinin kendi çok-gigabaytlık kopyasını gönderir, kayıt defteri hepsini depolar ve her node onu yeniden çeker. Birkaç düzine component'lik bir katalog, çoğunlukla yinelenmiş katmanların yüzlerce gigabaytı haline gelir.

Farklı base'ler problemi başka yollarla da büyütür: farklı CUDA versiyonları sabitlerler ve tek bir güvenlik yaması her Dockerfile'ı elle düzenlemek anlamına gelir.

build_system anahtarlarının küratörlü bir kataloğu her ikisini de ele alır. Her anahtar, platformun zaman çizelgesinde — component başına değil — yamalanmış, test edilmiş bir CUDA versiyonu, framework versiyonu ve destekleyici kütüphaneler kombinasyonunu sabitler ve — anahtar tek bir paylaşımlı base image'a çözüldüğünden — onu seçen her component, onları yinelemek yerine aynı katmanları yeniden kullanır. Yazar bir anahtar seçer; requirements.txt o zaman yalnızca component'e özgü olanı taşır: model loader'ı, transformer versiyonu, image-işleme kütüphanesi. Paylaşımlı katman bir kez, anahtarın arkasında inşa edilir.

Keyfi base image'lar yazmak yerine katalogdan seçmenin karşılığında yazarlar şunları elde eder: ekip üyeleri arasında yeniden üretilebilir build'ler, düzinelerce çatallanmış Dockerfile yerine bir anahtarın arkasına inen güvenlik güncellemeleri, öngörülebilir image boyutları ve CUDA / framework uyumluluk matrisini yazar adına sürdüren bir platform.

İzlenecek yol — bir anahtar seç, bağımlılıkları sabitle, yayımla

# component.yml — GPU yığınında bir Python Component'ilanguage: pybuild_system: 2-cuda12.8-torch2.8-onnxrtgpu1.22worker:  input_type: Image  output_type: "[BoundingBox]"

# requirements.txt — yalnızca tam versiyonlar; pipelogic / numpy / opencv / pyyaml / protobuf / pika'yı ASLA yeniden sabitleme
transformers==4.44.2
huggingface-hub==0.24.6
pillow==11.3.0

# bir version satırı oluşturmadan build'i uzaktan doğrulappl component publish --dry-run# bir prerelease yayımla (build uzak build kümesinde çalışır — yerel Docker yok)ppl component publish -m "add foo support"# prerelease'i yayımlanmış bir versiyona çevir (worker image yayımlar, tag'leri uygular)ppl component promote

ppl component publish, kaynak ağacını + component.yml'yi + kardeş Dockerfile'ları build kümesine yükler; build orada çalışır. Yerel Docker gerekmez.

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

Yaygın Python anahtarları (`language: py`)

`build_system`	runtime'da önyüklü	Şu durumda seç
`2`	Python 3.10, numpy, pipelogic	Saf Python Component, ML bağımlılığı yok.
`2-opencv4.11`	Yukarıdaki + opencv-python-headless 4.11	Image işleme, ML yok.
`2-torch2.8`	Yukarıdaki + torch 2.8 (CPU)	Torch CPU çıkarımı.
`2-torch2.8-vision`	Yukarıdaki + torch 2.8 + torchvision 0.23 (CPU)	Torch + torchvision, CPU.
`2-cuda12.6`	CUDA 12.6 + cuDNN 9 + opencv	Framework'süz CUDA 12.6.
`2-cuda12.6-torch2.8-onnxrtgpu1.22`	CUDA 12.6 + torch (cu126) + onnxruntime-gpu + opencv	CUDA 12.6'da Torch + ONNX GPU.
`2-cuda12.8`	CUDA 12.8 + cuDNN 9 + opencv	Framework'süz CUDA.
`2-cuda12.8-onnxrtgpu1.22`	CUDA + cuDNN 9 + onnxruntime-gpu	GPU'da ONNX çıkarımı.
`2-cuda12.8-torch2.8`	CUDA + torch + torchvision + opencv	Torch GPU çıkarımı.
`2-cuda12.8-torch2.8-onnxrtgpu1.22`	CUDA + torch + onnxruntime-gpu	Karışık Torch + ONNX GPU.
`2-cuda12.8-torch2.8-onnxrtgpu1.22-roboflow`	Yukarıdaki + rfdetr, inference (Roboflow yığını)	Roboflow-yığını Component'ler.
`2-cuda12.8-torch2.8-ultralytics`	Yukarıdaki + ultralytics + torchvision	YOLO / Ultralytics.

Yaygın C++ anahtarları (`language: cpp`)

`build_system`	Ne	Şu durumda seç
`2`	C++ toolchain, ML kütüphanesi yok	Saf C++ yardımcı program Component'i.
`2-ml`	Yukarıdaki + C++ ML SDK + OpenCV + FFmpeg	Image / sinyal / video işi yapan C++ Component'i.
`2-opencv4.11`	C++ toolchain + OpenCV + C++ ML SDK header'ları	OpenCV gerektiren C++ Component'i.

En hafif anahtarı seçme

Daha büyük anahtarlar daha büyük image'lar ve daha uzun çekmeler gönderir. Bir component yalnızca OpenCV'ye ihtiyaç duyuyorsa, tam GPU ML yığını değil, 2-opencv4.11 seçin. Emin olmadığınızda, 2-opencv4.11 (CPU image işi) veya 2-cuda12.8-torch2.8-onnxrtgpu1.22 (GPU ML) ile başlayın.

Bağımlılık sabitlemesi küratörlü katmanla nasıl etkileşir

Bu bölüm, bir pip install adımının runtime image'ın zaten sağladığıyla nasıl bir arada var olduğunu kapsar.

runtime image, pipelogic'i ve çekirdek bağımlılıklarını önyüklü gönderir. Bu küme, anahtara bağlı olarak numpy, opencv-python / opencv-python-headless, pyyaml, protobuf, pika ve bir avuç başkasını içerir. Bunlar sizin yeniden sabitleyeceğiniz şeyler değil. requirements.txt numpy==1.26.4 listelerse, build runtime'ın zaten sahip olduğunun üstüne paralel bir numpy kurar; component başlangıcında Python'un import mekanizması yolda önce hangisi varsa onu çözer ve sonuç ya bir ABI çatışmasıdır (anında çökme) ya da sessiz bir versiyon uyumsuzluğudur (incelikli bug'lar).

Kural şudur: runtime'ın gönderdiği her şeye component dokunmaz. component'in gerçekten ihtiyaç duyduğu ve runtime'ın göndermediği her şeyi, component belirli bir versiyona == ile sabitler. pip install adımı o zaman, çakışma olmadan, mevcut katmanın üstüne tam olarak ek paketleri kurar.

Sabitleme disiplini isteğe bağlı değildir. requirements.txt'te sabitlenmemiş bir transformers, build zamanında PyPI'nin döndürdüğü her ne ise ona çözülür — bugün 4.44.0, gelecek hafta 4.45.0, major bump indiğinde 5.0.0-rc1 — böylece bir build bir günden diğerine farklı bir bağımlılık ağacı çözebilir. Tam == sabitlemesi, build'in ya işe yarayanı yeniden ürettiği ya da "version not found" hatasıyla temizce başarısız olduğu anlamına gelir.

Küratörlü anahtarlar yetmediğinde

Bu bölüm, bir ekibin ihtiyaçları tek bir anahtara uymadığında seçenekleri kapsar.

Kabaca tercih sırasına göre:

xmake_packages (C++). Ekstra kütüphanelere ihtiyaç duyan C++ component'leri için, yeni bir builder'ı zorlamak yerine onları component.yml'de xmake_packages altında bildirin. xmake kayıt defteri çoğu durumu kapsar; basit paketler string girişleri, yapılandırma gerektiren paketler bir require satırlı nesne girişleridir. Build onları alır ve bağlar.

xmake_packages:  - fast_float  - require: arrow 7.0.0    package: arrow    configs:      parquet: true      snappy: true      zstd: true

Sistem paketleri için Dockerfile-base. Ekstra apt paketlerine (bir sistem kütüphanesi, bir font, bir codec, bir araç) ihtiyaç duyan component'ler için, apt-install kancalı bir kardeş Dockerfile-base bırakın. Build önce küratörlü base image'ı çalıştırır, ardından Dockerfile-base'i üstüne katmanlar, ardından pip install'i çalıştırır. Yalnızca sistem paketleri — Python bağımlılıkları, sabitleme disiplininin geçerli olduğu requirements.txt'te kalır.

# Dockerfile-baseRUN apt-get update && apt-get install -y --no-install-recommends \      libsndfile1 \ && rm -rf /var/lib/apt/lists/*

build_system: custom (build_system_base ile eşleştirilmiş). Dockerfile'ına tamamen sahip olması gereken component için — ekstra bir build aşaması, bir derleyici toolchain'i, küratörlü anahtarların kapsamadığı sistem düzeyinde bir build adımı. Hiçten bir build değildir: build_system_base küratörlü bir katalog anahtarını adlandırmalı, custom Dockerfile o base'den FROM ile inşa edilmeli ve pipelogic'i ve çekirdek runtime'ı sağlayan şey base olmalıdır. base bir katalog anahtarı olduğundan, ona doğru referans veren bir Dockerfile, o base yamalandığında platform tarafından yine de migrate edilebilir ve base'in katmanları paylaşımlı kalır. Yazarın maliyeti üstündeki build adımlarının sahibi olmak ve platformun component shim'ini elle bağlamaktır. custom build katmanı hakkı veren planlarda kullanılabilir; bir avuç birinci sınıf component (FFmpeg ve GStreamer alımı, FAISS, RNNoise, Gaussian-splatting) bu şekilde inşa edilir.

Tırmanma merdiveni var olur çünkü her adım operasyonel borç ekler. xmake_packages ucuzdur. Dockerfile-base bir apt katmanı ekler. custom, ekibe kendi Dockerfile'ını verir — yine bir katalog build_system_base'ine bağlı, ancak üstündeki build adımları onların sürdürmesi gerekenlerdir. Doğru yanıt neredeyse her zaman ihtiyacı karşılayan en soldaki seçenektir.

Çalıştır

ppl component builders                 # build_system anahtarlarının canlı kataloğuppl component publish --dry-run        # uzak build doğrulaması, version satırı yokppl component publish -m "<msg>"       # bir prerelease yayımlappl component promote                  # prerelease → yayımlanmış'a çevir

Bunun yeri

Build sistemleri, yazarın yazdığı component kaynağı ile deploy edilmiş bir container'da çalışan image arasındaki platformun küratörlü katmanıdır. O katmanın sahibi platformdur — küratörlü image'lar, desteklenen framework matrisleri, güvenlik güncellemeleri, katman önbellekleri. Yazar component'e özgü kısımları yazar; küratörlü katman altlarındaki her şeyi kapsar.

İlgili

Component'ler — inşa edilen birim.
Install modları — install: node paket kurulumunu deploy zamanına erteler.
Model'ler — build yığınlarını serving service'leri ve model artifact'leriyle eşleştirme.
Yayımlama semantiği — build'in beslediği publish + promote döngüsü.