メインコンテンツまでスキップ

Array of Structs を使用したデータモデル設計

モダンな AI アプリケーション、特にモノのインターネット（IoT）や自動運転では、通常、タイムスタンプとベクトル埋め込みを伴うセンサー読み取り値、エラーコードと音声スニペットを伴う診断ログ、位置・速度・シーンコンテキストを伴う走行区間など、豊富で構造化されたイベントを推論します。これには、データベースがネストされたデータの取り込みと検索をネイティブにサポートすることが必要です。

ユーザーに原子的な構造イベントをフラットなデータモデルへ変換させる代わりに、Zilliz Cloud は Array of Structs を導入します。配列内の各 Struct はスカラーとベクトルを保持でき、意味的な整合性を維持します。

Array of Structs を使用する理由​

自動運転からマルチモーダル検索まで、モダンな AI アプリケーションはネストされた異種データにますます依存しています。従来のフラットなデータモデルでは、「多数の注釈付きチャンクを含む 1 つのドキュメント」や「複数の観測された操作を含む 1 つの運転シーン」のような複雑な関係を表現するのは困難です。ここで、Zilliz Cloud の Array of Structs データ型が威力を発揮します。

Array of Structs を使用すると、構造化要素の順序付きセットを保存できます。各 Struct はスカラーフィールドとベクトル埋め込みの独自の組み合わせを保持します。このため、次の用途に最適です。

  • 階層データ: 多数の子レコードを持つ親エンティティです。たとえば、多数のテキストチャンクを含む書籍や、多数の注釈付きフレームを含む動画などがあります。

  • マルチモーダル埋め込み: 各 Struct は、メタデータとともに、テキスト埋め込みと画像埋め込みなどの複数のベクトルを保持できます。

  • 時間的または順序データ: Array フィールド内の Struct は、時系列イベントや段階的なイベントを自然に表現します。

JSON ブロブを保存したり、データを複数のコレクションに分割したりする従来の回避策とは異なり、Array of Structs は Zilliz Cloud 内でネイティブなスキーマ適用、ベクトルインデックス作成、効率的なストレージを提供します。

スキーマ設計ガイドライン​

検索用のデータモデル設計 で説明されているすべてのガイドラインに加えて、データモデル設計で Array of Structs の使用を開始する前に、次の点も考慮してください。

Struct スキーマを定義する​

コレクションに Array フィールドを追加する前に、内部の Struct スキーマを定義します。Struct 内の各フィールドは、スカラー（VARCHAR、INT、BOOLEAN など）またはベクトル（FLOAT_VECTOR）として明示的に型指定する必要があります。

Struct スキーマは、取得や表示に使用するフィールドのみを含めて簡潔に保つことをお勧めします。未使用のメタデータで肥大化しないでください。

最大容量を慎重に設定する​

各 Array フィールドには、エンティティごとに Array フィールドが保持できる要素の最大数を指定する属性があります。ユースケースの上限に基づいて設定してください。たとえば、ドキュメントごとに 1,000 個のテキストチャンク、運転シーンごとに 100 個の操作がある場合です。

値を過度に大きくするとメモリが浪費されるため、Array フィールド内の Struct の最大数を決めるには計算が必要です。

Struct 内のベクトルフィールドにインデックスを作成する​

ベクトルフィールドには、コレクション内のベクトルフィールドと Struct 内で定義されたベクトルフィールドの両方を含め、インデックス作成が必須です。Struct 内のベクトルフィールドには、インデックスタイプとして AUTOINDEX を、メトリックタイプとして MAX_SIM シリーズを使用する必要があります。

適用されるすべての制限の詳細については、制限 を参照してください。

実例: 自動運転向け CoVLA データセットのモデリング​

