VMRankerDppTheta Parameter: Controlling the Diversity-Relevance Trade-Off in DPP Ranking

The VMRankerDppTheta parameter is a runtime flag that balances relevance against embedding diversity in the VMRanker’s Determinantal Point Process (DPP) by controlling how strongly original candidate scores influence the quality factors in the kernel matrix.

In the xai-org/x-algorithm repository, the VMRanker re-ranks candidate posts using a Determinantal Point Process computed over their vector embeddings. The VMRankerDppTheta parameter serves as the primary tuning mechanism for this system, allowing operators to determine whether the final output prioritizes high-scoring content or maximally diverse content.

Parameter Definition and Default Configuration

The flag is declared as a typed parameter with a default value that favors a moderate balance between the two objectives.

Declaration in Home-Mixer Parameters

In home-mixer/params/param.rs, the parameter is registered with a default value of 0.65:

param!(
    VMRankerDppTheta,
    f64,
    "rust_home_mixer_vm_ranker_dpp_theta",
    0.65
);

This default value of 0.65 represents the production setting where both quality and similarity contribute meaningfully to the final ranking decision.

Integration in the VMRanker Scorer

The scorer retrieves the runtime value and forwards it into the DPP configuration struct. In home-mixer/scorers/vm_ranker.rs (line 98), the implementation builds a DppConfig:

let dpp_theta = query.params.get(VMRankerDppTheta);
let dpp_max_selected_rank = query.params.get(VMRankerDppMaxSelectedRank);
let config = DppConfig {
    top_k: query.params.get(VMRankerDppTopK),
    theta: dpp_theta,
    max_selected_rank: dpp_max_selected_rank,
    debug_viewer_id: query.viewer_id,
};

This config object is then passed to the VMRanker service where the actual DPP computation occurs.

Mathematical Mechanism: From Theta to Kernel

Inside vm-ranker/dpp.rs, the raw theta value undergoes a mathematical transformation that determines how candidate quality scores are weighted against embedding similarity.

Clamping and Alpha Derivation

The implementation first clamps the input to the valid interval [0, 1 − ε] to prevent division errors, then derives a scaling factor alpha:

let theta = config.theta.clamp(0.0, 1.0 - EPSILON);
let alpha = theta / (2.0 * (1.0 - theta));

This alpha value grows non-linearly as theta approaches 1.0, amplifying the differences between high and low scoring candidates.

Quality Factor Transformation

Each candidate’s normalized score qᵢ is exponentiated using alpha to produce a quality factor qfᵢ:

let qf: Vec<f64> = q.iter().map(|&qi| (alpha * qi).exp()).collect();

When theta is near zero, alpha approaches zero, causing every qfᵢ to approximate 1.0 regardless of the underlying score. When theta is large, the exponential function magnifies score disparities.

Kernel Construction

The final DPP kernel entry for any pair of candidates (i, j) combines these quality factors with their embedding cosine similarity:

let val = qf[i] * qf[j] * cos;
kernel[i * m + j] = val;
kernel[j * m + i] = val;

According to the source code in vm-ranker/dpp.rs (lines 18-22), this Kᵢⱼ = qfᵢ · qfⱼ · cos(i, j) formulation means that high theta values cause the quality factors to dominate the kernel, while low theta values allow the cosine similarity term (diversity) to drive the selection process.

Interpreting the VMRankerDppTheta Value Range

The theta value directly determines the behavioral mode of the re-ranker:

θ between 0 and 0.2: Alpha approaches zero, quality factors remain nearly constant, and the cosine similarity term dominates the kernel. The greedy DPP algorithm selects a highly diverse set of posts, potentially sacrificing top-scoring candidates to achieve embedding coverage.

θ between 0.4 and 0.6 (default 0.65): Both quality factors and similarity contribute to kernel values. This range provides the balanced trade-off used in production, where relevance and diversity are weighted approximately equally.

θ between 0.8 and 0.99: Alpha grows large, causing quality factors to vary exponentially with small score differences. The kernel becomes dominated by these quality terms, causing the DPP to behave like a standard score-sorted ranking with minimal diversity enforcement.

Practical Configuration Examples

You can override the default theta value per request by manipulating the parameter map before invoking the scorer:

use crate::home_mixer::params::Param;
use crate::home_mixer::scorers::vm_ranker::VMRanker;

// Favor diversity over raw score
let mut params = Param::default();
params.set(VMRankerDppTheta, 0.2_f64);

let query = ScoredPostsQuery {
    params,
    viewer_id: 12345,
    // ... other fields
};

let reranked = vm_ranker.score(&query).await?;

Setting VMRankerDppTheta to 0.2 as shown above reduces the influence of raw scores, causing the DPP to select candidates that maximize embedding diversity even if their initial relevance scores are lower.

Summary

• The VMRankerDppTheta parameter is defined in home-mixer/params/param.rs with a default value of 0.65.
• It is clamped to the range [0, 1-ε] and transformed into an alpha value inside vm-ranker/dpp.rs via the formula alpha = theta / (2 * (1 - theta)).
• This alpha scales the quality factors (qf = exp(alpha * score)) that populate the DPP kernel matrix alongside cosine similarities.
• Low theta values (near 0) flatten quality factors to approximately 1.0, forcing the DPP to optimize purely for embedding diversity.
• High theta values (near 1) amplify score differences, causing the system to approximate a standard relevance-sorted ranking.
• The parameter is configurable at query time by setting the VMRankerDppTheta flag in the request parameters map.

Frequently Asked Questions

What happens when VMRankerDppTheta is set to 0?

When VMRankerDppTheta is 0, the derived alpha value becomes 0, which causes every candidate's quality factor qfᵢ to equal exp(0) or 1.0. The DPP kernel then depends solely on the cosine similarity between embeddings, causing the greedy selection algorithm to prioritize maximum geometric diversity in the embedding space, potentially selecting lower-scoring posts if they provide better coverage.

What is the default value of VMRankerDppTheta?

The default value is 0.65, as defined in home-mixer/params/param.rs. This value was chosen to provide a balanced trade-off where both the original relevance scores and the embedding diversity influence the final ranking approximately equally.

How does VMRankerDppTheta mathematically influence the DPP kernel?

The parameter controls the kernel through an intermediate alpha variable calculated as theta / (2.0 * (1.0 - theta)). This alpha is multiplied by each candidate's normalized score and fed into an exponential function to create quality factors. These factors multiply into every kernel entry (Kᵢⱼ = qfᵢ * qfⱼ * cos(i,j)), meaning that as theta increases, the kernel values become increasingly sensitive to the original score magnitudes rather than the angular distance between embeddings.

Where can I modify the VMRankerDppTheta parameter in the codebase?

The parameter declaration lives in home-mixer/params/param.rs (lines 46-51). Runtime values are read in home-mixer/scorers/vm_ranker.rs (line 98) where they populate the DppConfig struct. The mathematical application of the value occurs in vm-ranker/dpp.rs (lines 94-95) during the rescoring phase. You can modify the default at the declaration site, or override it per-request via the query params map as shown in the configuration examples.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}