FiftyOne × Databricks Mosaic AI Search：为视觉数据构建可查询的向量相似性索引

FiftyOne × Databricks Mosaic AI Search：为视觉数据构建可查询的向量相似性索引

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

Databricks Mosaic AI Search 是内置于 Databricks Data Intelligence Platform 的向量数据库，与平台的数据治理与生产力工具深度集成。本文以 FiftyOne 官方集成文档为主线，系统讲解如何在 FiftyOne 中一键创建 Mosaic 向量索引、上传 embeddings、执行相似性查询（Python API 与 App 点选均可），并覆盖环境准备、三种认证方式、配置参数、索引管理与常见查询范式，帮助你在计算机视觉数据上直接复用 Mosaic 的向量检索能力。

本文内容对应 FiftyOne OSS 1.4.0 与 FiftyOne Enterprise 2.7.0 及以上版本（见 docs/source/integrations/mosaic.rst 中的版本声明），适用的核心 API 位于fiftyone.brain.compute_similarity与SampleCollection.sort_by_similarity。

提示：借助 Mosaic 相似性索引，你还可以直接用自然语言搜索数据（当底层模型支持文本提示时），详见 FiftyOne 的文本相似性搜索能力。

一、基本工作流（Basic Recipe）

在 FiftyOne 数据集上使用 Mosaic 建立相似性索引并查询数据，完整流程如下：

1. 连接你的 Databricks workspace，并创建一个 AI Search endpoint（向量搜索端点）。
2. 将数据集加载到 FiftyOne。
3. 为数据集中的样本（samples）或对象块（patches）计算 embedding 向量，或选择一个模型来生成 embeddings。
4. 调用compute_similarity()方法，设置backend="mosaic"并指定自定义的brain_key，为样本或对象块生成 Mosaic 相似性索引。
5. 使用该 Mosaic 索引，通过sort_by_similarity()查询数据。
6. （可选）删除索引。

运行上述流程前，你需要一个已启用 AI Search 的 Databricks 账号，并安装 Databricks AI Search Python 包：

pip install databricks-ai-search

同时按下文「认证」一节配置凭据，避免每次与 Mosaic 索引交互时手动输入。

下面是最小可运行示例——先加载数据集并直接由 FiftyOne 计算 embeddings、创建索引：

import fiftyone as fo import fiftyone.brain as fob import fiftyone.zoo as foz # Step 1: Load your data into FiftyOne dataset = foz.load_zoo_dataset("quickstart") # Steps 2 and 3: Compute embeddings and create a similarity index mosaic_index = fob.compute_similarity( dataset, brain_key="mosaic_index", backend="mosaic", )

索引生成后，通过brain_key查询数据：

# Step 4: Query your data query = dataset.first().id # query by sample ID view = dataset.sort_by_similarity( query, brain_key="mosaic_index", k=10, # limit to 10 most similar samples ) # Step 5 (optional): Cleanup # Delete the Mosaic index mosaic_index.cleanup() # Delete run record from FiftyOne dataset.delete_brain_run("mosaic_index")

可以看到，compute_similarity()在不指定model或embeddings时，会自动用默认模型为全部样本计算向量并建索引；sort_by_similarity()是定义在 fiftyone/core/collections.py 上的视图阶段，签名如下：

def sort_by_similarity(self, query, k=None, reverse=False, dist_field=None, brain_key=None)

其中query可以是样本/块的 ID、与索引同维度的向量、ID 列表或文本提示；k控制返回的最近邻数量，默认对整个集合排序；reverse=True则按最不相似排序（部分后端可能不支持）。

二、环境准备与安装（Setup）

使用 Mosaic AI Search 的前提：

• 拥有满足 AI Search 要求的 Databricks workspace；
• 已创建 AI Search endpoint（向量搜索端点）；
• 在 Databricks 中准备好用于创建 AI Search 索引的 catalog 与 schema（命名空间）。

