版本：v3.0.x

管理文件资源

文件资源是一个服务器注册的外部字典文件引用，文本分析器在运行时使用该引用。在 Milvus 3.0 中，四个分析器组件可以从文件资源而不是内联数组加载字典：

| 分析器组件

接受文件资源的参数

| | --- | --- | |

Jieba 标记符号生成器

extra_dict_file

| |

停止过滤器

stop_words_file

| |

反编译过滤器

word_list_file

| |

同义词过滤器

synonyms_file

文件资源解决了内联字典数组的两个实际问题：

真正的字典很大。中文杰巴词汇可能有数万行；同义词表通常有数千条规则。将它们内联到分析器配置中是不切实际的。
同一词典通常在 Collection 中共享。只需注册一次，然后通过名称进行引用，就能使 Schema 保持较小的规模，并且只需进行一次字典更新操作。

文件资源类型

Milvus 支持两种具有不同管理职责的文件资源类型：

| 类型

文件存放位置

谁管理文件

适合

| | --- | --- | --- | --- | |

远程

在您的 Milvus 集群已配置使用的对象存储（MinIO / S3 / GCS / Azure）中

Milvus，通过add_file_resource /remove_file_resource /list_file_resources 客户端 API

建议用于大多数部署。

| |

本地

在每个 Milvus 组件（数据节点、查询节点、流节点）的本地文件系统上的相同绝对路径上。

你--自己挂载文件，例如通过 Kubernetes 卷

开源/自托管方案，您更喜欢在 Milvus 之外管理字典文件。

本页其余部分将介绍这两种类型，从更常见的远程类型开始。

前提条件

对于远程文件资源，Milvus 部署必须配置对象存储。大多数部署已经配置了对象存储，请查看milvus.yaml 的minio: 部分（或相应的 Helm 图表值）。请注意bucketName 和rootPath 值；注册文件资源时会用到它们。
对于本地文件资源，您必须能够以相同的绝对路径将文件放置在每个 Milvus pod / 容器上。具体方法取决于部署情况（绑定挂载、ConfigMap 支持卷、init 容器等）。

注册远程文件资源

注册远程文件资源的工作流程分为三步：将文件上传到对象存储，以选定的名称在 Milvus注册，然后从任何需要它的分析器中引用它。

步骤 1.将字典文件上传到对象存储

使用自己的工具（mc,aws s3 cp,boto3 或任何兼容 S3 的客户端）将文件放入 Milvus 配置使用的存储桶中。

例如，如果milvus.yaml 包含

minio:
  bucketName: milvus-bucket
  rootPath: file

上传一个以rootPath 为前缀、名为chinese_terms.txt 的文件，就会将对象放到s3://milvus-bucket/file/chinese_terms.txt 。

在步骤 2 中，你将传递给add_file_resource 的path 参数是完整的对象密钥，包括 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") - 先上传文件，然后重试。

该调用具有惰性。使用相同的name 和path 调用add_file_resource 两次不会产生重复。

第 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 tokenizer、Stop filter、Decompounder filter 和 Synonym filter。

参数名称是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 是 idempotent 的：为一个不存在的名称调用该函数，将返回None ，而不会引发任何问题。

删除文件资源前，请删除或更改分析器配置引用该资源的任何 Collection。将文件资源保留到不依赖该资源的 Collection 中，可避免分析器在资源消失后查找失败的风险。

使用本地文件资源

本地文件资源直接指向每个 Milvus 组件本地文件系统的路径。没有add_file_resource 调用 - Milvus 不会跟踪本地资源。你需要将文件放置在每个相关 pod 或容器的相同绝对路径上，然后通过路径引用它：

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

本地文件资源只在你控制数据节点、查询节点和流节点的文件系统的部署中有效--通常是裸机上的自托管 Milvus 或 Kubernetes 集群上的自托管 Milvus，你可以在其中添加卷挂载。文件必须以完全相同的绝对路径存在于每个组件上，否则某些节点在加载分析器时会失败。

该文件在分析器首次创建时打开。如果此时路径不存在，则分析器创建失败，显示MilvusException(code=2000, "IOError: No such file or directory") 。

注意事项

整个集群的可用性不是即时的。 add_file_resource 返回后，Milvus 会将文件同步到需要它的每个组件。在这个短暂的窗口期间，引用资源的 Collection 可能会在尚未同步的节点上创建失败。典型的解决方法是在几秒钟后重试创建调用。
**只有当没有 Collection 依赖于资源时才删除。**在调用remove_file_resource 之前，删除或更改分析器配置引用该资源的任何 Collection，以避免分析器查找时找不到文件。
list_file_resources() 返回name 和path - 没有大小、校验和、上传时间或其他元数据**。**如果需要，可使用自己的命名约定来跟踪字典版本。

文件资源类型​

前提条件​

注册远程文件资源​

步骤 1.将字典文件上传到对象存储​

步骤 2.注册文件add_file_resource​

第 3 步从分析器引用文件资源​

列出文件资源​

删除文件资源​

使用本地文件资源​

注意事项​