Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

介绍

Dora是运行实时多AI和多硬件应用程序的支持多语言的框架。

Dora by Examples是一系列可运行的示例，旨在帮助用户快速入门和学习如何使用Dora框架。这些示例涵盖了各种应用场景，包括各类传感器使用，图像分类、目标检测、语音识别，电机控制等。包括Python、Rust、C++等语言的示例。

目录

安装

Dora 提供了多种安装方式

pip install dora-rs-cli

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dora-rs/dora/releases/latest/download/dora-cli-installer.sh | sh

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dora-rs/dora/releases/latest/download/dora-cli-installer.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://github.com/dora-rs/dorareleases/latest/download/dora-cli-installer.ps1 | iex"

cargo install dora-cli

docker pull ghcr.io/dora-rs/dora-slim #拉取镜像
docker run ghcr.io/dora-rs/dora-slim dora --help #运行容器

git clone https://github.com/dora-rs/dora.git
cd dora
cargo build --release -p dora-cli
PATH=$PATH:$(pwd)/target/release

important

本文主要围绕主分支的最新代码展开，如果想获得完全相同体验请尽量使用主分支上的Dora。 所有的样例以及部分多编程语言涉及到的特定包（Rust Crates）只在源码中给出，现阶段推荐从源码安装

确认完成安装

$ dora --version
dora-cli 0.3.11

从源码安装dora（以Ubuntu24.04为例）

安装Rust

安装rustup，rustup是管理Rust版本、编译工具链的重要工具

$ sudo apt install curl -y # 安装curl，如果未安装
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # 弹出选项，回车选择默认安装即可
$ export PATH=$PATH:$HOME/.cargo/bin # 设置环境变量

rustup安装画面

获取Dora源代码

$ sudo apt install git -y # 安装git，如果未安装
$ git clone https://github.com/dora-rs/dora.git
$ cd dora

编译Dora-CLI

Dora-CLI是非常实用的命令行工具，它提供了许多方便的命令来管理Dora项目。

$ sudo apt install build-essential -y # 安装C/C++编译环境相关的包（包括g++等），如果未安装
$ cargo build --release --package dora-cli

添加到环境变量

$ export PATH=$PATH:$(pwd)/target/release # 添加到环境变量

或者可以选择官方提供的脚本

$ ./install.sh

基础

在本章节中，我们将介绍一些基础概念和工具，帮助您开始使用Dora。

echo

路径: ./examples/echo

关键词：Node, Dataflow

Dora中，一个逻辑功能通常作为节点（Node）。不同逻辑功能的交互依赖于信息的交互（Dataflow）。为了方便不同节点之间的组合，Dora使用yaml文件来声明消息的“流动”。

yaml不仅声明了不同节点消息的输入、输出，还可以声明节点构建（编译、安装）的过程。在使用这些节点之前需要先进行构建。

构建

tip

如果使用uv管理的python可在命令中加入--uv参数

进入examples/echo文件夹，执行命令

$ dora build dataflow.yaml # --uv

输出：

Using Python 3.11.12 environment at: ...
Resolved 4 packages in 1.20s
      Built pyarrow-sender @ ...
Prepared 1 package in 693ms
Installed 1 package in 1ms
 ~ pyarrow-sender==0.3.11 (...)
Using Python 3.11.12 environment at: ...
Resolved 4 packages in 4ms
      Built dora-echo @ ...
Prepared 1 package in 507ms
Installed 1 package in 1ms
 + dora-echo==0.3.11 (...)
Using Python 3.11.12 environment at: ...
Resolved 4 packages in 3ms
      Built pyarrow-assert @ ...
Prepared 1 package in 499ms
Installed 1 package in 1ms
 ~ pyarrow-assert==0.3.11 (...)

运行

依据yaml文件运行Dora框架：

$ dora run dataflow.yaml # --uv

输出：

... INFO run_inner: dora_daemon::log:     pyarrow-assert finished successfully...

各节点的作用

