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
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.
Similarity search
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.