FiftyOne 插件生态系统完全指南：从发现、安装到开发与共享

FiftyOne 插件生态系统完全指南：从发现、安装到开发与共享

【免费下载链接】fiftyoneRefine high-quality datasets and visual AI models项目地址: https://gitcode.com/GitHub_Trending/fi/fiftyone

FiftyOne 插件（Plugins）是扩展 FiftyOne 视觉 AI 开发工作台的核心机制，它允许你在 App 内新增自定义操作（Operators）、渲染自定义面板（Panels）、集成第三方工具与 API，甚至编写可委派到后台计算集群的长时任务。本文以官方文档 Plugins Ecosystem 索引页 及其所属的插件文档体系为主线，系统讲解插件生态的构成、插件的下载安装、目录管理与配置、面板与操作符的使用、委托执行机制，以及插件的开发与社区贡献流程，读完即可上手使用并编写自己的第一个 FiftyOne 插件。

插件生态是什么

FiftyOne 插件生态系统（Plugins Ecosystem）是围绕 FiftyOne 核心工具构建的可扩展插件集合，涵盖前沿研究、最新模型与强大的附加组件。正如 index.rst 所描述的，这些插件能够"将 FiftyOne 变成你专属的视觉 AI 开发工作台"。

插件生态由两部分组成：

• 社区与官方插件：来自 voxel51/fiftyone-plugins 仓库及社区维护的众多插件，覆盖标注、评估、导入导出、脑分析（Brain）、模型与数据集下载等场景；
• FiftyOne Labs 实验特性：由 Voxel51 团队开发的实验性研究解决方案，分为机器学习实验与高级可视化工具两大类，详见 docs/source/labs/index.rst。Labs 特性是实验性的，可能独立于 FiftyOne 核心演进，使用时需自行审阅其文档。

需要明确的是：社区插件是各自作者维护的外部项目，不属于 FiftyOne 核心，可能独立变更，使用前应审阅每个插件的文档与许可证（index.rst 中对此有明确声明）。生态页面的搜索框支持按插件名称、描述、作者或分类进行检索。

从文档结构看，插件文档体系由以下页面组成，这也是阅读本指南的完整路径：

• Plugins Overview：插件能力总览与快速开始；
• Using Plugins：下载、管理、配置与使用插件；
• Developing Plugins：插件开发完整指南；
• Contributing Plugins：向生态提交共享插件；
• Getting started with agents：使用 Skills 开发智能体插件。

插件能做什么：能力总览与内置插件

根据 overview.rst，FiftyOne 插件框架（自 OSS 0.17.0 / Enterprise 1.0 起提供）允许你：

• 向 FiftyOne App 添加新功能；
• 创建与其他工具和 API 的集成；
• 渲染自定义面板（Panels）；
• 向菜单添加自定义操作（Operators）；
• 在 Enterprise 环境下编写可由用户在 App 内触发、并在连接的计算集群上执行的长时任务。

官方插件清单

官方文档推荐从以下插件开始上手，它们均发布在 FiftyOne Plugins 仓库中：

典型使用场景包括：用@voxel51/io直接在 App 内导入数据；用@voxel51/annotation将样本送去标注；用@voxel51/evaluation评估模型预测；用@voxel51/brain计算嵌入（可在后台执行）；用@voxel51/dashboard构建显示当前数据集统计信息的自定义仪表盘。

内置面板

FiftyOne 原生内置了多个以插件机制实现的功能。面板（Panels）是可以在 App Spaces 中打开并交互操作的微型全功能数据应用，可在打开面板间联动响应。FiftyOne 原生包含：

• Samples 面板：启动 App 时默认加载的媒体网格；
• Histograms 面板：数据集字段的直方图仪表盘；
• Embeddings 面板：用于嵌入可视化的画布；
• Map 面板：可视化含 GeoLocation 字段的数据集地理信息。

点击 "Samples" 标签旁的+图标即可打开新面板；也可以在 Python 中以编程方式配置 Spaces。此外，地图、嵌入等面板对应的前端实现位于 app/packages/ 各包中，例如 Map 面板对应 app/packages/map/、Embeddings 面板对应 app/packages/embeddings/，可作为二次开发的参考。

下载与安装插件

根据 using_plugins.rst，下载插件只需插件的 GitHub 仓库地址，或插件源码 ZIP 归档链接。支持 CLI 与 Python 两种方式。

CLI 方式

# 从 GitHub 仓库下载插件 fiftyone plugins download https://github.com/<user>/<repo>[/tree/branch] # 通过指定 GitHub 仓库信息下载 fiftyone plugins download <user>/<repo>[/<ref>] # 从仓库中下载指定插件 fiftyone plugins download \ https://github.com/<user>/<repo>[/tree/branch] \ --plugin-names <name1> <name2> <name3>