Turing Motors によって導入され、Winter Conference on Applications of Computer Vision（WACV）2025 で採択された Comprehensive Vision-Language-Action（CoVLA）データセットは、自動運転における Vision-Language-Action（VLA）モデルのトレーニングと評価のための豊富な基盤を提供します。通常はビデオクリップである各データポイントには、生の視覚入力だけでなく、次の内容を説明する構造化キャプションも含まれています。

  • 自車両の行動（例:「対向車に道を譲りながら左車線に合流する」）、

  • 存在する検出オブジェクト（例: 先行車両、歩行者、信号機）、および

  • シーンのフレームレベルのキャプション。

この階層的でマルチモーダルな性質により、Array of Structs 機能の理想的な対象となります。CoVLA データセットの詳細については、CoVLA Dataset Website を参照してください。

ステップ 1: データセットをコレクションスキーマにマッピングする​

CoVLA データセットは、10,000 個のビデオクリップ、合計 80 時間以上の映像で構成される大規模なマルチモーダル運転データセットです。20Hz のレートでフレームをサンプリングし、各フレームに、詳細な自然言語キャプション、車両状態に関する情報、検出オブジェクトの座標を注釈付けします。

データセットの構造は以下の通りです。

python
├── video_1                                       (VIDEO) # video.mp4
│   ├── video_id                                  (INT)
│   ├── video_url                                 (STRING)
│   ├── frames                                    (ARRAY)
│   │   ├── frame_1                               (STRUCT)
│   │   │   ├── caption                           (STRUCT) # captions.jsonl
│   │   │   │   ├── plain_caption                 (STRING)
│   │   │   │   ├── rich_caption                  (STRING)
│   │   │   │   ├── risk                          (STRING)
│   │   │   │   ├── risk_correct                  (BOOL)
│   │   │   │   ├── risk_yes_rate                 (FLOAT)
│   │   │   │   ├── weather                       (STRING)
│   │   │   │   ├── weather_rate                  (FLOAT)
│   │   │   │   ├── road                          (STRING)
│   │   │   │   ├── road_rate                     (FLOAT)
│   │   │   │   ├── is_tunnel                     (BOOL)
│   │   │   │   ├── is_tunnel_yes_rate            (FLOAT)
│   │   │   │   ├── is_highway                    (BOOL)
│   │   │   │   ├── is_highway_yes_rate           (FLOAT)
│   │   │   │   ├── has_pedestrain                (BOOL)
│   │   │   │   ├── has_pedestrain_yes_rate       (FLOAT)
│   │   │   │   ├── has_carrier_car               (BOOL)
│   │   │   ├── traffic_light                     (STRUCT) # traffic_lights.jsonl
│   │   │   │   ├── index                         (INT)
│   │   │   │   ├── class                         (STRING)
│   │   │   │   ├── bbox                          (LIST<FLOAT>)
│   │   │   ├── front_car                         (STRUCT) # front_cars.jsonl
│   │   │   │   ├── has_lead                      (BOOL)
│   │   │   │   ├── lead_prob                     (FLOAT)
│   │   │   │   ├── lead_x                        (FLOAT)
│   │   │   │   ├── lead_y                        (FLOAT)
│   │   │   │   ├── lead_speed_kmh                (FLOAT)
│   │   │   │   ├── lead_a                        (FLOAT)
│   │   ├── frame_2                               (STRUCT)
│   │   ├── ...                                   (STRUCT)
│   │   ├── frame_n                               (STRUCT)
├── video_2
├── ...
├── video_n

CoVLA データセットの構造は高度に階層化されており、収集されたデータが複数の .jsonl ファイルに分割され、.mp4 形式のビデオクリップも含まれていることがわかります。

Zilliz Cloud では、JSON フィールドまたは Array-of-Structs フィールドのいずれかを使用して、コレクションスキーマ内にネスト構造を作成できます。ベクトル埋め込みがネスト形式の一部である場合、サポートされるのは Array-of-Structs フィールドのみです。ただし、Array 内の Struct 自体にさらにネストされた構造を含めることはできません。CoVLA データセットを重要な関係を維持したまま保存するには、不要な階層を削除し、Zilliz Cloud のコレクションスキーマに適合するようにデータをフラット化する必要があります。

次の図は、後述するスキーマを使用してこのデータセットをモデリングする方法を示しています。

