Bileşen sözleşmesi

TL;DR

Her component, kaynağının yanında bir component.yml ile sevk edilir.
Dosya şunları bildirir: dil, build sistemi, tipli girişler ve çıkışlar, yapılandırma parametreleri, dosya bağımlılıkları, isteğe bağlı HTTP uç noktaları.
Her şey aşağı akışta — tip denetleyici, app builder, deploy'lar, agent kataloğu — bu dosyayı okur. Doğru yap, ve platformun geri kalanı component'ini ücretsiz doğrular.
Okuduğun sayfa zihinsel modeldir. Her flag ve uç durumla birlikte alan-alan şema için referansı CLI'dan al: ppl docs get component-api/component-contract.

`component.yml` aslında nedir

Dosya, component yazarı ile platformun geri kalanı arasındaki sözleşmedir. component'in tek otoriter tanımıdır: girişlerinde neyi kabul ettiği, çıkışlarında neyi emit ettiği, neyle yapılandırılabileceği, deploy zamanında neye ihtiyaç duyduğu. Diğer component'ler, görsel builder ve agent kataloğu hepsi aynı dosyayı okur — ayrı bir kayıt adımı yoktur.

Üst seviye biçimi

Tam bir component.yml altı kategori metadata'yı kapsar. Neredeyse hiçbir zaman hepsini kullanmazsın.

Category	Lives under	Purpose
Kimlik	`name`, `language`, `platform`, `tags`	Görünen ad, kaynak dil, hedef mimari, katalog etiketleri.
Build	`build_system`, `install`, `xmake_packages`	Container'ın karşı derlediği kürate edilmiş image çifti; derleme- vs. deploy-zamanı kurulumu.
Discovery	`categories`, `modalities`, `neighbors`, `alternatives`	Kataloğun component'i öne çıkarmak ve kardeşler önermek için kullandığı ipuçları.
Tip sözleşmesi	`worker.input_type` / `output_type` (veya çoğul)	Her bağlantıyı koruyan Pipelang tip ifadeleri.
Çalışma zamanı parametreleri	`worker.config_schema`	Operatörün deploy zamanında ayarladığı düğmeler; parametre başına bir giriş.
Dosya ve model bağımlılıkları	`worker.file_schema`, `worker.cache`	Platformun node'da sağladığı dosyalar; deploy'ları aşan model cache'leri.
HTTP uç noktaları	`http`	İsteğe bağlı. HTTP, WebSocket, SSE veya WebRTC üzerinden ingress/egress bildirir.

En küçük geçerli dosya kimlik + build + tek satırlık bir worker: bloğudur:

name: "Echo"language: pyplatform: linux/amd64build_system: 2worker:  input_type: "String"  output_type: "String"

Oradan, component büyüdükçe onu büyütürsün: parametrelere ihtiyaç duyduğunda config_schema ekle, diskte bir modele ihtiyaç duyduğunda file_schema ekle, component dış dünya için bir ingress veya egress olduğunda http: ekle.

Tip ifadeleri kısaca

input_type / output_type bir Pipelang tip ifadesi taşır. En sık kullanacağın formlar:

Atomik — "Int32", "Double", "String", "Bool", "Bytes", …
Adlandırılmış — "Image", "AudioFrame", "Tensor", "BoundingBox", …
Liste — "[BoundingBox]".
Tuple — "(Image, String)".
Record — "{x: Double, y: Double}".
Union — "Image | DepthImage".
Generic — "Polygon<Double>".

Küçük harf identifier'lar (t, frame) tip değişkenleridir; büyük harf identifier'lar somut tiplerdir. Tam dilbilgisi için — ayrıştırma kuralları, pack genişletmeleri, isteğe bağlı alanlar — bkz. /type-api/type-syntax. Kayıtlı adlandırılmış tiplerin kataloğu için bkz. /type-api/catalog.

Yapılandırma parametreleri

worker.config_schema, bir operatörün deploy zamanında ayarladığı düğmeleri bildirir — parametre başına bir giriş:

worker:  config_schema:    confidence_threshold:      type: Double      default: 0.5    color_model:      type: String<"BGR" | "RGB">      default: "BGR"    api_token:      type: Maybe<String>      secret: true

Her parametre bir type (herhangi bir tip ifadesi), isteğe bağlı bir default ve üç isteğe bağlı flag taşır:

mutable — true değerin çalışan bir deployment üzerinde değişmesine izin verir; varsayılan false onu deploy sırasında kilitler.
secret — true değeri bir workspace-secret referansı yapar, böylece ham değer asla grafikte yer almaz. Yalnızca String, Maybe<String> ve [String] secret olabilir.
description — parametreyi tanımlayan serbest metin.

