Gestire le risorse di file
Una risorsa file è un riferimento registrato dal server a un file dizionario esterno che gli analizzatori di testo consumano in fase di esecuzione. In Milvus 3.0, quattro componenti dell'analizzatore possono caricare i loro dizionari da una risorsa file invece che da un array in linea:
Componente dell'analizzatore |
Parametro che accetta una risorsa file |
|---|---|
|
|
|
|
|
|
|
Le risorse file risolvono due problemi pratici con gli array di dizionari in linea:
I dizionari reali sono grandi. Un vocabolario cinese Jieba può essere composto da decine di migliaia di righe; le tabelle dei sinonimi sono in genere migliaia di regole. L'inserimento nella configurazione dell'analizzatore non è pratico.
Lo stesso dizionario è solitamente condiviso tra le varie collezioni. Registrarlo una sola volta, e poi referenziarlo per nome, mantiene gli schemi piccoli e rende l'aggiornamento del dizionario un'unica operazione.
Tipi di risorse file
Milvus supporta due tipi di risorse file con diverse responsabilità di gestione:
Tipo |
Dove risiede il file |
Chi gestisce il file |
In forma |
|---|---|---|---|
Remoto |
Nel negozio di oggetti (MinIO / S3 / GCS / Azure) che il cluster Milvus è già configurato per utilizzare |
Milvus, attraverso le API client |
Consigliato per la maggior parte delle implementazioni. |
Locale |
Nello stesso percorso assoluto sul filesystem locale di ogni componente Milvus (DataNode, QueryNode, StreamingNode). |
L'utente può montare il file da solo, ad esempio tramite un volume Kubernetes. |
Scenari open-source / self-hosted in cui si preferisce gestire i file del dizionario al di fuori di Milvus. |
Il resto di questa pagina illustra entrambi i tipi, a partire dal tipo remoto più comune.
Prerequisiti
Per le risorse di file remote, la distribuzione Milvus deve essere configurata con un archivio di oggetti. La maggior parte delle distribuzioni lo sono già: controllate la sezione
minio:del vostromilvus.yaml(o i valori equivalenti della tabella di Helm). Notate i valoribucketNameerootPath; vi serviranno quando registrerete le risorse di file.Per le risorse di file locali, dovete essere in grado di collocare i file in ogni pod/contenitore Milvus nello stesso percorso assoluto. Il modo in cui farlo dipende dalla distribuzione (montaggio bind, volume supportato da ConfigMap, contenitore init, ecc.)
Registrare una risorsa file remota
La registrazione di una risorsa file remota è un flusso di lavoro in tre fasi: si carica il file nell'archivio oggetti, lo si registra con Milvus con un nome scelto, quindi lo si referenzia da qualsiasi analizzatore che ne abbia bisogno.
Passo 1. Caricare il file del dizionario nell'archivio oggetti
Utilizzare i propri strumenti (mc, aws s3 cp, boto3 o qualsiasi client compatibile con S3) per inserire il file nel bucket che Milvus è configurato per utilizzare.
Ad esempio, se milvus.yaml contiene:
minio:
bucketName: milvus-bucket
rootPath: file
Caricando un file chiamato chinese_terms.txt con rootPath come prefisso, l'oggetto viene collocato in s3://milvus-bucket/file/chinese_terms.txt.
L'argomento path da passare a add_file_resource nel passaggio 2 è la chiave completa dell'oggetto, compreso il prefisso rootPath - per l'esempio precedente, path="file/chinese_terms.txt". Un percorso senza il prefisso (per esempio, solo "chinese_terms.txt") viene rifiutato con l'errore file resource path not exist.
Passo 2. Registrare il file con 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 convalida in modo sincrono: la chiamata ritorna solo dopo che Milvus ha confermato l'esistenza dell'oggetto path nell'archivio oggetti configurato. Se l'oggetto manca, la chiamata solleva MilvusException(code=65535, "file resource path not exist") - caricare prima il file e poi riprovare.
La chiamata è idempotente. Chiamando due volte add_file_resource con gli stessi name e path non si creano duplicati.
Passo 3. Riferimento alla risorsa file da un analizzatore
Ogni volta che un parametro dell'analizzatore accetta un riferimento a un file (extra_dict_file, stop_words_file, word_list_file, synonyms_file), utilizzare la forma remota canonica:
{
"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
}
Tutti e quattro i parametri dell'analizzatore usano la stessa forma; solo la chiave dell'analizzatore circostante differisce. Per esempi concreti per analizzatore, vedere Jieba tokenizer, Stop filter, Decompounder filter e Synonym filter.
I nomi dei parametri sono resource_name e file_name - non name e file. L'uso di name / file (o "type": "resource" al posto di "type": "remote") solleva MilvusException al momento della creazione dell'analizzatore con un messaggio simile a resource name of remote file ... must be set.
Elenco delle risorse del file
resources = client.list_file_resources()
for r in resources:
print(r.name, r.path)
# chinese_terms file/chinese_terms.txt
list_file_resources() restituisce un elenco di oggetti FileResourceInfo, ciascuno con gli attributi .name e .path. Il cluster vuoto restituisce []. Non esiste get per risorsa; list_file_resources è l'unica API di lettura.
Rimuovere una risorsa file
client.remove_file_resource(name="chinese_terms")
remove_file_resource è idempotente: chiamarlo per un nome che non esiste restituisce None senza rilanciare.
Prima di rimuovere una risorsa file, eliminare o modificare tutte le collezioni le cui configurazioni dell'analizzatore fanno riferimento ad essa. Mantenere una risorsa file finché nessuna collezione dipende da essa evita il rischio che le ricerche dell'analizzatore falliscano dopo che la risorsa è stata rimossa.
Utilizzare una risorsa file locale
Una risorsa file locale punta direttamente a un percorso sul filesystem locale di ogni componente Milvus. Non c'è nessuna chiamata a add_file_resource - Milvus non tiene traccia delle risorse locali. Si posiziona il file nello stesso percorso assoluto su ogni pod o contenitore pertinente, quindi si fa riferimento al percorso:
{
"type": "local",
"path": "/var/lib/milvus/dicts/chinese_terms.txt",
}
Le risorse di file locali sono valide solo nelle distribuzioni in cui si controllano i filesystem dei DataNode, dei QueryNode e degli StreamingNode - tipicamente Milvus auto-ospitato su bare-metal o su un cluster Kubernetes dove è possibile aggiungere un volume di mount. Il file deve esistere esattamente nello stesso percorso assoluto su ogni componente, altrimenti alcuni nodi non riescono a caricare l'analizzatore.
Il file viene aperto alla prima creazione dell'analizzatore. Se il percorso non esiste a quel punto, la creazione dell'analizzatore fallisce con MilvusException(code=2000, "IOError: No such file or directory").
Considerazioni
La disponibilità dell'intero cluster non è istantanea. Dopo il ritorno di
add_file_resource, Milvus sincronizza il file con tutti i componenti che ne hanno bisogno. Durante questa breve finestra, una raccolta che fa riferimento alla risorsa potrebbe non essere creata sui nodi che non hanno ancora effettuato la sincronizzazione. La soluzione tipica consiste nel riprovare la chiamata di creazione dopo alcuni secondi.Rimuovere solo quando nessuna collezione dipende dalla risorsa. Eliminare o modificare qualsiasi raccolta la cui configurazione dell'analizzatore faccia riferimento alla risorsa prima di chiamare
remove_file_resource, per evitare che le ricerche dell'analizzatore non trovino il file.Solo metadati.
list_file_resources()restituiscenameepath, senza dimensioni, checksum, tempo di caricamento o altri metadati. Tenere traccia delle versioni dei dizionari con una propria convenzione di denominazione, se necessario.