Dateischema

Eine Komponente bettet die großen Artefakte, die sie benötigt, nicht ein. Stattdessen deklariert sie diese, und die Plattform stellt jedes File auf dem Node bereit, bevor die Komponente startet. Die Deklaration ist der Vertrag, gegen den ein Backend bindet: sie benennt die Slots, die eine Komponente füllt, den Typ, den jeder Slot akzeptiert, und den Konfigurationsparameter, der die aufgelöste Datei zur Laufzeit in die Komponente trägt.

Datei-Abhängigkeiten deklarieren

Eingabedateien werden unter worker.file_schema deklariert. Jeder Eintrag ist ein benannter Slot:

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

Der Slot-Schlüssel (model hier) ist das, wogegen ein Backend bindet — ppl backend add-file --key model. file_type steuert, welches hochgeladene File im Slot zulässig ist: es ist ein Wert oder eine |-getrennte Liste, wenn die Komponente tatsächlich mehrere Formate liest. Das vollständige Vokabular findet sich unter Dateitypen.

config_key ist der Weg, auf dem das gewählte File die laufende Komponente erreicht. Die Plattform synthetisiert diesen Parameter aus der Bindung und schreibt ihn zur Deploy-Zeit, daher darf er nicht zusätzlich unter config_schema erscheinen — ihn zweimal zu deklarieren ist ein Fehler wegen doppeltem Parameter. Was der Wert enthält, hängt vom optionalen component-Ziel ab: ohne Ziel wird das File in diese Komponente geladen und der Wert ist ein komponentenlokaler Pfad wie /files/model; mit gesetztem Ziel (triton, torchserve, vllm, sglang) wird das File in diesen Service geladen und der Wert ist der Anzeigename des Files.

Die übrigen Felder justieren den Slot: is_optional erlaubt es dem Slot, ungebunden zu bleiben, tag zeigt eine Slot-ID beim Binden an und grenzt Modellartefakt-Kandidaten ein, und mutable erlaubt es der Bindung, sich zu ändern, während das Backend deployt bleibt.

Files deklarieren, die eine Komponente erzeugt

Eine Komponente, die ein File schreibt, deklariert es unter worker.generated_file_schema:

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

Ausgabe-Deklarationen sind einfacher als Eingaben: name, ein einzelner file_type und ein config_key. Die |-Listenform wird hier nicht akzeptiert — eine Ausgabe ist genau eine Art von File.

Was eine Komponente erzeugt, committen

Eine Datei zu schreiben ist nicht dasselbe, wie eine zu erzeugen. Beim Deploy setzt die Plattform den config_key des Slots auf ein beschreibbares Verzeichnis, in das die Komponente die Dateien des Slots schreibt; dort geschriebene Dateien werden erst gespeichert, wenn sie committet sind. Eine Datei wird erst zu einem Workspace-File, wenn die Komponente sie committet, und nur committete Dateien werden überhaupt gespeichert — durch ein Lease-Collect, durch einen Teardown mit --save oder für den Betreiber.

Für den Commit injiziert die Plattform neben config_key zwei weitere String-Parameter: <config_key>_commit_url, die URL, an die eine fertige Datei des Slots committet wird, und <config_key>_commit_token, das Commit-Token des Slots. Keiner von beiden wird in config_schema deklariert. Für den Slot report oben heißen sie report_path_commit_url und report_path_commit_token.

Ein Commit ist ein einzelner HTTP-POST der Rohbytes der Datei an die Commit-URL mit zwei Headern: X-Pipelogic-Ingest-Token mit dem Token und X-Pipelogic-File-Name mit dem Namen, den das gespeicherte File erhält — genau ein Pfadelement, ohne Trennzeichen, nicht . oder .., ohne Steuerzeichen und höchstens 255 Bytes lang. Die Anfrage muss eine Content-Length tragen; ein chunked Body wird mit 422 abgelehnt. Ein 202 Accepted bedeutet, dass die Plattform die Datei angenommen hat und sie speichern wird. Ein 403 bedeutet, dass der Token-Header fehlt oder nicht das <config_key>_commit_token dieses Slots ist, und ein 422, dass Name oder Länge ungültig sind; beides ändert sich durch Wiederholen nicht. Transportfehler und 5xx-Antworten lohnen eine Wiederholung mit Backoff.

Wann committet wird, folgt aus der Art der Datei:

Committe ein Artefakt, sobald es vollständig ist — nie eine temporäre oder halb geschriebene Datei.
Eine Datei, die die Komponente an Ort und Stelle neu schreibt, etwa ein Snapshot oder ein Index, wird nach jedem Neuschreiben erneut committet. Jeder Commit wird zu einem eigenen gespeicherten File, älteste zuerst.
Eine leere Datei (0 Bytes) ist ein gültiges Artefakt.
Jeder Commit muss zurückgekehrt sein, bevor der Worker endet; ein beim Beenden noch laufender Commit geht verloren.

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")

In C++ committet die veröffentlichte Komponente Output JSONL File mit libcurl; das File-Egress-Pattern zeigt einen C++-Sink, der jede geschriebene Datei committet.

Verwandt

Dateitypen — jeder file_type-Wert, den ein Slot deklarieren kann.
Bundle-Struktursyntax — bundle{…}-Strukturen für Verzeichnis-Layouts.
Datei-Bindung — ein File hochladen und an einen dieser Slots binden.
component.yml — der vollständige Vertrag, zu dem dieses Schema gehört.
Modelle — Modellartefakt-Slots und die Runtime, die sie lädt.