PCIe を使用した最初のモデルを実行する

項目	値
カテゴリ	PCIe コプロセッシング
難易度	初級
推定所要時間	15 minutes
ラベル	PCIe, inference, tensor, image, detection

同じ YOLOv8s アーカイブと 640x480 のストリートシーンを使用して、3 つの独立したプログラムを実行します。各プログラムは 1 つのモードをデモンストレーションし、キュー 0 を同期的に使用し、1 つのモデルを閉じます。これにより、すべての例が十分に短く、個別にコピーできるようになります。

ウォークスルー

モデルで使用できるテンソルを実行する

ホストは、画像をモデルによって報告された [640, 640, 3] 入力に合わせてレターボックス処理し、BGR を RGB に変換し、ピクセルを [0, 1] にスケーリングします。Model.run() は、その FP32 テンソルをカード側の画像前処理なしで送信し、6 つすべての生の YOLO 出力ルートを出力します。

pcie_host/tutorials/024_run_your_first_model_over_pcie/run_tensor_mode.cpp

pcie::ConnectionOptions connection;
connection.card_id = card_id;
pcie::Model model(kModelPath, {}, connection);
const auto info = model.info();
if (info.inputs.size() != 1) {
  throw std::runtime_error("YOLOv8s must expose one input tensor");
}
const pcie::Tensor input = make_yolo_tensor(image, info.inputs[0]);
model.build(kBuildTimeoutMs);
const auto outputs = model.run(input, kRunTimeoutMs);
if (outputs.empty()) {
  throw std::runtime_error("tensor mode returned no outputs");
}
std::cout << "Tensor mode raw outputs:\n";
for (const auto& output : outputs) {
  std::cout << "  " << output.route.name << " " << dtype_name(output.dtype) << " "
            << shape_string(output.shape) << '\n';
}
model.close();

前処理をカードに移動する

preprocess.kind を Image に設定し、受信ピクセルを BGR として識別し、COCO_YOLO プリセットを選択します。ホストは現在、デコードされたピクセルを送信し、カードはレターボックスリサイズ、BGR から RGB への変換、および正規化を実行します。プログラムは、6 つの生の出力ルート名と形状を出力するため、テンソルモードと比較できます。

pcie_host/tutorials/024_run_your_first_model_over_pcie/run_image_mode.cpp

pcie::ConnectionOptions connection;
connection.card_id = card_id;
pcie::ModelOptions options;
options.preprocess.kind = pcie::InputKind::Image;
options.preprocess.color_convert.input_format = pcie::ColorFormat::BGR;
options.preprocess.color_convert.output_format = pcie::ColorFormat::RGB;
options.preprocess.resize.enable = pcie::AutoFlag::On;
options.preprocess.resize.mode = pcie::ResizeMode::Letterbox;
options.preprocess.normalize.preset = pcie::NormalizePreset::COCO_YOLO;
pcie::Model model(kModelPath, options, connection);
model.build(kBuildTimeoutMs);
const auto outputs = model.run(image, kRunTimeoutMs);
if (outputs.empty()) {
  throw std::runtime_error("image mode returned no outputs");
}
std::cout << "Image mode raw outputs:\n";
for (const auto& output : outputs) {
  std::cout << "  " << output.route.name << " " << dtype_name(output.dtype) << " "
            << shape_string(output.shape) << '\n';
}
model.close();

カードで検出をデコードする

BoxDecodeType.YoloV8、スコアしきい値、NMS しきい値、および出力制限を追加します。返される BBOX テンソルは、検出数の後に、固定サイズのレコードが続き、(x, y, width, height, score, class_id) が含まれます。例では、最初の 10 個のレコードを解析して、ソース画像座標で出力します。

pcie_host/tutorials/024_run_your_first_model_over_pcie/run_image_boxdecode.cpp

