Aller au contenu principal
Dernière mise à jour le

ai_decide function

Applies to: check marked yes Databricks SQL check marked yes Databricks Runtime

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

The ai_decide() function evaluates one or more questions against text or structured data. For each question, it returns either a probability, a choice from named criteria, or a score on an ordered scale. Use it to route support tickets, assess whether an event needs attention, or prioritize work using a rubric you define.

All questions in a call use the same input, called state. You can combine different question types in one call and use the returned answers in downstream SQL queries.

Data security​

Your document data is processed within the Databricks security perimeter. Databricks does not store the parameters that are passed into the AI function calls, but does retain metadata run details, such as the Databricks Runtime version used.

Requirements​

Apache 2.0 license

The underlying models that might be used at this time are licensed under the Apache 2.0 License, Copyright © The Apache Software Foundation. Customers are responsible for ensuring compliance with applicable model licenses.

Databricks recommends reviewing these licenses to ensure compliance with any applicable terms. If models emerge in the future that perform better according to Databricks's internal benchmarks, Databricks might change the model (and the list of applicable licenses provided on this page).

The model powering this function is made available using Model Serving Foundation Model APIs. See Applicable model terms for information about which models are available on Databricks and the licenses and policies that govern the use of those models.

If models emerge that perform better according to Databricks's internal benchmarks, Databricks might change the models and update the documentation.

Syntax​

SQL
ai_decide(state, questions [, options])

Arguments​

  • state: A VARIANT or STRING expression containing the content, context, and examples needed to answer the questions. The value can vary by row. Accepts either:

    • A STRING containing plain text or a JSON-encoded object or array. JSON objects and arrays are interpreted as structured data. Other strings are treated as text.
    • A VARIANT produced by another AI function (such as ai_parse_document or ai_extract)

  • questions: A constant STRING expression containing a nonempty JSON object. Each key is a nonempty question ID, and each value is a question definition. The same definitions apply to every row. See Question definitions.

  • options: An optional constant MAP<STRING, STRING> expression. The supported option is version, with the value '1.0'. Version 1.0 is the default. To specify it explicitly, use map('version', '1.0').

Question definitions​

Each question definition requires type and instructions, plus criteria when required by the question type. Required fields cannot be null. Other fields are not supported.

  • type: One of noul, choice, or score.
  • instructions: Instructions for evaluating the state, expressed as a string, JSON object, or JSON array.
  • criteria: The descriptions that define how to answer. The required shape depends on type.

Noul questions​

Use noul to estimate the likelihood that a question is true. The result is a number from 0 to 1.

The optional criteria object can contain true and false keys to describe those outcomes. Each description can be a string, JSON object, or JSON array. Omit criteria when you do not need these descriptions. If supplied, criteria must be an object and cannot be null.

JSON
{
  "needs_escalation": {
    "type": "noul",
    "instructions": "Does this ticket need immediate escalation?",
    "criteria": {
      "true": "An active service outage blocks the customer from working.",
      "false": "The customer can continue working or has a workaround."
    }
  }
}

Choice questions​

Use choice to select one label from a set of named criteria.

The required criteria object maps 1 to 255 nonempty labels to descriptions. Each description can be a string, JSON object, JSON array, or null. Use null when the label alone describes the choice.

JSON
{
  "team": {
    "type": "choice",
    "instructions": "Which team should handle this ticket?",
    "criteria": {
      "shipping": "Delivery or shipment issues",
      "billing": "Payment or invoice issues",
      "technical_support": "Product technical problems"
    }
  }
}

Score questions​

Use score to evaluate the state against an ordered scale.

The required criteria array contains 2 to 10 descriptions, ordered from lowest to highest. Each description can be a string, JSON object, or JSON array. The first criterion has index 0, the next has index 1, and so on.

The result is the probability-weighted average of these indices. It can be fractional and ranges from 0 to the number of criteria minus one. For example, probabilities of 0.1, 0.3, and 0.6 across three criteria produce a score of 1.5.