node-hub提供了很多现成的方便复用的节点

Dora中通过环境变量为节点提供参数

  • pyarrow-sender节点：生成了内容为DATA的信息
  • dora-echo节点：将输入的内容发送出去
  • pyarrow-assert节点：判断接收消息与DATA是否一致

额外的尝试

更改pyarrow-sender或pyarrow-assert的DATA参数，在二者不一致时运行会产生报错 输出：

... [ERROR]
Dataflow failed:

Node `pyarrow-assert` failed: exited with code 1 with stderr output: ...

多守护进程（Daemon）

地址：examples/multiple-daemons 关键词：Daemon, Coordinator

Dora通过Coordinator来协调多个Daemon的运行。Daemon可以来自不同的机器。这是Dora分布式的基础。

启动准备

启动一个协调器（Coordinator）

$ dora coordinator

其运行ip与端口的绑定设置，可通过添加--help参数来查看，样例中用默认的设置即可。

启动守护进程（Daemon）

$ dora daemon --machine-id A
$ dora daemon --machine-id B

分别启动两个分别名为A和B的守护进程。 可以通过--coordinator-addr和--coordinator-port来指定协调器的地址和端口。 具体可以参考dora daemon --help。

构建

$ dora build dataflow.yml

可以通过--coordinator-addr和--coordinator-port来指定协调器的地址和端口。 具体可以参考dora build --help。

运行

$ dora start dataflow.yml

可以通过--coordinator-addr和--coordinator-port来指定协调器的地址和端口。 具体可以参考dora start --help。

构建与加载

关键词：build, launch

Dora-cli 中常用的命令

Dora命令行工具提供了build和start等命令。

  • coordinator启动一个coordinator进程，用于调度协调。
  • daemon在本地启动一个daemon进程，用于运行dataflow，可以指定连接到任一coordinator。
  • start启动一份dataflow，可以指定连接到任一coordinator。
  • run相当于在本地自行创建一个coordinator、daemon并在其上加载对应的dataflow.yml。
  • ...

YAML配置文件

Dora通过使用YAML配置文件来描述dataflow。 形如：

nodes:
    - id: rust-node
      _unstable_deploy:
          machine: A
      build: cargo build --release -p rust-dataflow-example-node
      path: $DORA_EXAMPLES/target/release/rust-dataflow-example-node
      inputs:
          tick: dora/timer/millis/10
      outputs:
          - random

    - id: rust-status-node
      _unstable_deploy:
          machine: A
      build: cargo build --release -p rust-dataflow-example-status-node
      path: $DORA_EXAMPLES/target/release/rust-dataflow-example-status-node
      inputs:
          tick: dora/timer/millis/100
          random: rust-node/random
      outputs:
          - status

    - id: rust-sink
      _unstable_deploy:
          machine: B
      build: cargo build --release -p rust-dataflow-example-sink
      path: $DORA_EXAMPLES/target/release/rust-dataflow-example-sink
      inputs:
          message: rust-status-node/status

通过环境变量更灵活的启动

在build和path字段中都可以使用环境变量，例如$DORA_EXAMPLES。 这使得节点的位置可以更加灵活的放置。 值得注意的是，这两个字段中的环境变量会使用daemon所处运行环境的环境变量。

构建字段的技巧

Dora的build字段参考了Github Action的设计，但是其功能并不完备。 build字段允许通过多行来声明需要多个命令的构建。 如果需要借助脚本或更复杂的参数时可以使用bash -c "..."

编程语言

Dora的核心部分及大部分功能虽然使用Rust编写，但是也为其它编程语言提供了可编程接口支持多种编程语言，包括Python、C++等。

在本节中将展示不同编程语言中Dora的使用。

C/C++

需要预先准备的包

为了实现C/C++多语言混合编程，需要准备好相关的包。 需要从源码安装Dora，并且构建相关包：

  • 运行时
$ cargo build -p dora-runtime # --release
  • 如果需要使用C API
