Fonction `ai_query`

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

Important

Cette fonctionnalité est en préversion publique et conforme HIPAA.

Pendant l'aperçu :

Le modèle de langage sous-jacent peut gérer plusieurs langues, mais cette fonction IA est paramétrée pour l’anglais.
Consultez Fonctionnalités avec une disponibilité régionale limitée pour la disponibilité de la région AI Functions.

Effectue l'invocation d'un point de terminaison de service de modèle Azure Databricks existant et retourne sa réponse après l'avoir analysée.

ai_query est une fonction IA à usage général qui vous permet d’interroger des points de terminaison existants pour des charges de travail d’inférence en temps réel ou d’inférence par lots.

Consultez la fonction usage général : ai_query pour les modèles pris en charge et les configurations de point de terminaison requises.
Vous pouvez également utiliser ai_query pour interroger un agent AI déployé sur le point de terminaison du service de modèle ML, voir Interroger un agent Mosaic AI déployé
Pour utiliser ai_query dans des workflows de production, consultez Déployer des pipelines d'inférence par lots.

Exigences

Cette fonction n’est pas disponible sur Azure Databricks SQL classique.
Vous devez activer Azure Private Link pour utiliser cette fonctionnalité sur les entrepôts SQL pro.
Databricks Runtime 15.4 LTS ou version ultérieure est recommandé. L’utilisation de Databricks Runtime 15.3 ou inférieur peut entraîner des vitesses de performances plus lentes.
Votre espace de travail doit se trouver dans une région de service de modèle prise en charge.
Un point de terminaison de service de modèle existant avec votre modèle chargé. Si vous utilisez un modèle de base hébergé Databricks, un point de terminaison est créé pour vous. Sinon, consultez Créer des points de terminaison de service de modèle personnalisé ou Créer des points de terminaison de service de modèle de base.
L’interrogation des API de modèle de fondation est activée par défaut. Pour interroger des points de terminaison qui servent des modèles personnalisés ou des modèles externes :
- Activez AI_Query pour les modèles personnalisés et les modèles externes dans l’interface utilisateur Databricks Previews.
Le canal actuelde l’entrepôt Pipelines déclaratifs Spark Lakeflow n’utilise pas la dernière version de Databricks Runtime qui prend en charge ai_query(). Définissez les propriétés pipelines.channel de la table comme 'preview' pour utiliser ai_query().
```
> create or replace materialized view
    ai_query_mv
    TBLPROPERTIES('pipelines.channel' = 'PREVIEW') AS
  SELECT
    ai_query("databricks-meta-llama-3-3-70b-instruct", text) as response
  FROM
    messages
  LIMIT 10;
```

Syntax

Pour interroger un point de terminaison qui sert un modèle de base :

ai_query(endpoint, request)

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

ai_query(endpoint, request)

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

ai_query(endpoint, request, returnType, failOnError)

Arguments et retours