PATjwyoKzhPELnb14kBcnAEAnGv

上の図はビデオクリップの構造を示しており、次のフィールドで構成されています。

  • video_id は主キーとして機能し、INT64 タイプの整数を受け入れます。

  • states は、現在の動画の各フレームにおける自車両の状態を含む生の JSON ボディです。

  • captions は Array of Structs であり、各 Struct は次のフィールドを持ちます。

    • frame_id は、現在の動画内の特定のフレームを識別します。

    • plain_caption は、天候や道路状況などの周囲環境を含まない現在のフレームの説明であり、plain_cap_vector はそれに対応するベクトル埋め込みです。

    • rich_caption は、周囲環境を含む現在のフレームの説明であり、rich_cap_vector はそれに対応するベクトル埋め込みです。

    • risk は、現在のフレームで自車両が直面するリスクの説明であり、risk_vector はそれに対応するベクトル埋め込みです。また、

    • road、weather、is_tunnel、has_pedestrain など、フレームのその他すべての属性です。

  • traffic_lights は、現在のフレームで識別されたすべての信号機を含む JSON ボディです。

  • front_cars も、現在のフレームで識別されたすべての先行車を含む Array of Structs です。

ステップ 2: スキーマを初期化する​

まず、Caption Struct、front_cars Struct、およびコレクションのスキーマを初期化する必要があります。

  • Caption Struct のスキーマを初期化します。

    python
    from pymilvus import MilvusClient, DataType

    client = MilvusClient("YOUR_CLUSTER_ENDPOINT")

    # create the schema for the caption struct
    schema_for_caption = client.create_struct_field_schema()

    schema_for_caption.add_field(
        field_name="frame_id",
        datatype=DataType.INT64,
        description="ID of the frame to which the ego vehicle's behavior belongs"
    )

    schema_for_caption.add_field(
        field_name="plain_caption",
        datatype=DataType.VARCHAR,
        max_length=1024,
        description="plain description of the ego vehicle's behaviors"
    )

    schema_for_caption.add_field(
        field_name="plain_cap_vector",
        datatype=DataType.FLOAT_VECTOR,
        dim=768,
        description="vectors for the plain description of the ego vehicle's behaviors"
    )

    schema_for_caption.add_field(
        field_name="rich_caption",
        datatype=DataType.VARCHAR,
        max_length=1024,
        description="rich description of the ego vehicle's behaviors"
    )

    schema_for_caption.add_field(
        field_name="rich_cap_vector",
        datatype=DataType.FLOAT_VECTOR,
        dim=768,
        description="vectors for the rich description of the ego vehicle's behaviors"
    )

    schema_for_caption.add_field(
        field_name="risk",
        datatype=DataType.VARCHAR,
        max_length=1024,
        description="description of the ego vehicle's risks"
    )

    schema_for_caption.add_field(
        field_name="risk_vector",
        datatype=DataType.FLOAT_VECTOR,
        dim=768,
        description="vectors for the description of the ego vehicle's risks"
    )

    schema_for_caption.add_field(
        field_name="risk_correct",
        datatype=DataType.BOOL,
        description="whether the risk assessment is correct"
    )

    schema_for_caption.add_field(
        field_name="risk_yes_rate",
        datatype=DataType.FLOAT,
        description="probability/confidence of risk being present"
    )

    schema_for_caption.add_field(
        field_name="weather",
        datatype=DataType.VARCHAR,
        max_length=50,
        description="weather condition"
    )

    schema_for_caption.add_field(
        field_name="weather_rate",
        datatype=DataType.FLOAT,
        description="probability/confidence of the weather condition"
    )

    schema_for_caption.add_field(
        field_name="road",
        datatype=DataType.VARCHAR,
        max_length=50,
        description="road type"
    )

    schema_for_caption.add_field(
        field_name="road_rate",
        datatype=DataType.FLOAT,
        description="probability/confidence of the road type"
    )

    schema_for_caption.add_field(
        field_name="is_tunnel",
        datatype=DataType.BOOL,
        description="whether the road is a tunnel"
    )

    schema_for_caption.add_field(
        field_name="is_tunnel_yes_rate",
        datatype=DataType.FLOAT,
        description="probability/confidence of the road being a tunnel"
    )

    schema_for_caption.add_field(
        field_name="is_highway",
        datatype=DataType.BOOL,
        description="whether the road is a highway"
    )

    schema_for_caption.add_field(
        field_name="is_highway_yes_rate",
        datatype=DataType.FLOAT,
        description="probability/confidence of the road being a highway"
    )

    schema_for_caption.add_field(
        field_name="has_pedestrian",
        datatype=DataType.BOOL,
        description="whether there is a pedestrian present"
    )

    schema_for_caption.add_field(
        field_name="has_pedestrian_yes_rate",
        datatype=DataType.FLOAT,
        description="probability/confidence of pedestrian presence"
    )

    schema_for_caption.add_field(
        field_name="has_carrier_car",
        datatype=DataType.BOOL,
        description="whether there is a carrier car present"
    )

  • Front Car Struct のスキーマを初期化します。

    Notes

    先行車にベクトル埋め込みは含まれませんが、データサイズが JSON フィールドの最大値を超えるため、Struct の配列として含める必要があります。

    python
    schema_for_front_car = client.create_struct_field_schema()

    schema_for_front_car.add_field(
        field_name="frame_id",
        datatype=DataType.INT64,
        description="ID of the frame to which the ego vehicle's behavior belongs"
    )

    schema_for_front_car.add_field(
        field_name="has_lead",
        datatype=DataType.BOOL,
        description="whether there is a leading vehicle"
    )

    schema_for_front_car.add_field(
        field_name="lead_prob",
        datatype=DataType.FLOAT,
        description="probability/confidence of the leading vehicle's presence"
    )

    schema_for_front_car.add_field(
        field_name="lead_x",
        datatype=DataType.FLOAT,
        description="x position of the leading vehicle relative to the ego vehicle"
    )

    schema_for_front_car.add_field(
        field_name="lead_y",
        datatype=DataType.FLOAT,
        description="y position of the leading vehicle relative to the ego vehicle"
    )

    schema_for_front_car.add_field(
        field_name="lead_speed_kmh",
        datatype=DataType.FLOAT,
        description="speed of the leading vehicle in km/h"
    )

    schema_for_front_car.add_field(
        field_name="lead_a",
        datatype=DataType.FLOAT,
        description="acceleration of the leading vehicle"
    )

  • コレクションのスキーマを初期化します。

    python
    schema = client.create_schema()

    schema.add_field(
        field_name="video_id",
        datatype=DataType.VARCHAR,
        description="primary key",
        max_length=16,
        is_primary=True,
        auto_id=False
    )

    schema.add_field(
        field_name="video_url",
        datatype=DataType.VARCHAR,
        max_length=512,
        description="URL of the video"
    )

    schema.add_field(
        field_name="captions",
        datatype=DataType.ARRAY,
        element_type=DataType.STRUCT,
        struct_schema=schema_for_caption,
        max_capacity=600,
        description="captions for the current video"
    )

    schema.add_field(
        field_name="traffic_lights",
        datatype=DataType.JSON,
        description="frame-specific traffic lights identified in the current video"
    )

    schema.add_field(
        field_name="front_cars",
        datatype=DataType.ARRAY,
        element_type=DataType.STRUCT,
        struct_schema=schema_for_front_car,
        max_capacity=600,
        description="frame-specific leading cars identified in the current video"
    )