pcie::ConnectionOptions connection;
connection.card_id = card_id;
pcie::ModelOptions options;
options.preprocess.kind = pcie::InputKind::Image;
options.preprocess.color_convert.input_format = pcie::ColorFormat::BGR;
options.preprocess.color_convert.output_format = pcie::ColorFormat::RGB;
options.preprocess.resize.enable = pcie::AutoFlag::On;
options.preprocess.resize.mode = pcie::ResizeMode::Letterbox;
options.preprocess.normalize.preset = pcie::NormalizePreset::COCO_YOLO;
options.decode_type = pcie::BoxDecodeType::YoloV8;
options.score_threshold = 0.25F;
options.nms_iou_threshold = 0.45F;
options.top_k = 100;
pcie::Model model(kModelPath, options, connection);
model.build(kBuildTimeoutMs);
const auto boxes = parse_boxes(model.run(image, kRunTimeoutMs));
std::cout << "Image + boxdecode detections=" << boxes.size() << '\n';
for (std::size_t index = 0; index < std::min<std::size_t>(boxes.size(), 10); ++index) {
  const auto& box = boxes[index];
  std::cout << "  " << class_name(box.class_id) << " score=" << std::fixed
            << std::setprecision(3) << box.score << " box=(" << box.x << ", " << box.y << ", "
            << box.width << ", " << box.height << ")\n";
}
if (boxes.empty()) {
  throw std::runtime_error("no detections passed the score threshold");
}
model.close();

BBOX テンソルを解析する

ボックスデコードが 1 つの有効なテンソルを返したことを確認し、先頭のカウントを読み取り、ペイロードを超えるカウントは拒否します。残りの各 24 バイトのレコードは、次に 1 つの検出に変換されて出力されます。

pcie_host/tutorials/024_run_your_first_model_over_pcie/run_image_boxdecode.cpp

std::vector<Box> parse_boxes(const pcie::TensorList& outputs) {
  if (outputs.size() != 1 || outputs[0].data == nullptr || outputs[0].byte_offset < 0) {
    throw std::runtime_error("boxdecode must return one populated BBOX tensor");
  }
  const auto& tensor = outputs[0];
  const auto offset = static_cast<std::size_t>(tensor.byte_offset);
  if (offset > tensor.size_bytes || tensor.size_bytes - offset < sizeof(std::uint32_t)) {
    throw std::runtime_error("BBOX tensor is too small");
  }
  const auto* bytes = static_cast<const std::uint8_t*>(tensor.data) + offset;
  const std::size_t available = tensor.size_bytes - offset;
  const std::uint32_t count = read_value<std::uint32_t>(bytes);
  constexpr std::size_t record_size = 24;
  if (count > (available - 4) / record_size) {
    throw std::runtime_error("BBOX detection count exceeds its payload");
  }
  std::vector<Box> boxes;
  boxes.reserve(count);
  for (std::uint32_t index = 0; index < count; ++index) {
    const auto* record = bytes + 4 + index * record_size;
    boxes.push_back({read_value<std::int32_t>(record), read_value<std::int32_t>(record + 4),
                     read_value<std::int32_t>(record + 8), read_value<std::int32_t>(record + 12),
                     read_value<float>(record + 16), read_value<std::int32_t>(record + 20)});
  }
  return boxes;
}

実行

PCIe ホストパッケージをインストールし、チュートリアルの設定 で説明されているように、チュートリアルバンドルをダウンロードします。抽出された PCIe extras ルートから、次のコマンドを実行します。

sima-cli modelzoo get yolo_v8s

プログラムには、このディレクトリに yolo_v8s_mpk.tar.gz が必要です。Model Zoo の出力名と場所は異なる場合があります。コマンドが正確なパスを作成しなかった場合は、ダウンロードしたアーカイブを適切な場所にコピーし、確認してください。

cp /absolute/path/to/downloaded-yolov8s-archive.tar.gz yolo_v8s_mpk.tar.gz
test -f yolo_v8s_mpk.tar.gz

C++ (prebuilt):

./lib/sima-pcie-host/tutorials/tutorial_024_run_tensor_mode
./lib/sima-pcie-host/tutorials/tutorial_024_run_image_mode
./lib/sima-pcie-host/tutorials/tutorial_024_run_image_boxdecode

C++ (build from source):

./build.sh --target tutorial_024_run_tensor_mode
./build.sh --target tutorial_024_run_image_mode
./build.sh --target tutorial_024_run_image_boxdecode

./build/tutorials-standalone/tutorial_024_run_tensor_mode
./build/tutorials-standalone/tutorial_024_run_image_mode
./build/tutorials-standalone/tutorial_024_run_image_boxdecode

