---
title: Technical guide
description: Embedding specifications, choosing a dimension, and integration patterns.
---

## Specifications

| Property | Value |
|----------|-------|
| **Source** | Avra GFM |
| **Full dimension** | 1024 |
| **Supported prefixes** | 1024, 512, 256, 128, 64, 32, 16 |
| **Normalization** | L2-normalized at full dimension |
| **Distance** | Cosine similarity |

The embeddings are Matryoshka embeddings: the model is trained to put the most important information in the first dimensions, so a prefix of the vector is a valid, smaller embedding. One call returns the full 1024 dimensions, in the prediction's `result` as `embedding`. Shorten the vector client-side by keeping the first N elements:

```python
embedding_1024 = response["result"]["embedding"][0]  # full 1024 dimensions
embedding_256 = embedding_1024[:256]                  # the first 256
```

<svg class="fig" viewBox="0 0 640 230" role="img" aria-label="Seven bars, left-aligned, for 1024, 512, 256, 128, 64, 32, and 16 dimensions. Each bar is half the length of the one above it and starts at the first dimension. The 256 bar is highlighted as the place to start for tree models.">
  <text class="small label" x="60" y="22">Dimensions 1 to 1024, the most important first</text>
  <text class="mono end" x="50" y="49">1024</text>
  <rect class="soft" x="60" y="36" width="400" height="18" rx="3" />
  <text class="mono" x="470" y="49">embedding[:1024]</text>
  <text class="mono end" x="50" y="75">512</text>
  <rect class="soft" x="60" y="62" width="200" height="18" rx="3" />
  <text class="mono" x="270" y="75">embedding[:512]</text>
  <text class="mono end" x="50" y="101">256</text>
  <rect class="solid" x="60" y="88" width="100" height="18" rx="3" />
  <text class="mono accent" x="170" y="101">embedding[:256]</text>
  <text class="small label" x="292" y="101">start here for tree models</text>
  <text class="mono end" x="50" y="127">128</text>
  <rect class="soft" x="60" y="114" width="50" height="18" rx="3" />
  <text class="mono" x="120" y="127">embedding[:128]</text>
  <text class="mono end" x="50" y="153">64</text>
  <rect class="soft" x="60" y="140" width="25" height="18" rx="3" />
  <text class="mono" x="95" y="153">embedding[:64]</text>
  <text class="mono end" x="50" y="179">32</text>
  <rect class="soft" x="60" y="166" width="12.5" height="18" rx="3" />
  <text class="mono" x="82.5" y="179">embedding[:32]</text>
  <text class="mono end" x="50" y="205">16</text>
  <rect class="soft" x="60" y="192" width="6.25" height="18" rx="2" />
  <text class="mono" x="76.25" y="205">embedding[:16]</text>
</svg>

One vector, seven valid lengths. Each shorter embedding is the start of the longer one, so shortening is a slice of the first N numbers, with nothing to recompute.

:::warning
Shorten only to the supported prefixes (16, 32, 64, 128, 256, 512, 1024). An arbitrary selection of coordinates, or a mix of non-prefix subsets across experiments, discards the structure the model learned.
:::

**Why not PCA, t-SNE, or UMAP?**

Matryoshka embeddings differ from dimensionality reduction applied after the fact:

| Approach | How it works | Trade-offs |
|----------|--------------|------------|
| **Matryoshka** | The model is trained so that prefixes are valid embeddings | Nothing to compute: slice the array |
| **PCA** | A linear projection fitted on existing embeddings | Loses non-linear structure; a projection matrix to fit and store |
| **t-SNE** | A non-linear transform built for 2D and 3D visualization | Expensive; not designed for downstream models |
| **UMAP** | A non-linear transform, better than t-SNE for modeling | Still needs fitting, and new samples need a transform step |

With Matryoshka embeddings, the dimension becomes a hyperparameter you can tune at no extra cost. Keep PCA, t-SNE, and UMAP for visualization.

## Choosing a dimension

| Dimension | Use case | Model type |
|-----------|----------|------------|
| **16–64** | Tight resource limits, simple rules | Decision trees, logistic regression |
| **128** | Latency-sensitive scoring | Online scoring, linear models |
| **256–512** | Balanced performance | XGBoost, LightGBM, CatBoost |
| **1024** | Maximum signal | Deep learning, vector retrieval |

:::info
Start with **256 dimensions** for tree-based models, and move up only if validation metrics improve.
:::

## Late fusion

The recommended pattern: train your own model on embeddings together with your features. Avra GFM doesn't change; your model learns how to use it.

```mermaid
flowchart LR
  features["Your features<br/>revenue, age_months,<br/>bureau_score"] --> table["One training table"]
  emb["Avra embeddings<br/>emb_0 to emb_255"] --> table
  outcomes["Your outcomes<br/>default"] --> table
  table --> model["Your model,<br/>such as LightGBM"]
  class model accent
  classDef accent fill:#0A01FE,stroke:#0A01FE,color:#fff
```

