Feat/mlflow models from code migration vacation recommendation with bert

[gabisponciano]

MLflow 3.1.0 Models-from-Code Migration for Vacation Recommendation with BERT

Overview

This migration modernizes the "Vacation Recommendation with BERT" blueprint by transitioning from MLflow's legacy serialization-based model logging (python_model) to the models-from-code approach (loader_module + data_path). This update resolves MLflow 3.1.0 compatibility issues, improves code architecture, and maintains API compatibility for vacation recommendation workflows.

Key Changes

• Primary Goal: Eliminate MLflow 3.1.0 serialization errors and adopt the models-from-code pattern.
• Technical Approach: Introduce a clean separation of concerns with standalone BERT model classes.
• Universal Structure: Align with the standardized src/mlflow/ structure established in PR feat: MLflow 3.1.0 Models-from-Code Migration for Vanilla RAG Blueprint #208.
• Scope: Comprehensive migration affecting model loading, recommendation generation, and deployment workflows.

---

Universal Structure Standardization

The blueprint now follows the universal AI-Blueprints structure pattern:

Standardized Architecture

src/
├── utils.py               # Common utilities (e.g., get_model_path, load_config)
└── mlflow/
    ├── __init__.py        # Dynamic imports
    ├── model.py           # Business logic for BERT recommendation
    ├── loader.py          # Canonical loader
    ├── logger.py          # Canonical logger

Universal Loader & Logger Synchronization

• loader.py and logger.py: Exact copies from PR feat: MLflow 3.1.0 Models-from-Code Migration for Vanilla RAG Blueprint #208.
• Signature Handling: Signature creation occurs in the notebook and is passed to Logger.log_model(signature, ...).
• Loader Module: All references now use src.mlflow.loader.
• Class Names: Generic Model and Logger (no blueprint-specific prefixes).

---

Technical Changes

New Architecture Components

src/mlflow/model.py

• Purpose: Standalone BERT recommendation logic with zero MLflow dependencies.
• Class Name: class Model (generic name, no blueprint prefixes).
• Functionality:
  • Loads pre-trained BERT models and tokenizers.
  • Processes vacation-related input data.
  • Generates vacation recommendations based on embeddings.
  • Maintains the predict(model_input, params) API signature for backward compatibility.
• Design Pattern: Clean separation between BERT logic and MLflow integration.

src/mlflow/loader.py

• Purpose: MLflow models-from-code entry point implementing _load_pyfunc().
• Source: Exact copy from PR feat: MLflow 3.1.0 Models-from-Code Migration for Vanilla RAG Blueprint #208 with adaptations for BERT.
• Functionality:
  • Loads BERT model artifacts (e.g., tokenizer, model weights).
  • Validates artifact directory structure.
  • Returns an initialized Model instance for prediction.

src/mlflow/logger.py

• Purpose: MLflow registration layer for packaging BERT models.
• Source: Exact copy from PR feat: MLflow 3.1.0 Models-from-Code Migration for Vanilla RAG Blueprint #208 with signature parameter requirement.
• Key Changes:
  • Requires signature as the first parameter: Logger.log_model(signature, ...).

src/mlflow/__init__.py

• Purpose: Standardized dynamic imports for universal structure.
• Source: Exact copy from PR feat: MLflow 3.1.0 Models-from-Code Migration for Vanilla RAG Blueprint #208.
• Exports: Model and Logger.

---

Notebook Updates

Enhanced Signature Handling

Signature creation now occurs in the notebook:

from mlflow.models.signature import ModelSignature
from mlflow.types.schema import Schema, ColSpec

# Define model input/output schema for BERT recommendation
input_schema = Schema([
    ColSpec("string", "user_id"),  # User identifier
    ColSpec("string", "preferences")  # User preferences
])
output_schema = Schema([
    ColSpec("string", "recommendation")  # Recommended vacation
])
signature = ModelSignature(inputs=input_schema, outputs=output_schema)

# Pass signature to logger
Logger.log_model(
    signature=signature,
    artifact_path=MODEL_NAME,
    config_path=CONFIG_PATH,
    docs_path=ARTIFACTS_PATH,  # Contains BERT artifacts
    demo_folder=DEMO_FOLDER
)

---

Artifact Management

BERT Model Artifacts Structure

The blueprint now handles BERT-specific artifacts:

/artifacts/data/
    ├── config.yaml          # Model configuration
    ├── tokenizer/           # Tokenizer files
    ├── model/               # Pre-trained BERT model weights
    └── demo/                # UI components

---

Testing Strategy

Manual Testing

• Test Scenarios:
  • BERT model registration with vacation recommendation datasets.
  • Model loading and recommendation generation.
  • Deployment validation through Streamlit UI with various user inputs.
  • Notebook execution validation in both development and MLflow deployment contexts.
  • API endpoint testing with different payload configurations.

---

Quality Assurance

Code Quality

• Code Style: Consistent with repository standards, comprehensive docstrings, proper type hints.
• Universal Structure: Follows canonical pattern from PR feat: MLflow 3.1.0 Models-from-Code Migration for Vanilla RAG Blueprint #208.
• Documentation: Clear architectural layer responsibilities, detailed BERT recommendation documentation.
• Error Handling: Robust exception management with informative error messages and logging.

Performance Impact

• Model Loading: Faster initialization due to optimized artifact handling.
• Memory Usage: Reduced memory footprint by removing unnecessary MLflow inheritance.
• Deployment Time: Improved deployment reliability with models-from-code approach.

---

Review Guidelines

Critical Review Areas

1. Universal Structure: Verify alignment with canonical structure from PR feat: MLflow 3.1.0 Models-from-Code Migration for Vanilla RAG Blueprint #208.
2. Signature Handling: Confirm signature creation occurs in the notebook and is passed to the logger.
3. MLflow Integration: Verify loader.py correctly implements models-from-code pattern.
4. API Compatibility: Confirm Model.predict() maintains identical signature and behavior.
5. Artifact Handling: Validate proper organization and cleanup of BERT artifacts.
6. Configuration Management: Review model path resolution and environment variable handling.
7. ONNX Support: Review if ONNX is supported

---

Deployment Considerations

• Rollback Procedure: Previous python_model approach is incompatible with models-from-code.
• Environment Setup: Ensure MODEL_ARTIFACTS_PATH environment variable is configured in deployment containers.
• Dependencies: Verify MLflow 3.1.0 compatibility with transformers in target deployment environments.
• Artifact Dependencies: Ensure all required BERT artifacts are present in deployment packages.

---

Migration Status: ✅ Complete and Ready for Review

Specialized Features:

• ✅ BERT Models: Full support for vacation recommendation generation.
• ✅ User Preferences Analysis: Specialized recommendation logic for user preferences.
• ✅ Artifact Management: Optimized handling of tokenizer and model weights.
• ✅ Streamlined Deployment: Universal structure alignment with other blueprints.

---

Printed page of the Streamlit web app showing evidence of successful local deployment and API testing:

Streamlit for Vacation Recommendation with BERT.pdf

[ata-turhan]

Looks great 🚀