Python 方式

import fiftyone.plugins as fop # 从 GitHub 仓库下载插件 fop.download_plugin("https://github.com/<user>/<repo>[/tree/branch]") # 通过指定 GitHub 仓库信息下载 fop.download_plugin("<user>/<repo>[/<ref>]") # 下载仓库中的指定插件 fop.download_plugin(url_or_gh_repo, plugin_names=["<name1>", "<name2>"])

使用注意点：

• 一个 GitHub 仓库可能包含多个插件。默认会安装前三个目录层级内发现的所有插件，也可以通过--plugin-names选择特定插件；
• 所有插件都会下载到插件目录；
• 如需从有权限的私有 GitHub 仓库下载，可通过GITHUB_TOKEN环境变量提供个人访问令牌；
• CLI 下载命令还支持--max-depth 2等参数来调整插件搜索深度（用于嵌套目录）。

插件目录与配置

所有插件都必须存放在插件目录中，FiftyOne 才能识别。默认目录为~/fiftyone/__plugins__，可用FIFTYONE_PLUGINS_DIR环境变量自定义：

export FIFTYONE_PLUGINS_DIR=/path/to/your/plugins

也可以永久配置——在 FiftyOne 配置中设置plugins_dir：

{ "plugins_dir": "/path/to/your/plugins" }

查看当前插件目录：

fiftyone config plugins_dir # ~/fiftyone/__plugins__

注意：插件目录必须对 FiftyOne 服务器可读。相关配置解析逻辑可参考 fiftyone/core/config.py 中关于插件目录与allow_legacy_orchestrators等配置项的实现。

管理插件：列表、信息、启用与删除

fiftyone plugins与fiftyone operators两个 CLI 命令组提供了丰富的插件管理能力。

列出插件

fiftyone plugins list # 列出所有本地插件 fiftyone plugins list --enabled # 列出已启用插件 fiftyone plugins list --disabled # 列出已禁用插件

输出示例（插件名、版本、启用状态、目录）：

plugin version enabled directory ------------------- ------- ------- ---------------------------------------------------------- @voxel51/annotation 1.0.0 ✓ ~/fiftyone/__plugins__/fiftyone-plugins/plugins/annotation @voxel51/brain 1.0.0 ✓ ~/fiftyone/__plugins__/fiftyone-plugins/plugins/brain @voxel51/evaluation 1.0.0 ✓ ~/fiftyone/__plugins__/fiftyone-plugins/plugins/evaluation @voxel51/indexes 1.0.0 ✓ ~/fiftyone/__plugins__/fiftyone-plugins/plugins/indexes @voxel51/io 1.0.0 ✓ ~/fiftyone/__plugins__/fiftyone-plugins/plugins/io @voxel51/utils 1.0.0 ✓ ~/fiftyone/__plugins__/fiftyone-plugins/plugins/utils @voxel51/voxelgpt 1.0.0 ✓ ~/fiftyone/__plugins__/voxelgpt @voxel51/zoo 1.0.0 ✓ ~/fiftyone/__plugins__/fiftyone-plugins/plugins/zoo

列出操作符与面板

fiftyone operators list # 列出所有操作符与面板 fiftyone operators list --enabled # 列出已启用的 fiftyone operators list --disabled # 列出已禁用的 fiftyone operators list --panels-only # 仅列出面板

输出以 URI 形式展示每个操作符（@plugin-name/operator-name），并标记builtin（内置）与panel（面板）属性，例如@voxel51/io/import_samples、@voxel51/brain/compute_visualization、@voxel51/operators/clone_selected_samples（内置）等。

查看插件信息

fiftyone plugins info @voxel51/annotation

输出包含 name、version、url、license、description、fiftyone_compatibility、操作符列表、js_bundle、py_entry、server_path、secrets（所需密钥列表）与directory等元数据。

查看操作符信息

fiftyone operators info @voxel51/io/import_samples

输出包含execute_as_generator、unlisted、dynamic、on_startup、on_dataset_open、allow_immediate_execution、allow_delegated_execution、default_choice_to_delegated等执行选项，这些直接决定操作符在 App 中的表现（详见下文委托执行部分）。

安装插件依赖

fiftyone plugins requirements <name> --print # 打印插件依赖 fiftyone plugins requirements <name> --install # 安装插件依赖 fiftyone plugins requirements <name> --ensure # 确保依赖已满足

启用与禁用

