> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/ja/serufuhosuto/enterprise/stream-management-api.md).

# ストリーム管理 API

{% hint style="warning" %}
**単独サービスとしては提供終了です。** Inference SDK WebRTC クライアントを、 [Inference Server](/deployment/ja/serufuhosuto/inference-server.md) 現在の動画ストリーミングのデプロイに使用します。同じクライアントで、セルフホストおよびサーバーレスのランタイム上でモデルと Workflows を実行できます。参照: [動画処理](https://docs.roboflow.com/workflows/deploy/video-processing).
{% endhint %}

{% hint style="warning" %}
**エンタープライズ機能。** このページのスタンドアロンサービスを本番環境で使用するには、Roboflow Enterprise ライセンスが必要です。参照: [Roboflow Licensing](https://roboflow.com/licensing) 詳細をご覧ください。これは上記で説明した統合動画管理 API には適用されません。
{% endhint %}

## 概要

Stream Management API は、オンライン動画ストリーム上の Roboflow 物体検出モデルから予測を生成しました。動画ワーカーをリモート制御するための HTTP 管理レイヤーを追加しました。

これは、以下を含むがこれらに限定されないシナリオで役立ちます:

* 複数のオンライン動画ストリームに対して同時に推論を実行する。
* 連携が必要な複数のデバイスで推論を実行する。
* 動画処理を監視するための監視レイヤーを構築する。

![Stream Management の設計](https://storage.googleapis.com/com-roboflow-marketing/inference/stream_management_api_design.jpg)

### 使用例

Joe は、自社工場に設置された IP カメラ群で撮影した映像内の物体を監視したいと考えています。Roboflow プラットフォームで物体検出モデルを学習した後、デプロイの準備が整いました。工場に 4 台のカメラがあるため、Joe は Jetson デバイス上で 1 秒あたり 30 回以上の推論に十分対応できるコンパクトなモデルを選びます。デバイスごとの計算予算を踏まえると、すべてのカメラの映像を処理するには 2 台の Jetson デバイスが必要で、各動画ソースあたりおよそ毎秒 15 フレームで処理します。

デプロイを簡素化するために、Joe はローカルネットワーク内のすべての Jetson デバイスに Stream Management コンテナをデプロイします。これにより、HTTP 経由で各デバイスと通信して処理タスクをオーケストレーションできます。彼は、デバイスにコマンドを送信し、各動画ストリームの状態に関するメトリクスを取得する Web アプリを構築します。最後に、予測を受信する UDP サーバーを実装し、 `supervision` パッケージを使って映像内の物体を追跡します。

## 実行方法

### Docker で `docker compose`

最も一般的なユースケースは Docker Compose 設定としてパッケージ化されています。カメラデバイスのパススルーなど、コンテナ内でカスタム設定が必要な場合は、下の別コンテナ方式のオプションのほうが適している場合があります。

{% tabs %}
{% tab title="CPU" %}

```bash
docker compose -f ./docker/dockerfiles/stream-management-api.compose-cpu.yaml up
```

{% endtab %}

{% tab title="GPU" %}

```bash
docker compose -f ./docker/dockerfiles/stream-management-api.compose-gpu.yaml up
```

{% endtab %}

{% tab title="Jetson（JetPack 5.1.1）" %}

```bash
docker compose -f ./docker/dockerfiles/stream-management-api.compose-jetson.5.1.1.yaml up
```

Jetson デバイスでは、コンテナの初期起動やモデル初期化などの一部の操作に、他のプラットフォームより時間がかかります。Docker Compose 定義は現時点では Stream Manager の TCP ソケットポートが開くのを待たないため、HTTP API への最初のリクエストは HTTP 503 で応答される場合があります。
{% endtab %}
{% endtabs %}

### Docker で、API と Stream Manager を別々に実行する

{% tabs %}
{% tab title="CPU" %}

```bash
docker run -d --name stream_manager --network host roboflow/roboflow-inference-stream-manager-cpu:latest
docker run -d --name stream_management_api --network host roboflow/roboflow-inference-stream-management-api:latest
```

{% endtab %}

{% tab title="GPU" %}

```bash
docker run -d --name stream_manager --network host --runtime nvidia roboflow/roboflow-inference-stream-manager-gpu:latest
docker run -d --name stream_management_api --network host roboflow/roboflow-inference-stream-management-api:latest
```

{% endtab %}

{% tab title="Jetson（JetPack 5.1.1）" %}

```bash
docker run -d --name stream_manager --network host --runtime nvidia roboflow/roboflow-inference-stream-manager-jetson-5.1.1:latest
docker run -d --name stream_management_api --network host roboflow/roboflow-inference-stream-management-api:latest
```

{% endtab %}
{% endtabs %}

#### 設定パラメータ

**ストリーム管理API**

* `STREAM_MANAGER_HOST` - Stream Manager コンテナのホスト名。もし `--network host` を使用しない場合、またはリモートマシンを対象とする場合は、コンテナ名に変更してください。
* `STREAM_MANAGER_PORT` - Stream Manager と通信するために使用するポート。Stream Manager コンテナと一致している必要があります。

**Stream Manager**

* `PORT` - サーバーが実行されるポート。
* コンテナの `/tmp/cache` にボリュームをマウントすると、モデルを永続保存でき、推論パイプラインの初期化を高速化できます。
* カメラ接続はこのコンテナのレベルで有効にする必要があります。したがって、デバイスを Docker に渡す必要がある場合は、ここで行ってください。

#### イメージのビルド（任意）

```bash
# ストリーム管理 API
docker build -t roboflow/roboflow-inference-stream-management-api:dev -f docker/dockerfiles/Dockerfile.stream_management_api .

# Stream Manager
docker build -t roboflow/roboflow-inference-stream-manager-{device}:dev -f docker/dockerfiles/Dockerfile.onnx.{device}.stream_manager .
```

### ベアメタル展開

場合によっては、アプリケーションをホストレベルでデプロイする必要があります。これは可能ですが、プラットフォームに応じて Stream Manager と Stream Management API の dockerfile が行っているのと同じ方法で環境を整える必要があります。完了したら、次を実行します:

```bash
python -m inference.enterprise.stream_management.manager.app  # マネージャーを実行
python -m inference.enterprise.stream_management.api.app      # 管理 API を実行
```

## 統合方法

を実行した後、 `roboflow-inference-stream-management-api` コンテナでは、HTTP API は `http://127.0.0.1:8080` のデフォルト設定で利用できます。

呼び出して `wget http://127.0.0.1:8080/openapi.json` API の OpenAPI 仕様を取得します。これは [Swagger エディタ](https://editor.swagger.io/).

Python クライアントの例:

```python
import requests
from typing import Optional

URL = "http://127.0.0.1:8080"

def list_pipelines() -> dict:
    response = requests.get(f"{URL}/list_pipelines")
    return response.json()


def get_pipeline_status(pipeline_id: str) -> dict:
    response = requests.get(f"{URL}/status/{pipeline_id}")
    return response.json()


def pause_pipeline(pipeline_id: str) -> dict:
    response = requests.post(f"{URL}/pause/{pipeline_id}")
    return response.json()


def resume_pipeline(pipeline_id: str) -> dict:
    response = requests.post(f"{URL}/resume/{pipeline_id}")
    return response.json()


def terminate_pipeline(pipeline_id: str) -> dict:
    response = requests.post(f"{URL}/terminate/{pipeline_id}")
    return response.json()


def initialise_pipeline(
    video_reference: str,
    model_id: str,
    api_key: str,
    sink_host: str,
    sink_port: int,
    max_fps: Optional[int] = None,
) -> dict:
    response = requests.post(
        f"{URL}/initialise",
        json={
            "type": "init",
            "sink_configuration": {
                "type": "udp_sink",
                "host": sink_host,
                "port": sink_port,
            },
            "video_reference": video_reference,
            "model_id": model_id,
            "api_key": api_key,
            "max_fps": max_fps,
        },
    )
    return response.json()
```

{% hint style="info" %}
`initialise_pipeline()` には `video_reference` および `sink_configuration` 各リソース（動画ファイルまたはカメラデバイス）と URI（ストリーム参照、シンク参照）が **Stream Manager 環境から到達可能である**必要があります。たとえば Docker コンテナ内では、 `localhost` ホストマシンの localhost ではなく、コンテナの localhost にバインドされます。
{% endhint %}

## 開発者向けメモ

実装の中心となる要素は Stream Manager コンポーネントで、これはシングルスレッドの TCP サーバーとして動作します。TCP ソケットから受信したリクエストを処理し、動画ワーカープロセスを監督します。マルチプロセッシングキューは、ワーカーと Stream Manager の間でコマンドと結果をやり取りします。

Stream Manager へのリクエストはブロッキングモードで順次処理されるため、各リクエストは次のリクエストが開始される前に完了していなければなりません。

### 通信プロトコル: リクエスト

Stream Manager は次のバイナリプロトコルを受け付けます。各ペイロードには以下が含まれます:

```
[HEADER: 4B, big-endian, unsigned - int value with message size][MESSAGE: utf-8 serialised json of size dictated by header]
```

メッセージはデコード後に有効な JSON であり、有効なコマンドを表していなければなりません。

**`list_pipelines`**

```json
{
  "type": "list_pipelines"
}
```

**`init`**

```json
{
  "type": "init",
  "model_id": "some/1",
  "video_reference": "rtsp://192.168.0.1:554",
  "sink_configuration": {
    "type": "udp_sink",
    "host": "192.168.0.3",
    "port": 9999
  },
  "api_key": "YOUR_API_KEY",
  "max_fps": 16,
  "model_configuration": {
    "type": "object-detection",
    "class_agnostic_nms": true,
    "confidence": 0.5,
    "iou_threshold": 0.4,
    "max_candidates": 300,
    "max_detections": 3000
  },
  "video_source_properties": {
    "frame_width": 1920,
    "frame_height": 1080,
    "fps": 30
  }
}
```

{% hint style="info" %}
モデル ID は次の文字列で構成されます `<project_id>/<version_id>`。「 [model IDs](https://docs.roboflow.com/models/model-ids) これらの値を確認してください。
{% endhint %}

**`終了`**

```json
{
  "type": "terminate",
  "pipeline_id": "my_pipeline"
}
```

**`一時停止`**

```json
{
  "type": "mute",
  "pipeline_id": "my_pipeline"
}
```

**`再開`**

```json
{
  "type": "resume",
  "pipeline_id": "my_pipeline"
}
```

**`状態`**

```json
{
  "type": "status",
  "pipeline_id": "my_pipeline"
}
```

### 通信プロトコル: レスポンス

処理可能な各リクエスト（タイムアウトやソース切断なし）について、Stream Manager は次の形式で結果を返します:

```
[HEADER: 4B, big-endian, unsigned - int value with result size][RESULT: utf-8 serialised json of size dictated by header]
```

結果には次が含まれます:

* `request_id` - デバッグを容易にするために、Stream Manager によって割り当てられたリクエスト ID を表すランダムな文字列。
* `pipeline_id` - 適用可能な場合、そのコマンドが関連付けられているパイプライン。
* `response` - 操作応答のペイロード。

各 `response` には `状態` 次の 2 つの値のいずれかを持つ key があります: `success` または `failure`。失敗した応答には各種エラー処理を振り分けるための `error_type` key と、必要に応じて `error_class` および `error_message` という、エラーの内部詳細を示すフィールドが含まれます。成功した応答の内容は操作の種類によって異なります。

## 今後の課題

* 安全なリモート制御を可能にするため、API 接続層を保護する。
* Stream Manager の TCP ソケットを保護する。