Perform decision inference on the service | Elasticsearch Serverless API documentation

Perform decision inference on the service Experimental

POST /_inference/decision/{inference_id}

Answer a set of named questions about an input, such as whether a customer is complaining, which team should handle a request, or how angry a customer is. The questions are defined in the task settings of the inference endpoint, and can be replaced for a single request through task_settings.

Only the elastic service currently supports the decision task.

Required authorization

Cluster privileges: monitor_inference

Path parameters

inference_id string Required

The unique identifier for the inference endpoint.

Query parameters

timeout string

The amount of time to wait for the inference request to complete.

Default value is 30s.

application/json

Body Required

input string | object Required
The input to answer the questions about. It can be specified as a string, or as an object. The object form additionally allows specifying images.

string example:
```
"input": "I was charged twice for my order and nobody answers my emails."
```
object example:
```
"input": {
  "type": "image",
  "format": "base64",
  "value": "data:image/jpeg;base64,..."
}
```
One of:
string-1 string EmbeddingContentObjectItem object
An object containing the input data for a single item for the model to embed.
Hide attributes Show attributes

type string Required

The type of input to embed. Not all models support all input types. The audio, video, and pdf types are available in Elasticsearch 9.5.0 and later.

Values are text, image, audio, video, or pdf.

format string

The format of the input. For the text type this must be text. For all other types, this must be base64 or url. If not specified, this will default to text for the text type and base64 for all other types. The url format is available in Elasticsearch 9.6.0 and later. Not all services and models support all formats.

Values are text, base64, or url.

value string Required

The value of the input to embed. For the base64 format, this must be a base64-encoded data URI, i.e. "data:content/type;base64,...". For the url format, this must be a URL that points to the content, i.e. "https://example.com/image.jpg".
task_settings object

Task settings for the individual inference request. These settings override the task settings specified when creating the inference endpoint.
Hide task_settings attribute Show task_settings attribute object
- questions object
  
  The questions to answer, keyed by question name. The answers in the response use the same names. The questions replace the ones of the inference endpoint as a whole. At least one question is required.

Responses

200 application/json
Hide response attribute Show response attribute object
- decision object Required
  
  Hide decision attribute Show decision attribute object
  
  answers object Required
  
  The answers, keyed by the name of the question they answer.

POST /_inference/decision/{inference_id}

POST _inference/decision/my-decision-endpoint
{
  "input": "I was charged twice for my order and nobody answers my emails.",
  "task_settings": {
    "questions": {
      "is_complaint": {
        "type": "predicate",
        "instructions": "Is the customer complaining?"
      },
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "choices": {
          "billing": "Charges, refunds, invoices",
          "shipping": "Deliveries and returns",
          "other": null
        }
      },
      "anger": {
        "type": "score",
        "instructions": "How angry is the customer?",
        "levels": ["calm", "annoyed", { "label": "furious", "description": "Threatens to leave" }]
      }
    }
  }
}

resp = client.inference.decision(
    inference_id="my-decision-endpoint",
    input="I was charged twice for my order and nobody answers my emails.",
    task_settings={
        "questions": {
            "is_complaint": {
                "type": "predicate",
                "instructions": "Is the customer complaining?"
            },
            "team": {
                "type": "choice",
                "instructions": "Which team should handle this?",
                "choices": {
                    "billing": "Charges, refunds, invoices",
                    "shipping": "Deliveries and returns",
                    "other": None
                }
            },
            "anger": {
                "type": "score",
                "instructions": "How angry is the customer?",
                "levels": [
                    "calm",
                    "annoyed",
                    {
                        "label": "furious",
                        "description": "Threatens to leave"
                    }
                ]
            }
        }
    },
)

const response = await client.inference.decision({
  inference_id: "my-decision-endpoint",
  input: "I was charged twice for my order and nobody answers my emails.",
  task_settings: {
    questions: {
      is_complaint: {
        type: "predicate",
        instructions: "Is the customer complaining?",
      },
      team: {
        type: "choice",
        instructions: "Which team should handle this?",
        choices: {
          billing: "Charges, refunds, invoices",
          shipping: "Deliveries and returns",
          other: null,
        },
      },
      anger: {
        type: "score",
        instructions: "How angry is the customer?",
        levels: [
          "calm",
          "annoyed",
          {
            label: "furious",
            description: "Threatens to leave",
          },
        ],
      },
    },
  },
});

