Fonction ai_classify

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

La ai_classify() fonction classifie le contenu du texte en fonction des étiquettes personnalisées que vous fournissez. Vous pouvez utiliser des noms d’étiquettes simples pour la classification de base ou ajouter des descriptions d’étiquettes et des instructions pour améliorer la précision des cas d’usage tels que le routage du support client, la catégorisation des documents et l’analyse du contenu.

La fonction accepte du texte ou VARIANT de la sortie d’autres fonctions IA telles que ai_parse_document, ce qui active les flux de travail composables.

Pour qu’une version de l’interface utilisateur itérera ai_classify, consultez Classification.

Spécifications

Licence Apache 2.0

Les modèles sous-jacents qui peuvent être utilisés pour l’instant sont sous licence sous licence Apache 2.0, copyright © The Apache Software Foundation. Les clients sont tenus de veiller à la conformité aux licences de modèle applicables.

Databricks recommande de passer en revue ces licences pour vérifier leur conformité avec les conditions applicables. Si les modèles émergent à l’avenir qui fonctionnent mieux en fonction des benchmarks internes de Databricks, Databricks peut modifier le modèle (et la liste des licences applicables fournies sur cette page).

Le modèle qui alimente cette fonction est rendu disponible à l’aide des API Model Service Foundation. Consultez les conditions de modèle applicables pour plus d’informations sur les modèles disponibles sur Databricks et les licences et stratégies qui régissent l’utilisation de ces modèles.

Si des modèles apparaissent mieux selon les benchmarks internes de Azure Databricks, Databricks peut modifier les modèles et mettre à jour la documentation.

Tip

Databricks recommande d’utiliser la version 2.1 pour ai_classify. La version 1.0 est une interface héritée qui ne prend pas en charge ces fonctionnalités et n’est pas recommandée pour les charges de travail nouvelles ou de production.

La version 2.0 prend en charge :

  • Descriptions des étiquettes pour une précision améliorée
  • Classification multi-étiquettes
  • Instructions globales
  • Jusqu’à 500 étiquettes, comparativement à 20 dans la version 1.0
  • VARIANT entrée à partir de fonctions IA en amont telles que ai_parse_document
  • Retourne une structure VARIANT avec des informations d’erreur

La version 2.1 prend également en charge :

  • Scores de confiance pour chaque étiquette retournée, activé avec enableConfidenceScores
  • Justifications expliquant chaque étiquette retournée, activée avec enableRationales

Dans la version 2.1, chaque classification est response un objet par étiquette avec une value clé au lieu d’une chaîne d’étiquette simple. Cette modification de forme de sortie s’applique à tous les appels de la version 2.1, même lorsque les nouvelles options sont désactivées. Le passage de la version 2.0 à la version 2.1 n’est pas compatible avec la sortie. Mettez à jour vos requêtes et code en aval pour lire l’étiquette à partir de la value clé au lieu de la lire directement.

Pour épingler une version explicitement, passez options => map('version', '2.1').

Syntaxe

ai_classify(content, labels [, options])

Version 2

ai_classify(content, labels [, options])

Version 1 (héritée)

ai_classify(content, labels [, options])

