Skip to main content

Эмбеддинги в полях BLOB

Эмбеддинги в рабочих процессах ArcGIS сохраняются как числовые векторы с фиксированной точностью, хранящиеся в поле Binary Large Object (BLOB) базы геоданных с именем Embedding. Это представление является компактным, эффективным, платформо-независимым и оптимизированным для высокопроизводительных операций чтения/записи/запросов в различных рабочих средах выполнения и языках программирования.

Формат хранения эмбеддингов

Эмбеддинги хранятся как смежные 32-битные числа с плавающей запятой (Float32) в формате little-endian IEEE-754 без заголовков, разделителей или метаданных. Каждый элемент занимает ровно 4 байта.

Как хранятся эмбеддинги

Концептуальное представление

Эмбеддинг логически представляет собой числовой вектор.

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

На диске эмбеддинг хранится как необработанная последовательность байтов.

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

Размерность эмбеддинга D фиксируется для каждой модели.

Expected payload size = D * 4 bytes

Передача через REST и JSON

Когда эмбеддинги должны проходить через текстовые каналы (например, полезные данные JSON или REST API сервиса объектов ArcGIS), те же двоичные полезные данные передаются в виде строки, закодированной в 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 с фиксированной размерностью, закодированные как смежные двоичные данные little-endian внутри поля BLOB базы геоданных.

Используя arcpy и ArcGIS API for Python, эмбеддинги можно записывать и реконструировать детерминированным образом в файловых базах геоданных и размещенных сервисах пространственных объектов, сохраняя при этом полную совместимость со стандартами платформы ArcGIS.