ステップ 3: インデックスパラメーターを設定する​

すべてのベクトルフィールドにインデックスを作成する必要があります。要素 Struct 内のベクトルフィールドにインデックスを作成するには、インデックスタイプとして AUTOINDEX を、埋め込みリスト間の類似度を測定するメトリックタイプとして MAX_SIM シリーズを使用する必要があります。

python
index_params = client.prepare_index_params()

index_params.add_index(
    field_name="captions[plain_cap_vector]", 
    index_type="AUTOINDEX", 
    metric_type="MAX_SIM_COSINE", 
    index_name="captions_plain_cap_vector_idx"
)

index_params.add_index(
    field_name="captions[rich_cap_vector]", 
    index_type="AUTOINDEX", 
    metric_type="MAX_SIM_COSINE", 
    index_name="captions_rich_cap_vector_idx"
)

index_params.add_index(
    field_name="captions[risk_vector]", 
    index_type="AUTOINDEX", 
    metric_type="MAX_SIM_COSINE", 
    index_name="captions_risk_vector_idx"
)

これらのフィールド内のフィルタリングを高速化するために、JSON フィールドで JSON シャーディングを有効にすることをお勧めします。

ステップ 4: コレクションを作成する​

スキーマとインデックスの準備ができたら、次のようにしてターゲットコレクションを作成できます。