JSON
{
  "urgency": {
    "type": "score",
    "instructions": "How urgent is this ticket?",
    "criteria": [
      "Routine request with no time pressure",
      "Time-sensitive issue with a workaround",
      "Critical issue that blocks the customer"
    ]
  }
}

Returns​

Returns a VARIANT with the fields response, metadata, and error_message. The response field contains an answers object with one entry per question. Question IDs exactly match those provided in the questions parameter. Each answer includes a type field that matches the question type: noul, choice, or score. The following examples show the response field for each question type:

  • Noul questions: A probability from 0 to 1 estimating the likelihood that the question is true.

    JSON
    {
      "answers": {
        "needs_escalation": {
          "type": "noul",
          "probability": 0.1
        }
      }
    }

  • Choice questions: A choice containing the label with the highest probability and a probabilities object mapping every label to its probability. confidence is a number from 0 to 1 indicating how well the state supports the assessment. The probabilities values sum to 1. Label names exactly match those provided in criteria.

    JSON
    {
      "answers": {
        "team": {
          "type": "choice",
          "choice": "shipping",
          "probabilities": {
            "shipping": 0.8,
            "billing": 0.1,
            "technical_support": 0.1
          },
          "confidence": 0.9
        }
      }
    }

  • Score questions: A score containing the probability-weighted average of the criterion indices, a legend mapping string indices (such as "0") to the original criterion descriptions, and a probabilities object mapping those indices to probabilities. confidence is a number from 0 to 1 indicating how well the state supports the assessment. The probabilities values sum to 1.

    JSON
    {
      "answers": {
        "urgency": {
          "type": "score",
          "score": 1.5,
          "legend": {
            "0": "Routine request with no time pressure",
            "1": "Time-sensitive issue with a workaround",
            "2": "Critical issue that blocks the customer"
          },
          "probabilities": {
            "0": 0.1,
            "1": 0.3,
            "2": 0.6
          },
          "confidence": 0.8
        }
      }
    }

On success, metadata.version identifies the function version used and error_message is null.

On failure, response is null and error_message describes the failure. Invalid argument types or nonconstant question definitions can also cause query errors.

Examples​

The following example shows how to evaluate several questions in one call. Generated answers can vary between calls.

Evaluate multiple question types​

This example evaluates a product listing for its category, use of recycled materials, and suitability for hiking in rainy weather:

SQL
SELECT ai_decide(
  '{"name": "TrailShell jacket", "description": "Lightweight waterproof hiking jacket made from recycled polyester. Packs into its own pocket."}',
  '{
    "category": {
      "type": "choice",
      "instructions": "Which product category best fits this item?",
      "criteria": {
        "outerwear": "Jackets, coats, and other protective outer layers",
        "footwear": "Shoes, boots, and sandals",
        "accessories": "Bags, hats, and other accessories"
      }
    },
    "recycled_materials": {
      "type": "noul",
      "instructions": "Does the listing state that the product uses recycled materials?"
    },
    "hiking_suitability": {
      "type": "score",
      "instructions": "How suitable is this product for hiking in rainy weather?",
      "criteria": [
        "Not suitable for outdoor use in rain",
        "Offers some protection from rain",
        "Designed for hiking with waterproof protection"
      ]
    }
  }',
  map('version', '1.0')
) AS decision;

Example response:

JSON
{
  "response": {
    "answers": {
      "category": {
        "type": "choice",
        "choice": "outerwear",
        "probabilities": { "outerwear": 0.95, "footwear": 0.01, "accessories": 0.04 },
        "confidence": 0.95
      },
      "recycled_materials": { "type": "noul", "probability": 0.98 },
      "hiking_suitability": {
        "type": "score",
        "score": 1.8,
        "legend": {
          "0": "Not suitable for outdoor use in rain",
          "1": "Offers some protection from rain",
          "2": "Designed for hiking with waterproof protection"
        },
        "probabilities": { "0": 0.05, "1": 0.1, "2": 0.85 },
        "confidence": 0.9
      }
    }
  },
  "metadata": { "version": "1.0" },
  "error_message": null
}
Sur cette page