安装 Mosaic AI Vector Search 客户端

要使用 Mosaic 后端，必须安装 Databricks Vector Search Python 包：

pip install databricks-ai-search

切换到 Mosaic 后端

默认情况下，compute_similarity()与sort_by_similarity()使用 sklearn 后端。要改用 Mosaic，只需将compute_similarity()的可选参数backend设为"mosaic"：

import fiftyone.brain as fob fob.compute_similarity(..., backend="mosaic", ...)

也可以永久性地将 FiftyOne 默认相似性后端切换为 Mosaic，两种方式任选其一：

方式一：环境变量

export FIFTYONE_BRAIN_DEFAULT_SIMILARITY_BACKEND=mosaic

方式二：brain 配置文件

编辑位于~/.fiftyone/brain_config.json的 brain 配置，设置default_similarity_backend：

{ "default_similarity_backend": "mosaic" }

关于默认后端的三种设置层级（单次调用传参 > 会话级环境变量 > 持久化配置文件），在 docs/source/user_guide/similarity.rst 中有完整说明；该文档同时列出了所有内置后端的配置类，其中 Mosaic 对应fiftyone.brain.internal.core.mosaic.MosaicSimilarityConfig（实现位于独立的fiftyone-brain包）。

三、认证（Authentication）

Databricks 凭据可以通过多种方式提供，以下三种由官方文档明确支持。

环境变量（推荐）

把凭据存入环境变量，FiftyOne 每次建立 Databricks 连接时自动读取：

export FIFTYONE_BRAIN_SIMILARITY_MOSAIC_WORKSPACE_URL=https://<unique-url>.cloud.databricks.com/ export FIFTYONE_BRAIN_SIMILARITY_MOSAIC_PERSONAL_ACCESS_TOKEN=XXXXXXXX export FIFTYONE_BRAIN_SIMILARITY_MOSAIC_CATALOG_NAME=XXXXXXXX export FIFTYONE_BRAIN_SIMILARITY_MOSAIC_SCHEMA_NAME=XXXXXXXX export FIFTYONE_BRAIN_SIMILARITY_MOSAIC_ENDPOINT_NAME=XXXXXXXX

这是认证 Mosaic 客户端的一组示例变量，Databricks 还支持更多认证方式（如服务主体、OAuth 等），可按需扩展。

FiftyOne Brain 配置

在~/.fiftyone/brain_config.json中存放凭据（注意：该文件默认不存在，需自行创建）：

{ "similarity_backends": { "mosaic": { "workspace_url": "https://<unique-url>.cloud.databricks.com/", "personal_access_token": "XXXXXXXX", "catalog_name": "XXXXXXXX", "schema_name": "XXXXXXXX", "endpoint_name": "XXXXXXXX" } } }

关键字参数

也可以在每次调用需要连接 Databricks 的方法（如compute_similarity()）时手动传入凭据：

import fiftyone.brain as fob mosaic_index = fob.compute_similarity( ... backend="mosaic", brain_key="mosaic_index", workspace_url = "https://<unique-url>.cloud.databricks.com/", personal_access_token = "XXXXXXXX", catalog_name = "XXXXXXXX", schema_name = "XXXXXXXX", endpoint_name = "XXXXXXXX" )

需要特别注意的是：采用这种策略时，之后通过load_brain_results()加载索引时，也必须手动再次提供全部凭据：

mosaic_index = dataset.load_brain_results( "mosaic_index", workspace_url = "https://<unique-url>.cloud.databricks.com/", personal_access_token = "XXXXXXXX", catalog_name = "XXXXXXXX", schema_name = "XXXXXXXX", endpoint_name = "XXXXXXXX" )

四、Mosaic 配置参数

Mosaic 后端支持以下参数定制相似性查询：

• index_name（None）：要使用或创建的 Mosaic AI Search 索引名称。若不指定，会自动生成一个新的唯一名称。

该参数可通过上文任一策略指定。以下是一个包含全部可用参数的 brain 配置示例：

