Komponenten-Kontrakt

TL;DR

Jede component wird mit einer component.yml neben ihrem Quellcode ausgeliefert.
Die Datei deklariert: Sprache, Build-System, typisierte Ein- und Ausgaben, Konfigurationsparameter, Datei-Abhängigkeiten, optionale HTTP-Endpunkte.
Alles Nachgelagerte — Typprüfer, App-Builder, Deploys, Agent-Katalog — liest diese Datei. Mach sie richtig, und der Rest der Plattform validiert deine component kostenlos.
Die Seite, die du gerade liest, ist das mentale Modell. Für das Feld-für-Feld-Schema mit jedem Flag und Sonderfall hole die Referenz aus der CLI: ppl docs get component-api/component-contract.

Was `component.yml` eigentlich ist

Die Datei ist der Kontrakt zwischen dem component-Autor und dem Rest der Plattform. Sie ist die einzige autoritative Beschreibung der component: was sie auf ihren Eingängen akzeptiert, was sie auf ihren Ausgängen emittiert, womit sie konfiguriert werden kann, was sie zur Deploy-Zeit benötigt. Andere components, der visuelle Builder und der Agent-Katalog lesen alle dieselbe Datei — es gibt keinen separaten Registrierungsschritt.

Form der obersten Ebene

Eine vollständige component.yml deckt sechs Kategorien von Metadaten ab. Du verwendest fast nie alle davon.

Category	Lives under	Purpose
Identität	`name`, `language`, `platform`, `tags`	Anzeigename, Quellsprache, Zielarchitektur, Katalog-Labels.
Build	`build_system`, `install`, `xmake_packages`	Kuratiertes Image-Paar, gegen das der Container baut; Build- vs. Deploy-Zeit-Installation.
Discovery	`categories`, `modalities`, `neighbors`, `alternatives`	Hinweise, die der Katalog nutzt, um die component hervorzuheben und Geschwister vorzuschlagen.
Typ-Kontrakt	`worker.input_type` / `output_type` (oder Plural)	Pipelang-Typausdrücke, die jede Verdrahtung absichern.
Laufzeitparameter	`worker.config_schema`	Stellschrauben, die der Operator zur Deploy-Zeit setzt; ein Eintrag pro Parameter.
Datei- und Modell-Abhängigkeiten	`worker.file_schema`, `worker.cache`	Dateien, die die Plattform auf dem Node bereitstellt; Modell-Caches, die Deploys überdauern.
HTTP-Endpunkte	`http`	Optional. Deklariert Ingress/Egress über HTTP, WebSocket, SSE oder WebRTC.

Die kleinste zulässige Datei ist Identität + Build + ein einzeiliger worker:-Block:

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

Von dort lässt du sie wachsen, während die component wächst: füge config_schema hinzu, wenn du Parameter brauchst, füge file_schema hinzu, wenn du ein Modell auf der Platte brauchst, füge http: hinzu, wenn die component ein Ingress oder Egress für die Außenwelt ist.

Typausdrücke in Kürze

input_type / output_type tragen einen Pipelang-Typausdruck. Die Formen, die du am häufigsten verwenden wirst:

Atomar — "Int32", "Double", "String", "Bool", "Bytes", …
Benannt — "Image", "AudioFrame", "Tensor", "BoundingBox", …
Liste — "[BoundingBox]".
Tupel — "(Image, String)".
Record — "{x: Double, y: Double}".
Union — "Image | DepthImage".
Generisch — "Polygon<Double>".

Identifier mit Kleinbuchstaben (t, frame) sind Typvariablen; Identifier mit Großbuchstaben sind konkrete Typen. Für die vollständige Grammatik — Disambiguierungsregeln, Pack-Expansionen, optionale Felder — siehe /type-api/type-syntax. Für den Katalog der registrierten benannten Typen siehe /type-api/catalog.

Konfigurationsparameter

worker.config_schema deklariert die Stellschrauben, die ein Operator zur Deploy-Zeit setzt — ein Eintrag pro Parameter:

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

Jeder Parameter trägt einen type (jeder Typausdruck), einen optionalen default und drei optionale Flags:

mutable — true lässt den Wert auf einem laufenden deployment ändern; der Standard false sperrt ihn beim Deploy.
secret — true macht den Wert zu einer Workspace-Secret-Referenz, sodass der Rohwert nie im Graphen landet. Nur String, Maybe<String> und [String] können secret sein.
description — Freitext, der den Parameter beschreibt.

