VMF Tutorial: Von Mises-Fisher Distribution

VMF Tutorial: Von Mises-Fisher Distribution#

Sandbox Model — Experimental

This model is part of the CoreRec Sandbox — an experimental collection of algorithms for research and exploration. Sandbox models are not production-tested and may have incomplete implementations. For production-ready models, see the Production Models.

Introduction#

VMF is a Bayesian Models model for recommendation systems. This model implements Von Mises-Fisher Distribution.

How VMF Works#

Architecture#

VMF uses a sophisticated architecture for recommendation tasks.

Mathematical Foundation#

The model learns user and item representations for prediction.

Reference Implementation#

Implementation Note

The code examples below are reference implementations for learning purposes. This is a sandbox model and has not been production-tested. Verify behavior thoroughly before using in production.

Step 1: Import and Load Data#

from corerec.sandbox.collaborative_full.mf_base.vmf_base import VMF_base as VMF
from cr_learn import ml_1m
from sklearn.model_selection import train_test_split
import numpy as np

# Load dataset
data = ml_1m.load()
ratings_df = data['ratings']
print(f"Loaded {len(ratings_df)} ratings")

# Split data
train_df, test_df = train_test_split(ratings_df, test_size=0.2, random_state=42)

Step 2: Initialize Model#

model = VMFBase(
    name="VMF_Model",
    embedding_dim=64,
    epochs=20,
    batch_size=256,
    learning_rate=0.001,
    verbose=True
)

print(f"Initialized {model.name}")

Step 3: Train#

model.fit(
    user_ids=train_users,
    item_ids=train_items,
    ratings=train_ratings
)

print("Training complete!")

Step 4: Predict#

# Single prediction
score = model.predict(user_id=1, item_id=100)
print(f"Predicted score: {score:.3f}")

# Batch predictions
pairs = [(1, 100), (2, 200), (3, 300)]
scores = model.batch_predict(pairs)
for (uid, iid), s in zip(pairs, scores):
    print(f"User {uid}, Item {iid}: {s:.3f}")

Step 5: Recommend#

# Get top-10 recommendations
recommendations = model.recommend(
    user_id=1,
    top_k=10,
    exclude_items=[]
)

print(f"Top-10 recommendations for User 1:")
for rank, item_id in enumerate(recommendations, 1):
    print(f"  {rank}. Item {item_id}")

Step 6: Evaluate#

from sklearn.metrics import mean_squared_error
import numpy as np

# Rating prediction
predictions = [model.predict(u, i) for u, i, r in test_data]
test_rmse = rmse(test_df['rating'].values, predictions)
print(f"Test RMSE: {test_rmse:.4f}")

# Ranking quality

Step 7: Save & Load#

# Save model
model.save('artifacts/vmf_model')

# Load model
loaded = VMFBase.load('artifacts/vmf_model')
test_score = loaded.predict(1, 100)
print(f"Loaded model prediction: {test_score:.3f}")

Key Takeaways#

When to Use VMF#

✅ Best for datasets with bayesian models characteristics

Best Practices#

  1. Start with default parameters\n2. Tune embedding_dim based on data\n3. Use early stopping\n4. Monitor validation metrics

Scaling & Production Considerations#

If you plan to move this sandbox model toward production use, consider:

  • Data Volume: Test with realistic dataset sizes; sandbox implementations may not be optimized for large-scale data.

  • Distributed Training: For datasets exceeding single-machine memory, consider wrapping the model in distributed training frameworks (e.g., PyTorch DDP, Horovod).

  • Hyperparameter Tuning: Use systematic search (Optuna, Ray Tune) rather than manual tuning. The defaults in sandbox models are not tuned for any specific domain.

  • Serving Latency: Profile inference time. Some architectures (e.g., attention-based) may need quantization or ONNX export for low-latency serving.

  • Monitoring: Implement A/B testing and online metrics (CTR, engagement, diversity) before replacing an existing system.

  • Validation: Write comprehensive unit tests and integration tests before deploying. Sandbox models do not have CI coverage.

Further Reading#

Contents