FiftyOne 嵌入可视化

概述

使用深度学习嵌入和降维（UMAP/t-SNE）在2D中可视化您的数据集。探索聚类，发现异常值，并按任何字段对样本进行着色。

使用此技能时：

在2D中可视化数据集结构
在图像中寻找自然聚类
识别异常值或异常
按类别或元数据探索数据分布
理解嵌入空间关系

前提条件

安装并运行FiftyOne MCP服务器
安装并启用@voxel51/brain插件
数据集已加载到FiftyOne中的图像样本

关键指令

始终遵循这些规则：

1. 首先设置上下文

set_context(dataset_name="我的-数据集")

2. 启动FiftyOne App

Brain操作符是委托的，需要应用程序：

launch_app()

等待5-10秒初始化。

3. 动态发现操作符

# 列出所有brain操作符
list_operators(builtin_only=False)

# 获取特定操作符的模式
get_operator_schema(operator_uri="@voxel51/brain/compute_visualization")

4. 在可视化之前计算嵌入

降维需要嵌入：

execute_operator(
    operator_uri="@voxel51/brain/compute_similarity",
    params={
        "brain_key": "img_sim",
        "model": "clip-vit-base32-torch",
        "embeddings": "clip_embeddings",
        "backend": "sklearn",
        "metric": "cosine"
    }
)

5. 完成后关闭应用程序

close_app()

完整工作流程

第1步：设置

# 设置上下文
set_context(dataset_name="我的-数据集")

# 启动应用程序（brain操作符所需）
launch_app()

第2步：验证Brain插件

# 检查brain插件是否可用
list_plugins(enabled=True)

# 如果未安装：
download_plugin(
    url_or_repo="voxel51/fiftyone-plugins",
    plugin_names=["@voxel51/brain"]
)
enable_plugin(plugin_name="@voxel51/brain")

第3步：发现Brain操作符

# 列出所有可用操作符
list_operators(builtin_only=False)

# 获取compute_visualization的模式
get_operator_schema(operator_uri="@voxel51/brain/compute_visualization")

第4步：检查现有嵌入或计算新嵌入

首先，检查数据集是否已有嵌入，方法是查看操作符模式：

get_operator_schema(operator_uri="@voxel51/brain/compute_visualization")
# 查看"embeddings"选项中现有的嵌入字段
# （例如，"clip_embeddings", "dinov2_embeddings"）

**如果嵌入存在：**跳到第5步，使用现有的嵌入字段。

**如果嵌入不存在：**计算它们：

execute_operator(
    operator_uri="@voxel51/brain/compute_similarity",
    params={
        "brain_key": "img_viz",
        "model": "clip-vit-base32-torch",
        "embeddings": "clip_embeddings",  # 存储嵌入的字段名称
        "backend": "sklearn",
        "metric": "cosine"
    }
)

compute_similarity的必需参数：

brain_key - 此brain运行的唯一标识符
model - 来自FiftyOne模型库的模型，用于生成嵌入
embeddings - 存储嵌入的字段名称
backend - 相似性后端（使用"sklearn"）
metric - 距离度量（使用"cosine"或"euclidean"）

推荐的嵌入模型：

clip-vit-base32-torch - 适用于一般视觉+语义相似性
dinov2-vits14-torch - 适用于仅视觉相似性
resnet50-imagenet-torch - 经典的CNN特征
mobilenet-v2-imagenet-torch - 快速，轻量级选项

第5步：计算2D可视化

使用现有嵌入字段或第4步的brain_key：

# 选项A：使用现有嵌入字段（例如，clip_embeddings）
execute_operator(
    operator_uri="@voxel51/brain/compute_visualization",
    params={
        "brain_key": "img_viz",
        "embeddings": "clip_embeddings",  # 使用现有字段
        "method": "umap",
        "num_dims": 2
    }
)

# 选项B：使用compute_similarity中的brain_key
execute_operator(
    operator_uri="@voxel51/brain/compute_visualization",
    params={
        "brain_key": "img_viz",  # 与compute_similarity中相同的密钥
        "method": "umap",
        "num_dims": 2
    }
)

降维方法：

umap - （推荐）保留局部和全局结构，更快。需要umap-learn包。
tsne - 更好的局部结构，大型数据集上更慢。没有额外的依赖。
pca - 线性降维，最快但信息最少

第6步：引导用户到嵌入面板

计算可视化后，引导用户打开FiftyOne应用程序在http://localhost:5151/并：

点击顶部工具栏中的嵌入面板图标（散点图图标，看起来像网格点）
从下拉菜单中选择brain key（例如，img_viz）
点代表2D嵌入空间中的样本
使用**“按颜色”**下拉菜单按字段（例如，ground_truth，predictions）着色点
点击点以选择样本，使用套索工具选择组

**重要提示：**不要使用set_view(exists=["brain_key"]) - 这会过滤样本，对于可视化不需要。嵌入面板自动显示所有计算坐标的样本。

第7步：探索和过滤（可选）

在嵌入面板中查看时过滤样本：

# 过滤到特定类别
set_view(filters={"ground_truth.label": "dog"})