$ cargo build -p dora-node-api-c # --release
$ cargo build -p dora-operator-api-c # --release
  • 如果需要使用Rust API
$ cargo build -p dora-node-api-cxx # --release
$ cargo build -p dora-operator-api-cxx # --release

当使用启用release编译时，需注意将连接的地址target/debug替换为target/release 如果对Rust与C++的混合编译感兴趣，可以参阅cxx.rs

C++ 样例

数据流（Dataflow)

地址：./examples/c++-dataflow

关键词：C++, Node, Operator

Dora相关包的准备

需要预先准备的包 官方样例中使用clang++进行编译，实测g++也是可以使用的，对于大部分的Linux发行版（如Ubuntu等）使用默认安装的g++即可。

C API

构建

alias CXX='clang++' # CXX='g++'
mkdir build

# 构建算子
CXX -c operator-c-api/operator.cc -std=c++17 -o operator-c-api/operator.o -fPIC
CXX -shared operator-c-api/operator.o -ldora_operator_api_c -L../../target/debug/ -o ./build/liboperator_c_api.so

# 构建节点
CXX node-c-api/main.cc -lm -lrt -ldl -pthread -L../../target/debug -ldora_node_api_c -o ./build/node_c_api

#TBD#

#TBD#

Rust API

构建

alias CXX='clang++' # CXX='g++'
mkdir -p build

# 构建算子
cp ../../target/cxxbridge/dora-operator-api-cxx/src/lib.rs.h ./build/dora-operator-api.h
cp ../../target/cxxbridge/dora-operator-api-cxx/src/lib.rs.cc ./build/operator-bridge.cc
CXX -c ./operator-rust-api/operator.cc -std=c++17 -I./operator-rust-api -o operator-rust-api/operator.o -fPIC
CXX -c ./build/operator-bridge.cc -std=c++17 -I./operator-rust-api -o ./build/operator-bridge.o -fPIC
CXX -shared ./operator-rust-api/operator.o ./build/operator-bridge.o -ldora_operator_api_cxx -L../../target/debug/ -o ./build/liboperator_rust_api.so

# 构建节点
cp ../../target/cxxbridge/dora-node-api-cxx/src/lib.rs.h ./build/dora-node-api.h
cp ../../target/cxxbridge/dora-node-api-cxx/src/lib.rs.cc ./build/node-bridge.cc
CXX ./node-rust-api/main.cc ./build/node-bridge.cc -lm -lrt -ldl -pthread -L../../target/debug -ldora_node_api_cxx -o ./build/node_rust_api

#TBD#

#TBD#

运行

$ dora run dataflow.yaml

相关节点功能概览

  • node-c-api：使用C API对接收到的数据进行计数，并返回计数
  • node-rust-api： 使用Rust API对接收到的数据进行计数，并返回计数
  • operator-c-api：使用C API接受数据并除以2后发出
  • operator-rust-api：使用Rust API对接收到的所有消息进行计数，并将收到的消息发出

数据流（Arrow Dataflow）

地址：./examples/c++-arrow-dataflow

关键词：Arrow，Dataflow

Apache Arrow 是通用的、列式格式的、快速数据交换和内存中分析工具。支持多种语言。

安装Arrow

更详细的安装说明与选项请参考Arrow官方安装文档。

$ sudo apt update
$ sudo apt install -y -V ca-certificates lsb-release wget
$ wget https://packages.apache.org/artifactory/arrow/$(lsb_release --id --short | tr 'A-Z' 'a-z')/apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
$ sudo apt install -y -V ./apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
$ sudo apt update
$ sudo apt install -y -V libarrow-dev # For C++

构建

通过pkg-config --libs arrow和pkg-config --cflags arrow获得系统安装的Arrow库相关的编译设置

