Dosya şeması

Bir component, ihtiyaç duyduğu büyük artifact'leri gömmez. Bunun yerine onları bildirir ve platform, component başlamadan önce her File'ı node üzerinde sağlar. Bildirim, bir backend'in karşısında bağlandığı sözleşmedir: bir component'in doldurduğu slot'ları, her slot'un kabul ettiği türü ve çözümlenmiş dosyayı çalışma zamanında component'e taşıyan yapılandırma parametresini adlandırır.

Dosya bağımlılıklarını bildirme

Giriş dosyaları worker.file_schema altında bildirilir. Her giriş, adlandırılmış bir slot'tur:

worker:  file_schema:    model:      file_type: "weights"      config_key: "model_path"      is_optional: false      tag: "detector"

Slot anahtarı (burada model), bir backend'in karşısında bağlandığı şeydir — ppl backend add-file --key model. file_type, slot'ta hangi yüklenmiş File'ın izinli olduğunu denetler: tek bir değerdir veya component gerçekten birkaç biçim okuduğunda | ile ayrılmış bir listedir. Tam sözcük dağarcığı Dosya türleri içindedir.

config_key, seçilen File'ın çalışan component'e ulaşma yoludur. Platform bu parametreyi bağlamadan sentezler ve dağıtım zamanında yazar, bu nedenle ayrıca config_schema altında görünmemelidir — onu iki kez bildirmek yinelenen parametre hatasıdır. Değerin ne içerdiği, isteğe bağlı component hedefine bağlıdır: hedef yoksa, File bu component'e yüklenir ve değer /files/model gibi component-yerel bir yoldur; bir hedef ayarlıysa (triton, torchserve, vllm, sglang), File o servise yüklenir ve değer, File'ın görünen adıdır.

Kalan alanlar slot'u ayarlar: is_optional slot'un bağlanmamış kalmasına izin verir, tag bağlama anında bir slot kimliği yüzeye çıkarır ve model-artifact adaylarını daraltır, ve mutable backend dağıtık kalırken bağlamanın değişmesine izin verir.

Bir component'in ürettiği dosyaları bildirme

Bir File yazan component, onu worker.generated_file_schema altında bildirir:

worker:  generated_file_schema:    report:      name: "Evidence report"      file_type: "pdf"      config_key: "report_path"

Çıktı bildirimleri girişlerden daha basittir: name, tek bir file_type ve bir config_key. | liste biçimi burada kabul edilmez — bir çıktı tam olarak bir tür File'dır.

Bir component'in ürettiklerini commit etmek

Bir dosya yazmak, bir dosya üretmekle aynı şey değildir. Deploy sırasında platform, slot'un config_key'ini component'in slot'un dosyalarını yazdığı yazılabilir bir dizine ayarlar; oraya yazılan dosyalar commit edilene kadar kaydedilmez. Bir dosya ancak component onu commit ettiğinde bir workspace File'ı olur ve yalnızca commit edilen dosyalar kaydedilir — bir lease collect ile, --save ile yapılan bir teardown ile ya da operatör için.

Commit için platform config_key'in yanına iki string parametre daha enjekte eder: slot'un bitmiş bir dosyasının commit edildiği URL olan <config_key>_commit_url ve slot'un commit token'ı olan <config_key>_commit_token. İkisi de config_schema içinde bildirilmez. Yukarıdaki report slot'u için bunlar report_path_commit_url ve report_path_commit_token'dır.

Bir commit, dosyanın ham baytlarının commit URL'sine tek bir HTTP POST'udur ve iki header taşır: token'ı taşıyan X-Pipelogic-Ingest-Token ve kaydedilen File'ın alacağı adı taşıyan X-Pipelogic-File-Name — tek bir düz yol öğesi; ayırıcı yok, . veya .. değil, kontrol karakteri yok ve en fazla 255 bayt. İstek bir Content-Length taşımalıdır; chunked bir body 422 ile reddedilir. 202 Accepted, platformun dosyayı kabul ettiği ve kaydedeceği anlamına gelir. 403, token header'ının eksik olduğu ya da bu slot'un <config_key>_commit_token'ı olmadığı; 422 ise ad veya uzunluğun geçersiz olduğu anlamına gelir; ikisi de tekrar denemeyle değişmez. Taşıma hataları ve 5xx yanıtları backoff ile tekrar denemeye değer.

Ne zaman commit edileceği dosyanın ne olduğundan çıkar:

Bir artefaktı tamamlandığında commit edin — asla geçici veya yarım yazılmış bir dosyayı değil.
Component'in snapshot veya index gibi yerinde yeniden yazdığı bir dosya, her yeniden yazımdan sonra tekrar commit edilir. Her commit, en eskisi önce olmak üzere ayrı bir kayıtlı File olur.
Boş (0 bayt) bir dosya geçerli bir artefakttır.
Worker çıkmadan önce her commit dönmüş olmalıdır; çıkışta hâlâ sürmekte olan bir commit kaybolur.

import os, time, urllib.error, urllib.requestfrom pipelogic.worker import configdef commit(key, path):    """Commit the finished file at path to the slot whose config_key is key."""    with open(path, "rb") as f:        body = f.read()    req = urllib.request.Request(str(getattr(config, key + "_commit_url")), data=body, method="POST", headers={        "X-Pipelogic-Ingest-Token": str(getattr(config, key + "_commit_token")),        "X-Pipelogic-File-Name": os.path.basename(path),        "Content-Type": "application/octet-stream",    })    delay = 0.25    for attempt in range(5):        try:            with urllib.request.urlopen(req, timeout=60):                return        except urllib.error.HTTPError as e:            if e.code < 500:                raise RuntimeError(f"commit of {path} refused: HTTP {e.code}") from e        except urllib.error.URLError:            pass        time.sleep(delay)        delay *= 2    raise RuntimeError(f"commit of {path} failed after retries")

C++'ta yayınlanmış Output JSONL File component'i libcurl ile commit eder; file egress pattern'i yazdığı her dosyayı commit eden bir C++ sink'i gösterir.

İlgili

Dosya türleri — bir slot'un bildirebileceği her file_type değeri.
Bundle yapı sözdizimi — dizin yerleşimi için bundle{…} yapıları.
Dosya bağlama — bir File yükleyin ve onu bu slot'lardan birine bağlayın.
component.yml — bu şemanın parçası olduğu tam sözleşme.
Modeller — model-artifact slot'ları ve onları yükleyen runtime.