Gérer les ressources de fichiers

Une ressource de fichier est une référence enregistrée par le serveur à un fichier de dictionnaire externe que les analyseurs de texte consomment au moment de l'exécution. Dans Milvus 3.0, quatre composants d'analyse peuvent charger leurs dictionnaires à partir d'une ressource de fichier plutôt qu'à partir d'un tableau en ligne :

Composant d'analyse	Paramètre acceptant une ressource fichier
Jieba tokenizer	extra_dict_file
Filtre d'arrêt	stop_words_file
Filtre de décompactage	word_list_file
Filtre de synonyme	synonyms_file

Les ressources de fichiers résolvent deux problèmes pratiques avec les tableaux de dictionnaires en ligne :

• Les dictionnaires réels sont volumineux. Un vocabulaire chinois Jieba peut comporter des dizaines de milliers de lignes ; les tables de synonymes sont généralement composées de milliers de règles. Les intégrer dans la configuration de l'analyseur n'est pas pratique.

• Le même dictionnaire est généralement partagé entre plusieurs collections. En l'enregistrant une fois, puis en le référençant par son nom, les schémas restent petits et les mises à jour du dictionnaire se font en une seule opération.

Types de ressources de fichiers

Milvus prend en charge deux types de ressources de fichiers avec des responsabilités de gestion différentes :

Type	Où se trouve le fichier	Qui gère le fichier	En forme
A distance	Dans le magasin d'objets (MinIO / S3 / GCS / Azure) que votre cluster Milvus est déjà configuré pour utiliser.	Milvus, via les API client add_file_resource / remove_file_resource / list_file_resources	Recommandé pour la plupart des déploiements.
Local	Au même chemin absolu sur le système de fichiers local de chaque composant Milvus (DataNode, QueryNode, StreamingNode).	Vous - montez le fichier vous-même, par exemple via un volume Kubernetes.	Scénarios open-source / auto-hébergés dans lesquels vous préférez gérer les fichiers de dictionnaire en dehors de Milvus.

Le reste de cette page présente les deux types, en commençant par le type distant le plus courant.

Conditions préalables

• Pour les ressources de fichiers distants, votre déploiement Milvus doit être configuré avec un magasin d'objets. La plupart des déploiements le sont déjà - vérifiez la section minio: de votre milvus.yaml (ou les valeurs équivalentes du tableau Helm). Notez les valeurs bucketName et rootPath; vous en aurez besoin lors de l'enregistrement des ressources de fichiers.

• Pour les ressources de fichiers locales, vous devez pouvoir placer des fichiers sur chaque pod/conteneur Milvus au même chemin absolu. La manière de procéder dépend de votre déploiement (montage bind, volume soutenu par ConfigMap, conteneur init, etc.)

Enregistrer une ressource de fichier distante

L'enregistrement d'une ressource fichier distante est un flux de travail en trois étapes : télécharger le fichier vers le stockage d'objets, l'enregistrer avec Milvus sous un nom choisi, puis le référencer à partir de n'importe quel analyseur qui en a besoin.

Étape 1. Télécharger le fichier du dictionnaire vers le stockage d'objets

Utilisez votre propre outil (mc, aws s3 cp, boto3, ou tout client compatible S3) pour placer le fichier dans le seau que Milvus est configuré pour utiliser.

Par exemple, si milvus.yaml contient :

minio:
  bucketName: milvus-bucket
  rootPath: file

Le téléchargement d'un fichier nommé chinese_terms.txt avec rootPath comme préfixe place l'objet à s3://milvus-bucket/file/chinese_terms.txt.

L'argument path que vous transmettrez à add_file_resource à l'étape 2 est la clé complète de l'objet, y compris le préfixe rootPath - pour l'exemple ci-dessus, path="file/chinese_terms.txt". Un chemin sans préfixe (par exemple, juste "chinese_terms.txt") est rejeté avec l'erreur file resource path not exist.

