# Adding Custom Embeddings

## Overview

Aquarium uses **neural network embeddings** to enable features like clustering and similarity search. They can be thought of as lists of numbers that represent the essential visual qualities of an image. By default, Aquarium will try to compute embeddings for you by using our standard neural network, as long as you are not working in [Anonymous mode](/aquarium/data-privacy/anonymous-mode.md).

If you are a customer working in **Anonymous mode** or you wish to **provide your own embeddings**, our Python library makes it easy to attach your own values. 

{% hint style="info" %}
If you chose a data sharing scheme that requires you to use your own embeddings, check out our [**full page on embeddings**](/aquarium/concepts/embeddings.md) for some sample code, along with guidance for using your own models.
{% endhint %}

## Assumptions

Your embeddings need to be:

* **A vector of up to length 2048** 
  * If your embedding vector is longer, contact Aquarium in order to accommodate 

## How to Add Custom Embeddings

### If Working In Anonymous Mode

If you are adding custom embeddings because you are in Anonymous mode, please add in the flag `is_anon_mode` when you call `create_dataset()`. 

Example:

<pre class="language-python"><code class="lang-python"><strong>al_client.create_dataset(
</strong>        PROJECT_NAME, 
        DATASET_NAME, 
        dataset=dataset, 
        embedding_distance_metric='cosine',
        is_anon_mode=True
)
</code></pre>

### Adding Your Embedding Vectors

Aquarium uses the terms frame and crop quite often. With respect to embeddings, think of a frame as the entire image, and think of crop as an object/region of interest.

{% hint style="info" %}
**Important!**

When you upload custom embeddings, you **must** upload an embedding at both the frame level and the crop level. In addition, you need to add an embedding to **each** crop using `add_crop_embedding().`

If you are working with a **Classification** or **Semantic Segmentation** project, you most likely will only have image level embeddings (whereas with object detection there are usually image and object level embeddings). For these projects, to satisfy the requirement of frame and crop level embeddings, please add your image level embeddings to each crop using `add_crop_embeddings()`.
{% endhint %}

Example code snippet:

<pre class="language-python"><code class="lang-python"># example of adding label level embeddings
frame.add_frame_embedding(embedding=[1.0,2.0,3.0, ...])
for label_id, label_embedding in label_embeddings.items():
    frame.add_crop_embedding(label_id=label_id, embedding=label_embedding)

<strong># once you have added all the labels, metadata, and embeddings to the frame object
</strong># then add the frame to the dataset    
dataset.add_frame(frame)

# example of adding inference level embeddings
inference_frame.add_frame_embedding(embedding=[1.0,2.0,3.0, ...])
for inf_id, inf_embedding in inference_embeddings.items():
    inference_frame.add_crop_embedding(label_id=inf_id, embedding=inf_embedding)

# once you have added all the inferences, metadata, and embeddings to the inference frame object
# then add the inference frame to the dataset    
inference_set.add_frame(inference_frame)
</code></pre>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://legacy-docs.aquariumlearning.com/aquarium/concepts/adding-custom-embeddings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.