For AI agents: the complete documentation index is available at https://docs.ovhcloud.com/it/llms.txt, the full documentation bundle is available at https://docs.ovhcloud.com/it/llms-full.txt, and this page is available as Markdown at https://docs.ovhcloud.com/it/guides/public-cloud/ai-machine-learning/ai-endpoints-decision-models.md.
Vai al contenuto

AI Endpoints - Decision Models

Vedi come Markdown

Learn how to classify, score and answer yes/no questions about a text with calibrated probabilities using OVHcloud AI Endpoints Decision Models

Info

AI Endpoints is covered by the OVHcloud Public Cloud Special Conditions (see Appendix 10 – "Specific Conditions – AI Endpoints").

Introduction

AI Endpoints is a serverless platform provided by OVHcloud that offers easy access to a selection of world-renowned, pre-trained AI models. The platform is designed to be simple, secure, and intuitive, making it an ideal solution for developers who want to enhance their applications with AI capabilities without extensive AI expertise or concerns about data privacy.

Decision Models are designed to answer typed questions about a text, with calibrated probabilities. Instead of generating free-form text that you then have to parse, you describe the questions you want to ask and receive structured answers that you can plug directly into your application logic (routing, moderation, triage, analytics, etc.).

You can ask three types of questions, detailed in Question types: choice picks one option, score rates the text on ordered levels and noul answers yes or no.

Decision Models are available through the /v1/systemone endpoint, which follows the System One format created by TypeSafe. Clients already written for this format only need a new base URL, an AI Endpoints API key and the name of a model from our Catalog to work with AI Endpoints. The OpenAI-compatible /v1/decisions endpoint is not available yet.

Requirements

The examples provided in this guide can be used with one of the following environments:

Python
JavaScript
cURL

A Python environment with the requests library installed.

pip install requests

These examples use the clef-flash Decision Model.

Authentication

The examples provided in this guide are authenticated and expect the OVH_AI_ENDPOINTS_ACCESS_TOKEN environment variable to be set:

export OVH_AI_ENDPOINTS_ACCESS_TOKEN='your_api_key'

Follow the instructions in the AI Endpoints - Getting started guide to create an API key and for more information on authentication.

Quickstart

The endpoint is available at the following URL:

https://oai.endpoints.kepler.ai.cloud.ovh.net/api/v1/systemone

A request contains three elements:

  • model: the decision model to use.
  • state: what you want to ask questions about. This is usually a text, but it can also be any JSON object (a ticket, an email, a document...), which is sent to the model as JSON text.
  • questions: an object where each key is the name you give to a question, and each value describes the question (its type and its criteria).

Ask a single question

This first example classifies a customer message into a department.

Python
JavaScript
cURL
import os
import requests

url = "https://oai.endpoints.kepler.ai.cloud.ovh.net/api/v1/systemone"
headers = {
    "Authorization": f"Bearer {os.getenv('OVH_AI_ENDPOINTS_ACCESS_TOKEN')}",
    "Content-Type": "application/json"
}
payload = {
    "model": "clef-flash",
    "state": "Hello, I would like to download the invoice of the previous month for my Public Cloud project. Where can I find it?",
    "questions": {
        "department": {
            "type": "choice",
            "criteria": {
                "billing": "Payments, invoices and refunds",
                "technical": "Technical questions about a service",
                "sales": None
            }
        }
    }
}

response = requests.post(url, json=payload, headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print("Error:", response.status_code, response.text)

The response looks like the following:

{
  "model": "clef-flash",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.9758,
      "probabilities": {
        "billing": 0.9758,
        "technical": 0.019,
        "sales": 0.0053
      }
    }
  },
  "usage": {
    "input_tokens": 165,
    "output_tokens": 0
  },
  "object": "decision"
}

Only the input tokens (usage.input_tokens) are billed: Decision Models do not generate text, so output_tokens is 0.

Ask several questions at once

You can ask several questions about the same text in a single request. Each question is identified by its key in questions, and its answer comes back under the same key in answers.

The following example combines the three question types on a single customer message:

Python
JavaScript
cURL
import os
import requests

url = "https://oai.endpoints.kepler.ai.cloud.ovh.net/api/v1/systemone"
headers = {
    "Authorization": f"Bearer {os.getenv('OVH_AI_ENDPOINTS_ACCESS_TOKEN')}",
    "Content-Type": "application/json"
}
payload = {
    "model": "clef-flash",
    "state": "Hi, I just deployed my first Public Cloud instance and I would like to enable automatic backups before launching my website next week. How can I set this up, and what does it cost?",
    "questions": {
        "department": {
            "type": "choice",
            "criteria": {
                "billing": "Invoice, payment or subscription issues",
                "technical": "Technical questions about a service",
                "sales": "Pricing, offers or product questions"
            }
        },
        "frustration": {
            "type": "score",
            "criteria": [
                "Calm, just stating facts",
                "Frustrated but civil",
                "Very angry, strong language"
            ]
        },
        "is_urgent": {
            "type": "noul",
            "instructions": "The message conveys urgency or time-sensitivity"
        }
    }
}

