Mitglieder-MatchCompatible with Milvus v3.0.2+

Übersicht

Der Membership-Match-Filter filtert Entitäten, indem er prüft, ob der Wert eines Skalarfelds zu einer vom Aufrufer bereitgestellten Menge gehört. Der Client erstellt einen kompakten binären Membership-Filter-Blob und übergibt diesen als Wert für eine Ausdrucksvorlage.

Dies ersetzt umfangreiche „ IN [...] “-Listen. Ein „ IN “-Filter serialisiert jedes Element in die Anfrage, sodass ausreichend große Elementmengen das gRPC-Empfangslimit des Proxys überschreiten können. Mit „ membership_match “ validiert der Proxy den Blob und bindet ihn in den Abfrageplan ein, ohne eine Elementliste neu zu erstellen.

Membership Match workflow: the client builds a reusable blob, the proxy validates it, and QueryNodes evaluate it. Ablauf des „Membership Match“-Workflows: Der Client erstellt einen wiederverwendbaren Blob, der Proxy validiert ihn und die QueryNodes werten ihn aus.

Das Diagramm zeigt die festgelegte Arbeitsteilung. Der Client erstellt den Blob einmalig und verwendet ihn für mehrere Anfragen wieder; der Proxy überprüft die Ummantelung und die Größenbeschränkungen und bettet den Blob unverändert in den Abfrageplan ein; und die QueryNodes werten den Plan anhand von Rohdaten oder eines Indexes aus.

Der Operator verfügt über zwei Kodierungen mit unterschiedlichen Korrektheitsgarantien:

  • Bloom (type=bloom): Ungefähre Zugehörigkeit. Falsch-positive Ergebnisse sind möglich; bei einem gültigen Filter sind keine falsch-negativen Ergebnisse zu erwarten. Typische Anwendung: Filter mit hohem Datenaufkommen zur Zielgruppenansprache oder zum Ausschluss, bei denen gelegentliche falsch-positive Ergebnisse akzeptabel sind.
  • Roaring (type=roaring): Exakte Zugehörigkeit für ganzzahlige Werte. Typische Verwendung: ACLs, Mandantensichtbarkeit, Compliance-Filter und Löschvorgänge nach ID-Sätzen.

Verwenden Sie die Bloom- Zugehörigkeit nicht für Autorisierungsentscheidungen oder destruktive Löschvorgänge. Ein falsch-positiver Treffer kann eine Entität offenlegen oder eine Entität löschen, die nicht zur beabsichtigten Menge gehört.

Checkliste für den Betrieb

  • Überprüfen Sie den Typ des Zielfelds und erstellen Sie den Blob aus derselben Wertedomäne.
  • Wählen Sie „Bloom“ nur dann aus, wenn Fehlalarme akzeptabel sind.
  • Wählen Sie „Roaring“ für ACL-, Compliance-, Mandantenisolierungs- und Löschvorgänge.
  • Erstellen Sie große Blobs einmalig und verwenden Sie sie wieder; erstellen Sie sie nicht bei jeder Anfrage neu.
  • Planen Sie die Blob-Größe in serialisierten Bytes ein, nicht anhand der Anzahl der Elemente.
  • Schließen Sie in einem Cluster mit gemischten Versionen zunächst das rollierende Upgrade ab (zuerst die Proxys), bevor Sie „ membership_match “ aktivieren.
  • Testen Sie den Ausdruck an einer Nicht-Produktionssammlung, bevor Sie einen destruktiven Workflow aktivieren.

Syntax des Ausdrucks

membership_match(<field>, {<template>}, type=bloom)
membership_match(<field>, {<template>}, type=roaring)
membership_match(<field>, {<template>})
not membership_match(<field>, {<template>}, type=bloom)

Das zweite Argument ist ein Platzhalter in der Vorlage. Das SDK stellt den Platzhalterwert als Protobuf- bytes bereit, der den vom Client erstellten Filter-Blob enthält. Halten Sie den type in Produktionsausdrücken explizit, damit der beabsichtigte Korrektheitsvertrag im Code und in den Protokollen sichtbar ist.

Das Argument „ type “ ist optional. Jeder Blob enthält einen selbstbeschreibenden Magic-Header – „ MBF1 “ für Bloom und „ MRB1 “ für Roaring – und der Server liest diesen Header aus, wenn „ type “ weggelassen wird. Ein expliziter „ type “, der mit dem Blob-Header in Konflikt steht, wird als Anforderungsfehler abgelehnt, und unbekannte oder abgeschnittene Header führen zu einem „Fail-Closed“-Zustand.

Wählen Sie die Kodierung