Étape 2. Enregistrer le fichier avec 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 valide de manière synchrone : l'appel ne revient que lorsque Milvus a confirmé que l'objet existe à l'adresse path dans le magasin d'objets configuré. Si l'objet est manquant, l'appel soulève MilvusException(code=65535, "file resource path not exist") - téléchargez d'abord le fichier, puis réessayez.

L'appel est idempotent. Appeler add_file_resource deux fois avec les mêmes name et path ne crée pas de doublons.

Étape 3. Faire référence à la ressource fichier à partir d'un analyseur

Chaque fois qu'un paramètre d'analyseur accepte une référence de fichier (extra_dict_file, stop_words_file, word_list_file, synonyms_file), utilisez la forme distante canonique :

{
    "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
}

Les quatre paramètres de l'analyseur utilisent la même forme ; seule la clé de l'analyseur qui les entoure diffère. Pour des exemples concrets par analyseur, voir Jieba tokenizer, Stop filter, Decompounder filter, et Synonym filter.

Les noms des paramètres sont resource_name et file_name - et non name et file. L'utilisation de name / file (ou "type": "resource" au lieu de "type": "remote") soulève MilvusException au moment de la création de l'analyseur avec un message comme resource name of remote file ... must be set.

Liste des ressources de fichiers

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

list_file_resources() renvoie une liste d'objets FileResourceInfo, chacun avec les attributs .name et .path. Le groupe vide renvoie []. Il n'y a pas de get par ressource ; list_file_resources est la seule API de lecture.

Supprimer une ressource fichier

client.remove_file_resource(name="chinese_terms")

remove_file_resource est idempotente : l'appeler pour un nom qui n'existe pas renvoie None sans relance.

Avant de supprimer une ressource fichier, supprimez ou modifiez toutes les collections dont les configurations d'analyseur la référencent. Le fait de conserver une ressource fichier jusqu'à ce qu'aucune collection n'en dépende permet d'éviter que les recherches de l'analyseur échouent après la disparition de la ressource.

Utiliser une ressource fichier locale

Une ressource de fichier locale pointe directement sur un chemin du système de fichiers local de chaque composant Milvus. Il n'y a pas d'appel add_file_resource - Milvus ne suit pas les ressources locales. Vous placez vous-même le fichier au même chemin absolu sur chaque pod ou conteneur concerné, puis vous y faites référence par le chemin :

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

Les ressources de fichiers locaux ne sont valables que dans les déploiements où vous contrôlez les systèmes de fichiers des DataNodes, QueryNodes et StreamingNodes - généralement Milvus auto-hébergé sur bare-metal ou sur un cluster Kubernetes où vous pouvez ajouter un montage de volume. Le fichier doit exister exactement au même chemin absolu sur chaque composant ; sinon, certains nœuds échouent lors du chargement de l'analyseur.

Le fichier est ouvert lorsque l'analyseur est créé pour la première fois. Si le chemin n'existe pas à ce moment-là, la création de l'analyseur échoue avec MilvusException(code=2000, "IOError: No such file or directory").

Points à prendre en considération

• La disponibilité à l'échelle du cluster n'est pas instantanée. Après le retour de add_file_resource, Milvus synchronise le fichier avec chaque composant qui en a besoin. Pendant cette brève fenêtre, la création d'une collection faisant référence à la ressource peut échouer sur les nœuds qui n'ont pas encore été synchronisés. La solution consiste généralement à réessayer l'appel de création après quelques secondes.

• Ne supprimer que si aucune collection ne dépend de la ressource. Supprimez ou modifiez toute collection dont la configuration de l'analyseur fait référence à la ressource avant d'appeler remove_file_resource, afin d'éviter que les recherches de l'analyseur ne parviennent pas à trouver le fichier.

• Métadonnées uniquement. list_file_resources() renvoie name et path - il n'y a pas de taille, de somme de contrôle, de temps de téléchargement ou d'autres métadonnées. Gardez une trace des versions du dictionnaire avec votre propre convention de nommage si vous en avez besoin.