{ "similarity_backends": { "mosaic": { "index_name": "your-index" } } }

不过，实践中更常见的做法是直接把它传给compute_similarity()，用于配置某个特定的新索引：

mosaic_index = fob.compute_similarity( ... backend="mosaic", brain_key="mosaic_index", index_name="your-index", )

从实现角度看，这类参数最终会汇聚到MosaicSimilarityConfig（fiftyone.brain.internal.core.mosaic.MosaicSimilarityConfig）中：每次调用compute_similarity()传入的关键字参数、brain_config.json中similarity_backends.mosaic段落的配置，以及对应的FIFTYONE_BRAIN_SIMILARITY_MOSAIC_*环境变量，共同决定了后端实例化时使用的连接信息与索引标识。

五、管理 Brain Runs

FiftyOne 提供一系列方法管理 brain runs（即相似性计算在数据集上留下的运行记录）。

列出 brain runs——查看数据集上可用的 brain keys：

import fiftyone.brain as fob # List all brain runs dataset.list_brain_runs() # Only list similarity runs dataset.list_brain_runs(type=fob.Similarity) # Only list specific similarity runs dataset.list_brain_runs( type=fob.Similarity, patches_field="ground_truth", supports_prompts=True, )

获取 brain run 信息——查看某个 brain run 的配置：

info = dataset.get_brain_info(brain_key) print(info)

加载索引实例——用load_brain_results()取回该 brain run 对应的SimilarityIndex实例。

重命名 brain key：

dataset.rename_brain_run(brain_key, new_brain_key)

删除运行记录：

dataset.delete_brain_run(brain_key)

上述方法均定义在 fiftyone/core/collections.py 中，例如list_brain_runs（L4927）、rename_brain_run（L4949）、get_brain_info（L4958）、load_brain_results（L4970）、delete_brain_run（L5008），它们对所有相似性后端统一生效。

注意：delete_brain_run()只删除 FiftyOne 数据集上的 brain run记录，不会删除关联的 Mosaic 索引。删除 Mosaic 索引需显式执行：

# Delete the Mosaic index mosaic_index = dataset.load_brain_results(brain_key) mosaic_index.cleanup()

六、实战示例：常见向量检索工作流

以下示例均假设已按上文配置好 Databricks 账号与凭据。

创建相似性索引

创建新的 Mosaic 相似性索引，需为compute_similarity()提供embeddings或model参数，共有四种常见写法：

import fiftyone as fo import fiftyone.brain as fob import fiftyone.zoo as foz dataset = foz.load_zoo_dataset("quickstart") model_name = "clip-vit-base32-torch" model = foz.load_zoo_model(model_name) brain_key = "mosaic_index" # Option 1: Compute embeddings on the fly from model name fob.compute_similarity( dataset, model=model_name, backend="mosaic", brain_key=brain_key, ) # Option 2: Compute embeddings on the fly from model instance fob.compute_similarity( dataset, model=model, backend="mosaic", brain_key=brain_key, ) # Option 3: Pass pre-computed embeddings as a numpy array embeddings = dataset.compute_embeddings(model) fob.compute_similarity( dataset, embeddings=embeddings, backend="mosaic", brain_key=brain_key, ) # Option 4: Pass pre-computed embeddings by field name dataset.compute_embeddings(model, embeddings_field="embeddings") fob.compute_similarity( dataset, embeddings="embeddings", backend="mosaic", brain_key=brain_key, )

四种方式的差异在于 embeddings 的供给途径：前两种由 FiftyOne 在创建索引时实时计算（按模型名或模型实例），后两种复用已算好的向量（numpy 数组或数据集字段）。

创建对象块（patch）相似性索引

通过patches_field参数，可以为数据集内的目标检测对象块建立相似性索引（每个检测框对应的图像块作为一个检索单元）：