Verwenden Sie „Bloom“, wenn ein Fehlalarm akzeptabel ist. „Bloom“ akzeptiert Felder mit vorzeichenbehafteten Ganzzahlen (INT8/16/32/64), VARCHAR-Felder und JSON-Pfade. Ein Bloom-Filter ist keine exakte Zulassungsliste.

fpr (Falsch-Positiv-Rate) ist die Wahrscheinlichkeit, dass ein Bloom-Filter einen Wert als Element meldet, obwohl dieser Wert nie eingefügt wurde: „ fpr=0.005 “ bedeutet, dass etwa einer von 200 Nicht-Element-Werten fälschlicherweise als vorhanden gemeldet wird. Eine niedrigere FPR erzeugt einen größeren Blob.

Verwenden Sie „Roaring“, wenn jede Übereinstimmung exakt sein muss. „Roaring“ akzeptiert nur vorzeichenbehaftete Ganzzahlfelder; Elemente werden vor der Serialisierung auf INT64 vorzeichenverlängert, sodass ein INT8 mit dem Wert -1 und ein INT64 mit dem Wert -1 dasselbe Element darstellen. Verwenden Sie diese Option nicht für UUIDs oder andere Zeichenfolgenfelder.

DimensionBloom (type=bloom)Roaring (type=roaring)
GenauigkeitUngefähr; falsch-positive Ergebnisse möglich; keine falsch-negativen ErgebnisseExakt; keine falsch-positiven und keine falsch-negativen Ergebnisse
FelderINT8/16/32/64, VARCHAR, JSON-PfadeNur vorzeichenbehaftete INT8/16/32/64
Blob-GrößeAnzahl der Elemente und FPR; etwa 11 Bit pro Element bei einem FPR von 0,005; Körper als ZweierpotenzWertverteilung; dichte Mengen lassen sich auf weitaus kleinere Größen komprimieren; zufällige 64-Bit-Werte erreichen die Obergrenze des High-Containers von 262.144
LöschenWird beim Parsen abgelehntZulässig
Typische VerwendungZielgruppen- und AusschlussfilterACL, Compliance, Mandantenisolierung, Löschen nach ID-Satz

JSON-Pfade sind streng typisiert, Zeile für Zeile: Eine JSON -Zeichenkette wird als VARCHAR- Wert ausgewertet, eine JSON -Ganzzahl als INT64- Wert, und ein JSON-Double entspricht niemals einem ganzzahligen Element – im Gegensatz zum exakten „ IN “, bei dem 5,0 gleich 5 ist. Wenn Ihre Schreiboperationen Ganzzahlen als Float kodieren, normalisieren Sie diese beim Schreiben oder verwenden Sie ein typisiertes Skalarfeld.

Erstellen Sie bei beiden Kodierungen die Elementmenge aus derselben Wertedomäne wie das Zielfeld. Erstellen Sie keinen Bloom-Filter aus dem String- "10086" und wenden Sie ihn nicht auf ein „ INT64 “-Feld an. Der Blob-Header protokolliert die eingefügten Wertdomänen, und ein Blob mit falscher Domäne wird vom Proxy mit einem Parameterfehler abgelehnt, anstatt stillschweigend keine Übereinstimmung zu finden. Verwenden Sie einen erstellten Blob über mehrere Anfragen hinweg wieder, anstatt ihn für jede Abfrage neu zu erstellen.

Für Mengen mit wenigen tausend Elementen oder weniger bleibt die einfache „ IN “-Methode die einfachste Option. Der Server wählt nicht zwischen „IN“, „Bloom“ und „Roaring“ aus. Die Auswahl der Kodierung liegt in der Verantwortung des Aufrufers.

So wählen Sie eine Kodierung aus:

  1. Stellen Sie fest, ob die Arbeitslast Fehlalarme toleriert. Ist dies nicht der Fall, kommt „Bloom“ niemals in Frage.
  2. Für eine exakte Zugehörigkeit verwenden Sie „Roaring“ mit einem Feld für vorzeichenbehaftete Ganzzahlen. Dichte oder gruppierte Werte lassen sich zu den kleinsten Blobs komprimieren.
  3. Prüfen Sie die Größenbeschränkungen. Gleichmäßig zufällige 64-Bit-Werte können die Obergrenze von 262.144 für High-Container oder die Größenbeschränkungen überschreiten. Ist dies der Fall, verwenden Sie eine herkömmliche IN -Liste, die den Anforderungsgrenzen entspricht.
  4. Für eine exakte Zugehörigkeit bei nicht-ganzzahligen Feldern verwenden Sie „IN“. Für diese Felder gibt es keine Kodierung für exakte Zugehörigkeit.