$ mkdir build
$ cp ../../target/cxxbridge/dora-node-api-cxx/src/lib.rs.cc ./build/node-bridge.cc
$ cp ../../target/cxxbridge/dora-node-api-cxx/src/lib.rs.h ./build/dora-node-api.h
$ alias CXX=g++
$ CXX ./build/node-bridge.cc ./node-rust-api/main.cc -std=c++17 -lm -lrt -ldl -pthread -ldora_node_api_cxx -L../../target/debug/ $(pkg-config --libs arrow) $(pkg-config --cflags arrow) -o ./build/node_rust_api

运行

dora run dataflow.yml

C数据流

地址：./examples/c-dataflow

关键词：Dataflow, C

构建C API相关包

$ cargo build -p dora-node-api-c
$ cargo build -p dora-operator-api-c

Node

Source

$ alias C=gcc # 用clang亦可以
$ C node.c -lm -lrt -ldl -pthread -ldora_node_api_c -L../../target/debug/ -o ./build/c_node

Sink

$ C sink.c -lm -lrt -ldl -pthread -ldora_node_api_c -L../../target/debug/ -o ./build/c_sink

Operator

$ C -c operator.c -o build/operator.o -fPIC # 编译
$ C -shared build/operator.o -L../../target/debug/ -ldora_operator_api_c -o ./build/liboperator.so

CMake数据流

地址：./examples/cmake-dataflow

关键词：CMake, Dataflow

CMake是一个跨平台的构建系统，它允许开发者使用简单的脚本来描述项目的依赖关系和构建规则，从而实现跨平台的构建。C/C++ Dora项目也可以使用CMake来构建。

构建

$ cmake -DDORA_ROOT_DIR=../../ -B./build . # 通过DORA_ROOT_DIR变量指定Dora项目的根目录
$ cmake --build ./build
$ cmake --install ./build

运行

$ dora run dataflow.yml

ROS2数据流

地址：./examples/c++-ros2-dataflow

关键词：ROS2

确保ROS2环境已正确安装和配置

Dora通过ros2-client与ROS进行交互 C++ API为了与ROS通信，需要启用ROS2桥接功能。

准备相关依赖

由于例子与turtlesim和AddTwoInts相关

$ sudo apt install ros-jazzy-turtlesim ros-jazzy-examples-rclcpp-minimal-service

$ source /opt/ros/jazzy/setup.bash
$ cargo build --package dora-node-api-cxx --features ros2-bridge
$ mkdir build
$ cp ../../target/cxxbridge/dora-node-api-cxx/dora-node-api.cc ./build/dora-node-api.cc
$ cp ../../target/cxxbridge/dora-node-api-cxx/dora-node-api.h ./build/dora-node-api.h
$ cp ../../target/cxxbridge/dora-node-api-cxx/dora-ros2-bindings.cc ./build/dora-ros2-bindings.cc
$ cp ../../target/cxxbridge/dora-node-api-cxx/dora-ros2-bindings.h ./build/dora-ros2-bindings.h

当ROS2中的包出现变化时，需要重新构建dora-node-api-cxx从而确保dora-ros2-bindings的正确性。 在构建前务必先source需要使用的ROS环境，以确保各ROS包能被检测到并生成桥接文件

编译

$ alias CXX=g++ # clang++ 也可以
$ CXX ./node-rust-api/main.cc ./build/dora-ros2-bindings.cc ./build/dora-node-api.cc -std=c++17 -lm -lrt -ldl -lz -pthread -ldora_node_api_cxx -L ../../target/debug/ -o ./build/node_rust_api

运行

打开另外两个终端

需要使用rmw_fastrtps_cppJazzy 中应该是默认的，如果在.bashrc等地方设置成了别的注意要设置回来。 更改设置后重启daemon，ros2 daemon stop, ros2 daemon start

启动turtlesim

$ source /opt/ros/jazzy/setup.bash
$ ros2 run turtlesim turtlesim_node

启动AddTwoInts服务

$ source /opt/ros/jazzy/setup.bash
$ ros2 run examples_rclcpp_minimal_service service_main

启动Dora节点

$ dora run dataflow.yml

CUDA基准测试

Python