Les arguments

  • content : Une expression VARIANT ou STRING. Accepte soit :

  • labels STRING: expression définissant les étiquettes de classification. Il peut s’agir d’un littéral de chaîne ou d’une expression SQL qui prend la valeur d’une STRINGcolonne de table Delta. Les étiquettes peuvent être les suivantes :

    • Étiquettes simples : tableau JSON de noms d’étiquettes. 
      ["urgent", "not_urgent"]
    • Étiquettes avec descriptions : noms d’étiquettes de mappage d’objets JSON à des descriptions. Les descriptions d’étiquette doivent comporter 0 à 1 000 caractères. 
      {
  "billing_error": "Payment, invoice, or refund issues",
  "product_defect": "Any malfunction, bug, or breakage",
  "account_issue": "Login failures, password resets"
}

    Chaque étiquette doit comporter 1 à 100 caractères. labels doit contenir au moins 2 étiquettes et pas plus de 500 étiquettes. Pour connaître les taxonomies supérieures à 500 étiquettes, consultez la classification avec 500 étiquettes.

  • options: option facultative MAP<STRING, STRING> contenant les options de configuration :

    • version: commutateur de version pour prendre en charge la migration ("1.0", "2.0"ou "2.1"). La valeur par défaut est basée sur les types d’entrée, mais revient à "1.0".
    • instructions: description globale de la tâche et du domaine pour améliorer la qualité de la classification. Doit être inférieur à 20 000 caractères.
    • multilabel: définissez la valeur pour "true" retourner plusieurs étiquettes lorsque plusieurs catégories s’appliquent. La valeur par défaut est "false" (classification à étiquette unique).
    • enableConfidenceScores: défini pour "true" inclure un confidence_score (0 à 1) pour chaque étiquette retournée. Nécessite la version "2.1". La valeur par défaut est "false".
    • enableRationales: défini pour "true" inclure une courte justification expliquant chaque étiquette retournée, fondée dans le texte d’entrée. Nécessite la version "2.1". La valeur par défaut est "false".

Version 2

  • content : Une expression VARIANT ou STRING. Accepte soit :

  • labels STRING: expression définissant les étiquettes de classification. Il peut s’agir d’un littéral de chaîne ou d’une expression SQL qui prend la valeur d’une STRINGcolonne de table Delta. Les étiquettes peuvent être les suivantes :

    • Étiquettes simples : tableau JSON de noms d’étiquettes. 
      ["urgent", "not_urgent"]
    • Étiquettes avec descriptions : noms d’étiquettes de mappage d’objets JSON à des descriptions. Les descriptions d’étiquette doivent comporter 0 à 1 000 caractères. 
      {
  "billing_error": "Payment, invoice, or refund issues",
  "product_defect": "Any malfunction, bug, or breakage",
  "account_issue": "Login failures, password resets"
}

    Chaque étiquette doit comporter 1 à 100 caractères. labels doit contenir au moins 2 étiquettes et pas plus de 500 étiquettes. Pour connaître les taxonomies supérieures à 500 étiquettes, consultez la classification avec 500 étiquettes.

  • options: option facultative MAP<STRING, STRING> contenant les options de configuration :

    • version: commutateur de version pour prendre en charge la migration ( pour le"1.0" comportement v1, "2.0" pour le comportement v2). La valeur par défaut est basée sur les types d’entrée, mais revient à "1.0".
    • instructions: description globale de la tâche et du domaine pour améliorer la qualité de la classification. Doit être inférieur à 20 000 caractères.
    • multilabel: définissez la valeur pour "true" retourner plusieurs étiquettes lorsque plusieurs catégories s’appliquent. La valeur par défaut est "false" (classification à étiquette unique).

Version 1 (héritée)

  • content STRING: expression contenant le texte à classer.

  • labels: littéral ARRAY<STRING> avec les étiquettes de classification de sortie attendues. Doit contenir au moins 2 éléments, et pas plus de 20 éléments. Chaque étiquette doit comporter 1 à 50 caractères.

  • options: option facultative MAP<STRING, STRING> contenant les options de configuration :

    • version: commutateur de version pour prendre en charge la migration ( pour le"1.0" comportement v1, "2.0" pour le comportement v2). La valeur par défaut est basée sur les types d’entrée, mais revient à "1.0".

Retours

Retourne un VARIANT conteneur :

{
  "response": [{ "value": "label_name", "confidence_score": 0.97, "rationale": "Short justification for the label." }],
  "metadata": {
    "version": "2.1"
  },
  "error_message": null // null on success, or error message on failure
}

Chaque élément est response un objet par étiquette avec une value clé plutôt qu’une chaîne d’étiquette simple. Quand enableConfidenceScores c’est "true"le cas, chaque objet inclut également un confidence_score (0 à 1). Lorsque enableRationales c’est "true"le cas, chaque objet inclut également un rationale. Lorsque les deux options sont activées, l’ordre de clé dans chaque objet est value, confidence_scorepuis rationale.