Bir parametrenin type'ı daraltılabilir — platformun zorladığı bir yüklem tarafından daraltılır. String<"BGR" | "RGB"> yalnızca o iki string'i kabul eder; Int32<0..=255> bir aralığı sınırlar; Int64<%8> sekizin katını gerektirir; String<email> bir biçimi kontrol eder. Daraltılmış bir değer kısıtın dışına düşerse change-parameter'da reddedilir, böylece component onu yeniden doğrulamak zorunda kalmaz — type: String artı elle yazılmış bir izin verilen değer listesine bir String<…> enum'unu tercih et. Değerler yerine tüm tiplerin kapalı bir kümesi için oneof[T1, T2] kullan. Tam küme için bkz. /type-api/type-syntax.

Burada file_schema'dan bir config_key'yi yeniden bildirme — platform o parametreyi dosya bağlamasından sentezler ve onu kopyalamak doğrulamada başarısız olur.

Dosya ve model bağımlılıkları

worker.file_schema, platformun component çalışmadan önce node'da sağladığı File'ları bildirir — her slot bir file_type, bir config_key ve isteğe bağlı bir component hedefini sabitler. config_key yinelenen-parametre kuralı ve component hedef davranışı dahil tam slot referansı File schema'dedir; kabul edilen file_type değerleri file type kataloğu'ndadır.

Üretilen dosyalar

worker.generated_file_schema, bir component'in çalışma zamanında ürettiği File'ları bildirir, her biri bir name, tek bir file_type ve platformun yazılacak yolla doldurduğu bir config_key ile. Üretilen dosya, çalıştırmadan sonra aşağı akış tüketicilerine ve operatöre erişilebilir hale gelir. Bkz. File schema.

Model ve artefakt cache'leme

cache, büyük model artefaktlarını deploy'lar arasında node'da tutar, böylece özdeş girişler yeniden indirmek yerine bir pull'u yeniden kullanır. Her cache, adlandırılmış bir kurallar listesidir:

worker:  cache:    capybara:      - ids: model_cfg            # config keys whose values seed the cache lookup        revision: model_revision  # optional — config key holding the artifact revision        when:                     # optional — only cache when these config values match          backend: gpu        allow_local_paths: false  # optional — allow paths outside the managed cache dir

Cache anahtarı ids config anahtarlarının değerlerinden artı isteğe bağlı revision'dan türetilir: farklı config değerleri farklı cache girişlerine çözülür, böylece bir model adını veya revizyonu değiştirmek yeni pull yapar, eski giriş ise sıcak kalır. when cache'lemeyi config'i eşleşen deployment'larla sınırlar (örneğin yalnızca backend: gpu olduğunda cache'le) ve allow_local_paths yönetilen cache dizini dışında yaşayan artefaktları etkinleştirir. Bu, HuggingFace, docaligner ve benzeri model yükleyicilerin arkasındaki mekanizmadır.

HTTP ve WebSocket uç noktaları

Dış dünyayla konuşan bir component http uç noktaları bildirir. Platform TLS'i, auth'u ve genel URL'i yönetir — component yalnızca bildirilen portu dinler:

http:  image-input:    port: 9000    kind: ingress              # ingress | egress    transports: [http, ws]     # subset of http | ws | sse | webrtc | multipart    media: [video, audio]      # media kinds the endpoint carries    format: binary             # binary | json | text    config_param: transport    # a config key picks the active protocol at runtime    config_param_map:      http: [http]      websocket: [ws]      both: [http, ws]

Sabit tek-protokollü bir uç nokta için tekil transport: / method: alanlarını kullan; operatörün protokolü deploy zamanında seçtiği durumlarda çoğul transports:'ı config_param ve config_param_map ile kullan. Uç nokta adı (image-input), ppl backend forward'un hedeflediği şeydir.

Derleme ortamı

build_system, container'ın karşı derlediği kürate edilmiş derleme-ve-çalışma-zamanı image'ını seçer — registry'yi ppl component builders ile listele (build_system_base yalnızca build_system: custom için gereklidir). install, bağımlılıkların ne zaman kurulacağını seçer: node, requirements.txt kurulumunu her node'da deploy zamanına erteler, başka her şey derleme zamanında kurar. xmake_packages C++ requires ekler ve depends_on component'in çalışma zamanında ihtiyaç duyduğu kardeş component slug'larını listeler.

Bunun yeri

component.yml, yazdığın kod ile onu çalıştıran platform arasındaki sözleşme katmanıdır. Compile zamanında (doğrulama, tip denetimi), release zamanında (katalog girişi, şema introspeksiyonu) ve deploy zamanında (parametre bağlama, dosya sağlama) okunur. Biçimi bir kez doğru yap; sözleşme değişene kadar bir daha asla dokunma.

Tam şema için

Website modeli kapsar. Her alanın, her varsayılanın, her uç durumun, her doğrulama kuralının, kategoriye göre her örneğin ve doğrulama hata modlarının tablosu için referansı CLI'dan al:

ppl docs get component-api/component-contract

İlgili

/concepts/components — bir platform primitifi olarak component.
/type-api/type-syntax — input_type / output_type için tam dilbilgisi.
/type-api/catalog — yerleşik adlandırılmış tiplerin kataloğu.
/file-api/file-types — geçerli file_type slot'ları.
/concepts/build-systems — build_system registry'si.
/concepts/install-modes — install: node vs. derleme-zamanı kurulumu.