为了更方便的管理Python包，Dora推荐使用uv进行管理

安装UV

$ sudo apt install curl # 安装curl，如果未安装
$ curl -LsSf https://astral.sh/uv/install.sh | sh

Python 样例

数据流（Dataflow）

地址：examples/python-dataflow

关键词：Python, Dataflow

官方的Node Hub文件夹中提供了许多现成的节点 本例中用到的有

  • opencv-video-capture用于读取摄像头
  • dora-yolo用于进行目标检测
  • dora-rerun用于进行可视化

dataflow.yml除了用于描述输入输出外，还可以通过build字段进行简单的构建或安装

准备Python环境

$ uv venv -p 3.10 --seed

安装对应的包

当在dora build时加上--uv标签，会自动在使用pip前添加uv以使用uv管理的Python版本

$ dora build dataflow.yml --uv

运行

$ dora run dataflow.yml --uv

默认的视图中可能只包含照片项，在弹出的rerun窗口中右键时间轴上的/项，点击添加到新的视图中

运行效果

动态节点

$ dora build dataflow_dynamic.yml --uv # 安装所需要的节点
$ dora up # 启动本地的 daemon 和 coordinator
$ dora start dataflow_dynamic.yml --uv

在另外一个中端窗口运行

$ uv run opencv-plot --name plot

算子（Operator）

地址：examples/python-operator-dataflow

关键词：Operator

Operator提供了更加轻量化的方案，并且有更多Dora的高级功能，拥有更快的通信速度。

安装依赖

$ uv venv -p 3.11 --seed # 创建环境
$ uv pip install -e ../../apis/python/node # 安装Dora Python API
$ source .venv/bin/activate
$ pip install -r requirements.txt # 安装依赖，如果要体验dataflow_llm，则使用requirements_llm.txt

由于Operator暂未适配--uv标签作为启动参数，为了使用uv管理的Python，所以要在终端中source .venv/bin/activate

$ dora run dataflow.yml

运行效果

异步

地址：examples/python-async

关键词：异步

$ uv venv -p 3.11 --seed # 创建环境
$ uv pip install -e ../../apis/python/node # 安装Dora Python API
$ dora build dataflow.yml --uv # 安装依赖

运行

$ dora run dataflow.yml --uv

本例较为简单展示了使用Python通过异步方式进行消息IO。

  • receive_data.py 异步接收数据
  • send_data.py 发送数据

多Python环境共存

地址：examples/python-multi-env

关键词：多环境

uv通过VIRTUAL_ENV环境变量可以切换不同的Python的环境，则只需要在dataflow.yml中配置即可

构建环境

$ uv venv -p 3.11 -n env_1
$ uv venv -p 3.11 -n env_2
$ dora build dataflow.yml --uv

运行

$ dora run dataflow.yml --uv

运行效果应与python-dataflow一致。

ROS2数据流

准备相关依赖

由于例子与turtlesim和AddTwoInts相关

$ sudo apt install ros-jazzy-turtlesim ros-jazzy-examples-rclcpp-minimal-service

准备Python环境

$ uv venv -p 3.10 --seed
$ uv pip install -e ../../apis/node

启动

启动turtlesim

$ source /opt/ros/jazzy/setup.bash
$ ros2 run turtlesim turtlesim_node

启动AddTwoInts服务

$ source /opt/ros/jazzy/setup.bash
$ ros2 run examples_rclcpp_minimal_service service_main

$ source /opt/ros/jazzy/setup.bash
$ dora run dataflow.yml --uv

Rust

Rust 样例

Rust数据流（Dataflow）

地址：./examples/rust-dataflow

关键词：Rust，Dataflow

构建节点

$ dora build dataflow.yml

运行

$ dora run dataflow.yml

动态节点

Dora允许节点不一定有dataflow.yml启动，只需要预先将其path声明为dynamic即可。

构建

$ dora build dataflow_dynamic.yml

运行

  1. 启动dataflow.yml