Le response champ contient :

  • Mode à étiquette unique (valeur par défaut) : tableau avec un élément contenant la meilleure étiquette correspondante
  • Mode multi-étiquette (multilabel: "true") : tableau avec plusieurs étiquettes lorsque plusieurs catégories s’appliquent
  • Les noms d’étiquette correspondent exactement à ceux fournis dans le labels paramètre

Retourne NULL si content c’est NULL le cas ou si le contenu ne peut pas être classé.

Version 2

Retourne un VARIANT conteneur :

{
  "response": ["label_name"], // Array with single label (or multiple if multilabel=true)
  "metadata": {
    "version": "2.0"
  },
  "error_message": null // null on success, or error message on failure
}

Le response champ contient :

  • Mode à étiquette unique (valeur par défaut) : tableau avec un élément contenant la meilleure étiquette correspondante
  • Mode multi-étiquette (multilabel: "true") : tableau avec plusieurs étiquettes lorsque plusieurs catégories s’appliquent
  • Les noms d’étiquette correspondent exactement à ceux fournis dans le labels paramètre

Retourne NULL si content c’est NULL le cas ou si le contenu ne peut pas être classé.

Version 1 (héritée)

Retourne un STRING. La valeur correspond à l’une des chaînes fournies dans l’argument labels.

Retourne NULL si content c’est NULL le cas ou si le contenu ne peut pas être classé.

Exemples

Étiquettes simples : noms d’étiquettes uniquement

Dans la version 2.1, chaque classification est un objet par étiquette avec une value clé au lieu d’une chaîne simple, même lorsque les nouvelles options sont désactivées.

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]',
    MAP('version', '2.1')
  );
 {
   "response": [{"value": "urgent"}],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

Avec des scores de confiance

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]',
    MAP('version', '2.1', 'enableConfidenceScores', 'true')
  );
 {
   "response": [{"value": "urgent", "confidence_score": 0.97}],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

Avec des justifications

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]',
    MAP('version', '2.1', 'enableRationales', 'true')
  );
 {
   "response": [{"value": "urgent", "rationale": "A leaked password is a security incident requiring immediate action."}],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

Avec des scores de confiance et des logiques (multi-étiquette)

> SELECT ai_classify(
    'Customer wants refund and reports product arrived broken.',
    '{
      "billing_issue": "Payment or refund requests",
      "product_defect": "Damaged or malfunctioning items"
    }',
    MAP('version', '2.1', 'multilabel', 'true', 'enableConfidenceScores', 'true', 'enableRationales', 'true')
  );
 {
   "response": [
     {"value": "billing_issue", "confidence_score": 0.91, "rationale": "Customer explicitly requests a refund."},
     {"value": "product_defect", "confidence_score": 0.88, "rationale": "Reports the product arrived broken."}
   ],
   "metadata": {
     "version": "2.1"
   },
   "error_message": null
 }

Composabilité avec ai_parse_document

> WITH parsed_docs AS (
    SELECT
      path,
      ai_parse_document(
        content,
        MAP('version', '2.0')
      ) AS parsed_content
    FROM READ_FILES('/Volumes/support/tickets/', format => 'binaryFile')
  )
  SELECT
    path,
    ai_classify(
      parsed_content,
      '["billing_error", "product_defect", "account_issue", "feature_request"]',
      MAP('version', '2.1', 'instructions', 'Customer support ticket classification.')
    ) AS ticket_category
  FROM parsed_docs;

Classification par lots

> SELECT
    description,
    ai_classify(
      description,
      '["clothing", "shoes", "accessories", "furniture", "electronics"]',
      MAP('version', '2.1')
    ) AS category
  FROM products
  LIMIT 10;

Classification avec 500 étiquettes+