対応する C++ および Python プログラムは、テンソルモードと画像モードの両方で同じ 6 つの生の出力コントラクトを出力し、その後、デコードされた人、車、またはその他の見えるオブジェクトを出力します。

Tensor mode raw outputs:
  bbox_0 FP32 [80, 80, 64]
  ...
[OK] 024_run_tensor_mode
Image mode raw outputs:
  bbox_0 FP32 [80, 80, 64]
  ...
[OK] 024_run_image_mode
Image + boxdecode detections=...
  person score=... box=(...)
[OK] 024_run_image_boxdecode

デフォルトはカード 0 とキュー 0 です。別のカードを使用する場合にのみ、--card N を渡します。その管理アドレスは自動的に導き出されます。

実践

アプリケーションが正確に model.info() によって報告された dtype、形状、レイアウト、カラー順序、および数値範囲を生成する場合に、テンソルモードを使用します。アプリケーションが自然にデコードされたピクセルを所有し、カードに反復可能なモデル前処理を適用させたい場合は、画像モードを使用します。アプリケーションが生の特徴マップではなく、検出を必要とする場合は、ボックスデコードを有効にします。

すべてのモードは、同じ pcie::Model/pyneatpcie.Model ライフサイクルを使用します。ModelOptions と送信されたペイロードのみが変更されます。PCIe推論を非同期で実行 を使用して、push() と pull() を使用して、送信と完了をオーバーラップさせます。

完全なソース

完全なソースプログラムを表示

Tensor Mode

pcie_host/tutorials/024_run_your_first_model_over_pcie/run_tensor_mode.cpp

// Run YOLOv8s tensor-mode inference over PCIe.
//
// Usage:
//   tutorial_024_run_tensor_mode [--card 0]

#include <simaai/neat/pcie/Model.h>

#include <opencv2/imgcodecs.hpp>
#include <opencv2/imgproc.hpp>

#include <algorithm>
#include <cmath>
#include <cstdint>
#include <cstdlib>
#include <filesystem>
#include <iostream>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>

namespace pcie = simaai::neat::pcie;

namespace {

constexpr int kBuildTimeoutMs = 180000;
constexpr int kRunTimeoutMs = 30000;
constexpr char kModelPath[] = "yolo_v8s_mpk.tar.gz";
constexpr char kImagePath[] = "share/sima-pcie-host/tutorials/assets/street-scene.png";

int parse_card(const int argc, char** argv) {
  int card_id = 0;
  for (int index = 1; index < argc; ++index) {
    const std::string arg = argv[index];
    if (arg == "--card" && index + 1 < argc) {
      card_id = std::stoi(argv[++index]);
    } else if (arg == "-h" || arg == "--help") {
      std::cout << "Usage: " << argv[0] << " [--card 0]\n";
      std::exit(0);
    } else {
      throw std::runtime_error("unknown or incomplete argument: " + arg);
    }
  }
  return card_id;
}

std::string shape_string(const std::vector<std::int64_t>& shape) {
  std::string text = "[";
  for (std::size_t index = 0; index < shape.size(); ++index) {
    text += (index == 0 ? "" : ", ") + std::to_string(shape[index]);
  }
  return text + "]";
}

const char* dtype_name(const pcie::TensorDType dtype) {
  switch (dtype) {
  case pcie::TensorDType::UInt8:
    return "UINT8";
  case pcie::TensorDType::Int8:
    return "INT8";
  case pcie::TensorDType::UInt16:
    return "UINT16";
  case pcie::TensorDType::Int16:
    return "INT16";
  case pcie::TensorDType::Int32:
    return "INT32";
  case pcie::TensorDType::BFloat16:
    return "BF16";
  case pcie::TensorDType::Float32:
    return "FP32";
  case pcie::TensorDType::Float64:
    return "FP64";
  }
  return "UNKNOWN";
}

pcie::Tensor make_yolo_tensor(const cv::Mat& bgr, const pcie::TensorInfo& input) {
  if (input.shape.size() != 3 || input.shape[2] != 3) {
    throw std::runtime_error("expected a three-channel HWC YOLO input");
  }
  const int target_height = static_cast<int>(input.shape[0]);
  const int target_width = static_cast<int>(input.shape[1]);
  const double scale = std::min(static_cast<double>(target_width) / bgr.cols,
                                static_cast<double>(target_height) / bgr.rows);
  const int resized_width = std::max(1, static_cast<int>(std::round(bgr.cols * scale)));
  const int resized_height = std::max(1, static_cast<int>(std::round(bgr.rows * scale)));

  cv::Mat resized;
  cv::resize(bgr, resized, cv::Size(resized_width, resized_height));
  cv::Mat letterboxed(target_height, target_width, CV_8UC3, cv::Scalar(114, 114, 114));
  const int left = (target_width - resized_width) / 2;
  const int top = (target_height - resized_height) / 2;
  resized.copyTo(letterboxed(cv::Rect(left, top, resized_width, resized_height)));

  cv::Mat rgb;
  cv::cvtColor(letterboxed, rgb, cv::COLOR_BGR2RGB);
  cv::Mat normalized;
  rgb.convertTo(normalized, CV_32FC3, 1.0 / 255.0);
  if (!normalized.isContinuous()) {
    normalized = normalized.clone();
  }
  const auto* begin = normalized.ptr<float>();
  std::vector<float> values(begin, begin + normalized.total() * normalized.channels());
  return pcie::Tensor::from_vector(std::move(values), input.shape, input.name);
}

} // namespace