fiftyone plugins enable <name> # 启用插件 fiftyone plugins enable <name1> <name2> ... # 启用多个 fiftyone plugins enable --all # 启用全部 fiftyone plugins disable <name> # 禁用插件 fiftyone plugins disable --all # 禁用全部

禁用状态以enabled: false形式存储于插件的配置设置中。被禁用插件的操作符不会出现在 App 的操作符浏览器中，可通过fiftyone app config plugins查看，例如：

{ "map": { "mapboxAccessToken": "XXXXXXXX" }, "@voxel51/zoo": { "enabled": false }, ... }

删除插件

fiftyone plugins delete <name> # 删除单个插件 fiftyone plugins delete <name1> <name2> ... # 删除多个 fiftyone plugins delete --all # 删除全部

插件配置与密钥（Secrets）

支持配置的插件，可将系统级设置存放于 App 配置的plugins键下，或将数据集级设置存放于数据集的 App 配置中。

部分插件需要 API Token 或登录凭据等敏感信息，这些密钥以secrets键声明在插件的fiftyone.yml中。例如@voxel51/annotation声明：

secrets: - FIFTYONE_CVAT_URL - FIFTYONE_CVAT_USERNAME - FIFTYONE_CVAT_PASSWORD - FIFTYONE_CVAT_EMAIL - FIFTYONE_LABELBOX_URL - FIFTYONE_LABELBOX_API_KEY - FIFTYONE_LABELSTUDIO_URL - FIFTYONE_LABELSTUDIO_API_KEY

密钥通过同名环境变量提供，例如使用 CVAT 后端：

FIFTYONE_CVAT_URL=... FIFTYONE_CVAT_USERNAME=... FIFTYONE_CVAT_PASSWORD=... FIFTYONE_CVAT_EMAIL=...

运行时，插件执行上下文会自动注入插件声明的可用密钥，操作符通过ctx.secrets字典访问：

def execute(self, ctx): url = ctx.secrets["FIFTYONE_CVAT_URL"] username = ctx.secrets["FIFTYONE_CVAT_USERNAME"] password = ctx.secrets["FIFTYONE_CVAT_PASSWORD"] email = ctx.secrets["FIFTYONE_CVAT_EMAIL"]

密钥的加载与管理实现在 fiftyone/plugins/secrets.py 中，可作为深入阅读入口。

使用操作符（Operators）

操作符（Operators）是插件框架中允许开发者在 App 内定义自定义操作的强大特性（自 OSS 0.21.0 / Enterprise 1.3.0 起提供）。部分操作符会以按钮、图标或菜单项形式暴露在 App 各处；而操作符浏览器（Operator Browser）允许用户搜索所有可用（已启用）的操作符。

