FiftyOne Agent Ecosystem 实战指南:用 MCP 与 Skills 让 AI 助手直接操作数据集
FiftyOne Agent Ecosystem 实战指南:用 MCP 与 Skills 让 AI 助手直接操作数据集
本文以 FiftyOne 官方文档 Agent Ecosystem(含 Using Agents 与 Developing Tools & Skills)为主线,系统讲解 FiftyOne Agent Ecosystem 的组成、安装配置、可用工具与二次开发方法,并结合仓库源码说明其底层实现。读完本文,你将掌握:如何把 Claude、Cursor、VS Code、GitHub Copilot 等 AI 工具接入 FiftyOne 数据集,如何用一句自然语言完成数据导入、模型推理、查重、评估等真实操作,以及如何编写 Operator 与 SKILL.md 技能,让 Agent 学会你的自定义工作流。
可用性说明:Agent Ecosystem 自 FiftyOne OSS 1.16.0、FiftyOne Enterprise 2.19.0 起可用。
什么是 Agent Ecosystem:MCP 与 Skills 的分工
FiftyOne Agent Ecosystem 的核心是让 AI 助手不止于生成代码,而是真正对数据采取行动。它可以导入数据集、运行模型推理、查找重复样本、评估预测结果、构建自定义插件——全部通过一条自然语言指令完成。
这套体系由两个互补的组件构成,分别解决"连接"与"引导"两个问题:
- FiftyOne MCP Server:负责连接。它实现了开放的 Model Context Protocol(MCP)标准,把 Agent 与 FiftyOne 的 80+ 运算符、数据集管理、模型推理、brain 计算以及 App 连接起来,让任何兼容 MCP 的 Agent 都能直接访问你的数据和工具。
- FiftyOne Skills:负责引导。每个 Skill 都是一段专家工作流,教会 Agent"如何正确、在何时"完成某个特定任务(导入数据、查找重复、可视化 embedding 等),把工具封装成可重复的端到端流程。
用文档中的话来说:MCP 暴露系统能做什么,Skills 解释何时以及如何去做。仅有工具时,Agent 的能力是强大但模糊的;Skills 把经验、决策和护栏编码成工作流,让 Agent 从"我会调用函数"升级为"我知道如何端到端地完成这个任务"。两者合在一起,才构成"两部分、一个系统"(Two Parts, One System)的完整生态。
快速上手:四步接入你的 AI 工具
Step 1:安装 MCP Server
在安装了 FiftyOne 的同一个 Python 环境中安装:
pip install fiftyone-mcp-server
警告:必须安装到与 FiftyOne 相同的 Python 环境中。如果使用 virtualenv 或 conda 环境,请先激活该环境,或在 AI 工具配置中使用可执行文件的完整路径。
验证安装是否成功:
fiftyone-mcp
正常会看到以下输出:
Starting fiftyone-mcp server...
fiftyone-mcp server initialized successfully
按 Ctrl+C 停止它。配置完成后,你的 AI 工具会自动管理服务器生命周期,无需手动启停。
Step 2:配置你的 AI 工具
不同 AI 工具的配置方式如下(均可直接复制使用)。
Claude Code——使用命令行注册:
claude mcp add fiftyone -- fiftyone-mcp
Claude Desktop——编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"fiftyone": {
"command": "fiftyone-mcp"
}
}
}
Cursor——添加到 ~/.cursor/mcp.json(全局)或 .cursor/mcp.json(项目级):
{
"mcpServers": {
"fiftyone": {
"command": "fiftyone-mcp"
}
}
}
保存后重启 Cursor 生效。
VS Code——添加到 .vscode/mcp.json:
{
"servers": {
"fiftyone": {
"command": "fiftyone-mcp",
"type": "stdio"
}
}
}
GitHub Copilot——在工作区创建 .vscode/mcp.json(不存在则新建):
{
"servers": {
"fiftyone": {
"type": "stdio",
"command": "fiftyone-mcp"
}
}
}
然后在 Copilot Chat 中启用 Agent mode,MCP 工具会在服务器配置完成后自动出现。
Gemini CLI——Gemini CLI 扩展会自动注册 MCP 服务器,将 Skills 与 MCP 一起安装:
gemini extensions install https://github.com/voxel51/fiftyone-skills.git --consent
如果 fiftyone-mcp 不在 PATH 中,编辑扩展配置改用可执行文件的完整路径。
Antigravity——在项目目录创建或编辑 .antigravity/mcp.json:
{
"mcpServers": {
"fiftyone": {
"command": "fiftyone-mcp"
}
}
}
保存后重启 Antigravity 生效。
uvx(免安装方案)——如果你安装了 uv,可以完全跳过 pip install 步骤:
{
"mcpServers": {
"fiftyone": {
"command": "uvx",
"args": ["fiftyone-mcp-server"]
}
}
}
Step 3:安装 Skills
Skills 教会 Agent 如何端到端完成复杂的 FiftyOne 工作流。运行下面的命令,下载通用安装器(universal installer)并从默认技能包安装:
curl -sL skil.sh | sh -s -- voxel51/fiftyone-skills
你还可以参考《Developing Tools & Skills》开发并安装自己的 Skills,教会 Agent 针对你项目的自定义工作流。完整的可用 Skills 列表与各 Agent 的分步安装说明见 Agent Ecosystem 首页(该页的技能卡片由文档构建脚本从 marketplace 清单动态生成,详见后文"从源码看实现")。
Step 4:开始使用
配置完成后,直接用自然语言与你的 Agent 对话即可:
"List all my datasets"
"Load quickstart dataset and show summary"
"Open the map panel and show me the embeddings"
"Select samples with confidence above 0.9"
"What plugins are available? Install the brain plugin"
"Find near-duplicate images in my dataset"
Agent 会自动发现运算符(operators)并执行相应的工具,无需你手动指定函数。
可用工具全景
MCP Server 按功能类别为 Agent 提供了以下工具组(数据来自 using_agents.rst 的工具清单):
| 类别 | 工具数 | 功能说明 |
|---|---|---|
| 📊 Dataset Management | 3 | 列出、加载、汇总数据集 |
| 🎯 App Operations | 29 | 控制 App 界面(视图、面板、选择等) |
| ⚡ Operator System | 3 | 发现并执行任意 FiftyOne 运算符 |
| 🔄 Pipelines | 2 | 运行流水线并管理委托操作 |
| 🔌 Plugin Management | 5 | 发现、安装、管理插件 |
| 🖥️ Session | 1 | 启动 FiftyOne App 服务器 |
| 📈 Aggregations | 8 | 计数、去重、边界、均值、直方图等 |
| 🧬 Samples | 5 | 在样本上添加、打标签、取消标签、设置值 |
| 🗂️ Schema | 2 | 检查并修改数据集字段 schema |
| 🎨 App Config | 6 | 配色方案、侧边栏分组、激活字段 |
其中 Operator System 的三件套(发现、理解、执行)正是后文"把 Operator 变成 Agent 工具"的接入点:Agent 通过 list_operators 发现全部已安装运算符,通过 get_operator_schema 理解运算符接受哪些输入,通过 execute_operator 实际运行它。
Tool Modes:按集成方式选择工具集
哪些工具可用取决于你的集成方式:
| 集成方式 | Modes | 适用场景 |
|---|---|---|
| Voxel-Agent | app + sdk |
在 FiftyOne Enterprise 中的 Agent(完整的 UI 控制 + 数据操作) |
| Terminal / CLI | session + sdk |
无头 Agent(启动 App、查询数据、执行运算符) |
简单说:在 Enterprise App 里聊天时用 app 模式获得完整的界面控制能力;在终端/CLI 环境下则用 session 模式(可启动 App 服务器)配合 sdk 模式执行数据操作与运算符。
从源码看实现:Skill 的发现与解析机制
Agent Ecosystem 并不只是外部仓库,FiftyOne 本仓库已经内置了完整的 Skills 支持层,可以印证文档所述机制。
插件内技能加载:fiftyone/plugins/skills.py
skills.py 定义了 SkillDefinition 类与 list_skills() 函数。SkillDefinition 封装了技能的四个核心属性(源码中的 to_dict() 输出结构):
name:技能名称,优先取 YAML frontmatter 中的name字段,缺省时用 SKILL.md 所在目录名description:技能描述(决定 Agent 何时激活该技能,见下文编写规范)category:技能分类(如数据导入、去重等,用于过滤)plugin_name:提供该技能的插件名
list_skills(enabled=True, plugin=None, category=None) 的加载流程如下:
- 调用
fiftyone.plugins.list_plugins()列出插件定义(支持按enabled筛选启用/禁用/全部); - 按
plugin参数过滤插件、按category参数过滤技能; - 对每个插件执行
_iter_plugin_skills():读取插件fiftyone.yml中声明的skills列表,扫描插件目录下的skills/子目录,为每个含SKILL.md的子目录解析 YAML frontmatter,最后只产出在 fiftyone.yml 中显式声明的技能。
由此可以确认文档中的一个关键约定:SKILL.md frontmatter 中的 name 必须与插件 fiftyone.yml 中 skills: 声明的名称一致,否则技能不会被加载(源码中会输出 Skill '%s' declared but not found in skills/ 的调试日志并跳过)。
CLI 查询入口:fiftyone skills list
cli.py 中的 SkillsCommand 提供了命令行查询技能的能力:
# 列出全部可用技能
fiftyone skills list
# 只列某个插件的技能
fiftyone skills list --plugin @voxel51/my-plugin
# 只列某个分类的技能
fiftyone skills list --category data-ingestion
# 只列已启用插件的技能
fiftyone skills list --enabled
# 只显示技能名称
fiftyone skills list --names-only
其底层正是调用 fop.list_skills()(见 _print_skills_list 的实现),并按插件分组输出名称、分类、来源插件与启用状态。
文档技能卡片:动态生成
Agent Ecosystem 首页 通过 .. include:: skills_ecosystem/skill_cards.rst 嵌入技能卡片,而 skills_ecosystem/ 目录与卡片文件由构建脚本 generate_skills_docs.py 在文档构建时动态生成:脚本从技能仓库的 .claude-plugin/marketplace.json 拉取 marketplace 清单、解析每个技能 SKILL.md 的 YAML frontmatter,生成卡片 RST(customcarditem 块,含 emoji、描述、分类标签、跳转链接)与逐技能的详情页。这就是为什么首页能提供可搜索的技能卡片列表,同时每个技能页的 description 会注入 SEO 的 meta 描述与关键字。
开发自有工具:把 Operator 变成 Agent 工具
FiftyOne 提供两条扩展 Agent 能力的途径:
- Operators(运算符):编写一个 FiftyOne operator,它通过 MCP Server 立刻就能被任何 Agent 调用,无需额外接线;
- Skills(技能):编写一个 FiftyOne skill,教会 Agent 何时以及如何执行一段代码/运算符调用序列,以完成某个更高级的任务。
两者的配合方式是:operator 负责执行,skill 负责引导,并且可以打包进同一个插件发布。
任何 Operator 都自动成为 Agent 工具
你在插件中注册的任意 Operator 都会自动对 Agent 可用。Agent 通过 MCP 连接后,只需三步即可使用它:
- 调用
list_operators发现所有已安装运算符; - 调用
get_operator_schema理解运算符接受哪些输入; - 调用
execute_operator运行它。
安装插件即可,无需任何额外配置。
一个最小示例:按置信度过滤
以下是一个按置信度阈值过滤样本的最小 Operator(来自 developing_skills.rst):
import fiftyone.operators as foo
from fiftyone.operators import types
from fiftyone import ViewField as F
class ShowHighConfidence(foo.Operator):
@property
def config(self):
return foo.OperatorConfig(
name="show_high_confidence",
label="Show High Confidence",
description="Filter samples by minimum confidence threshold",
)
def resolve_input(self, ctx):
inputs = types.Object()
inputs.float(
"threshold",
label="Minimum confidence",
default=0.9,
)
return types.Property(inputs)
def execute(self, ctx):
threshold = ctx.params.get("threshold", 0.9)
view = ctx.dataset.filter_labels(
"predictions", F("confidence") > threshold
)
ctx.ops.set_view(view)
def register(p):
p.register(ShowHighConfidence)
对照仓库中 operator.py 的 Operator 基类可以印证:子类必须实现 config 属性与 execute(ctx) 方法(基类中 execute 直接抛出 NotImplementedError),而 resolve_input(ctx) 用于声明输入 schema,供 UI 或 Agent 渲染表单/理解参数——这正是 get_operator_schema 得以工作的基础。每个 Operator 还有 uri(plugin_name/operator_name)作为唯一标识,以及 risk_level 属性供 Agent 的护栏系统(guardrail)对工具调用分类。
插件安装后,Agent 可以自然地进行如下对话:
"Show me samples with confidence above 0.85"
此时 Agent 实际执行的是 execute_operator,参数为:
{"operator": "show_high_confidence", "params": {"threshold": 0.85}}
完整的 Operator 与面板 API 参考见仓库中的 Developing plugins 指南。
编写一个 Skill:SKILL.md 规范
Skill 是一个遵循 Agent Skills 规范的 SKILL.md 文件,它告诉 Agent:何时激活该工作流、需要检查哪些前置条件、按什么步骤执行。
文件布局:
skills/
└── my-skill/
└── SKILL.md
SKILL.md 格式:
---
name: my-skill
description: When to activate this skill (shown to the agent)
category: Curation
emoji: ✂️
---
# Overview
What this skill does in one paragraph.
# Prerequisites
- FiftyOne installed
- MCP server configured (if interacting with live datasets)
# Key Directives
ALWAYS load the dataset before running any operation.
NEVER delete samples without confirming with the user first.
# Workflow
Step-by-step instructions the agent follows to complete the task.
# Troubleshooting
Common errors and how to resolve them.
最重要的字段是 description:它决定 Agent 何时决定调用该技能。文档给出的经验是:描述要具体、面向行动,例如 "Import a dataset from local disk, Hugging Face Hub, or cloud storage into FiftyOne" 远优于笼统的 "import data"。
在插件中随附 Skill:让生态变成能力
把 Operator 和它的 Skill 一起发布最干净的方式,是在插件的 fiftyone.yml 中声明技能:
name: "@myorg/my-plugin"
version: "1.0.0"
fiftyone:
version: ">=0.23"
skills:
- my-skill
注意:skills: 下声明的名称必须与对应 SKILL.md 的 YAML frontmatter 中的 name 字段一致。如前面源码分析所示,skills.py 通过扫描插件 skills/ 目录并匹配该字段来解析技能;definitions.py 中的 PluginDefinition.skills 属性则负责从 fiftyone.yml 元数据读出声明列表。
当用户安装你的插件时,Skill 自动可用:Agent 既能通过 MCP 发现对应的 Operator,又拥有如何使用它的结构化指导,用户端零手动配置。这就是 FiftyOne 插件生态如何演进为 Agent 能力生态——每一个随附 Skill 的插件,都在扩展 Agent 开箱即用的能力边界。
向社区贡献一个 Skill
只有在技能是通用的、打磨完善、且跨项目广泛有用时,才适合贡献到公开技能仓库;针对特定数据集、模型或内部工作流开发的技能,更适合留在自己的插件中。
向 voxel51/fiftyone-skills 仓库贡献技能的步骤:
- Fork 该仓库;
- 复制一个现有技能目录作为起点(例如
skills/fiftyone-find-duplicates/); - 更新
SKILL.md为你的工作流; - 添加你的技能到
.claude-plugin/marketplace.json; - 用你的 AI 助手测试它;
- 提交 Pull Request。
资源清单
| 资源 | 说明 |
|---|---|
| FiftyOne MCP Server | MCP 服务器源码与贡献指南(PyPI 包名 fiftyone-mcp-server) |
| FiftyOne Skills | AI 助手的专家工作流技能仓库 |
| FiftyOne Plugins | 官方插件合集 |
| Model Context Protocol | MCP 规范 |
MCP Discovery Manifest(/.well-known/mcp.json) |
机器可读的 FiftyOne MCP 服务器清单 |
Skills Manifest(/.well-known/skills.json) |
FiftyOne 技能市场清单的指针 |
| 本仓库文档 | Agent Ecosystem 首页、Using Agents、Developing Tools & Skills |
至此,你已经掌握了 FiftyOne Agent Ecosystem 的完整链路:从安装 MCP Server、为各类 AI 工具配置接入,到理解内置工具分组与 Tool Modes,再到用 Operator + SKILL.md 扩展 Agent 的自定义能力。下一步,可以直接在你的数据集上对 Agent 说一句"Find near-duplicate images in my dataset",体验从提示词到真实数据操作的完整闭环。