response = requests.post(url, json=payload, headers=headers)

if response.status_code == 200:
    for question, answer in response.json()["answers"].items():
        print(question, answer)
else:
    print("Error:", response.status_code, response.text)

The Python example prints one line per question. The output looks like this:

department {'type': 'choice', 'choice': 'sales', 'confidence': 0.4986, 'probabilities': {'billing': 0.033, 'technical': 0.4684, 'sales': 0.4986}}
frustration {'type': 'score', 'score': 0.0251, 'confidence': 0.9767, 'legend': {'0': 'Calm, just stating facts', '1': 'Frustrated but civil', '2': 'Very angry, strong language'}, 'probabilities': {'0': 0.9767, '1': 0.0216, '2': 0.0017}}
is_urgent {'type': 'noul', 'noul': 0.07}

Question types

Choice

A choice question picks one option among a list that you define.

"department": {
  "type": "choice",
  "instructions": "Which department should handle this message?",
  "criteria": {
    "billing": "Invoice, payment or subscription issues",
    "technical": "Technical questions about a service",
    "sales": null
  }
}
  • criteria is an object where each key is an option and each value is a description that helps the model understand what the option means.
  • The description can be null when the name of the option is self-explanatory. Precise descriptions generally lead to more reliable answers.
  • instructions states what is asked. It is optional for a choice question but recommended.
  • The order matters: keep a stable order and do not sort the options differently from one request to another.

The answer contains the selected choice, the probabilities of every option (which sum to 1), and the confidence in the selected choice, between 0 and 1 (the higher the value, the greater the certainty):

{
  "type": "choice",
  "choice": "sales",
  "confidence": 0.4986,
  "probabilities": { "billing": 0.033, "technical": 0.4684, "sales": 0.4986 }
}

Score

A score question rates the text on ordered levels.

"frustration": {
  "type": "score",
  "instructions": "How frustrated is the customer?",
  "criteria": [
    "Calm, just stating facts",
    "Frustrated but civil",
    "Very angry, strong language"
  ]
}
  • criteria is an ordered list describing each level of the scale, from the lowest to the highest. The first item is level 0, the second is level 1, and so on. Provide between 2 and 10 levels.
  • instructions states what is asked. It is optional for a score question but recommended.
  • The order matters, so do not reorder the levels from one request to another.

The answer contains the score, a legend that maps each level to its description, the probabilities of every level and the same confidence as for a choice question:

{
  "type": "score",
  "score": 0.0251,
  "confidence": 0.9767,
  "legend": {
    "0": "Calm, just stating facts",
    "1": "Frustrated but civil",
    "2": "Very angry, strong language"
  },
  "probabilities": { "0": 0.9767, "1": 0.0216, "2": 0.0017 }
}

The score is a continuous value between the lowest and the highest level. It is the average of the levels weighted by their probability (here, 0 × 0.9767 + 1 × 0.0216 + 2 × 0.0017 ≈ 0.025), which lets you distinguish a text clearly sitting on a level from a text sitting between two levels.

Noul

A noul question answers a yes or no question about the text.

"is_urgent": {
  "type": "noul",
  "instructions": "The message conveys urgency or time-sensitivity"
}
  • instructions is required for a noul question. It is a statement describing the property to check, and the answer is the probability that this statement is true for the text.
  • criteria is optional. It can be omitted, or contain the optional keys "true" and "false" to describe what each answer means.

The answer contains a single value between 0 and 1:

{
  "type": "noul",
  "noul": 0.07
}

A value close to 1 means that the statement is very likely true, a value close to 0 means that it is very likely false.

Endpoint Limitations

  • Decision Models read text only: images, audio and unknown fields in the request are rejected.
  • A choice question accepts 2 to 255 options and a score question 2 to 10 levels.
  • The context of clef-flash is 16,384 tokens, including the state and the questions.
  • Rate limits are described in the AI Endpoints - Features, Capabilities and Limitations guide.
  • The quality of the answers depends on how clear your criteria and instructions are. Use distinct options and precise descriptions.

Conclusion

In this guide, we have explained how to use the Decision Models available on AI Endpoints. You can now classify, score and qualify texts with calibrated probabilities through the System One format, and integrate these answers into your own applications.

Go Further

Browse the full AI Endpoints documentation to further understand the main concepts and get started.

For training or technical assistance implementing our solutions, contact your sales representative or visit our Professional Services page to request a quote and have your project analysed by our experts.

Feedback

Please send us your questions, feedback, and suggestions to improve the service:

Questa pagina ti è stata utile?