打开方式：点击样本网格上方的操作符浏览器图标，或在键盘上输入反引号`。操作符提供动态输入表单收集所需输入，点击底部的Execute/Schedule按钮执行实际操作。有些操作符执行即时动作，有些则委托到其他进程执行。

通过 SDK 调用操作符

自 OSS 0.23.0 / Enterprise 1.5.0 起，许多操作符设计为可通过 SDK 以编程方式执行。按约定，此类操作符实现__call__()以提供良好的函数式调用接口。例如@voxel51/utils/compute_metadata：

import fiftyone as fo import fiftyone.operators as foo import fiftyone.zoo as foz dataset = foz.load_zoo_dataset("quickstart") compute_metadata = foo.get_operator("@voxel51/utils/compute_metadata") # (重新)计算数据集的元数据 compute_metadata(dataset, overwrite=True)

其中get_operator()用于按 URI 获取操作符。其底层__call__()实现将关键字参数打包为操作符的ctx.params，再交给execute_operator()执行：

class ComputeMetadata(foo.Operator): def __call__( self, sample_collection, overwrite=False, num_workers=None, ): ctx = dict(view=sample_collection.view()) params = dict( overwrite=overwrite, num_workers=num_workers, ) return foo.execute_operator(self.uri, ctx, params=params)

对于execute()返回数据的操作符，可通过返回的ExecutionResult对象的result属性访问结果：

op = foo.get_operator("@an-operator/with-results") result = op(...) print(result.result) # {...}

在 notebook 环境中执行操作符会返回asyncio.Task，需要await获取结果：

result = await op(...) print(result.result) # {...}

请求委托执行

支持委托执行的操作符，可通过向execute_operator()传入request_delegation=True来请求委托。compute_metadata正是如此（其 OperatorConfig 设置allow_immediate_execution=True, allow_delegated_execution=True）：

compute_metadata = foo.get_operator("@voxel51/utils/compute_metadata") # 调度一个委托操作来(重新)计算元数据 compute_metadata(dataset, overwrite=True, delegate=True)

直接执行

可以直接调用execute_operator()编程式执行任意操作符。通常需要查看操作符execute()实现以了解所需参数。示例：导出 COCO 标签：

import fiftyone as fo import fiftyone.operators as foo import fiftyone.zoo as foz dataset = foz.load_zoo_dataset("quickstart") ctx = { "view": dataset.take(10), "params": dict( export_type="LABELS_ONLY", dataset_type="COCO", labels_path=dict(absolute_path="/tmp/coco/labels.json"), label_field="ground_truth", ) } foo.execute_operator("@voxel51/io/export_samples", ctx)

同样，结果通过result.result访问（notebook 中需await）。请求委托：

foo.execute_operator(operator_uri, ctx=ctx, request_delegation=True)

这与在 App 操作符输入弹窗中选择Schedule等效。Enterprise 用户还可指定委托目标：

foo.execute_operator( operator_uri, ctx=ctx, request_delegation=True, delegation_target="overnight", )

委托任意函数调用

自 OSS 0.23.2 / Enterprise 1.5.3 起，@voxel51/utils/delegate操作符提供通用工具，可委托任意函数调用，支持三种形式：执行任意函数fcn(*args, **kwargs)；对数据集/视图应用函数fcn(dataset_or_view, *args, **kwargs)；调用数据集/视图的实例方法dataset_or_view.fcn(*args, **kwargs)。示例：

import fiftyone as fo import fiftyone.operators as foo import fiftyone.zoo as foz dataset = foz.load_zoo_dataset("quickstart") delegate = foo.get_operator("@voxel51/utils/delegate") # 计算元数据 delegate("compute_metadata", dataset=dataset) # 计算可视化 delegate( "fiftyone.brain.compute_visualization", dataset=dataset, brain_key="img_viz", ) # 导出视图 delegate( "export", view=dataset.to_patches("ground_truth"), export_dir="/tmp/patches", dataset_type="fiftyone.types.ImageClassificationDirectoryTree", label_field="ground_truth", ) # 将导出的 patches 加载为新数据集 delegate( "fiftyone.Dataset.from_dir", dataset_dir="/tmp/patches", dataset_type="fiftyone.types.ImageClassificationDirectoryTree", label_field="ground_truth", name="patches", persistent=True, )

委托执行与编排器

委托操作（Delegated Operations）允许你在 App 内调度可能耗时较长的任务，在后台执行的同时继续工作。官方定位是：借助委托操作，FiftyOne 既是数据集管理与可视化工具，也是定义数据摄取、整理、评估等工作流的工作流自动化工具。

• FiftyOne Enterprise：开箱即用地提供连接的计算集群来大规模执行委托操作，也可接入 Databricks 或 Anyscale 等自有计算方案；
• FiftyOne Open Source：可小规模地通过本地编排器运行委托操作。

Open Source 编排器

自 OSS 1.1.0 / Enterprise 2.2.0 起，Open Source 用户通过以下命令运行委托操作：

fiftyone delegated launch

该命令启动一个服务，持续检查已排队的委托操作并在其进程中串行执行。同时必须确保运行 App/SDK 的环境中设置了allow_legacy_orchestrators配置标志：

export FIFTYONE_ALLOW_LEGACY_ORCHESTRATORS=true

该配置项在 fiftyone/core/config.py 中定义，可通过 docs/source/user_guide/config.rst 了解 FiftyOne 配置体系的完整说明。

管理委托操作

fiftyone delegated命令组提供多种状态查看工具：

# 列出所有委托操作 fiftyone delegated list # 列出特定委托操作 fiftyone delegated list \ --dataset quickstart \ --operator @voxel51/io/export_samples \ --state COMPLETED \ --sort-by COMPLETED_AT \ --limit 10

查看单个委托操作的元数据（含输入、执行状态与错误堆栈）：

fiftyone delegated info <id>

清理委托操作：

# 删除某数据集关联的所有失败操作 fiftyone delegated cleanup --dataset quickstart --state FAILED # 删除所有与不存在数据集关联的委托操作 fiftyone delegated cleanup --orphan # 仅打印信息而不实际删除 fiftyone delegated cleanup --orphan --dry-run

委托操作的服务端存储与执行逻辑可参考 fiftyone/server/ 与 fiftyone/operators/delegated.py。

插件开发基础：类型、组件与插件解剖

根据 developing_plugins.rst，插件的构建块包括：Panels（面板）、Operators（操作符）、Skills（技能）与Components（组件），共同构成可定制的交互式数据应用。

插件类型

• Python 插件：基于fiftyone包、pip 包与 Python 构建，可包含面板、操作符与技能；
• JS 插件：基于@fiftyoneTypeScript 包、npm 包与 TypeScript 构建，可包含面板、操作符、技能与自定义组件；
• 两者也可组合使用。

技能（Skills）

技能是教 AI 智能体如何用自然语言执行复杂 FiftyOne 工作流的 Markdown 文件。每个技能描述一个可要求智能体执行的任务，提供分步指导，使智能体能够自主完成工作流。技能相关文档见 docs/source/agents/developing_skills.rst，开发技能入门见 docs/source/getting_started/agents/index.rst。

插件解剖与 fiftyone.yml

FiftyOne 通过在插件目录中搜索fiftyone.yml或fiftyone.yaml文件来识别插件。典型目录结构：

/path/to/your/plugins/dir/ my-js-plugin/ fiftyone.yml package.json dist/ index.umd.js my-py-plugin/ fiftyone.yml __init__.py requirements.txt

如果源码已存在于磁盘，可用create_plugin()或fiftyone plugins create命令将其制作成插件（会复制代码到插件目录并生成fiftyone.yml）。若 App 正在运行，重启服务器并刷新浏览器才能看到新插件。

fiftyone.yml是所有插件必需的元数据文件，声明插件元数据、暴露的操作符/面板、所需密钥。可用字段如下：

官方推荐使用@user-or-org-name/plugin-name命名约定。Python 插件需包含__init__.py（必需入口，定义操作符/面板）与requirements.txt；JS 插件需包含package.json（含 JS bundle 路径信息）与dist/index.umd.js（bundle 文件）。

以本仓库自带的 plugins/operators/fiftyone.yml（@voxel51/operators，核心内置操作符）为例，它声明了edit_field_info、clone_selected_samples、create_index、save_view等数十个内置操作符；plugins/panels/fiftyone.yml（@voxel51/panels）则声明了similarity_search、init_similarity_run等操作符以及model_evaluation_panel_builtin、similarity_search_panel两个内置面板。这些是本仓库中"以内置插件形式实现核心功能"的实例。

操作符开发、执行上下文（ctx）、输入定义（字符串、数值、布尔、日期、下拉/自动补全、单选、条件输入、文件、列表、代码、标签页输入等模式）及缓存、异步数据加载等进阶内容，均收录在 developing_plugins.rst 中；Python 侧的底层实现可见 fiftyone/operators/（如 fiftyone/operators/operator.py、fiftyone/operators/types.py），插件注册与加载核心在 fiftyone/plugins/core.py 与 fiftyone/plugins/definitions.py。

向社区贡献插件

根据 contributing_plugins.rst，共享插件可以帮你解决他人同类问题、获得社区反馈与贡献、在官方插件生态中展示作品、建立贡献者声誉。

通过 GitHub 共享

最简单的共享方式是发布到 GitHub：创建公共仓库，提供清晰的README.md（说明插件功能、安装指引、带代码片段的使用示例、运行截图/GIF）。用户随后可直接安装：

fiftyone plugins download https://github.com/your-username/your-plugin

提交到插件生态

插件生态页面会直接渲染你插件 GitHub 仓库的 README，因此务必精心编写 README（清晰描述、使用示例与截图）。

提交流程：

1. Fork 仓库：在 GitHub 上 Forkvoxel51/fiftyone-plugins；
2. 添加到社区表格：编辑 README，新增一行与现有行格式一致的条目；
3. 提交 Pull Request：包含清晰标题（如 "Add my-awesome-plugin to community plugins"）、插件功能简述、便于检索的分类/标签；
4. 评审流程：FiftyOne 团队评审 PR，合并后插件即出现在插件生态页面。

质量检查清单

共享前请确认：

需要帮助时，可在社区论坛提问、浏览插件生态获取灵感，或参阅完整开发文档 developing_plugins.rst。

小结

从生态索引页出发，本文完整覆盖了 FiftyOne 插件的四条主线：发现与下载（CLI/Python、GitHub 仓库与私有仓库令牌）、管理与配置（插件目录、fiftyone plugins/fiftyone operators命令族、密钥机制）、使用与执行（操作符浏览器、SDK 调用、委托执行与编排器）、以及开发与贡献（插件类型、fiftyone.yml结构、生态提交流程）。在此基础上，可以进一步深入 developing_plugins.rst 学习操作符输入定义与面板开发，或参考本仓库 plugins/ 下的内置插件实例开始动手实践。

【免费下载链接】fiftyoneRefine high-quality datasets and visual AI models项目地址: https://gitcode.com/GitHub_Trending/fi/fiftyone