int main(int argc, char** argv) {
  try {
    const int card_id = parse_card(argc, argv);
    if (!std::filesystem::is_regular_file(kModelPath)) {
      throw std::runtime_error(std::string("model does not exist: ") + kModelPath);
    }
    const cv::Mat image = cv::imread(kImagePath, cv::IMREAD_COLOR);
    if (image.empty()) {
      throw std::runtime_error(std::string("OpenCV could not decode: ") + kImagePath);
    }

    // CORE LOGIC
    pcie::ConnectionOptions connection;
    connection.card_id = card_id;
    pcie::Model model(kModelPath, {}, connection);
    const auto info = model.info();
    if (info.inputs.size() != 1) {
      throw std::runtime_error("YOLOv8s must expose one input tensor");
    }
    const pcie::Tensor input = make_yolo_tensor(image, info.inputs[0]);
    model.build(kBuildTimeoutMs);
    const auto outputs = model.run(input, kRunTimeoutMs);
    if (outputs.empty()) {
      throw std::runtime_error("tensor mode returned no outputs");
    }
    std::cout << "Tensor mode raw outputs:\n";
    for (const auto& output : outputs) {
      std::cout << "  " << output.route.name << " " << dtype_name(output.dtype) << " "
                << shape_string(output.shape) << '\n';
    }
    model.close();

    std::cout << "[OK] 024_run_tensor_mode\n";
    return 0;
  } catch (const std::exception& error) {
    std::cerr << "[FAIL] " << error.what() << '\n';
    return 1;
  }
}

Image Mode

pcie_host/tutorials/024_run_your_first_model_over_pcie/run_image_mode.cpp

// Run YOLOv8s image-mode inference over PCIe.
//
// Usage:
//   tutorial_024_run_image_mode [--card 0]

#include <simaai/neat/pcie/Model.h>

#include <opencv2/imgcodecs.hpp>

#include <cstdint>
#include <cstdlib>
#include <filesystem>
#include <iostream>
#include <stdexcept>
#include <string>
#include <vector>

namespace pcie = simaai::neat::pcie;

namespace {

constexpr int kBuildTimeoutMs = 180000;
constexpr int kRunTimeoutMs = 30000;
constexpr char kModelPath[] = "yolo_v8s_mpk.tar.gz";
constexpr char kImagePath[] = "share/sima-pcie-host/tutorials/assets/street-scene.png";

int parse_card(const int argc, char** argv) {
  int card_id = 0;
  for (int index = 1; index < argc; ++index) {
    const std::string arg = argv[index];
    if (arg == "--card" && index + 1 < argc) {
      card_id = std::stoi(argv[++index]);
    } else if (arg == "-h" || arg == "--help") {
      std::cout << "Usage: " << argv[0] << " [--card 0]\n";
      std::exit(0);
    } else {
      throw std::runtime_error("unknown or incomplete argument: " + arg);
    }
  }
  return card_id;
}

std::string shape_string(const std::vector<std::int64_t>& shape) {
  std::string text = "[";
  for (std::size_t index = 0; index < shape.size(); ++index) {
    text += (index == 0 ? "" : ", ") + std::to_string(shape[index]);
  }
  return text + "]";
}

const char* dtype_name(const pcie::TensorDType dtype) {
  switch (dtype) {
  case pcie::TensorDType::UInt8:
    return "UINT8";
  case pcie::TensorDType::Int8:
    return "INT8";
  case pcie::TensorDType::UInt16:
    return "UINT16";
  case pcie::TensorDType::Int16:
    return "INT16";
  case pcie::TensorDType::Int32:
    return "INT32";
  case pcie::TensorDType::BFloat16:
    return "BF16";
  case pcie::TensorDType::Float32:
    return "FP32";
  case pcie::TensorDType::Float64:
    return "FP64";
  }
  return "UNKNOWN";
}

} // namespace

