Docs

Datei-Upload und Backend-Bindung

Kurzfassung

  • Eine Datei ist ein typisiertes workspace-Artefakt, das ein component zur Laufzeit konsumiert. Jeder Upload ist typisiert (onnx, mar, gguf, weights, csv, image, parquet, …), über file_id adressierbar und über viele backends hinweg wiederverwendbar.
  • Ein component deklariert Datei-Slots in seiner component.yml (file_schema). Ein backend bindet eine bestimmte hochgeladene Datei mit ppl backend add-file in einen bestimmten Slot auf einem bestimmten vertex. Die Bindung ist Teil des backend-Graphen — reproduzierbar, rückgängig zu machen, redeploybar.
  • Die Datei und die Bindung sind getrennt. Das Hochladen eines Modells erzeugt ein workspace-Artefakt; das Artefakt läuft erst, nachdem es in einen backend-vertex gebunden und das backend deployt wurde. Dieselbe Datei kann gleichzeitig in viele backends und viele vertices gebunden werden.
  • Die optionalen Config-Metadaten einer Datei können vertex-Parameter-Standards zur Bindezeit setzen. Das ist das Muster für ein Artefakt, das seinen eigenen Konfidenz-Schwellwert, seine Labels oder seine Vorverarbeitungs-Config trägt: die Datei wird selbstbeschreibend, und der backend-Graph übernimmt diese Standards automatisch.
  • Der Flow ist abgeschlossen, wenn die gebundene Datei in der runtime funktioniert, nicht wenn der Upload gelingt. Auf das Binden folgt ein Fixture-Run, und der Fixture-Run ist der Teil, der das Verhalten bestätigt.

Was eine Datei ist

Eine Datei ist ein typisiertes, benanntes workspace-Artefakt, das ein component zur Laufzeit konsumiert — einmal hochgeladen, per Referenz in einen backend-vertex gebunden, über backends hinweg wiederverwendet. Das Primitiv, das mentale Modell und warum Dateien von components getrennt sind, leben in Files. Diese Seite ist der praktische Pfad: hochladen, Config anhängen, binden, beweisen.

Hochladen

Verwende diesen Schritt, wenn die Datei noch nicht im workspace ist.

Upload schiebt eine lokale Datei (oder ein Verzeichnis) in den workspace-Dateispeicher und registriert sie mit einem Typ, einem Anzeigenamen und einer README. Die nicht-interaktive Form ist die, die man in Skripten und Agent-Flows verwendet:

ppl file upload <path> --type <type> --name "<display>" --readme @./README.mdppl file upload <path> --type <type> --name "<display>" --readme @./README.md --config ./file.config.yml

--type ist das tragende Flag: es bestimmt, welche Art von Artefakt der Upload ist und welche file_schema-Slots die resultierende Datei akzeptieren. Ein falscher Typ beim Upload bedeutet, dass der Bind-Schritt sie später ablehnt, oder der Bind gelingt und die runtime auf einen inkompatiblen Loader trifft. Die Plattform stellt ein breites Typ-Vokabular bereit: Modell-Artefakte (triton_model, onnx, safetensors, checkpoint, weights, tokenizer, lora, gguf, mar), Daten-Fixtures (csv, json, jsonl, image, audio, video, parquet, arrow, numpy, bundle, binary) und Config-/Doc-Typen (yaml, toml, text, markdown, openapi, jsonschema, config).

Der Triton-Fall ist erwähnenswert, weil er der häufigste Upload-Fehler ist. --type triton_model erwartet ein Triton-Modell-Repository-Verzeichnis, übergeben als Verzeichnispfad, kein vorab getarrtes Archiv — siehe /file-api/file-types für das Layout und die Verzeichnis-nicht-Archiv-Regel. Der Bind validiert, und der Fehler taucht erst auf, wenn die runtime das Modell lädt.

Eine Beschreibung ist beim Upload erforderlich: übergib sie inline mit --readme oder aus einer Datei mit --readme @<path>. Ein Anzeigename kommt von --name. Beide auf der Kommandozeile zu übergeben hält den Flow nicht-interaktiv — ein Agent-Flow, der die Beschreibung weglässt, bleibt an einem Editor-Prompt hängen, den er nicht beantworten kann.

Config an eine Datei anhängen