# 按标签过滤
set_view(tags=["validated"])

# 清除过滤器以显示所有
clear_view()

这些过滤器将更新嵌入面板，仅显示匹配的样本。

第8步：寻找异常值

异常值出现在远离聚类的孤立点：

# 计算独特性分数（越高=越独特/异常值）
execute_operator(
    operator_uri="@voxel51/brain/compute_uniqueness",
    params={
        "brain_key": "img_viz"
    }
)

# 查看最独特的样本（潜在的异常值）
set_view(sort_by="uniqueness", reverse=True, limit=50)

第9步：寻找聚类

使用应用程序的嵌入面板直观识别聚类，然后：

选项A：在应用程序中使用套索选择

使用套索工具选择聚类
选定的样本被突出显示
标记或导出选定的样本

选项B：使用相似性找到聚类成员

# 按与代表性样本的相似性排序
execute_operator(
    operator_uri="@voxel51/brain/sort_by_similarity",
    params={
        "brain_key": "img_viz",
        "query_id": "来自聚类的样本_id",
        "k": 100
    }
)

第10步：清理

close_app()

可用工具

会话视图工具

工具	描述
`set_view(filters={...})`	按字段值过滤样本
`set_view(tags=[...])`	按标签过滤样本
`set_view(sort_by="...", reverse=True)`	按字段排序样本
`set_view(limit=N)`	限制为N个样本
`clear_view()`	清除过滤器，显示所有样本

可视化的Brain操作符

使用list_operators()发现和get_operator_schema()查看参数：

操作符	描述
`@voxel51/brain/compute_similarity`	计算嵌入和相似性索引
`@voxel51/brain/compute_visualization`	将嵌入降低到2D/3D以进行可视化
`@voxel51/brain/compute_uniqueness`	按独特性（异常值检测）评分样本
`@voxel51/brain/sort_by_similarity`	按与查询样本的相似性排序

常见用例

用例1：基本数据集探索

在可视化数据集结构并探索聚类：

set_context(dataset_name="我的-数据集")
launch_app()

# 检查模式中现有的嵌入
get_operator_schema(operator_uri="@voxel51/brain/compute_visualization")

# 如果嵌入存在（例如，clip_embeddings），直接使用它们：
execute_operator(
    operator_uri="@voxel51/brain/compute_visualization",
    params={
        "brain_key": "exploration",
        "embeddings": "clip_embeddings",
        "method": "umap",  # 或者如果umap-learn未安装则使用"tsne"
        "num_dims": 2
    }
)

# 引导用户到应用程序嵌入面板http://localhost:5151/
# 1. 点击嵌入面板图标
# 2. 从下拉菜单中选择"exploration"
# 3. 使用"按颜色"按ground_truth或预测着色

用例2：在数据集中找到异常值

识别异常或错误标记的样本：

set_context(dataset_name="我的-数据集")
launch_app()

# 检查模式中现有的嵌入
get_operator_schema(operator_uri="@voxel51/brain/compute_visualization")

# 如果没有嵌入存在，计算它们：
execute_operator(
    operator_uri="@voxel51/brain/compute_similarity",
    params={
        "brain_key": "outliers",
        "model": "clip-vit-base32-torch",
        "embeddings": "clip_embeddings",
        "backend": "sklearn",
        "metric": "cosine"
    }
)

# 计算独特性分数
execute_operator(
    operator_uri="@voxel51/brain/compute_uniqueness",
    params={"brain_key": "outliers"}
)

# 生成可视化（使用现有嵌入字段或brain_key）
execute_operator(
    operator_uri="@voxel51/brain/compute_visualization",
    params={
        "brain_key": "outliers",
        "embeddings": "clip_embeddings",  # 如果可用，使用现有字段
        "method": "umap",  # 或者如果umap-learn未安装则使用"tsne"
        "num_dims": 2
    }
)

# 引导用户到应用程序http://localhost:5151/
# 1. 点击嵌入面板图标
# 2. 从下拉菜单中选择"outliers"
# 3. 异常值出现在远离聚类的孤立点
# 4. 可选地，在应用程序侧边栏按独特性字段排序

用例3：在嵌入空间中比较类别

查看不同类别如何聚类：

set_context(dataset_name="我的-数据集")
launch_app()

# 检查模式中现有的嵌入
get_operator_schema(operator_uri="@voxel51/brain/compute_visualization")

# 如果没有嵌入存在，计算它们：
execute_operator(
    operator_uri="@voxel51/brain/compute_similarity",
    params={
        "brain_key": "class_viz",
        "model": "clip-vit-base32-torch",
        "embeddings": "clip_embeddings",
        "backend": "sklearn",
        "metric": "cosine"
    }
)

# 生成可视化（使用现有嵌入字段或brain_key）
execute_operator(
    operator_uri="@voxel51/brain/compute_visualization",
    params={
        "brain_key": "class_viz",
        "embeddings": "clip_embeddings",  # 如果可用，使用现有字段
        "method": "umap",  # 或者如果umap-learn未安装则使用"tsne"
        "num_dims": 2
    }
)