int main(int argc, char** argv) {
  try {
    const int card_id = parse_card(argc, argv);
    if (!std::filesystem::is_regular_file(kModelPath)) {
      throw std::runtime_error(std::string("model does not exist: ") + kModelPath);
    }
    const cv::Mat image = cv::imread(kImagePath, cv::IMREAD_COLOR);
    if (image.empty()) {
      throw std::runtime_error(std::string("OpenCV could not decode: ") + kImagePath);
    }

    // CORE LOGIC
    pcie::ConnectionOptions connection;
    connection.card_id = card_id;
    pcie::ModelOptions options;
    options.preprocess.kind = pcie::InputKind::Image;
    options.preprocess.color_convert.input_format = pcie::ColorFormat::BGR;
    options.preprocess.color_convert.output_format = pcie::ColorFormat::RGB;
    options.preprocess.resize.enable = pcie::AutoFlag::On;
    options.preprocess.resize.mode = pcie::ResizeMode::Letterbox;
    options.preprocess.normalize.preset = pcie::NormalizePreset::COCO_YOLO;
    pcie::Model model(kModelPath, options, connection);
    model.build(kBuildTimeoutMs);
    const auto outputs = model.run(image, kRunTimeoutMs);
    if (outputs.empty()) {
      throw std::runtime_error("image mode returned no outputs");
    }
    std::cout << "Image mode raw outputs:\n";
    for (const auto& output : outputs) {
      std::cout << "  " << output.route.name << " " << dtype_name(output.dtype) << " "
                << shape_string(output.shape) << '\n';
    }
    model.close();

    std::cout << "[OK] 024_run_image_mode\n";
    return 0;
  } catch (const std::exception& error) {
    std::cerr << "[FAIL] " << error.what() << '\n';
    return 1;
  }
}

Image Boxdecode

pcie_host/tutorials/024_run_your_first_model_over_pcie/run_image_boxdecode.cpp

// Run YOLOv8s image inference with card-side box decode over PCIe.
//
// Usage:
//   tutorial_024_run_image_boxdecode [--card 0]

#include <simaai/neat/pcie/Model.h>

#include <opencv2/imgcodecs.hpp>

#include <algorithm>
#include <cstdint>
#include <cstring>
#include <cstdlib>
#include <filesystem>
#include <iomanip>
#include <iostream>
#include <stdexcept>
#include <string>
#include <vector>

namespace pcie = simaai::neat::pcie;