Die Mitgliedschaftsabgleichfunktion ist über die RESTful-HTTP-API nicht verfügbar. Parameter in HTTP-Ausdrucksvorlagen akzeptieren nur Werte vom Typ „bool“, „number“, „string“ und „array“; es gibt keinen binären Typ „ bytes “ für den Blob. Verwenden Sie ein gRPC-basiertes SDK, um Mitgliedschafts-Blobs zu übergeben.

SDK-Anfragemuster

Die folgenden Codeausschnitte konzentrieren sich auf die Erstellung von Mitgliedschafts-Blobs und deren Übergabe als Filtervorlagenparameter. Sie setzen voraus, dass die Sammlungen und Felder bereits vorhanden und geladen sind, die SDK-Clients verbunden sind und Abfragevektoren, Mitgliederlisten sowie andere referenzierte Variablen definiert sind. Die Einrichtung der Sammlungen und das vollständige Anwendungsgerüst werden ausgelassen.

from pymilvus import MilvusClient, build_bloom_filter, build_roaring_bitmap

client = MilvusClient(uri="http://localhost:19530")
bloom_blob = build_bloom_filter(["creator-a", "creator-b"], fpr=0.005)
client.search(collection_name="posts", data=[query_vector], anns_field="embedding", limit=10,
              filter="membership_match(creator_id, {members}, type=bloom)",
              filter_params={"members": bloom_blob})

roaring_blob = build_roaring_bitmap([1001, 1002, 1003])
client.query(collection_name="docs", filter="membership_match(user_id, {members}, type=roaring)",
             filter_params={"members": roaring_blob}, output_fields=["user_id", "title"])
bloomBlob, err := milvusclient.NewBloomFilterBlob([]int64{1001, 1002}, fpr)
if err != nil { return err }
search := milvusclient.NewSearchOption("posts", topK, vectors).
    WithFilter("membership_match(creator_id, {members}, type=bloom)").
    WithTemplateParam("members", bloomBlob)

roaringBlob, err := milvusclient.NewRoaringBitmapBlob([]int64{1001, 1002})
if err != nil { return err }
query := milvusclient.NewQueryOption("docs").
    WithFilter("membership_match(user_id, {members}, type=roaring)").
    WithTemplateParam("members", roaringBlob)
byte[] bloomBlob = BloomFilterUtils.buildBloomFilter(userIds, BloomFilterUtils.DEFAULT_FPR);
QueryReq request = QueryReq.builder().collectionName("docs")
    .filter("membership_match(user_id, {members}, type=bloom)")
    .filterTemplateValues(Collections.singletonMap("members", bloomBlob)).build();
byte[] roaringBlob = RoaringBitmapUtils.buildRoaringBitmap(userIds);
const bloomBlob = buildBloomFilter(userIds);
await client.query({ collection_name: 'docs',
  filter: 'membership_match(user_id, {members}, type=bloom)',
  exprValues: { members: bloomBlob } });
const roaringBlob = buildRoaringBitmap(integerIds);

Löschen mit „Roaring“

Verwenden Sie beim Löschen von Entitäten, die durch eine externe Ganzzahl-ID-Menge ausgewählt wurden, einen exakten Roaring-Blob. Überprüfen Sie die Mitgliedermenge und den Feldtyp der Sammlung, bevor Sie den Löschbefehl ausführen. Verwenden Sie kein Bloom: Eine ungefähre Zugehörigkeit ist kein sicheres Löschprädikat, und Bloom-Formen werden in Löschausdrücken bereits bei der Analyse abgelehnt.

roaring_blob = build_roaring_bitmap([1001, 1002, 1003])
client.delete(collection_name="docs", filter="membership_match(id, {members}, type=roaring)",
              filter_params={"members": roaring_blob})
roaringBlob, err := milvusclient.NewRoaringBitmapBlob([]int64{1001, 1002, 1003})
if err != nil { return err }
_, err = client.Delete(ctx, milvusclient.NewDeleteOption("docs").
    WithExpr("membership_match(id, {members}, type=roaring)").
    WithTemplateParam("members", roaringBlob))
byte[] roaringBlob = RoaringBitmapUtils.buildRoaringBitmap(userIds);
DeleteReq request = DeleteReq.builder().collectionName("docs")
    .filter("membership_match(id, {members}, type=roaring)")
    .filterTemplateValues(Collections.singletonMap("members", roaringBlob)).build();
const roaringBlob = buildRoaringBitmap(integerIds);
await client.delete({ collection_name: 'docs',
  filter: 'membership_match(id, {members}, type=roaring)',
  exprValues: { members: roaringBlob } });

Die Löschsemantik folgt einer exakten, dreipoligen Übereinstimmung:

Feldwertmembership_match(…)nicht membership_match(…)
NULLkein Abgleich (NULL)keine Übereinstimmung (NULL)
in der MitgliedermengeÜbereinstimmungkeine Übereinstimmung
außerhalb der Mengekeine ÜbereinstimmungÜbereinstimmung

