BLOB フィールドでのエンベディング

ArcGIS ワークフローでのエンベディングは、Embedding という名前のジオデータベースの Binary Large Object (BLOB) フィールドに保存される、固定精度の数値ベクターとして保存されます。この表現はコンパクト、効率的、プラットフォームに中立で、ランタイムやプログラミング言語間で高性能な読み取り/書き込み/クエリー操作を行うために最適化されています。

エンベディングの格納形式

エンベディングは、ヘッダー、区切り文字、またはメタデータを含まない、連続したリトルエンディアン IEEE-754 32 ビット浮動小数点 (Float32) 値として保存されます。各エレメントは正確に 4 バイトを占有します。

エンベディングの保存方法

概念的な表現

エンベディングは、論理的には数値ベクターです。

E = [e0, e1, e2, …, e(D-1)]

ディスク上では、エンベディングは未加工のバイト列として保存されます。

[e0] [e1] [e2] ... [e(D-1)]

エンベディングのディメンション D はモデルごとに固定されています。

Expected payload size = D * 4 bytes

REST および JSON による転送

エンベディングをテキストのみのチャネル経由 (JSON ペイロード、ArcGIS Feature Service REST API など) で送信する必要がある場合は、同じバイナリーペイロードが Base64 エンコードされた文字列として転送されます。保存されているジオデータベースの値は未加工のバイナリーのままであり、バイナリーのレイアウトは変更されません。

フィーチャクラスへのエンベディングの書き込み

embedding = np.array([0.12, -0.98, 1.42, 0.33], dtype='<f4')
embedding_bytes = np.asarray(embedding, dtype='<f4', order='C').tobytes()
with arcpy.da.InsertCursor(
 feature_class_path,
 ["SHAPE@", "Name", "Embedding"]
) as cursor:
 cursor.insertRow([geometry, "Sample Feature", embedding_bytes])

エンベディングの読み取り

保存されたエンベディングを次のように読み取って検証します:

# Embedding Dimension
D = 4
with arcpy.da.SearchCursor(feature_class, ["Embedding"]) as cursor:
 for row in cursor:
     blob_bytes = row[0]
     if blob_bytes is None:
         continue
     if len(blob_bytes) % 4 != 0:
         raise ValueError("Invalid embedding payload size.")
     if len(blob_bytes) != D * 4:
         raise ValueError("Unexpected embedding dimension.")
     embedding = np.frombuffer(blob_bytes, dtype='<f4')
     print(embedding)

検証要件

エンベディングベクターを再構築する前に、以下を実行します:

len(blob_bytes) == D * 4 を確認する
常にリトルエンディアンであることを確認する

ベストプラクティス

以下では、エンベディングを操作する際のベストプラクティスについて説明します。

明示的なデータタイプを強制します。
```
np.asarray(embedding, dtype='<f4', order='C')
```
モデルのディメンションを一定に保ちます。
エンベディングのディメンション D は、モデルのバージョンごとに固定されている必要があります。
プラットフォーム固有の直列化を行わないようにします。保存に Pickle や JSON 数値配列を使用したり、明示的な <f4 なしで構造体をパッキングしたりしないでください。サポートされている唯一の形式は Contiguous little-endian IEEE-754 float32 bytes です。

まとめ

ArcGIS Pro では、エンベディングはジオデータベースの BLOB フィールド内に、連続したリトルエンディアンのバイナリーデータとしてエンコードされた固定ディメンションの Float32 ベクターとして保存されます。

ArcPy と ArcGIS API for Python を使用することで、ファイルジオデータベースとホストフィーチャサービスの間でエンベディングを確実に書き込んで再構築でき、ArcGIS プラットフォーム規格との完全な互換性を維持できます。