Skip to main content
Use the distribution embedder setting to correct the returned _rankingScores of semantic hits with an affine transformation. Tuning distribution is useful when your chosen embedder consistently rates unrelated documents as “somewhat relevant”, making it hard for downstream code (or users) to tell truly good matches apart from noise.
Changing distribution does not trigger a reindexing operation. This makes it safe to iterate on, unlike most other embedder settings.

​
When to tune distribution

Different embedding models produce _rankingScore values on different effective ranges. Some models report high scores for nearly every document, while others spread their scores more evenly. Tuning distribution rescales these raw scores so that:
  • Very relevant hits land near 1.
  • Somewhat relevant hits land near 0.5.
  • Irrelevant hits land near 0.
This gives you a consistent scale across indexes and models, which makes it easier to set a score threshold or compare results across embedders.

​
How distribution works

distribution is an optional field compatible with all embedder sources. It is an object with two fields, both numbers between 0 and 1:
FieldMeaning
meanThe semantic score of “somewhat relevant” hits before applying the distribution setting.
sigmaThe average absolute difference in _rankingScores between “very relevant” hits and “somewhat relevant” hits, and between “somewhat relevant” hits and “irrelevant” hits.
Meilisearch applies these values as an affine correction on top of the raw semantic scores.

​
Tuning workflow

Configuring distribution requires a certain amount of trial and error. In practice:
  1. Run representative semantic searches against your index with showRankingScore: true.
  2. Note the _rankingScores of hits you consider “very relevant”, “somewhat relevant”, and “irrelevant”.
  3. Record the observed mean (the score of your “somewhat relevant” hits) and sigma (the average distance between your relevance tiers).
  4. Update your embedder with the new distribution values.
  5. Re-run the searches and check that top hits now score near 1, borderline hits near 0.5, and poor hits near 0.
  6. Repeat until the scores match your expectations.

​
Example configuration

curl \
  -X PATCH 'MEILISEARCH_URL/indexes/INDEX_NAME/settings' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "embedders": {
      "default": {
        "source": "openAi",
        "model": "text-embedding-3-small",
        "distribution": {
          "mean": 0.7,
          "sigma": 0.3
        }
      }
    }
  }'
In this example, documents the embedder currently rates around 0.7 are treated as “somewhat relevant”, and scores are spread out so that truly good matches move toward 1 while weak matches drift toward 0.

​
Next steps

Choose an embedder

Compare embedding providers and pick the right one for your use case.

Custom hybrid ranking

Tune semanticRatio to balance keyword and semantic results.