```python
import pandas as pd
from lightgbm import LGBMClassifier

# Your features
df = pd.DataFrame({
    "revenue": [...],
    "age_months": [...],
    "bureau_score": [...],
    "default": [...]  # target
})

# Add Avra embeddings (256 dimensions for tree models)
embedding_cols = [f"emb_{i}" for i in range(256)]
for i, col in enumerate(embedding_cols):
    df[col] = [emb[i] for emb in embeddings_256d]

# Train
X = df.drop("default", axis=1)
y = df["default"]

model = LGBMClassifier()
model.fit(X, y)
```

### Tuning the dimension

Because prefixes are valid embeddings, you can compare dimensions without embedding again:

```python
import numpy as np
import optuna
import lightgbm as lgb
from sklearn.model_selection import train_test_split
from sklearn.metrics import roc_auc_score

# From the late fusion example above
embedding_1024 = np.array(embeddings_1024d)  # (n_samples, 1024)
base_features = df[["revenue", "age_months", "bureau_score"]].values
labels = df["default"].values

idx = np.arange(len(df))
train_idx, val_idx, y_train, y_val = train_test_split(
    idx, labels, test_size=0.2, random_state=42, stratify=labels
)

X_train_base = base_features[train_idx]
X_val_base = base_features[val_idx]

def objective(trial):
    dim = trial.suggest_categorical("embedding_dim", [16, 32, 64, 128, 256, 512, 1024])

    emb_train = embedding_1024[train_idx, :dim]
    emb_val = embedding_1024[val_idx, :dim]

    X_train = np.hstack([X_train_base, emb_train])
    X_val = np.hstack([X_val_base, emb_val])

    model = lgb.LGBMClassifier(
        n_estimators=trial.suggest_int("n_estimators", 200, 1200),
        learning_rate=trial.suggest_float("learning_rate", 0.01, 0.2, log=True),
        num_leaves=trial.suggest_int("num_leaves", 31, 255),
        max_depth=trial.suggest_int("max_depth", 3, 10),
        subsample=trial.suggest_float("subsample", 0.6, 1.0),
        colsample_bytree=trial.suggest_float("colsample_bytree", 0.6, 1.0),
        random_state=42,
        verbosity=-1
    )

    model.fit(
        X_train,
        y_train,
        eval_set=[(X_val, y_val)],
        callbacks=[lgb.early_stopping(50, verbose=False)]
    )

    preds = model.predict_proba(X_val)[:, 1]
    return roc_auc_score(y_val, preds)

study = optuna.create_study(direction="maximize")
study.optimize(objective, n_trials=50, show_progress_bar=True)

print(f"Best AUC: {study.best_value:.4f}")
print(f"Best dimension: {study.best_params['embedding_dim']}")
```

For credit and other time-dependent targets, split by date rather than at random, so validation mirrors how the model will be used.

## Similarity search

Find the companies closest to a seed:

```python
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity

def find_similar(seed_embedding, candidate_embeddings, top_k=100):
    similarities = cosine_similarity([seed_embedding], candidate_embeddings)[0]
    top_indices = np.argsort(similarities)[-top_k:][::-1]
    return top_indices, similarities[top_indices]

# Companies similar to one of your best customers
best_customer_emb = get_embedding("12345678000199")
similar_idx, scores = find_similar(best_customer_emb, all_embeddings, top_k=1000)
```

A shortened prefix isn't unit-length anymore. Normalize it again before computing cosine similarity, or use a library that normalizes for you.

## Versions and caching

Embeddings from different model versions aren't interchangeable. Store each vector with the version that produced it:

```python
cache_record = {
    "cnpj": "12345678000199",
    "embedding": embedding,
    "model_version": "...",   # the version_id you called
    "generated_at": "...",
    "dimension": 1024,
}
```

Never mix versions in one training set, one index, or one comparison. When the version changes, embed again and retrain and revalidate the models built on the embeddings. Subscribe to the `model-version-promotion` [webhook](/pt-BR/core/webhooks) to know when.

Within a version, embeddings can still change as the knowledge graph receives fresh data, while the model's weights stay the same. Refresh on the cadence your use case needs, and record when each vector was generated.

## Monitoring

Watch the distribution of the embeddings you score with over time:

```python
import numpy as np
from scipy.stats import ks_2samp

historical_norms = [np.linalg.norm(e[:256]) for e in historical_embeddings]
current_norms = [np.linalg.norm(e[:256]) for e in current_embeddings]

stat, pvalue = ks_2samp(historical_norms, current_norms)
if pvalue < 0.05:
    alert("Embedding distribution shift detected")
```

At the full 1024 dimensions the vectors are unit-length, so compare a prefix, as in the preceding example, or the distribution of individual dimensions.
