Partager via

Fonction ai_query

  • Article

S’applique à : case marquée oui Databricks SQL case marquée oui Databricks Runtime

Important

Cette fonctionnalité est disponible en préversion publique.

Appelle un point de terminaison de mise en service de modèle Azure Databricks existant, analyse et retourne ensuite sa réponse.

Consultez les guides suivants pour savoir comment utiliser ai_query différents cas d’usage :

Exigences

Remarque

  • Dans Databricks Runtime 14.2 et versions ultérieures, cette fonction est prise en charge dans les notebooks Databricks, notamment les notebooks exécutés en tant que tâche dans un flux de travail Databricks.
  • Dans Databricks Runtime 14.1 et ci-dessous, cette fonction n’est pas prise en charge dans les notebooks Databricks.

Syntaxe

Pour interroger un point de terminaison servant un modèle externe ou un modèle de base :

ai_query(endpointName, request)

Pour interroger un point de terminaison de mise en service de modèle personnalisé avec un schéma de modèle :

ai_query(endpointName, request)

Pour interroger un point de terminaison de mise en service de modèle personnalisé sans schéma de modèle :

ai_query(endpointName, request, returnType, failOnError)

Arguments

  • endpointName : littéral de CHAÎNE, le nom d’un point de terminaison de mise en service Databricks Foundation Model, un point de terminaison de mise en service de modèle externe ou un point de terminaison de modèle personnalisé dans le même espace de travail pour les invocations. L’utilisateur qui définit doit disposer de l’autorisation PEUT INTERROGER sur le point de terminaison.
  • request : expression, la requête utilisée pour appeler le point de terminaison.
    • Si le point de terminaison est un point de terminaison de service des modèles externes ou un point de terminaison d’API du modèle Databricks Foundation, la requête doit être une CHAINE.
    • Si le point de terminaison est un point de terminaison de service des modèles personnalisés, la requête peut être une unique colonne ou une expression de struct. Les noms de champ struct doivent correspondre aux noms des fonctionnalités d’entrée attendus par le point de terminaison.
  • returnType : Une expression, le returnType attendu du point de terminaison. Ceci est similaire au paramètre de schéma dans from_json fonction, qui accepte une expression STRING ou l’appel de schema_of_json fonction.
    • Dans Databricks Runtime 14.2 et versions ultérieures, si cette expression n’est pas fournie, ai_query() déduit automatiquement le type de retour du schéma de modèle du point de terminaison de mise en service de modèle personnalisé.
    • Dans Databricks Runtime 14.1 et versions antérieures, cette expression est requise pour interroger un point de terminaison de mise en service de modèle personnalisé.
  • failOnError: (facultatif) Littéral booléen par défaut sur true. Cet indicateur indique s’il faut inclure l’état d’erreur dans la ai_query réponse. Le format de réponse est différent lorsqu’il est défini sur false.
  • modelParameters (facultatif) : champ de struct qui contient des paramètres de modèle de conversation, d’achèvement et d’incorporation pour servir les modèles de base ou les modèles externes. Ces paramètres de modèle doivent être des paramètres constants et non dépendants des données. Lorsque ces paramètres de modèle ne sont pas spécifiés ou définis sur null la valeur par défaut est utilisé. À l’exception de temperature laquelle la valeur par défaut est 0.0, les valeurs par défaut pour ces paramètres de modèle sont identiques à celles répertoriées dans la référence de l’API REST du modèle Foundation.

Retours

Réponse analysée du point de terminaison.

  • Si failOnError => true, la fonction retourne le même résultat que le comportement existant, qui est la réponse analysée du point de terminaison. Le type de données de la réponse analysée est déduit du type de modèle, du point de terminaison de schéma du modèle ou du returnType paramètre dans la ai_query fonction.
  • Si failOnError => false, la fonction retourne la réponse analysée et la chaîne d’état d’erreur en tant qu’objet STRUCT.
    • Si l’inférence de la ligne a réussi, le errorStatus champ a la valeur Null.
    • Si l’inférence de la ligne a échoué en raison d’erreurs de point de terminaison de modèle, le response champ a la valeur Null.
    • Si l’inférence de la ligne a échoué en raison d’autres erreurs, la requête entière échoue.

Exemples

Voici un exemple d’inférence par lots utilisant et failOnError modelParameters avec et .max_tokens temperature Cet exemple montre également comment concaténer l’invite de votre modèle et de la colonne d’inférence à l’aide concat()de . Il existe plusieurs façons d’effectuer la concaténation, comme l’utilisation ||, concat()ou format_string().


CREATE OR REPLACE TABLE ${output_table_name} AS (
  SELECT
      ${input_column_name},
      AI_QUERY(
        "${endpoint}",
        CONCAT("${prompt}", ${input_column_name}),
        failOnError => false,
        modelParameters => named_struct('max_tokens', ${num_output_tokens},'temperature', ${temperature})
      ) as response
    FROM ${input_table_name}
    LIMIT ${input_num_rows}
)

Pour interroger un point de terminaison de service de modèle externe :

> SELECT ai_query(
    'my-external-model-openai-chat',
    'Describe Databricks SQL in 30 words.'
  ) AS summary

  "Databricks SQL is a cloud-based platform for data analytics and machine learning, providing a unified workspace for collaborative data exploration, analysis, and visualization using SQL queries."

Pour interroger un modèle de fondation pris en charge par les API Modèle de fondation Databricks :

> SELECT *,
  ai_query(
    'databricks-meta-llama-3-1-70b-instruct',
    "Can you tell me the name of the US state that serves the provided ZIP code? zip code: " || pickup_zip
    )
  FROM samples.nyctaxi.trips
  LIMIT 10

Si vous le souhaitez, vous pouvez également encapsuler un appel à ai_query() dans une fonction définie par l’utilisateur pour l’appel de fonction, comme suit :

> CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-1-70b-instruct',
    CONCAT('Correct this to standard English:\n', text));
> GRANT EXECUTE ON correct_grammar TO ds;
- DS fixes grammar issues in a batch.
> SELECT
    * EXCEPT text,
    correct_grammar(text) AS text
  FROM articles;

Pour interroger un point de terminaison en service des modèles personnalisés :


> SELECT text, ai_query(
    endpoint => 'spam-classification-endpoint',
    request => named_struct(
      'timestamp', timestamp,
      'sender', from_number,
      'text', text),
    returnType => 'BOOLEAN') AS is_spam
  FROM messages

> SELECT ai_query(
    'weekly-forecast',
    request => struct(*),
    returnType => 'FLOAT') AS predicted_revenue
  FROM retail_revenue

> SELECT ai_query(
    'custom-llama-2-7b-chat',
    request => named_struct("messages",
        ARRAY(named_struct("role", "user", "content", "What is ML?"))),
    returnType => 'STRUCT<candidates:ARRAY<STRING>>')

  {"candidates":["ML stands for Machine Learning. It's a subfield of Artificial Intelligence that involves the use of algorithms and statistical models to enable machines to learn from data, make decisions, and improve their performance on a specific task over time."]}

Exemple de requête pour définir le canal DLT en préversion :

> create or replace materialized view
    ai_query_mv
    TBLPROPERTIES('pipelines.channel' = 'PREVIEW') AS
  SELECT
    ai_query("databricks-dbrx-instruct", text) as response
  FROM
    messages