Verwalten von Dateiressourcen

Eine Dateiressource ist ein vom Server registrierter Verweis auf eine externe Wörterbuchdatei, die von Textanalysatoren zur Laufzeit verwendet wird. In Milvus 3.0 können vier Analyzer-Komponenten ihre Wörterbücher aus einer Dateiressource laden, anstatt aus einem Inline-Array:

Analyzer-Komponente	Parameter, der eine Dateiressource akzeptiert
Jieba Tokenisierer	extra_dict_file
Stop-Filter	stop_words_file
Decompounder-Filter	word_list_file
Synonym-Filter	synonyms_file

Dateiressourcen lösen zwei praktische Probleme mit Inline-Wörterbuch-Arrays:

• Echte Wörterbücher sind groß. Ein chinesisches Jieba-Vokabular kann Zehntausende von Zeilen umfassen; Synonymtabellen bestehen normalerweise aus Tausenden von Regeln. Sie in die Konfiguration des Analysators einzubinden ist unpraktisch.

• Ein und dasselbe Wörterbuch wird normalerweise in mehreren Sammlungen verwendet. Durch die einmalige Registrierung und die anschließende Referenzierung über den Namen werden die Schemata klein gehalten und die Aktualisierung des Wörterbuchs wird zu einem einzigen Vorgang.

Datei-Ressourcen-Typen

Milvus unterstützt zwei Arten von Dateiressourcen mit unterschiedlichen Verwaltungsaufgaben:

Typ	Wo sich die Datei befindet	Wer verwaltet die Datei	Anpassen
Entfernt	In dem Objektspeicher (MinIO / S3 / GCS / Azure), für den Ihr Milvus-Cluster bereits konfiguriert ist	Milvus, über die Client-APIs add_file_resource / remove_file_resource / list_file_resources	Empfohlen für die meisten Einsätze.
Lokal	Unter demselben absoluten Pfad auf dem lokalen Dateisystem jeder Milvus-Komponente (DataNode, QueryNode, StreamingNode)	Sie - mounten Sie die Datei selbst, zum Beispiel über ein Kubernetes-Volume	Open-Source / selbst gehostete Szenarien, in denen Sie es vorziehen, Wörterbuchdateien außerhalb von Milvus zu verwalten.

Der Rest dieser Seite geht auf beide Arten ein, beginnend mit dem häufigeren Remote-Typ.

Voraussetzungen

• Für Remote-Dateiressourcen muss Ihr Milvus-Einsatz mit einem Objektspeicher konfiguriert sein. Die meisten Einsätze sind bereits so konfiguriert - überprüfen Sie den Abschnitt minio: Ihres milvus.yaml (oder die entsprechenden Helm-Diagrammwerte). Beachten Sie die Werte bucketName und rootPath; Sie benötigen sie bei der Registrierung von Dateiressourcen.

• Bei lokalen Dateiressourcen müssen Sie in der Lage sein, Dateien auf jedem Milvus-Pod/Container unter demselben absoluten Pfad abzulegen. Wie Sie dies tun, hängt von Ihrem Einsatz ab (Bind-Mount, ConfigMap-gestütztes Volume, Init-Container usw.).

Registrieren einer entfernten Dateiressource

Die Registrierung einer entfernten Dateiressource ist ein dreistufiger Arbeitsablauf: Hochladen der Datei in den Objektspeicher, Registrierung bei Milvus unter einem gewählten Namen, dann Verweis auf die Datei von jedem Analysator, der sie benötigt.

Schritt 1. Hochladen der Wörterbuchdatei in den Objektspeicher

Verwenden Sie Ihr eigenes Tool (mc, aws s3 cp, boto3, oder einen beliebigen S3-kompatiblen Client), um die Datei in den Bucket zu legen, für den Milvus konfiguriert ist.

Zum Beispiel, wenn milvus.yaml enthält:

minio:
  bucketName: milvus-bucket
  rootPath: file

Das Hochladen einer Datei mit dem Namen chinese_terms.txt und dem Präfix rootPath legt das Objekt unter s3://milvus-bucket/file/chinese_terms.txt ab.

Das Argument path, das Sie in Schritt 2 an add_file_resource übergeben, ist der vollständige Objektschlüssel, einschließlich des Präfixes rootPath - im obigen Beispiel also path="file/chinese_terms.txt". Ein Pfad ohne das Präfix (z. B. nur "chinese_terms.txt") wird mit dem Fehler file resource path not exist zurückgewiesen.

Schritt 2. Registrieren Sie die Datei mit add_file_resource

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

client.add_file_resource(
    name="chinese_terms",                # short, unique name you'll reference later
    path="file/chinese_terms.txt",       # full S3 object key, including the rootPath prefix
)

add_file_resource validiert synchron: der Aufruf kehrt erst zurück, nachdem Milvus bestätigt hat, dass das Objekt unter path im konfigurierten Objektspeicher existiert. Fehlt das Objekt, löst der Aufruf MilvusException(code=65535, "file resource path not exist") aus - laden Sie zuerst die Datei hoch und versuchen Sie es dann erneut.