response = client.inference.decision(
  inference_id: "my-decision-endpoint",
  body: {
    "input": "I was charged twice for my order and nobody answers my emails.",
    "task_settings": {
      "questions": {
        "is_complaint": {
          "type": "predicate",
          "instructions": "Is the customer complaining?"
        },
        "team": {
          "type": "choice",
          "instructions": "Which team should handle this?",
          "choices": {
            "billing": "Charges, refunds, invoices",
            "shipping": "Deliveries and returns",
            "other": nil
          }
        },
        "anger": {
          "type": "score",
          "instructions": "How angry is the customer?",
          "levels": [
            "calm",
            "annoyed",
            {
              "label": "furious",
              "description": "Threatens to leave"
            }
          ]
        }
      }
    }
  }
)

$resp = $client->inference()->decision([
    "inference_id" => "my-decision-endpoint",
    "body" => [
        "input" => "I was charged twice for my order and nobody answers my emails.",
        "task_settings" => [
            "questions" => [
                "is_complaint" => [
                    "type" => "predicate",
                    "instructions" => "Is the customer complaining?",
                ],
                "team" => [
                    "type" => "choice",
                    "instructions" => "Which team should handle this?",
                    "choices" => [
                        "billing" => "Charges, refunds, invoices",
                        "shipping" => "Deliveries and returns",
                        "other" => null,
                    ],
                ],
                "anger" => [
                    "type" => "score",
                    "instructions" => "How angry is the customer?",
                    "levels" => array(
                        "calm",
                        "annoyed",
                        [
                            "label" => "furious",
                            "description" => "Threatens to leave",
                        ],
                    ),
                ],
            ],
        ],
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"input":"I was charged twice for my order and nobody answers my emails.","task_settings":{"questions":{"is_complaint":{"type":"predicate","instructions":"Is the customer complaining?"},"team":{"type":"choice","instructions":"Which team should handle this?","choices":{"billing":"Charges, refunds, invoices","shipping":"Deliveries and returns","other":null}},"anger":{"type":"score","instructions":"How angry is the customer?","levels":["calm","annoyed",{"label":"furious","description":"Threatens to leave"}]}}}}' "$ELASTICSEARCH_URL/_inference/decision/my-decision-endpoint"

var response = await client.Inference
    .DecisionAsync(inferenceId: "my-decision-endpoint", d1 => d1
        .Input("I was charged twice for my order and nobody answers my emails.")
        .TaskSettings(d2 => d2
            .Questions(d3 => d3
                .Predicate("is_complaint", d4 => d4
                    .Instructions("Is the customer complaining?")
                )
                .Choice("team", d4 => d4
                    .Choices(new Dictionary<string, string?>()
                    {
                        { "billing", "Charges, refunds, invoices" },
                        { "shipping", "Deliveries and returns" },
                        { "other", null }
                    })
                    .Instructions("Which team should handle this?")
                )
                .Score("anger", d4 => d4
                    .Instructions("How angry is the customer?")
                    .Levels(["calm", "annoyed", new DecisionScoreLevelObject()
                    {
                        Description = "Threatens to leave",
                        Label = "furious"
                    }])
                )
            )
        )
    );

Request example

Run `POST _inference/decision/my-decision-endpoint` to answer questions about a customer message

{
  "input": "I was charged twice for my order and nobody answers my emails.",
  "task_settings": {
    "questions": {
      "is_complaint": {
        "type": "predicate",
        "instructions": "Is the customer complaining?"
      },
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "choices": {
          "billing": "Charges, refunds, invoices",
          "shipping": "Deliveries and returns",
          "other": null
        }
      },
      "anger": {
        "type": "score",
        "instructions": "How angry is the customer?",
        "levels": ["calm", "annoyed", { "label": "furious", "description": "Threatens to leave" }]
      }
    }
  }
}

Response examples (200)

A response from `POST _inference/decision/my-decision-endpoint`, with an answer for each question.

{
  "decision": {
    "answers": {
      "is_complaint": {
        "type": "predicate",
        "probability": 0.94
      },
      "team": {
        "type": "choice",
        "choice": "billing",
        "probabilities": [
          { "value": "billing", "probability": 0.91 },
          { "value": "shipping", "probability": 0.04 },
          { "value": "other", "probability": 0.05 }
        ],
        "confidence": 0.89
      },
      "anger": {
        "type": "score",
        "score": 1.4,
        "probabilities": [
          { "value": 0, "label": "calm", "probability": 0.1 },
          { "value": 1, "label": "annoyed", "probability": 0.4 },
          { "value": 2, "label": "furious", "probability": 0.5 }
        ],
        "confidence": 0.62
      }
    }
  }
}