Gerir recursos de ficheiro
Um recurso de ficheiro é uma referência registada no servidor a um ficheiro de dicionário externo que os analisadores de texto consomem em tempo de execução. No Milvus 3.0, quatro componentes do analisador podem carregar os seus dicionários a partir de um recurso de ficheiro em vez de um array em linha:
Componente do analisador |
Parâmetro que aceita um recurso de ficheiro |
|---|---|
|
|
|
|
|
|
|
Os recursos de ficheiro resolvem dois problemas práticos com as matrizes de dicionário em linha:
Os dicionários reais são grandes. Um vocabulário chinês Jieba pode ter dezenas de milhares de linhas; as tabelas de sinónimos têm normalmente milhares de regras. Incluí-los na configuração do analisador é impraticável.
O mesmo dicionário é normalmente partilhado entre colecções. Registá-lo uma vez, e depois referenciá-lo pelo nome, mantém os esquemas pequenos e faz com que as actualizações do dicionário sejam uma única operação.
Tipos de recursos de ficheiros
O Milvus suporta dois tipos de recursos de ficheiros com diferentes responsabilidades de gestão:
Tipo |
Onde reside o ficheiro |
Quem gere o ficheiro |
Apto |
|---|---|---|---|
Remoto |
No armazenamento de objectos (MinIO / S3 / GCS / Azure) que o seu cluster Milvus já está configurado para utilizar |
Milvus, através das APIs de cliente |
Recomendado para a maioria das implementações. |
Local |
No mesmo caminho absoluto no sistema de ficheiros local de cada componente Milvus (DataNode, QueryNode, StreamingNode) |
Você - monte o ficheiro você mesmo, por exemplo, através de um volume Kubernetes |
Cenários de código aberto / auto-hospedados onde você prefere gerenciar arquivos de dicionário fora do Milvus. |
O restante desta página percorre os dois tipos, começando com o tipo remoto mais comum.
Pré-requisitos
Para recursos de arquivo remoto, sua implantação do Milvus deve ser configurada com um armazenamento de objetos. A maioria das implantações já está - verifique a seção
minio:do seumilvus.yaml(ou os valores equivalentes do gráfico Helm). Observe os valoresbucketNameerootPath; você precisará deles ao registrar recursos de arquivo.Para recursos de ficheiros locais, tem de conseguir colocar ficheiros em todos os pods/contentores do Milvus no mesmo caminho absoluto. A forma como o faz depende da sua implementação (montagem de ligação, volume apoiado por ConfigMap, contentor de inicialização, etc.).
Registar um recurso de ficheiro remoto
O registro de um recurso de arquivo remoto é um fluxo de trabalho de três etapas: carregue o arquivo no armazenamento de objetos, registre-o no Milvus com um nome escolhido e faça referência a ele em qualquer analisador que precise dele.
Passo 1. Carregar o ficheiro do dicionário para o armazenamento de objectos
Utilize as suas próprias ferramentas (mc, aws s3 cp, boto3, ou qualquer cliente compatível com S3) para colocar o ficheiro no balde que o Milvus está configurado para utilizar.
Por exemplo, se milvus.yaml contém:
minio:
bucketName: milvus-bucket
rootPath: file
Carregar um ficheiro denominado chinese_terms.txt com rootPath como prefixo coloca o objeto em s3://milvus-bucket/file/chinese_terms.txt.
O argumento path que você passará para add_file_resource na Etapa 2 é a chave completa do objeto, incluindo o prefixo rootPath - para o exemplo acima, path="file/chinese_terms.txt". Um caminho sem o prefixo (por exemplo, apenas "chinese_terms.txt") é rejeitado com o erro file resource path not exist.
Passo 2. Registar o ficheiro com 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 valida de forma síncrona: a chamada só regressa depois de o Milvus ter confirmado que o objeto existe em path no armazenamento de objectos configurado. Se o objeto estiver em falta, a chamada dá origem a MilvusException(code=65535, "file resource path not exist") - carregue primeiro o ficheiro e depois tente de novo.
A chamada é idempotente. Chamar add_file_resource duas vezes com os mesmos name e path não cria duplicados.
Passo 3. Referenciar o recurso de ficheiro a partir de um analisador
Sempre que um parâmetro do analisador aceitar uma referência de ficheiro (extra_dict_file, stop_words_file, word_list_file, synonyms_file), utilize a forma remota canónica:
{
"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
}
Todos os quatro parâmetros do analisador utilizam a mesma forma; apenas a chave do analisador circundante difere. Para exemplos concretos por analisador, consulte o tokenizador Jieba, o filtro Stop, o filtro Decompounder e o filtro Synonym.
Os nomes dos parâmetros são resource_name e file_name - e não name e file. A utilização de name / file (ou "type": "resource" em vez de "type": "remote") faz surgir MilvusException no momento da criação do analisador com uma mensagem como resource name of remote file ... must be set.
Listar recursos do ficheiro
resources = client.list_file_resources()
for r in resources:
print(r.name, r.path)
# chinese_terms file/chinese_terms.txt
list_file_resources() devolve uma lista de objectos FileResourceInfo, cada um com atributos .name e .path. O cluster vazio devolve []. Não existe get por recurso; list_file_resources é a única API de leitura.
Remover um recurso de ficheiro
client.remove_file_resource(name="chinese_terms")
remove_file_resource é idempotente: chamá-lo para um nome que não existe devolve None sem aumentar.
Antes de remover um recurso de ficheiro, elimine ou altere quaisquer colecções cujas configurações de analisador o referenciem. Manter um recurso de ficheiro até que nenhuma coleção dependa dele evita o risco de as pesquisas do analisador falharem depois de o recurso ter desaparecido.
Usar um recurso de arquivo local
Um recurso de ficheiro local aponta diretamente para um caminho no sistema de ficheiros local de cada componente Milvus. Não há nenhuma chamada add_file_resource - Milvus não rastreia recursos locais. Coloca-se o ficheiro no mesmo caminho absoluto em cada pod ou contentor relevante e, em seguida, faz-se referência a ele por caminho:
{
"type": "local",
"path": "/var/lib/milvus/dicts/chinese_terms.txt",
}
Os recursos de arquivo local são válidos apenas em implantações em que você controla os sistemas de arquivos de DataNodes, QueryNodes e StreamingNodes - normalmente Milvus auto-hospedado em bare-metal ou em um cluster Kubernetes onde você pode adicionar uma montagem de volume. O arquivo deve existir exatamente no mesmo caminho absoluto em todos os componentes; caso contrário, alguns nós falham ao carregar o analisador.
O ficheiro é aberto quando o analisador é criado pela primeira vez. Se o caminho não existir nesse momento, a criação do analisador falhará com MilvusException(code=2000, "IOError: No such file or directory").
Considerações
A disponibilidade em todo o cluster não é instantânea. Após o regresso de
add_file_resource, o Milvus sincroniza o ficheiro com todos os componentes que dele necessitam. Durante essa breve janela, uma coleção que faz referência ao recurso pode falhar ao ser criada em nós que ainda não foram sincronizados. A correção típica é tentar novamente a chamada de criação após alguns segundos.Remova apenas quando nenhuma coleção depender do recurso. Elimine ou altere qualquer coleção cuja configuração do analisador faça referência ao recurso antes de chamar
remove_file_resource, para evitar que as pesquisas do analisador não consigam encontrar o ficheiro.Apenas metadados.
list_file_resources()retornanameepath- não há tamanho, soma de verificação, tempo de carregamento ou outros metadados. Mantenha o controlo das versões do dicionário com a sua própria convenção de nomenclatura, se precisar.