import fiftyone as fo import fiftyone.brain as fob import fiftyone.zoo as foz dataset = foz.load_zoo_dataset("quickstart") fob.compute_similarity( dataset, patches_field="ground_truth", model="clip-vit-base32-torch", backend="mosaic", brain_key="mosaic_patches", )

连接已有索引

如果 Mosaic 中已存在存储了样本/块向量的索引，可通过index_name直接连接，并用embeddings=False跳过向量计算：

import fiftyone as fo import fiftyone.brain as fob import fiftyone.zoo as foz dataset = foz.load_zoo_dataset("quickstart") fob.compute_similarity( dataset, model="clip-vit-base32-torch", # zoo model used (if applicable) embeddings=False, # don't compute embeddings index_name="your-index", # the existing Mosaic index brain_key="mosaic_index", backend="mosaic", )

向索引增删 embeddings

修改数据集后，可用add_to_index()与remove_from_index()同步更新 Mosaic 索引：

import numpy as np import fiftyone as fo import fiftyone.brain as fob import fiftyone.zoo as foz dataset = foz.load_zoo_dataset("quickstart") mosaic_index = fob.compute_similarity( dataset, model="clip-vit-base32-torch", brain_key="mosaic_index", backend="mosaic", ) print(mosaic_index.total_index_size) # 200 view = dataset.take(10) ids = view.values("id") # Delete 10 samples from a dataset dataset.delete_samples(view) # Delete the corresponding vectors from the index mosaic_index.remove_from_index(sample_ids=ids) # Add 20 samples to a dataset samples = [fo.Sample(filepath="tmp%d.jpg" % i) for i in range(20)] sample_ids = dataset.add_samples(samples) # Add corresponding embeddings to the index embeddings = np.random.rand(20, 512) mosaic_index.add_to_index(embeddings, sample_ids) print(mosaic_index.total_index_size) # 210

注意示例中的 embeddings 维度为 512，需与索引所用模型（这里是 CLIP）的输出维度保持一致。

从索引取回 embeddings

用get_embeddings()按 ID 从 Mosaic 索引取回向量：

import fiftyone as fo import fiftyone.brain as fob import fiftyone.zoo as foz dataset = foz.load_zoo_dataset("quickstart") mosaic_index = fob.compute_similarity( dataset, model="clip-vit-base32-torch", brain_key="mosaic_index", backend="mosaic", ) # Retrieve embeddings for the entire dataset ids = dataset.values("id") embeddings, sample_ids, _ = mosaic_index.get_embeddings(sample_ids=ids) print(embeddings.shape) # (200, 512) print(sample_ids.shape) # (200,) # Retrieve embeddings for a view ids = dataset.take(10).values("id") embeddings, sample_ids, _ = mosaic_index.get_embeddings(sample_ids=ids) print(embeddings.shape) # (10, 512) print(sample_ids.shape) # (10,)

七、查询 Mosaic 索引

通过在任意数据集或视图上追加sort_by_similarity()阶段即可查询 Mosaic 索引。查询可以是以下任意一种：

• 一个 ID（样本或块）
• 一个与索引同维度的查询向量
• 一个 ID 列表（样本或块）
• 一段文本提示（当模型支持时）

import numpy as np import fiftyone as fo import fiftyone.brain as fob import fiftyone.zoo as foz dataset = foz.load_zoo_dataset("quickstart") fob.compute_similarity( dataset, model="clip-vit-base32-torch", brain_key="mosaic_index", backend="mosaic", ) # Query by vector query = np.random.rand(512) # matches the dimension of CLIP embeddings view = dataset.sort_by_similarity(query, k=10, brain_key="mosaic_index") # Query by sample ID query = dataset.first().id view = dataset.sort_by_similarity(query, k=10, brain_key="mosaic_index") # Query by a list of IDs query = [dataset.first().id, dataset.last().id] view = dataset.sort_by_similarity(query, k=10, brain_key="mosaic_index") # Query by text prompt query = "a photo of a dog" view = dataset.sort_by_similarity(query, k=10, brain_key="mosaic_index")

关键语义：对DatasetView执行相似性搜索时，只会返回该视图内的结果；如果视图中包含未纳入索引的样本，它们永远不会出现在结果里。这意味着你可以对整个Dataset建立一次索引，之后通过构造包含目标图片的视图，在数据集任意子集上反复检索——这正是 docs/source/user_guide/similarity.rst 所描述的通用相似性 API 与视图系统协同的最佳实践。

八、访问底层 Mosaic 客户端

每个 Mosaic 索引都暴露client属性，可直接访问底层的 Mosaic 客户端实例并调用其方法：

import fiftyone as fo import fiftyone.brain as fob import fiftyone.zoo as foz dataset = foz.load_zoo_dataset("quickstart") mosaic_index = fob.compute_similarity( dataset, model="clip-vit-base32-torch", brain_key="mosaic_index", backend="mosaic", ) mosaic_client = mosaic_index.client print(mosaic_client)

这为高级场景（如直接使用 Databricks Vector Search 原生 API 做索引管理、元数据过滤等）留出了充分的扩展空间。

九、高级用法

如「Mosaic 配置参数」一节所述，通过向compute_similarity()传入可选参数，可以定制 Mosaic 索引。下面是一个综合示例：指定自定义索引名，并且只对数据集的一个子集填充向量（先用embeddings=False创建空索引，再分批add_to_index）：

import fiftyone as fo import fiftyone.brain as fob import fiftyone.zoo as foz dataset = foz.load_zoo_dataset("quickstart") # Create a custom Mosaic index mosaic_index = fob.compute_similarity( dataset, model="clip-vit-base32-torch", embeddings=False, # we'll add embeddings below brain_key="mosaic_index", backend="mosaic", index_name="custom-quickstart-index", ) # Add embeddings for a subset of the dataset view = dataset.take(10) embeddings, sample_ids, _ = mosaic_index.compute_embeddings(view) mosaic_index.add_to_index(embeddings, sample_ids)

这里的mosaic_index.compute_embeddings(view)是SimilarityIndex实例提供的能力，与add_to_index()组合即可实现"先建索引、后分批灌入向量"的增量式构建。

十、实现要点与源码对照

从本仓库源码可以进一步确认 Mosaic 集成在 FiftyOne 中的落点：

• sort_by_similarity()是SampleCollection上的视图阶段方法，完整签名与 docstring 见 fiftyone/core/collections.py，它要求先通过fiftyone.brain.compute_similarity建立相似性索引，并支持 ID、向量、向量数组与文本提示四类查询输入。
• 所有 brain run 管理方法（list_brain_runs、get_brain_info、load_brain_results、rename_brain_run、delete_brain_run）同样定义于 fiftyone/core/collections.py，是后端无关的统一 API。
• Mosaic 后端的实现（MosaicSimilarityConfig等）位于独立的fiftyone-brain包（fiftyone.brain.internal.core.mosaic），仓库侧的相似性总览文档 docs/source/user_guide/similarity.rst 列出了包括 sklearn、Qdrant、Redis、Pinecone、MongoDB、Elasticsearch、pgvector、Mosaic、Milvus、LanceDB 在内的全部内置后端及其配置类，便于横向对比。
• 默认后端的切换机制（backend参数、FIFTYONE_BRAIN_DEFAULT_SIMILARITY_BACKEND环境变量、~/.fiftyone/brain_config.json中的default_similarity_backend）在 docs/source/user_guide/similarity.rst 中有完整定义，Mosaic 集成文档中给出的配置示例与之完全一致。

综上，Mosaic 集成遵循 FiftyOne 统一的相似性后端抽象：你既可以用最小参数一键建索引，也可以通过index_name、patches_field、model/embeddings与 brain config 实现精细控制；查询侧统一走sort_by_similarity()，配合视图系统即可在任意数据子集上执行向量检索与自然语言检索。

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