Verwende dies, wenn das Artefakt seine eigenen Laufzeit-Standards tragen soll.

Eine Datei kann beim Upload ein --config <yaml>-Dokument angehängt haben. Die Config hat zwei Effekte: ihre tags sind durchsuchbare Metadaten in der workspace-Dateiliste, und ihre config_schema-Standards fließen in passende vertex-Parameter, wenn die Datei später an einen backend-vertex gebunden wird.

tags:  - detector  - warehouseconfig_schema:  confidence_threshold:    type: Double    default: 0.35  labels:    type: String    default: warehouse_labels

Die config_schema-Standards stimmen nach Namen überein: jeder Eintrag, dessen Name mit einem Parameter auf dem vertex des konsumierenden components übereinstimmt, ersetzt zur Bindezeit den Wert dieses vertex-Parameters. Das ist es, was ein Modell-Artefakt selbstbeschreibend macht — das Artefakt und seine bevorzugten Laufzeit-Einstellungen reisen zusammen, und der backend-Graph übernimmt sie automatisch. Das Binden einer Datei, deren Config confidence=0.35 setzt, lässt das backend bei 0.35 laufen, ohne einen separaten Parameter-Schritt.

Der Seiteneffekt ist ebenfalls tragend. Ein vertex-Parameter, der zuvor mit ppl backend change-parameter gesetzt wurde, wird ersetzt, wenn eine Datei mit einem passenden config_schema-Eintrag gebunden wird. Der Wert des Artefakts gewinnt für die Parameter, die das Artefakt besitzt. Die Regel: alles in config_schema gehört zur Datei, und alles andere bleibt unter change-parameter-Kontrolle auf dem Graphen.

An einen vertex binden

Verwende diesen Schritt, sobald die Datei im workspace ist und der backend-vertex einen Slot dafür deklariert.

Das Binden hängt eine file_id an einen bestimmten file_schema-Slot auf einem bestimmten vertex eines bestimmten backends an:

ppl backend add-file <backend_id> --vertex <vertex_id> --key <file_schema_key> --file <file_id>

--key ist der Slot-Name, der vom konsumierenden component deklariert wird (zum Beispiel --key model für eine file_schema.model-Deklaration). Die Plattform validiert, dass der Dateityp dem entspricht, was der Slot akzeptiert, sodass ein nicht passender Typ beim Binden statt zur Laufzeit abgelehnt wird.

Der Bind ist eine einzige Graph-Operation im event-gesourcten backend-Log: er fügt einen Eintrag hinzu, wendet alle config_schema-Standards an, die mit der Datei kamen, und wird Teil der reproduzierbaren Historie des backends. Das nächste deploy oder redeploy übernimmt die neue Bindung. Eine gebundene Datei durch eine andere zu ersetzen ist dieselbe Operation, auf eine andere file_id gerichtet, und die vorherige Bindung ist über das backend-Operations-Log rückgängig zu machen.

Siehe Backend-Operationen dafür, wie das im Operations-Log landet, und Deployen und überwachen dafür, was nach einer Änderung der Bindung neu deployt.

Die Bindung beweisen

Verwende diesen Schritt jedes Mal. Das Binden ist nicht abgeschlossen, bis die runtime das Verhalten bestätigt.

Eine gebundene Datei bedeutet, dass die Plattform validiert hat, dass der Typ des Artefakts für den Slot akzeptabel ist. Es bedeutet nicht, dass das Artefakt korrekten Output produziert. Ein Detektor kann binden und dann das falsche Label-Set laden; ein Tokenizer kann binden und dann nicht zum erwarteten Vokabular des Modells passen; ein Triton-Repository kann binden und dann auf ein backend verweisen, das der Container nicht installiert hat. Jeder dieser Fehler taucht erst auf, wenn die runtime die Datei lädt und ausübt.

Der Beweis-Schritt ist ein Fixture-Run durch das deployte backend. Die billige Form ist ein Live-backend-Test gegen eine kleine repräsentative Eingabe; die gründliche Form ist die in Verhalten beweisen beschriebene Versions-Vergleichs-Beweis-Schleife. Was zählt, ist, dass die gebundene Datei den erwarteten semantischen Output produziert, nicht dass der Bind-Aufruf gelungen ist.

Verwandt

War diese Seite hilfreich?