namespace {

constexpr int kBuildTimeoutMs = 180000;
constexpr int kRunTimeoutMs = 30000;
constexpr char kModelPath[] = "yolo_v8s_mpk.tar.gz";
constexpr char kImagePath[] = "share/sima-pcie-host/tutorials/assets/street-scene.png";

int parse_card(const int argc, char** argv) {
  int card_id = 0;
  for (int index = 1; index < argc; ++index) {
    const std::string arg = argv[index];
    if (arg == "--card" && index + 1 < argc) {
      card_id = std::stoi(argv[++index]);
    } else if (arg == "-h" || arg == "--help") {
      std::cout << "Usage: " << argv[0] << " [--card 0]\n";
      std::exit(0);
    } else {
      throw std::runtime_error("unknown or incomplete argument: " + arg);
    }
  }
  return card_id;
}

struct Box {
  int x;
  int y;
  int width;
  int height;
  float score;
  int class_id;
};

template <typename T> T read_value(const std::uint8_t* data) {
  T value{};
  std::memcpy(&value, data, sizeof(value));
  return value;
}

std::vector<Box> parse_boxes(const pcie::TensorList& outputs) {
  if (outputs.size() != 1 || outputs[0].data == nullptr || outputs[0].byte_offset < 0) {
    throw std::runtime_error("boxdecode must return one populated BBOX tensor");
  }
  const auto& tensor = outputs[0];
  const auto offset = static_cast<std::size_t>(tensor.byte_offset);
  if (offset > tensor.size_bytes || tensor.size_bytes - offset < sizeof(std::uint32_t)) {
    throw std::runtime_error("BBOX tensor is too small");
  }
  const auto* bytes = static_cast<const std::uint8_t*>(tensor.data) + offset;
  const std::size_t available = tensor.size_bytes - offset;
  const std::uint32_t count = read_value<std::uint32_t>(bytes);
  constexpr std::size_t record_size = 24;
  if (count > (available - 4) / record_size) {
    throw std::runtime_error("BBOX detection count exceeds its payload");
  }
  std::vector<Box> boxes;
  boxes.reserve(count);
  for (std::uint32_t index = 0; index < count; ++index) {
    const auto* record = bytes + 4 + index * record_size;
    boxes.push_back({read_value<std::int32_t>(record), read_value<std::int32_t>(record + 4),
                     read_value<std::int32_t>(record + 8), read_value<std::int32_t>(record + 12),
                     read_value<float>(record + 16), read_value<std::int32_t>(record + 20)});
  }
  return boxes;
}

std::string class_name(const int class_id) {
  switch (class_id) {
  case 0:
    return "person";
  case 1:
    return "bicycle";
  case 2:
    return "car";
  case 3:
    return "motorcycle";
  case 5:
    return "bus";
  case 7:
    return "truck";
  default:
    return "class_" + std::to_string(class_id);
  }
}

} // namespace

int main(int argc, char** argv) {
  try {
    const int card_id = parse_card(argc, argv);
    if (!std::filesystem::is_regular_file(kModelPath)) {
      throw std::runtime_error(std::string("model does not exist: ") + kModelPath);
    }
    const cv::Mat image = cv::imread(kImagePath, cv::IMREAD_COLOR);
    if (image.empty()) {
      throw std::runtime_error(std::string("OpenCV could not decode: ") + kImagePath);
    }

    // CORE LOGIC
    pcie::ConnectionOptions connection;
    connection.card_id = card_id;
    pcie::ModelOptions options;
    options.preprocess.kind = pcie::InputKind::Image;
    options.preprocess.color_convert.input_format = pcie::ColorFormat::BGR;
    options.preprocess.color_convert.output_format = pcie::ColorFormat::RGB;
    options.preprocess.resize.enable = pcie::AutoFlag::On;
    options.preprocess.resize.mode = pcie::ResizeMode::Letterbox;
    options.preprocess.normalize.preset = pcie::NormalizePreset::COCO_YOLO;
    options.decode_type = pcie::BoxDecodeType::YoloV8;
    options.score_threshold = 0.25F;
    options.nms_iou_threshold = 0.45F;
    options.top_k = 100;
    pcie::Model model(kModelPath, options, connection);
    model.build(kBuildTimeoutMs);
    const auto boxes = parse_boxes(model.run(image, kRunTimeoutMs));
    std::cout << "Image + boxdecode detections=" << boxes.size() << '\n';
    for (std::size_t index = 0; index < std::min<std::size_t>(boxes.size(), 10); ++index) {
      const auto& box = boxes[index];
      std::cout << "  " << class_name(box.class_id) << " score=" << std::fixed
                << std::setprecision(3) << box.score << " box=(" << box.x << ", " << box.y << ", "
                << box.width << ", " << box.height << ")\n";
    }
    if (boxes.empty()) {
      throw std::runtime_error("no detections passed the score threshold");
    }
    model.close();

    std::cout << "[OK] 024_run_image_boxdecode\n";
    return 0;
  } catch (const std::exception& error) {
    std::cerr << "[FAIL] " << error.what() << '\n';
    return 1;
  }
}

ソース

• C++ — Tensor Mode
• C++ — Image Mode
• C++ — Image Boxdecode
• Python — Tensor Mode
• Python — Image Mode
• Python — Image Boxdecode
• README