BLOB 字段中的嵌入

ArcGIS 工作流中的嵌入以固定精度数值矢量的形式保留并存储在名为 Embedding 的地理数据库二进制大型对象 (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 要素服务 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 中，嵌入以固定维度 Float32 矢量形式存储，编码为地理数据库 BLOB 字段中的连续小端二进制数据。

利用 ArcPy 和 ArcGIS API for Python，嵌入可在文件地理数据库和托管要素服务之间被确定性地写入与重建，同时保持与 ArcGIS 平台标准的完全兼容。