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(endpoint, request)

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

ai_query(endpoint, request)

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

ai_query(endpoint, request, returnType, failOnError)

Arguments

  • endpoint: UnSTRING littéral, le nom d’un point de terminaison de service Databricks Foundation Model, un point de terminaison de service de modèle de base externe ou un point de terminaison de modèle personnalisé dans le même espace de travail pour les invocations. Le définisseur doit disposer d'une permission CAN QUERY 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 un STRING.
    • 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, returnType attendue à partir du point de terminaison. Ceci est similaire au paramètre de schéma dans from_json fonction, qui accepte à la fois une expression STRING ou un 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.
  • 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 qui a une valeur par défaut de 0.0, les valeurs par défaut pour ces paramètres de modèle sont identiques à celles répertoriées dans référence de l’API REST du modèle Foundation.
  • responseFormat (facultatif) : champ de chaîne JSON qui spécifie le format de réponse que vous souhaitez que le modèle suive. Trois types de chaînes de caractères de format de réponse sont pris en charge :
    • text
    • json_object
    • json_schema

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 champ errorStatus est null.
    • Si l’inférence de la ligne a échoué en raison d’erreurs de point de terminaison de modèle, le champ response est null.
    • Si l’inférence de la ligne a échoué en raison d’autres erreurs, la requête entière échoue.
  • Selon le type de chaîne JSON spécifié dans responseFormat, la réponse suivante est retournée :
    • Pour responseFormat => '{“type”, “text”}', la réponse est une chaîne telle que “Here is the response”.
    • Pour responseFormat => '{“type”, “json_object”}', la réponse est une chaîne JSON de paire clé-valeur, telle que {“key”: “value”}.
    • Pour responseFormat => '{“type”, “json_schema”...}', la réponse est une chaîne JSON. Consultez les exemples .
  • Si failOnError => false et que vous avez spécifié responseFormat, la fonction retourne la réponse analysée et la chaîne d’état d’erreur en tant qu’objet STRUCT.

Exemples

L’exemple suivant spécifie un format de réponse json_schema :


SELECT
  ai_query(
    "llama-3-1-70b",
    <request>,
    responseFormat =>'{
                        "type": "json_schema",
                        "json_schema":
                          {
                           "name": "research_paper_extraction",
                           "schema":
                             {
                              "type": "object",
                              "properties":
                               {
                                "title": { "type": "string" }
                               }
                             },
                            "strict": true
                          }
                      }'
  )

Voici un exemple de sortie pour le format de réponse json_schema spécifié :

{"title": "<the title of the paper>"}

Voici un exemple d’inférence par lots utilisant et failOnErrormodelParameters avec et .max_tokenstemperature 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
  LIMIT 10

> 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
  LIMIT 10;