Improve Relevance

Interaction Signals

Capture implicit user behavior — clicks, views, dwell time, purchases — to feed into retrieval optimization.

curl -X POST "https://api.mixpeek.com/v1/retrievers/$RETRIEVER_ID/interactions" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "execution_id": "exec_abc",
    "document_id": "doc_xyz",
    "signal_type": "click",
    "position": 3,
    "metadata": { "dwell_time_ms": 4500 }
  }'

Signal Strength

Signal	Weight	When to track
`impression`	Low	Document appeared in results
`click`	Medium	User clicked a result
`view`	Medium	User viewed the detail page
`dwell`	High	User spent significant time
`purchase` / `convert`	Highest	User completed a goal action

Track position for every signal — it’s critical for learning which results should rank higher. Interaction API →

Auto-Tune (Learned Fusion)

Auto-Tune automatically adapts fusion weights per user based on their interaction history. Instead of manually choosing weights, the system uses Thompson Sampling to learn the optimal blend of features for each user.

How It Works

Concept page — Thompson Sampling, context levels, reward signals

Reward Signals

Configure which interactions drive learning and how much

Rollout Guide

Traffic splitting, shadow mode, kill switch, per-user opt-out

Quick setup:

# 1. Create a retriever with learned fusion
retriever = client.retrievers.create(
    retriever_name="personalized-search",
    stages=[{
        "stage_type": "filter",
        "stage_id": "feature_search",
        "parameters": {
            "searches": [
                {
                    "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
                    "query": "{{INPUT.query}}",
                    "top_k": 100
                },
                {
                    "feature_uri": "mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding",
                    "query": "{{INPUT.query}}",
                    "top_k": 100
                }
            ],
            "fusion": "learned",
            "learning_config": {
                "context_features": ["INPUT.user_id"],
                "reward_map": {"click": 1.0, "purchase": 3.0}
            },
            "final_top_k": 25
        }
    }]
)

# 2. Send interactions — learning happens automatically
client.retrievers.interactions.create(
    feature_id="doc_123",
    interaction_type=["click"],
    position=2,
    user_id="user_abc"
)

For a step-by-step walkthrough, see the Build a Feedback Loop tutorial.

Fusion Strategies

When a retriever has multiple search stages, fusion strategies determine how scores combine into the final ranking.

Strategy	How it works	Best for
RRF (Reciprocal Rank Fusion)	Combines ranks, not scores. `1/(k + rank)`	Default — works well with no tuning
DBSF (Distribution-Based Score Fusion)	Normalizes score distributions then averages	When scores have different scales
Weighted	Manual weights per stage	When you know which stage matters more
Max	Takes the highest score across stages	When any match is sufficient
Learned	Auto-tunes weights from interaction signals	When you have 500+ interactions

Configure fusion on the retriever:

{
  "fusion_strategy": {
    "type": "learned",
    "fallback": "rrf",
    "min_interactions": 500
  }
}

Learned fusion uses Thompson Sampling to automatically shift weight toward stages that produce results users engage with. It starts with the fallback strategy and transitions as interactions accumulate.

Evaluations

Measure retriever quality against ground truth datasets with standard IR metrics.

# Create a ground truth dataset
curl -X POST "https://api.mixpeek.com/v1/retrievers/$RETRIEVER_ID/evaluations/datasets" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_name": "product-search-eval",
    "queries": [
      { "query": {"query_text": "wireless headphones"}, "relevant_document_ids": ["doc_1", "doc_2"] }
    ]
  }'

# Run evaluation
curl -X POST "https://api.mixpeek.com/v1/retrievers/$RETRIEVER_ID/evaluations" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{ "dataset_id": "'$DATASET_ID'", "limit": 20 }'

Returns Precision, Recall, F1, NDCG, MAP, and MRR at configurable cutoffs. Use evaluations to compare retriever configurations before deploying changes. Evaluation API →

Analytics

Monitor retriever performance in production:

Stage latency breakdown — identify which stages are slow
Cache hit rates — verify caching is effective
Score distributions — detect relevance drift
Query patterns — understand what users search for

Use the analytics endpoints to build dashboards or trigger alerts on degradation.

The Feedback Loop

Search → Results → User interacts → Signal captured → Fusion learns → Better results

Users search via retrievers
Interaction signals capture what they engage with
Learned fusion adjusts stage weights automatically
Annotations provide explicit ground truth for edge cases
Evaluations measure improvement quantitatively
The cycle repeats — retrieval improves with usage

​Interaction Signals

​Signal Strength

​Auto-Tune (Learned Fusion)