Die Tabelle lässt sich Zeile für Zeile wie folgt interpretieren: Ein „Delete“ mit „ membership_match “ entfernt die Entitäten innerhalb der Menge, ein „Delete“ mit „ not membership_match “ entfernt die Entitäten außerhalb der Menge, und NULL-Entitäten bleiben bei beiden Polaritäten erhalten.

  • Entitäten mit einem NULL-Feldwert werden unter keiner der beiden Polaritäten gelöscht.
  • Eine leere Bitmap löscht nichts. „ not membership_match(<field>, {<empty>}, type=roaring) “ löscht jede Entität mit einem Nicht-NULL-Feldwert – also genau das Komplement –, was je nach Design eine große Menge sein kann.
  • not membership_match ist das exakte Komplement der Elementmenge über Nicht-NULL-Entitäten, keine Annäherung.

Bei versiegelten Segmenten, die indexbasiert geladen werden und keine rohen Skalardaten enthalten, verwendet die Auswertung eine begrenzte Rückwärtssuche, sofern der Index dies unterstützt. Wenn weder rohe Felddaten noch ein geeigneter Index verfügbar sind, schlägt die Anfrage mit „ FieldNotLoaded “ fehl, anstatt ungefilterte Entitäten zurückzugeben.

Operative Einschränkungen

EinstellungStandardKonfigurierbarWas es begrenzt
proxy.maxMembershipFilterSize64 MiBmilvus.yaml Proxyein Blob-Inhalt
proxy.maxMembershipFilterPlanSize128 MiBmilvus.yaml ProxyAggregat pro Anfrage
proxy.grpc.serverMaxRecvSize128 MiBmilvus.yaml Proxygesamte Anfrage
Roaring High-Container-Obergrenze262.144im Code festgelegtpro Filter
Geschätzter Speicherbedarf für „Roaring Decoded“64 MiBim Code festgelegtpro Filter
MBF1-Format-Obergrenze128 MiBim Code festgelegtObergrenze des Blob-Formats
Bloom fpr0,005Client-BuilderZielwert für Falsch-Positiv-Ergebnisse

Die Einstellungen unter „ proxy.* “ sind Teil der Milvus-Serverkonfiguration: Sie werden vom Cluster-Betreiber unter milvus.yaml im Abschnitt „ proxy “ festgelegt und können zum Zeitpunkt der Filterung nicht pro Anfrage oder pro Ausdruck angepasst werden. Die „Roaring Admissions“ und die Obergrenze für das MBF1-Format sind in der Implementierung fest vorgegeben und können nirgendwo konfiguriert werden. Die Zeile „ fpr “ ist die einzige clientseitige Steuerungsmöglichkeit: Sie wird beim Erstellen des Blobs ausgewählt, wobei der zulässige Bereich zwischen 0,0001 und 0,05 liegt.

Der Blob-Körper fasst bei der Standard-FPR maximal etwa 48,6 Millionen INT64-Elemente, wobei der feste 32-Byte-Envelope-Header zusätzlich zulässig ist. Das anfrageweite Budget deckt die aggregierte serialisierte Größe der Mitgliederlisten sowie die aggregierte geschätzte dekodierte Größe der Roaring-Filter ab; HybridSearch-Unteranfragen und Scorer-Filter teilen sich dieses Budget. Bloom-Körper sind Zweierpotenzen: Eine Mitgliederanzahl, die knapp über einer Stufengrenze liegt, verdoppelt den Blob, und ein etwas höherer FPR passt oft in die nächstniedrigere Stufe. Wenn der Proxy einen übergroßen Bloom-Blob ablehnt, schlägt der Fehler eine „ fpr “ vor, die passt.

  • Die Ergebnisse von Mitgliedschaftsausdrücken werden nicht über mehrere Abfragen hinweg zwischengespeichert.
  • Cluster mit gemischten Versionen schlagen fehl: QueryNodes, auf denen älterer Code läuft, lehnen Pläne ab, die Knoten des Mitgliedschaftsplans enthalten. Aktualisieren Sie zuerst die Proxys und schließen Sie dann das rollierende Upgrade ab, bevor Sie den Operator aktivieren.
  • Serverprotokolle schwächen Blob-Bytes ab. Der Ausdruckstext enthält nur den Vorlagennamen; die binäre Nutzlast wird außerhalb des Bandes in den Vorlagenwerten übertragen.

Übersetzt vonDeepL

Verwaltetes Milvus kostenlos testen

Zilliz Cloud ist unkompliziert, basiert auf Milvus und ist 10-mal schneller.

Loslegen
Feedback

War diese Seite hilfreich?