Der type eines Parameters kann verfeinert werden — durch ein Prädikat eingegrenzt, das die Plattform erzwingt. String<"BGR" | "RGB"> akzeptiert nur diese beiden Strings; Int32<0..=255> begrenzt einen Bereich; Int64<%8> erfordert ein Vielfaches von acht; String<email> prüft ein Format. Ein verfeinerter Wert wird bei change-parameter abgelehnt, wenn er außerhalb der Bedingung fällt, sodass die component ihn nicht neu validieren muss — bevorzuge ein String<…>-Enum gegenüber type: String plus einer handgeschriebenen Liste erlaubter Werte. Für eine geschlossene Menge ganzer Typen statt Werte verwende oneof[T1, T2]. Siehe /type-api/type-syntax für die vollständige Menge.

Deklariere hier keinen config_key aus file_schema erneut — die Plattform synthetisiert diesen Parameter aus der Datei-Bindung, und Duplizieren schlägt bei der Validierung fehl.

Datei- und Modell-Abhängigkeiten

worker.file_schema deklariert die Files, die die Plattform auf dem Node bereitstellt, bevor die component läuft — jeder Slot fixiert einen file_type, einen config_key und ein optionales component-Ziel. Die vollständige Slot-Referenz, einschließlich der config_key-Duplicate-Parameter-Regel und des component-Zielverhaltens, steht in File schema; die akzeptierten file_type-Werte stehen im File-Type-Katalog.

Erzeugte Dateien

worker.generated_file_schema deklariert die Files, die eine component zur Laufzeit erzeugt, jeweils mit einem name, einem einzelnen file_type und einem config_key, den die Plattform mit dem Pfad füllt, in den geschrieben werden soll. Die erzeugte Datei wird nachgelagerten Konsumenten und dem Operator nach dem Lauf verfügbar. Siehe File schema.

Modell- und Artefakt-Caching

cache hält große Modell-Artefakte über Deploys hinweg auf dem Node, sodass identische Eingaben einen Pull wiederverwenden, statt erneut herunterzuladen. Jeder Cache ist eine benannte Liste von Regeln:

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

Der Cache-Key wird aus den Werten der ids-config-Keys plus der optionalen revision abgeleitet: unterschiedliche config-Werte lösen sich zu unterschiedlichen Cache-Einträgen auf, sodass das Austauschen eines Modellnamens oder einer Revision frisch pullt, während der alte Eintrag warm bleibt. when beschränkt das Cachen auf Deployments, deren config übereinstimmt (zum Beispiel nur cachen, wenn backend: gpu), und allow_local_paths aktiviert Artefakte, die außerhalb des verwalteten Cache-Verzeichnisses leben. Dies ist der Mechanismus hinter HuggingFace, docaligner und ähnlichen Modell-Loadern.

HTTP- und WebSocket-Endpunkte

Eine component, die mit der Außenwelt spricht, deklariert http-Endpunkte. Die Plattform übernimmt TLS, Auth und die öffentliche URL — die component lauscht nur auf dem deklarierten Port:

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]

Verwende die Singular-Felder transport: / method: für einen festen Single-Protocol-Endpunkt; verwende die Plural-Felder transports: mit config_param und config_param_map, wenn der Operator das Protokoll zur Deploy-Zeit auswählt. Der Endpunktname (image-input) ist das, was ppl backend forward adressiert.

Build-Umgebung

build_system wählt das kuratierte Compile-und-Laufzeit-Image, gegen das der Container baut — liste die Registry mit ppl component builders auf (build_system_base ist nur für build_system: custom erforderlich). install wählt, wann Abhängigkeiten installiert werden: node verschiebt die requirements.txt-Installation auf die Deploy-Zeit auf jedem Node, alles andere installiert zur Build-Zeit. xmake_packages fügt C++-requires hinzu, und depends_on listet Geschwister-component-Slugs auf, die die component zur Laufzeit benötigt.

Wo das hineinpasst

component.yml ist die Kontraktschicht zwischen dem Code, den du geschrieben hast, und der Plattform, die ihn ausführt. Sie wird zur Compile-Zeit (Validierung, Typprüfung), zur Release-Zeit (Katalog-Eintrag, Schema-Introspektion) und zur Deploy-Zeit (Parameter-Bindung, Datei-Bereitstellung) gelesen. Bring die Form einmal richtig hin; rühre sie nie wieder an, bis sich der Kontrakt ändert.

Für das vollständige Schema

Die Website deckt das Modell ab. Für die Tabelle jedes Feldes, jedes Defaults, jedes Sonderfalls, jeder Validierungsregel, jedes Beispiels nach Kategorie und der Validierungsfehler-Modi hole die Referenz aus der CLI:

ppl docs get component-api/component-contract

Verwandt

/concepts/components — die component als Plattform-Primitiv.
/type-api/type-syntax — die vollständige Grammatik für input_type / output_type.
/type-api/catalog — Katalog der eingebauten benannten Typen.
/file-api/file-types — gültige file_type-Slots.
/concepts/build-systems — die build_system-Registry.
/concepts/install-modes — install: node vs. Build-Zeit-Installation.