Skip to main content

Embeddings in BLOB-Feldern

Embeddings werden in ArcGIS-Workflows als numerische Vektoren mit fester Genauigkeit dargestellt und in einer Geodatabase in einem BLOB-Feld (Binary Large Object) mit dem Namen Embedding gespeichert. Die Darstellung ist kompakt, effizient, plattformneutral und optimiert für leistungsstarke Lese-/Schreib-/Abfrageoperationen über Laufzeitumgebungen und Programmiersprachen hinweg.

Embedding-Speicherformat

Embeddings werden als zusammenhängende Little-Endian-IEEE-754 32-Bit-Gleitkommawerte (Float32) ohne Header, Trennzeichen oder Metadaten gespeichert. Jedes Element belegt genau 4 Byte.

Speicherung von Embeddings

Konzeptionelle Darstellung

Ein Embedding ist logisch gesehen ein numerischer Vektor.

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

Auf der Festplatte wird das Embedding als Raw-Byte-Sequenz gespeichert.

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

Die Embedding-Dimension D ist pro Modell festgelegt.

Expected payload size = D * 4 bytes

Transport über REST und JSON

Wenn Embeddings nur textbasierte Kanäle durchlaufen müssen (zum Beispiel JSON-Payloads oder ArcGIS Feature Service REST-APIs), wird dieselbe binäre Payload als Base64-codierte Zeichenkette transportiert. Der in der Geodatabase gespeicherte Wert bleibt ein Raw-Binärwert, und das Binärlayout bleibt unverändert.

Schreiben eines Embeddings in eine Feature-Class

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

Lesen eines Embeddings

Lesen und überprüfen Sie das gespeicherte Embedding wie folgt:

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

Validierungsanforderungen

Gehen Sie vor der Rekonstruktion des Embedding-Vektors wie folgt vor:

  • Vergewissern Sie sich, dass len(blob_bytes) == D * 4

  • Prüfen Sie immer, ob das Format "Little Endian" ist

Best Practices

Im Folgenden werden die Empfehlungen für die Arbeit mit Embeddings beschrieben.

  • Erzwingen Sie einen expliziten Datentyp.

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

  • Sorgen Sie für konsistente Modelldimensionen.

  • Die Embedding-Dimension D muss für eine Modellversion unverändert bleiben.

  • Vermeiden Sie eine plattformspezifische Serialisierung. Verwenden Sie kein Pickle, keine JSON-Zahlenarrays zur Speicherung und kein Struct-Packing ohne explizite Angabe von <f4 usw. Es wird ausschließlich das folgende Format unterstützt: Contiguous little-endian IEEE-754 float32 bytes.

Fazit

In ArcGIS Pro werden Embeddings als Float32-Vektoren mit fester Dimension gespeichert, die als zusammenhängende Little-Endian-Binärdaten innerhalb eines BLOB-Feldes in der Geodatabase codiert sind.

Mit ArcPy und der ArcGIS API für Python können Embeddings deterministisch über File-Geodatabases und gehostete Feature-Services hinweg geschrieben und rekonstruiert werden, wobei die vollständige Kompatibilität mit den Standards der ArcGIS-Plattform erhalten bleibt.