# 引导用户到应用程序http://localhost:5151/
# 1. 点击嵌入面板图标
# 2. 从下拉菜单中选择"class_viz"
# 3. 使用"按颜色"下拉菜单按ground_truth或预测着色
# 查找：
# - 良好分隔的聚类=良好的类别区分
# - 重叠的聚类=相似的类别或混淆
# - 散布的点=类别内高方差

用例4：分析模型预测

在嵌入空间中比较真实值与预测值：

set_context(dataset_name="我的-数据集")
launch_app()

# 检查模式中现有的嵌入
get_operator_schema(operator_uri="@voxel51/brain/compute_visualization")

# 如果没有嵌入存在，计算它们：
execute_operator(
    operator_uri="@voxel51/brain/compute_similarity",
    params={
        "brain_key": "pred_analysis",
        "model": "clip-vit-base32-torch",
        "embeddings": "clip_embeddings",
        "backend": "sklearn",
        "metric": "cosine"
    }
)

# 生成可视化（使用现有嵌入字段或brain_key）
execute_operator(
    operator_uri="@voxel51/brain/compute_visualization",
    params={
        "brain_key": "pred_analysis",
        "embeddings": "clip_embeddings",  # 如果可用，使用现有字段
        "method": "umap",  # 或者如果umap-learn未安装则使用"tsne"
        "num_dims": 2
    }
)

# 引导用户到应用程序http://localhost:5151/
# 1. 点击嵌入面板图标
# 2. 从下拉菜单中选择"pred_analysis"
# 3. 按ground_truth着色-查看真实类别分布
# 4. 按预测着色-查看模型视图
# 5. 查找不匹配项以发现错误

用例5：用于发布质量图表的t-SNE

使用t-SNE获得更好的局部结构（没有额外的依赖）：

set_context(dataset_name="我的-数据集")
launch_app()

# 检查模式中现有的嵌入
get_operator_schema(operator_uri="@voxel51/brain/compute_visualization")

# 如果没有嵌入存在，计算它们（DINOv2用于视觉相似性）：
execute_operator(
    operator_uri="@voxel51/brain/compute_similarity",
    params={
        "brain_key": "tsne_viz",
        "model": "dinov2-vits14-torch",
        "embeddings": "dinov2_embeddings",
        "backend": "sklearn",
        "metric": "cosine"
    }
)

# 生成t-SNE可视化（不需要umap-learn依赖）
execute_operator(
    operator_uri="@voxel51/brain/compute_visualization",
    params={
        "brain_key": "tsne_viz",
        "embeddings": "dinov2_embeddings",  # 如果可用，使用现有字段
        "method": "tsne",
        "num_dims": 2
    }
)

# 引导用户到应用程序http://localhost:5151/
# 1. 点击嵌入面板图标
# 2. 从下拉菜单中选择"tsne_viz"
# 3. t-SNE比UMAP提供更好的局部聚类结构

故障排除

错误：“没有可用的执行器”

原因：委托的操作符需要应用程序执行器
解决方案：确保调用了launch_app()并等待5-10秒

错误：“找不到brain key”

原因：未计算嵌入
解决方案：首先使用brain_key运行compute_similarity

错误：“找不到操作符”

原因：Brain插件未安装
解决方案：使用download_plugin()和enable_plugin()安装

错误：“您必须安装umap-learn>=0.5包”

原因：UMAP方法需要umap-learn包
解决方案：
1. 安装umap-learn：询问用户是否要运行pip install umap-learn
2. 改用t-SNE：将method更改为"tsne"（无需额外依赖）
3. 改用PCA：将method更改为"pca"（最快，无需额外依赖）
- 安装umap-learn后，重新启动Claude Code/MCP服务器并重试

可视化缓慢

对于大型数据集，使用UMAP代替t-SNE
使用更快的嵌入模型：mobilenet-v2-imagenet-torch
首先处理子集：set_view(limit=1000)

嵌入面板未显示

确保已计算可视化（不仅仅是嵌入）
检查brain_key在compute_similarity和compute_visualization中的匹配
刷新应用程序页面

点颜色不正确

验证字段是否存在于样本上
检查字段类型是否兼容（分类，检测或字符串）

最佳实践

动态发现 - 使用list_operators()和get_operator_schema()获取当前操作符名称和参数
选择正确的模型 - CLIP用于语义相似性，DINOv2用于视觉相似性
从UMAP开始 - 通常比t-SNE更快，更适合探索
使用独特性进行异常值检测 - 比单独的视觉检查更可靠
存储嵌入 - 通过brain_key重用于多个可视化
子集大型数据集 - 首先在子集上计算，然后在整个数据集上计算

性能说明

嵌入计算时间：

1,000张图像：~1-2分钟
10,000张图像：~10-15分钟
100,000张图像：~1-2小时

可视化计算时间：

UMAP：~30秒10,000个样本
t-SNE：~5-10分钟10,000个样本
PCA：~5秒10,000个样本

内存要求：

每张图像约2KB用于嵌入
每张图像约16字节用于2D坐标

FiftyOne嵌入可视化Skill fiftyone-embeddings-visualization