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

Struct の配列によるデータモデル設計

現代の AI アプリケーションでは、特にモノのインターネット(IoT)や自動運転において、タイムスタンプとベクトル埋め込みを持つセンサー読み取り値、エラーコードと音声スニペットを持つ診断ログ、位置・速度・シーンコンテキストを持つ走行セグメントなど、豊かで構造化されたイベントを対象に推論することが一般的です。このため、データベースにはネストされたデータの取り込みと検索をネイティブにサポートすることが求められます。

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

Struct の配列を使用する理由​

自動運転からマルチモーダル検索まで、現代の AI アプリケーションはネストされた異種データにますます依存しています。従来のフラットなデータモデルでは、「1 つの文書に多数の注釈付きチャンクが含まれる」や「1 つの運転シーンで複数の観測された操作が行われる」といった複雑な関係を表現するのが困難です。Zilliz Cloud の Struct の配列データ型は、まさにこのような場面で真価を発揮します。

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

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

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

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

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

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

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

Struct スキーマを定義する​

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

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

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

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

値を過度に大きくするとメモリが浪費されます。また、配列フィールド内の 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)モデルのトレーニングと評価のための豊富な基盤を提供します。各データポイントは通常、動画クリップであり、生の視覚入力だけでなく、次を説明する構造化キャプションも含みます。

  • 自車両の動作(例: 「対向車に道を譲りながら左に合流する」)

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

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

この階層的でマルチモーダルな性質により、Struct の配列機能に最適です。CoVLA データセットの詳細については、CoVLA データセットのウェブサイト を参照してください。

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

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

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

plaintext
├── 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 フィールドまたは Struct の配列フィールドのいずれかを使用して、コレクションスキーマ内にネストされた構造を作成できます。ネストされた形式にベクトル埋め込みが含まれる場合、サポートされるのは Struct の配列フィールドのみです。ただし、配列内の Struct 自体にさらにネストされた Struct を含めることはできません。Milvus v3.0.x と互換性のある Dedicated クラスターでは、1 レベルのネストを持つスカラー配列サブフィールドを含めることができます(On-Demand クラスターではまだ利用できません)。重要な関係を維持したまま CoVLA データセットを保存するには、不要な階層を削除し、Zilliz Cloud のコレクションスキーマに適合するようにデータをフラット化する必要があります。

The diagram below illustrates how we can model this dataset using the スキーマ illustrated in the following スキーマ:

データセットモデル

上の図は、次のフィールドで構成される動画クリップの構造を示しています。

  • video_id は主キーとして機能し、動画識別子を VARCHAR 値として格納します。

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

  • captions は Struct の配列であり、各 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 も Struct の配列であり、現在のフレームで識別されたすべての先行車を含みます。

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

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

キャプション Struct のスキーマを初期化します。

python
from pymilvus import MilvusClient, DataType
import json
from openai import OpenAI

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT", token="YOUR_CLUSTER_TOKEN")

# 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"
)

先行車 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 フィールドで JSON shredding を有効にすることをお勧めします。

ステップ 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)が含まれます。

これらのファイルから各動画クリップのデータ部分をマージし、データを挿入する必要があります。以下は、特定の動画クリップのデータ部分をマージするためのスクリプトです。スキーマに一致する、768 次元のベクトルを返すモデルと、OpenAI 互換の埋め込みエンドポイントを設定してください。ファイル処理の例では Python を使用しています。以下の挿入例は SDK リクエストの形式を示しています。Python 以外の挿入例に含まれる合成ベクトルはペイロード構造を説明するためのものであり、検索用の埋め込みに置き換える必要があります。

python
import json
from openai import OpenAI

openai_client = OpenAI(
base_url='YOUR_EMBEDDING_API_BASE_URL',
api_key='YOUR_EMBEDDING_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="YOUR_768_DIMENSION_EMBEDDING_MODEL"):
response = openai_client.embeddings.create(input=text, model=model)
vector = response.data[0].embedding
if len(vector) != 768:
raise ValueError("The configured embedding model must return 768 dimensions")
return vector

# 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']}