Embeddings dans les champs BLOB

Les embeddings dans les flux de travail ArcGIS sont conservés sous forme de vecteurs numériques à précision fixe stockés dans un champ BLOB (Binary Large Object) de géodatabase nommé Embedding. La représentation est compacte, efficace, neutre par rapport à la plateforme et optimisée pour des opérations de lecture/écriture/requête hautes performances à travers les environnements d’exécution et les langages de programmation.

Format de stockage des embeddings

Les embeddings sont stockés sous forme de valeurs de virgule flottante 32 bits (Float32) IEEE-754 Little Endian contiguës sans en-têtes, délimiteurs ni métadonnées. Chaque élément occupe exactement 4 octets.

Comment les embeddings sont stockés

Représentation conceptuelle

Un embedding est logiquement un vecteur numérique.

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

Sur le disque, l’embedding est stocké sous la forme d’une séquence d’octets brut.

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

La dimension d’embedding D est fixée par modèle.

Expected payload size = D * 4 bytes

Transport via REST et JSON

Lorsque des embeddings doivent traverser des canaux texte uniquement (par exemple, des charges utiles JSON ou des API REST de service d’entités ArcGIS), la même charge utile binaire est transportée sous forme de chaîne encodée en base64. La valeur de géodatabase stockée reste binaire brute, et la disposition binaire reste inchangée.

Écrire un embedding dans une classe d’entités

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

Lire un embedding

Lisez et vérifiez l’embedding stocké comme suit :

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

Exigences de validation

Avant de reconstruire le vecteur d’embedding, procédez comme suit :

Confirmer len(blob_bytes) == D * 4
Toujours vérifier qu’il y a peu de valeurs Little Endian

Bonnes pratiques

Les sections ci-après décrivent les pratiques conseillées à observer pour utiliser des embeddings.

Appliquez un type de données explicite.

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

Gardez les dimensions du modèle cohérentes.
La dimension d’embedding D doit rester fixe selon la version du modèle.
Évitez la sérialisation spécifique à la plateforme. N’utilisez pas de pickle, de tableaux numériques JSON pour le stockage, le packing de struct sans <f4 explicite, etc. Le seul format pris en charge est le suivant : Contiguous little-endian IEEE-754 float32 bytes

Conclusion

Dans ArcGIS Pro, les embeddings sont stockés sous forme de vecteurs Float32 à dimension fixe codés comme des données binaires Little Endian contiguës au sein d’un champ BLOB de géodatabase.

Avec ArcPy et ArcGIS API for Python, les embeddings peuvent être écrits et reconstruits de manière déterministe à travers des géodatabases de fichiers et des services d’entités hébergés tout en maintenant une compatibilité totale avec les standards de la plateforme ArcGIS.