Pular para o conteúdo
AvraAvra
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

Technical guide

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:

embedding_1024 = response["result"]["embedding"][0]  # full 1024 dimensions
embedding_256 = embedding_1024[:256]                  # the first 256
Dimensions 1 to 1024, the most important first1024embedding[:1024]512embedding[:512]256embedding[:256]start here for tree models128embedding[:128]64embedding[:64]32embedding[:32]16embedding[:16]
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.
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

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.

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:

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.

Find the companies closest to a seed:

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:

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 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:

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.

Esta página foi útil?