Argument	Description	Returns
`endpoint`	Le nom d’un point de terminaison de mise en service Databricks Foundation Model, le nom d’un point de terminaison de mise en service de modèles externes ou le nom d’un point de terminaison de mise en service de modèles personnalisés au sein du même espace de travail pour les appels en tant que littéral `STRING`. Le définisseur doit disposer d'une permission `CAN QUERY` sur le point de terminaison.
`request`	Requête utilisée pour appeler le point de terminaison en tant qu’expression. 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 de modèle personnalisé, la requête peut être une seule colonne ou une expression STRUCT. Les noms de champs STRUCT doivent correspondre aux noms des caractéristiques de données d'entrée attendus par le point de terminaison.
`returnType`	(Facultatif pour Databricks Runtime 15.2 et versions ultérieures) Attendu `returnType` du point de terminaison en tant qu’expression. Cela est similaire au paramètre de schéma dans `from_json` la fonction, qui accepte à la fois une expression et un appel de la `STRING` fonction `schema_of_json`. Pour Databricks Runtime 15.2 et versions ultérieures, cette expression est facultative. S’il n’est pas fourni, `ai_query()` déduit automatiquement le type de retour à partir du schéma de modèle du point de terminaison de service de modèle personnalisé. Pour Databricks Runtime 15.1 et ci-dessous, cette expression est requise pour interroger un point de terminaison de service de modèle personnalisé. Utilisez le paramètre pour spécifier des `responseFormat` formats de réponse pour les modèles de base de conversation.
`failOnError`	(Facultatif) Littéral booléen qui a la valeur true par défaut. Nécessite Databricks Runtime 15.3 ou version ultérieure. Cet indicateur indique s’il faut inclure l’état d’erreur dans la `ai_query` réponse. Consultez l'Exemple d'utilisation de `failOnError` pour gérer les erreurs.	Les éléments suivants décrivent le comportement de retour en fonction du `failOnError` scénario : 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 un `STRUCT` objet qui contient la réponse analysée et la chaîne d’état d’erreur. Si l’inférence de la ligne réussit, le `errorStatus` champ est `null`. Si l’inférence de la ligne échoue en raison d’erreurs de point de terminaison de modèle, le `response` champ est `null`. Si l’inférence de la ligne échoue en raison d’autres erreurs, la requête entière échoue.
`modelParameters`	(Facultatif) Champ struct qui contient les paramètres de modèle de conversation, de complétion et d’incorporation pour la mise en service de modèles de base ou de modèles externes. Ces paramètres de modèle doivent être des paramètres constants et non dépendants des données. Nécessite Databricks Runtime 15.3 ou version ultérieure. 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. Consultez Configurer un modèle en passant des paramètres de modèle pour un exemple.
`responseFormat`	(Facultatif) Spécifiez le format de réponse que vous souhaitez que le modèle de base de conversation suive. Nécessite Databricks Runtime 15.4 LTS ou version ultérieure. Disponible uniquement pour l’interrogation des modèles de base de conversation instantanée. Deux styles de format de réponse sont pris en charge. Chaîne JSON de style DDL Chaîne JSON. Trois types de chaînes JSON de format de réponse sont pris en charge :`text`, `json_object`, `json_schema` Consultez Appliquer le schéma de sortie avec une sortie structurée pour obtenir des exemples.	Les éléments suivants décrivent ce qui se passe quand `failOnError` est également défini quand `responseFormat` est spécifié : 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`. 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", "json_schema"...}'`, la réponse est une chaîne JSON.
`files`	(Facultatif) Spécifiez les fichiers et le contenu à utiliser dans vos demandes d'entrée multimodales à l'aide de `files=>content`. `files` est le nom de paramètre attendu par le modèle d’entrée modale et `content` fait référence à la colonne du DataFrame qui contient le contenu binaire des fichiers image que vous souhaitez utiliser dans votre requête. Requis pour les demandes multimodales. Seules les entrées d’image : `JPEG` ou `PNG` sont prises en charge. Consultez les entrées multimodales à titre d'exemple. Comme indiqué dans cet exemple, vous pouvez spécifier la colonne `content` de la sortie de `read_files` au paramètre `files`.

Exemple : Interroger un modèle de base

Pour interroger un point de terminaison de mise en service de modèles externes :

> 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-3-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 inclure dans un wrapper un appel à ai_query() au sein d’une fonction UDF pour l’appel de fonction :

 CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-3-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;

Entrées multimodales

ai_query prend en charge nativement les entrées d’image multimodales. Consultez les types de modèles fondamentaux pour les modèles de vision pris en charge hébergés par Databricks.

Voici les types d’entrée pris en charge :

JPEG
PNG

L’exemple suivant montre comment interroger un modèle fondation pris en charge par les API Databricks Foundation Model pour des entrées multimodales. Dans cet exemple, le files => content paramètre est utilisé pour transmettre les données du fichier image à ai_query

files: nom du paramètre attendu par le modèle pour l’entrée multimodale
content: colonne dans le DataFrame retourné par READ_FILES, qui contient le contenu binaire du fichier image.


> SELECT *, ai_query(
  'databricks-llama-4-maverick',
 'what is this image about?', files => content)
as output FROM READ_FILES("/Volumes/main/multimodal/unstructured/image.jpeg");

Pour interroger un modèle de base pris en charge par les API Databricks Foundation Model pour les entrées modales et spécifier une sortie structurée :

> SELECT *, ai_query(
  'databricks-llama-4-maverick', 'What is interesting or important about this image?',
    responseFormat => ‘{
      "type": "json_schema",
        "json_schema": {
          "name": "output",
          "schema": {
            "type": "object",
            "properties": {
              "summary": {"type": "string"},
              "num_people": {"type": "integer"},
              "num_animals": {"type": "integer"},
              "interesting_fact": {"type": "string"},
              "possible_context": {"type": "string"}
            }
        },
        "strict": true
      }
    }’,
    files => content
  )
  as output FROM READ_FILES("/Volumes/main/user/volume1/image.jpeg");