$ dora up
$ dora start dataflow_dynamic.yml
  1. 在另一个终端启动动态节点
$ ../../target/debug/rust-dataflow-example-sink-dynamic

实现区别

通过工具查看动态节点与普通节点的区别

节点区别

本地通信方式

Dora提供TCP、共享内存、Socket三种本地的节点通信方式。 在dataflow.yml中可以显示指定使用何种通信方式。

这是dataflow_socket.yml给出的

communication:
  _unstable_local: UnixDomain

$ dora build dataflow_socket.yml
$ dora run dataflow_socket.yml

Rust网址数据流

地址：examples/rust-dataflow-url

关键词：url

warning

由于Dora官方在发布新版本时已经不再包含rust-node的动态库文件，因此，此样例无法正确运行。

并非所有共享节点的作者都乐意通过git的形式进行共享， 于是Dora提供了另外一种更为通用的方式，即通过HTTP协议进行数据流传输。 这种方式还为二进制分发提供了便利。

$ dora build dataflow.yml
$ dora run dataflow.yml

通过git获取节点

地址：examples/rust-dataflow-git

关键词：git

对于有的第三方节点，通常不会在意其实现细节，只需要关注其功能和接口即可。 利用git可以轻松对这些第三方的节点进行版本管理，确保代码的稳定性和可维护性。

$ dora build dataflow.yml
$ dora run dataflow.yml

Rust ROS2数据流

地址：./examples/rust-ros2-dataflow

关键词：ROS2，Rust

准备相关依赖

由于例子与turtlesim和AddTwoInts相关

$ sudo apt install ros-jazzy-turtlesim ros-jazzy-examples-rclcpp-minimal-service

构建

$ source /opt/ros/jazzy/setup.bash # 需要先应用ros2相关环境，在构建时才能找到相应ros消息类型
$ dora build dataflow.yml

启动

启动turtlesim

$ source /opt/ros/jazzy/setup.bash
$ ros2 run turtlesim turtlesim_node

启动AddTwoInts服务

$ source /opt/ros/jazzy/setup.bash
$ ros2 run examples_rclcpp_minimal_service service_main

$ source /opt/ros/jazzy/setup.bash
$ dora run dataflow.yml

进阶

Dora 官方提供了很多开箱即用的Node-hub， 其中包括但不限于：

可视化

使用相机

av1编码

深度相机

深度图像处理

物体识别

大语言模型

OpenAI

语音到语音

语音到文字

地址：./examples/speech-to-text/ 关键词：AI，语音识别

$ dora build whisper.yaml --uv
$ dora run whisper.yaml --uv

该样例默认使用openai/whisper-large-v3-turbo模型， 如果你想使用其他模型，可以通过为dora-whisper节点添加MODEL_NAME_OR_PATH环境变量来更改所使用的模型。

国内用户如果收到网络影响可以使用hf-mirror镜像来加速模型参数的拉取。 例如可以直接执行

HF_ENDPOINT=https://hf-mirror.com dora build whisper.yaml --uv

追踪

翻译

视觉语言模型

场景应用

alexk-lcr

aloha

reachy

reachy1

reachy2

reachy2远程

lebai

so100

远程

franka

PiPer

其他样例

基准测试

Python Arrow测试

附录

词汇表

  • 节点（Node）
  • 算符（Operator）
  • 协作器（Coordinator）

其具体关系请参阅Dora设计

ROS2安装

ROS2安装的详细文档，请以ROS2官方文档为准

locale  # check for UTF-8

sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

locale  # verify settings

启用需要的仓库

sudo apt install software-properties-common
sudo add-apt-repository universe

sudo apt update && sudo apt install curl -y
export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F\" '{print $4}')
curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo $VERSION_CODENAME)_all.deb" # If using Ubuntu derivates use $UBUNTU_CODENAME
sudo dpkg -i /tmp/ros2-apt-source.deb

安装相应包

sudo apt install ros-jazzy-desktop
# or sudo apt install ros-jazzy-desktop