Incorporaciones en campos BLOB

Las incorporaciones en los flujos de trabajo de ArcGIS se mantienen como vectores numéricos de precisión fija almacenados en un campo BLOB (objeto binario grande) de geodatabase denominado Embedding. La representación es compacta, eficiente e independiente de la plataforma, y está optimizada para operaciones de lectura/escritura/consulta de alto rendimiento en todo tipo de entornos de ejecución y lenguajes de programación.

Formato de almacenamiento de incorporaciones

Las incorporaciones se almacenan como valores de punto flotante de 32 bits (Float32) de tipo little-endian contiguos (Float32) sin cabeceras, delimitadores ni metadatos. Cada elemento ocupa exactamente 4 bytes.

Representación conceptual

Desde un punto de vista lógico, una incorporación es un vector numérico.

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

La incorporación se almacena en el disco como una secuencia de bytes en bruto.

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

La dimensión de incrustación D es fija para cada modelo.

Expected payload size = D * 4 bytes

Transporte a través de REST y JSON

Cuando las incorporaciones deben transmitirse por canales de solo texto (por ejemplo, cargas útiles JSON o API REST de ArcGIS Feature Service), la misma carga útil binaria se transporta como una cadena codificada en Base64. El valor almacenado de la geodatabase permanece como datos binarios en bruto, y la disposición binaria no cambia.

Escritura de una incorporación a una clase de entidad

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])

Lectura de una incorporación

Lea y verifique la incorporación almacenada de la siguiente manera:

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

Requisitos de validación

Antes de reconstruir el vector de incorporación, haga lo siguiente:

• Confirme len(blob_bytes) == D * 4

• Compruebe siempre el formato little-endian

Prácticas recomendadas

A continuación se describen las mejores prácticas para trabajar con incorporaciones.

• Imponga un tipo de dato explícito.

  np.asarray(embedding, dtype='<f4', order='C')
  

• Mantenga la coherencia de las dimensiones del modelo.

• La dimensión de la incorporación D debe permanecer fija para cada versión del modelo.

• Evite la serialización específica de la plataforma. No use pickle, arreglos numéricos JSON para almacenamiento, empaquetado de estructuras sin explicitar <f4, etc. El único formato admitido es el siguiente: Contiguous little-endian IEEE-754 float32 bytes

Conclusión

En ArcGIS Pro, las incorporaciones se almacenan como vectores Float32 de dimensión fija codificados como datos binarios little-endian contiguos dentro de un campo BLOB de una geodatabase.

Utilizando ArcPy y la API de ArcGIS para Python, las incorporaciones pueden escribirse y reconstruirse de forma determinista a través de geodatabases de archivos y servicios de funcionalidades alojados sin perder ni un ápice de compatibilidad con los estándares de la plataforma ArcGIS.