Der Aufruf ist idempotent. Wenn add_file_resource zweimal mit denselben name und path aufgerufen wird, werden keine Duplikate erzeugt.

Schritt 3. Verweis auf die Dateiressource von einem Analyzer

Wo immer ein Analyzer-Parameter einen Dateiverweis akzeptiert (extra_dict_file, stop_words_file, word_list_file, synonyms_file), verwenden Sie die kanonische Remote-Form:

{
    "type": "remote",
    "resource_name": "chinese_terms",    # must match the name in add_file_resource
    "file_name": "chinese_terms.txt",    # filename only — Milvus uses this to identify the file inside the resource
}

Alle vier Analyzer-Parameter verwenden die gleiche Form; nur der sie umgebende Analyzer-Schlüssel unterscheidet sich. Konkrete Beispiele für einzelne Analysatoren finden Sie unter Jieba tokenizer, Stop filter, Decompounder filter und Synonym filter.

Die Parameternamen lauten resource_name und file_name - nicht name und file. Die Verwendung von name / file (oder "type": "resource" anstelle von "type": "remote") löst MilvusException bei der Erstellung des Analysators mit einer Meldung wie resource name of remote file ... must be set aus.

Dateiressourcen auflisten

resources = client.list_file_resources()
for r in resources:
    print(r.name, r.path)
# chinese_terms file/chinese_terms.txt

list_file_resources() gibt eine Liste von FileResourceInfo Objekten zurück, jedes mit den Attributen .name und .path. Der leere Cluster gibt [] zurück. Es gibt kein get pro Ressource; list_file_resources ist die einzige Lese-API.

Entfernen einer Dateiressource

client.remove_file_resource(name="chinese_terms")

remove_file_resource ist idempotent: der Aufruf für einen Namen, der nicht existiert, gibt None zurück, ohne dass eine Erhöhung erfolgt.

Bevor Sie eine Dateiressource entfernen, löschen oder ändern Sie alle Sammlungen, deren Analyzer-Konfigurationen auf sie verweisen. Wenn man eine Dateiressource so lange behält, bis keine Sammlung mehr von ihr abhängt, vermeidet man das Risiko, dass Suchvorgänge des Analyzers fehlschlagen, nachdem die Ressource entfernt wurde.

Verwenden Sie eine lokale Dateiressource

Eine lokale Dateiressource verweist direkt auf einen Pfad im lokalen Dateisystem der einzelnen Milvus-Komponenten. Es gibt keinen Aufruf von add_file_resource - Milvus verfolgt keine lokalen Ressourcen. Sie platzieren die Datei unter demselben absoluten Pfad auf jedem relevanten Pod oder Container selbst und referenzieren sie dann über den Pfad:

{
    "type": "local",
    "path": "/var/lib/milvus/dicts/chinese_terms.txt",
}

Lokale Dateiressourcen sind nur in Bereitstellungen gültig, in denen Sie die Dateisysteme von DataNodes, QueryNodes und StreamingNodes kontrollieren - typischerweise selbst gehostetes Milvus auf Bare-Metal oder auf einem Kubernetes-Cluster, wo Sie einen Volume-Mount hinzufügen können. Die Datei muss auf jeder Komponente unter genau demselben absoluten Pfad vorhanden sein; andernfalls schlagen einige Knoten beim Laden des Analyzers fehl.

Die Datei wird geöffnet, wenn der Analyzer zum ersten Mal erstellt wird. Wenn der Pfad zu diesem Zeitpunkt nicht existiert, schlägt die Erstellung des Analyzers mit MilvusException(code=2000, "IOError: No such file or directory") fehl.

Überlegungen

• Die clusterweite Verfügbarkeit ist nicht sofort gegeben. Nachdem add_file_resource zurückgekehrt ist, synchronisiert Milvus die Datei mit jeder Komponente, die sie benötigt. Während dieses kurzen Zeitfensters kann die Erstellung einer Sammlung, die auf die Ressource verweist, auf Knoten, die noch nicht synchronisiert wurden, fehlschlagen. Die typische Lösung ist, den Erstellungsaufruf nach ein paar Sekunden zu wiederholen.

• Entfernen Sie nur, wenn keine Sammlung von der Ressource abhängt. Löschen oder ändern Sie jede Sammlung, deren Analyzer-Konfiguration auf die Ressource verweist, bevor Sie remove_file_resource aufrufen, um zu vermeiden, dass Analyzer-Lookups die Datei nicht finden.

• Nur Metadaten. list_file_resources() gibt name und path zurück - es gibt keine Größe, Prüfsumme, Upload-Zeit oder andere Metadaten. Verfolgen Sie die Wörterbuchversionen mit Ihrer eigenen Namenskonvention, wenn Sie sie benötigen.