Pipelines
Chain models into multi-stage inference pipelines with YAML
A pipeline chains multiple models into a single inference flow — for example a voice assistant that transcribes speech, generates a reply, and speaks it back. Pipelines are defined in YAML and run through the same engine on every platform.
# voice-assistant.yaml
name: voice-assistant
stages:
- whisper-tiny # Speech → text
- qwen2.5-0.5b-instruct # Generate a reply
- kokoro-82m # Text → speechxybrid run --config voice-assistant.yaml --input-audio question.wav -o response.wavThe output Envelope of each stage becomes the input of the next: audio → text → text → audio.
Multi-model pipelines (MMP) are experimental. Single-stage pipelines are stable and are how the SDKs run individual models internally.
Pipeline schema
Only stages is required:
| Field | Required | Description |
|---|---|---|
name | No | Display name used in logs and traces |
registry | No | Registry URL for model resolution (default https://api.xybrid.dev) |
stages | Yes | List of stages — at least one |
Stage formats
A stage is either a plain string or a full object.
Simple — just the model ID, optionally pinned to a version:
stages:
- kokoro-82m
- qwen2.5-0.5b-instruct@1.0Object — full control over routing and generation options:
stages:
- id: assistant
model: openai/gpt-4o-mini
target: cloud
provider: openai
system_prompt: "You are a helpful voice assistant. Keep responses concise."
max_tokens: 150
temperature: 0.7| Field | Description |
|---|---|
id | Stage identifier (defaults to the model ID) |
model | Model ID from the registry, or the cloud model for cloud stages: a canonical ID such as openai/gpt-4o-mini through Xybrid Platform, the provider's own model name with backend: direct |
version | Model version (e.g. "1.0") |
target | Where to run: device, cloud, or auto (default) — see Hybrid Execution. auto with a provider is a hybrid stage: local model plus a cloud leg, chosen per request by policy and device state |
provider | Cloud provider for cloud or hybrid stages: openai, anthropic, google, deepseek, elevenlabs, openrouter, custom |
cloud_model | Model sent on the cloud leg of a hybrid stage (defaults to model), named like a cloud stage's model |
backend | gateway (default) uses Xybrid Platform with XYBRID_API_KEY; direct with an OpenAI-compatible provider calls the provider's API with $<PROVIDER>_API_KEY |
gateway_url, api_key | Explicit endpoint and credential for the cloud leg (api_key accepts $ENV_VAR); credentials are never inherited across origins |
thinking | DeepSeek only: enabled or disabled (DeepSeek reasons by default; disabled keeps max_tokens for the answer) |
execution_provider | ONNX Runtime execution provider: cpu, coreml, coreml-ane, coreml-gpu. Parsed, not applied yet: ONNX models run on the CPU whatever the value, and nothing is auto-selected when it is unset. Loading a pipeline whose stage sets it to anything but cpu logs a warning (the iOS and Android SDKs write it to the system log; elsewhere it shows only where the host installs a Rust log logger), and xybrid run, xybrid repl and xybrid prepare print it |
| (any other key) | Passed to the stage as an option — system_prompt, max_tokens, temperature, top_p apply to both legs of a hybrid stage |
Hybrid stages (target: auto with a provider) are currently supported by xybrid run. The Flutter and Rust SDK pipeline APIs treat this combination as cloud-only and do not load its local model.
Use crates/xybrid-cli/examples/hybrid-platform.yaml for the primary platform
integration. hybrid-deepseek.yaml is the separate direct-provider testing example.
Mixing device and cloud stages
A pipeline can route each stage independently — keep audio on-device for privacy and latency, and burst to the cloud for a bigger model:
name: voice-assistant
stages:
- whisper-tiny # on-device ASR
- model: openai/gpt-4o-mini # cloud LLM
target: cloud
provider: openai
system_prompt: "You are a helpful voice assistant."
max_tokens: 150
- kokoro-82m # on-device TTSRunning pipelines
CLI
# Validate the YAML without running
xybrid prepare voice-assistant.yaml
# Show the execution plan (models, targets, download status)
xybrid plan voice-assistant.yaml
# Preview routing decisions without executing
xybrid run --config voice-assistant.yaml --input-audio q.wav --dry-run
# Run it
xybrid run --config voice-assistant.yaml --input-audio q.wav -o response.wavFlutter
final pipeline = await Xybrid.pipeline(yaml: yamlString).load();
await pipeline.loadModels(); // optional preload
final result = await pipeline.run(
XybridEnvelope.audio(bytes: audioBytes, sampleRate: 16000),
);Rust
use xybrid::Xybrid;
use xybrid::ir::{Envelope, EnvelopeKind};
let input = Envelope::new(EnvelopeKind::Audio(audio_bytes));
// One call: parse, resolve, download, execute
let result = Xybrid::run_pipeline(&yaml, &input)?;
// Or staged: inspect and preload first
let pipeline = Xybrid::pipeline(&yaml)?.load()?;
pipeline.load_models()?;
let result = pipeline.run(&input)?;SDK support
| Platform | Pipelines |
|---|---|
| Dart (Flutter) | ✅ Available |
| Rust | ✅ Available |
| Kotlin | ✅ Available |
| Swift | ✅ Available |
| React Native | ✅ Available |
| C# (Unity) | ✅ Available |
Related
- Hybrid Execution — how
target: autodecides between device and cloud - Models — the model catalog
- xybrid run — full CLI reference