Pour classifier avec plus de 500 étiquettes, nous vous recommandons d’incorporer vos documents et étiquettes, de récupérer les principales étiquettes k par document, puis d’exécuter ai_classify sur le sous-ensemble plus petit.

Consultez le tutoriel : Classifier des documents avec 500 étiquettes pour une procédure pas à pas.

Version 2

Étiquettes simples : noms d’étiquettes uniquement

> SELECT ai_classify(
    'My password is leaked.',
    '["urgent", "not_urgent"]'
  );
 {
   "response": ["urgent"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Étiquettes avec descriptions

> SELECT ai_classify(
    'Customer cannot complete checkout due to payment processing error.',
    '{
      "billing_error": "Payment, invoice, or refund issues",
      "product_defect": "Any malfunction, bug, or breakage",
      "account_issue": "Login failures, password resets",
      "feature_request": "Customer suggestions for improvements"
    }'
  );
 {
   "response": ["billing_error"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Étiquettes de la table Delta

Transmettez des étiquettes à partir d’une table Delta en les convertissant en chaîne JSON. Par exemple, en fonction d’une table d’étiquettes avec schéma news_topics(topic STRING, description STRING), vous pouvez passer vos étiquettes comme ai_classify suit :

SELECT
  ai_classify(
    "Leicester City Wins Premier League Title at 5000-1 Odds",
    l.labels,
    MAP('version', '2.0')
  ) AS classification
FROM (
  SELECT to_json(map_from_entries(collect_list(struct(topic, description)))) AS labels
  FROM news_topics
) l;

Utilisation d’instructions globales

> SELECT ai_classify(
    'User reports app crashes on startup after update.',
    '["critical", "high", "medium", "low"]',
    MAP('instructions', 'Classify bug severity based on user impact and frequency.')
  );
 {
   "response": ["critical"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Classification multi-étiquettes

> SELECT ai_classify(
    'Customer wants refund and reports product arrived broken.',
    '{
      "billing_issue": "Payment or refund requests",
      "product_defect": "Damaged or malfunctioning items",
      "shipping_issue": "Delivery problems"
    }',
    MAP('version', '2.0','multilabel', 'true')
  );
 {
   "response": ["billing_issue", "product_defect"],
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Version 1 (héritée)

> SELECT ai_classify("My password is leaked.", ARRAY("urgent", "not urgent"));
  urgent

> SELECT
    description,
    ai_classify(description, ARRAY('clothing', 'shoes', 'accessories', 'furniture')) AS category
  FROM
    products
  LIMIT 10;

Limites

Limitations de la version 2.1 :

  • Cette fonction n’est pas disponible sur Azure Databricks SQL Classic.

  • Cette fonction ne peut pas être utilisée avec views.

  • Les noms d’étiquette doivent être de 1 à 100 caractères chacun.

  • Le labels paramètre doit contenir entre 2 et 500 étiquettes uniques.

  • Les descriptions d’étiquette doivent être de 0 à 1 000 caractères chacune.

  • La taille totale maximale du contexte est de 128 000 jetons.

Version 2

Limitations de la version 2 :

  • Cette fonction n’est pas disponible sur Azure Databricks SQL Classic.

  • Cette fonction ne peut pas être utilisée avec views.

  • Les noms d’étiquette doivent être de 1 à 100 caractères chacun.

  • Le labels paramètre doit contenir entre 2 et 500 étiquettes uniques.

  • Les descriptions d’étiquette doivent être de 0 à 1 000 caractères chacune.

  • La taille totale maximale du contexte est de 128 000 jetons.

Version 1 (héritée)

Limitations de la version 1 (héritée) :

  • Cette fonction n’est pas disponible sur Azure Databricks SQL Classic.

  • Cette fonction ne peut pas être utilisée avec views.

  • Les noms d’étiquette doivent être de 1 à 50 caractères chacun.

  • Le labels tableau doit contenir entre 2 et 20 étiquettes.

  • L’entrée content doit être inférieure à 128 000 jetons (environ 300 000 caractères).

  • Last updated on