> For the complete documentation index, see [llms.txt](https://docs.seldon.ai/seldon-core-2/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.seldon.ai/seldon-core-2/user-guide/experiment.md).

# Experiments

An Experiment defines a traffic split between Models or Pipelines. This allows new versions of models and pipelines to be tested.

An experiment spec has three sections:

* `candidates` (required) : a set of candidate models to split traffic.
* `default` (optional) : an existing candidate who endpoint should be modified to split traffic as defined by the candidates.
  * Each candidate has a traffic weight. The percentage of traffic will be this weight divided by the sum of traffic weights.
* `mirror` (optional) : a single model to mirror traffic to the candidates. Responses from this model\
  will not be returned to the caller.

An example experiment with a `defaultModel` is shown below:

{% @github-files/github-code-block url="<https://github.com/SeldonIO/seldon-core/blob/v2/samples/experiments/ab-default-model.yaml>" %}

This defines a split of 50% traffic between two models `iris` and `iris2`. In this case we want to\
expose this traffic split on the existing endpoint created for the `iris` model. This allows us to\
test new versions of models (in this case `iris2`) on an existing endpoint (in this case `iris`).\
The `default` key defines the model whose endpoint we want to change. The experiment will become\
active when both underplying models are in Ready status.

An experiment over two separate models which exposes a new API endpoint is shown below:

{% @github-files/github-code-block url="<https://github.com/SeldonIO/seldon-core/blob/v2/samples/experiments/ab.yaml>" %}

To call the endpoint add the header `seldon-model: <experiment-name>.experiment` in this case:`seldon-model: experiment-iris.experiment`. For example with curl:

```bash
curl http://${MESH_IP}/v2/models/experiment-iris/infer \
   -H "Content-Type: application/json" \
   -H "seldon-model: experiment-iris.experiment" \
   -d '{"inputs": [{"name": "predict", "shape": [1, 4], "datatype": "FP32", "data": [[1, 2, 3, 4]]}]}'
```

For examples see the [local experiments notebook](/seldon-core-2/user-guide/examples/local-experiments.md).

## Pipeline Experiments

Running an experiment between some pipelines is very similar. The difference is `resourceType: pipeline`\
needs to be defined and in this case the candidates or mirrors will refer to pipelines. An example is\
shown below:

{% @github-files/github-code-block url="<https://github.com/SeldonIO/seldon-core/blob/v2/samples/experiments/addmul10.yaml>" %}

For an example see the [local experiments notebook](/seldon-core-2/user-guide/examples/local-experiments.md).

## Mirror Experiments

A mirror can be added easily for model or pipeline experiments. An example model mirror experiment is\
shown below:

{% @github-files/github-code-block url="<https://github.com/SeldonIO/seldon-core/blob/v2/samples/experiments/sklearn-mirror.yaml>" %}

For an example see the [local experiments notebook](/seldon-core-2/user-guide/examples/local-experiments.md).

An example pipeline mirror experiment is shown below:

{% @github-files/github-code-block url="<https://github.com/SeldonIO/seldon-core/blob/v2/samples/experiments/addmul10-mirror.yaml>" %}

For an example see the [local experiments notebook](/seldon-core-2/user-guide/examples/local-experiments.md).

## Sticky Sessions

To allow cohorts to get consistent views in an experiment each inference request passes back\
a response header `x-seldon-route` which can be passed in future requests to an experiment to\
bypass the random traffic splits and get a prediction from the sequence of models and pipelines\
used in the initial request.

Note: you must pass the normal `seldon-model` header along with the `x-seldon-route` header.

This is illustrated in the [local experiments notebook](/seldon-core-2/user-guide/examples/local-experiments.md).

{% hint style="info" %}
Caveats: the models used will be the same but not necessarily the same replica instances. This\
means at present this will not work for stateful models that need to go to the same model replica instance.
{% endhint %}

## Service Meshes

As an alternative you can choose to run experiments at the service mesh level if you use one of\
the popular service meshes that allow header based routing in traffic splits. For further discussion\
see [here](https://github.com/SeldonIO/seldon-core/blob/v2/docs-gb/kubernetes/service-meshes.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.seldon.ai/seldon-core-2/user-guide/experiment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.