python
client.create_collection(
    collection_name="covla_dataset",
    schema=schema,
    index_params=index_params
)

ステップ 5: データを挿入する​

Turing Motos は、CoVLA データセットを、生のビデオクリップ（.mp4）、状態（states.jsonl）、キャプション（captions.jsonl）、信号機（traffic_lights.jsonl）、先行車（front_cars.jsonl）など、複数のファイルに整理しています。

これらのファイルからビデオクリップごとのデータをマージして挿入する必要があります。以下は、特定のビデオクリップのデータをマージするスクリプトです。

python
import json
from openai import OpenAI

openai_client = OpenAI(
    api_key='YOUR_OPENAI_API_KEY',
)

video_id = "0a0fc7a5db365174" # represent a single video with 600 frames

# get all front car records in the specified video clip
entries = []
front_cars = []
with open('data/front_car/{}.jsonl'.format(video_id), 'r') as f:
    for line in f:
        entries.append(json.loads(line))

for entry in entries:
    for key, value in entry.items():
        value['frame_id'] = int(key)
        front_cars.append(value)

# get all traffic lights identified in the specified video clip
entries = []
traffic_lights = []
frame_id = 0
with open('data/traffic_lights/{}.jsonl'.format(video_id), 'r') as f:
    for line in f:
        entries.append(json.loads(line))

for entry in entries:
    for key, value in entry.items():
        if not value or (value['index'] == 1 and key != '0'):
            frame_id+=1

        if value:
            value['frame_id'] = frame_id
            traffic_lights.append(value)
        else:
            value_dict = {}
            value_dict['frame_id'] = frame_id
            traffic_lights.append(value_dict)

# get all captions generated in the video clip and convert them into vector embeddings
entries = []
captions = []
with open('data/captions/{}.jsonl'.format(video_id), 'r') as f:
    for line in f:
        entries.append(json.loads(line))

def get_embedding(text, model="embeddinggemma:latest"):
    response = openai_client.embeddings.create(input=text, model=model)
    return response.data[0].embedding

# Add embeddings to each entry
for entry in entries:
    # Each entry is a dict with a single key (e.g., '0', '1', ...)
    for key, value in entry.items():
        value['frame_id'] = int(key)  # Convert key to integer and assign to frame_id

        if "plain_caption" in value and value["plain_caption"]:
            value["plain_cap_vector"] = get_embedding(value["plain_caption"])
        if "rich_caption" in value and value["rich_caption"]:
            value["rich_cap_vector"] = get_embedding(value["rich_caption"])
        if "risk" in value and value["risk"]:
            value["risk_vector"] = get_embedding(value["risk"])

        captions.append(value)

data = {
    "video_id": video_id,
    "video_url": "https://your-storage.com/{}".format(video_id),
    "captions": captions,
    "traffic_lights": traffic_lights,
    "front_cars": front_cars
}

データを適切に処理したら、次のようにして挿入できます。

python
client.insert(
    collection_name="covla_dataset",
    data=[data]
)

# {'insert_count': 1, 'ids': ['0a0fc7a5db365174']}
このページは役に立ちましたか？
Ctrl I