Управление файловыми ресурсами

Файловый ресурс - это зарегистрированная на сервере ссылка на внешний файл словаря, который текстовые анализаторы потребляют во время выполнения. В Milvus 3.0 четыре компонента анализатора могут загружать свои словари из файлового ресурса, а не из встроенного массива:

Компонент анализатора	Параметр, принимающий файловый ресурс
Токенизатор Jieba	extra_dict_file
Стоп-фильтр	stop_words_file
Фильтр декомпонентов	word_list_file
Фильтр синонимов	synonyms_file

Файловые ресурсы решают две практические проблемы, связанные с массивами встроенных словарей:

• Реальные словари очень велики. Словарь китайского языка Jieba может состоять из десятков тысяч строк; таблицы синонимов обычно состоят из тысяч правил. Встраивать их в конфигурацию анализатора непрактично.

• Один и тот же словарь обычно используется во всех коллекциях. Регистрация его один раз и последующее обращение к нему по имени позволяет сохранить схемы небольшими и сделать обновление словаря одной операцией.

Типы файловых ресурсов

Milvus поддерживает два типа файловых ресурсов с разными обязанностями по управлению:

Тип	Где находится файл	Кто управляет файлом	Подходит
Удаленный	В хранилище объектов (MinIO / S3 / GCS / Azure), на использование которого уже настроен ваш кластер Milvus	Milvus, через клиентские API add_file_resource / remove_file_resource / list_file_resources.	Рекомендуется для большинства развертываний.
Локальный	По одному и тому же абсолютному пути в локальной файловой системе каждого компонента Milvus (DataNode, QueryNode, StreamingNode).	Вы сами монтируете файл, например, через том Kubernetes.	Сценарии с открытым исходным кодом / самостоятельным хостингом, когда вы предпочитаете управлять файлами словарей вне Milvus.

Остальная часть этой страницы посвящена обоим типам, начиная с более распространенного удаленного типа.

Необходимые условия

• Для удаленных файловых ресурсов развертывание Milvus должно быть сконфигурировано с хранилищем объектов. Большинство развертываний уже настроены - проверьте раздел minio: вашего milvus.yaml (или эквивалентные значения диаграммы Helm). Обратите внимание на значения bucketName и rootPath; они понадобятся вам при регистрации файловых ресурсов.

• Для локальных файловых ресурсов вы должны иметь возможность размещать файлы в каждой капсуле/контейнере Milvus по одному и тому же абсолютному пути. Как вы это сделаете, зависит от вашего развертывания (bind mount, том с поддержкой ConfigMap, init-контейнер и т. д.).

Регистрация удаленного файлового ресурса

Регистрация удаленного файлового ресурса - это трехэтапный рабочий процесс: загрузите файл в хранилище объектов, зарегистрируйте его в Milvus под выбранным именем, а затем ссылайтесь на него в любом анализаторе, которому он нужен.

Шаг 1. Загрузка файла словаря в хранилище объектов

С помощью собственного инструментария (mc, aws s3 cp, boto3 или любого S3-совместимого клиента) поместите файл в ведро, которое настроено на использование Milvus.

Например, если milvus.yaml содержит:

minio:
  bucketName: milvus-bucket
  rootPath: file

Загрузка файла с именем chinese_terms.txt и префиксом rootPath помещает объект на s3://milvus-bucket/file/chinese_terms.txt.

Аргумент path, который вы передадите в add_file_resource на шаге 2, - это полный ключ объекта, включая префикс rootPath - для приведенного выше примера path="file/chinese_terms.txt". Путь без префикса (например, просто "chinese_terms.txt") будет отклонен с ошибкой file resource path not exist.

Шаг 2. Зарегистрируйте файл в 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 проверяет синхронно: вызов возвращается только после того, как Milvus подтвердит, что объект по адресу path существует в сконфигурированном хранилище объектов. Если объект отсутствует, вызов вызывает ошибку MilvusException(code=65535, "file resource path not exist") - сначала загрузите файл, а затем повторите попытку.

Вызов является идемпотентным. Вызов add_file_resource дважды с одними и теми же name и path не создает дубликатов.

Шаг 3. Ссылка на файловый ресурс из анализатора

Везде, где параметр анализатора принимает ссылку на файл (extra_dict_file, stop_words_file, word_list_file, synonyms_file), используйте каноническую удаленную форму:

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

Все четыре параметра анализатора используют одну и ту же форму; различается только окружающий ключ анализатора. Конкретные примеры анализаторов см. в разделах "Токенизатор Jieba", "Стоп-фильтр", "Декомпундер" и "Синоним".

Имена параметров resource_name и file_name - не name и file. Использование name / file (или "type": "resource" вместо "type": "remote") приводит к появлению MilvusException во время создания анализатора с сообщением, подобным resource name of remote file ... must be set.

Список ресурсов файла

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

list_file_resources() возвращает список объектов FileResourceInfo, каждый из которых имеет атрибуты .name и .path. Пустой кластер возвращает []. Для каждого ресурса get не существует; list_file_resources - единственный API для чтения.

Удаление файлового ресурса

client.remove_file_resource(name="chinese_terms")

remove_file_resource является идемпотентным: его вызов для несуществующего имени возвращает None без повышения.

Перед удалением файлового ресурса удалите или измените все коллекции, конфигурации анализатора которых ссылаются на него. Сохранение файлового ресурса до тех пор, пока ни одна коллекция не будет зависеть от него, позволяет избежать риска сбоя поиска анализатора после того, как ресурс исчезнет.

Использование локального файлового ресурса

Локальный файловый ресурс указывает непосредственно на путь в локальной файловой системе каждого компонента Milvus. Нет никакого вызова add_file_resource - Milvus не отслеживает локальные ресурсы. Вы сами размещаете файл по тому же абсолютному пути в каждом соответствующем стручке или контейнере, а затем ссылаетесь на него по пути:

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

Локальные файловые ресурсы действительны только в тех развертываниях, где вы контролируете файловые системы DataNodes, QueryNodes и StreamingNodes - обычно это самостоятельное размещение Milvus на пустом металле или на кластере Kubernetes, где вы можете добавить монтирование тома. Файл должен существовать по одному и тому же абсолютному пути на каждом компоненте, иначе некоторые узлы не смогут загрузить анализатор.

Файл открывается при первом создании анализатора. Если в этот момент путь не существует, создание анализатора завершится неудачей с ошибкой MilvusException(code=2000, "IOError: No such file or directory").

Соображения

• Доступность всего кластера не является мгновенной. После возвращения add_file_resource Milvus синхронизирует файл со всеми компонентами, которым он нужен. Во время этого короткого окна коллекция, ссылающаяся на ресурс, может не создаться на узлах, которые еще не синхронизировались. Типичное решение - повторить вызов create через несколько секунд.

• Удаляйте только в том случае, если ни одна коллекция не зависит от ресурса. Удалите или измените любую коллекцию, чья конфигурация анализатора ссылается на ресурс, перед вызовом remove_file_resource, чтобы избежать неудачных поисков файла в анализаторе.

• Только метаданные. list_file_resources() возвращает name и path - нет размера, контрольной суммы, времени загрузки или других метаданных. Если вам нужно, отслеживайте версии словарей с помощью собственного соглашения об именовании.