Exemple : Interroger un modèle ML traditionnel

Pour interroger un modèle personnalisé ou un modèle ML traditionnel servant le point de terminaison :


> 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

Exemples de scénarios avancés

Les sections suivantes fournissent des exemples de cas d’usage avancés tels que la gestion des erreurs ou la façon d’incorporer ai_query dans une fonction définie par l’utilisateur.

Passer un tableau de messages

L’exemple suivant montre comment transmettre un tableau de messages à votre application de modèle ou d’agent à l’aide de ai_query.

> SELECT ai_query(
    'custom-llama-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."]}

Concaténer la colonne de prompt et celle d’inférence

Il existe plusieurs façons de concaténer l’invite et la colonne d’inférence, comme l’utilisation de ||, CONCAT(), ou format_string() :

SELECT
CONCAT('${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

Alternatively:

SELECT
'${prompt}' || ${input_column_name} AS concatenated_prompt
FROM ${input_table_name};

Ou à l’aide de format_string():

SELECT
format_string('%s%s', '${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

Configurer un modèle en passant des paramètres de modèle

Personnalisez le comportement du modèle en transmettant des paramètres spécifiques tels que des jetons et une température maximales. Par exemple:

SELECT text, ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "Please summarize the following article: " || text,
    modelParameters => named_struct('max_tokens', 100, 'temperature', 0.7)
) AS summary
FROM uc_catalog.schema.table;

Gérer les erreurs à l’aide de `failOnError`

Utilisez l’argument failOnError pour que ai_query gère les erreurs. L’exemple suivant montre comment vérifier que si une ligne a une erreur, elle n’arrête pas l’exécution de la requête entière. Consultez arguments et retours pour les comportements attendus en fonction de la façon dont cet argument est défini.


SELECT text, ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "Summarize the given text comprehensively, covering key points and main ideas concisely while retaining relevant details and examples. Ensure clarity and accuracy without unnecessary repetition or omissions: " || text,
failOnError => false
) AS summary
FROM uc_catalog.schema.table;

Appliquer le schéma de sortie avec une sortie structurée

Vérifiez que la sortie est conforme à un schéma spécifique pour faciliter le traitement en aval à l’aide de responseFormat. Consultez les sorties structurées sur Azure Databricks.

L’exemple suivant applique un schéma de chaîne JSON de style DDL :

SELECT ai_query(
    "databricks-gpt-oss-20b",
    "Extract research paper details from the following abstract: " || abstract,
    responseFormat => 'STRUCT<research_paper_extraction:STRUCT<title:STRING, authors:ARRAY<STRING>, abstract:STRING, keywords:ARRAY<STRING>>>'
)
FROM research_papers;

Vous pouvez également utiliser un format de réponse basé sur un schéma JSON :

SELECT ai_query(
    "databricks-gpt-oss-20b",
    "Extract research paper details from the following abstract: " || abstract,
    responseFormat => '{
      "type": "json_schema",
      "json_schema": {
        "name": "research_paper_extraction",
        "schema": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "authors": {"type": "array", "items": {"type": "string"}},
            "abstract": {"type": "string"},
            "keywords": {"type": "array", "items": {"type": "string"}}
          }
      },
      "strict": true
    }
  }'
)
FROM research_papers;

Une sortie attendue peut ressembler à ceci :

{ "title": "Understanding AI Functions in Databricks", "authors": ["Alice Smith", "Bob Jones"], "abstract": "This paper explains how AI functions can be integrated into data workflows.", "keywords": ["Databricks", "AI", "LLM"] }

Utiliser `ai_query` dans les fonctions définies par l’utilisateur

Vous pouvez encapsuler un appel à ai_query dans une fonction UDF, facilitant ainsi l'utilisation de fonctions dans différents processus de travail et leur partage.

CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-3-70b-instruct',
    CONCAT('Correct this to standard English:\n', text));

GRANT EXECUTE ON correct_grammar TO ds;

SELECT
    * EXCEPT text,
    correct_grammar(text) AS text
  FROM articles;

Rétroaction

Cette page a-t-elle été utile ?

Last updated on 2025-11-24