ai_extract Fonction

S’applique à : Databricks SQL Databricks Runtime

La ai_extract() fonction extrait des données structurées à partir de texte et de documents en fonction d’un schéma que vous fournissez. Vous pouvez utiliser des noms de champs simples pour l’extraction de base ou définir des schémas complexes avec des objets imbriqués, des tableaux, une validation de type et des descriptions de champs pour les documents métier tels que les factures, les contrats et les dépôts financiers.

La fonction accepte du texte ou VARIANT de la sortie d’autres fonctions IA telles que ai_parse_document, ce qui permet des workflows composables pour le traitement de documents de bout en bout.

Pour qu’une interface utilisateur visuelle valide et itérer sur les résultats de ai_extract, consultez Extraction d’informations.

Spécifications

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 les modèles émergent à l’avenir qui fonctionnent mieux en fonction des benchmarks internes de Databricks, Databricks peut modifier les modèles et mettre à jour la documentation.

• Cette fonction est disponible uniquement dans certaines régions, consultez la disponibilité des fonctions IA.
• Cette fonction n’est pas disponible sur Azure Databricks SQL Classic.
• Consultez la page de tarification de Databricks SQL.
• Dans Databricks Runtime 15.1 et versions ultérieures, cette fonction est prise en charge dans les notebooks Databricks, notamment ceux exécutés en tant que tâche dans un workflow Databricks.
• Les charges de travail d’inférence par lots nécessitent Databricks Runtime 15.4 ML LTS pour améliorer les performances.

Syntaxe

Databricks recommande d’utiliser la version 2 de cette fonction, car elle prend en charge l’extraction et les descriptions de champs imbriqués.

Version 2.1 (recommandé)

ai_extract(
    content VARIANT | STRING,
    schema STRING,
    [options MAP<STRING, STRING>]
) RETURNS VARIANT

Version 2

ai_extract(
    content VARIANT | STRING,
    schema STRING,
    [options MAP<STRING, STRING>]
) RETURNS VARIANT

Édition 1

ai_extract(
    content STRING,
    labels ARRAY<STRING>,
    [options MAP<STRING, STRING>]
) RETURNS STRUCT

Les arguments

Version 2.1 (recommandé)

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

  • Texte brut en tant que texte brut STRING
  • Produit VARIANT par une autre fonction IA (par exemple ai_parse_document)

• schema: littéral STRING définissant le schéma JSON pour l’extraction. Le schéma peut être :

  • Schéma simple : tableau JSON de noms de champs (supposé être des chaînes)

    "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    

  • Schéma avancé : objet JSON avec des informations de type, des descriptions et des structures imbriquées
    • Prend en charge string, , integernumber, booleanet enum les types. Effectue la validation de type. Les valeurs qui ne sont pas valides entraînent une erreur. Maximum de 500 valeurs d’énumération.
    • Prend en charge les objets imbriqués à l’aide de "type": "object""properties"
    • Prend en charge les tableaux de primitives ou d’objets à l’aide de "type": "array""items"
    • Champ facultatif "description" pour chaque propriété pour guider la qualité de l’extraction

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

  • version: commutateur de version pour prendre en charge la migration ("2.1", "2.0", "1.0"). La valeur par défaut est basée sur les types d’entrée.
  • instructions: description globale de la tâche et du domaine pour améliorer la qualité de l’extraction. Doit être inférieur à 20 000 caractères.
  • enableCitations: Lorsque true, la sortie de chaque champ du schéma d’extraction inclut une liste de zéro ou plusieurs citations, ce qui indique dans le document l’extraction de la sortie.
  • enableConfidenceScores: Quand true, la sortie de chaque champ du schéma d’extraction inclut un score de confiance compris entre 0 et 1, indiquant la façon dont certains modèles concernent cette valeur. Le seuil de confiance approprié dépend de votre cas d’usage spécifique, et vous devez choisir un seuil qui s’aligne sur votre tolérance au risque et à l’erreur.

Version 2

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

  • Texte brut en tant que texte brut STRING
  • Produit VARIANT par une autre fonction IA (par exemple ai_parse_document)

• schema: littéral STRING définissant le schéma JSON pour l’extraction. Le schéma peut être :

  • Schéma simple : tableau JSON de noms de champs (supposé être des chaînes)

    "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    

  • Schéma avancé : objet JSON avec des informations de type, des descriptions et des structures imbriquées
    • Prend en charge string, , integernumber, booleanet enum les types. Effectue la validation de type. Les valeurs qui ne sont pas valides entraînent une erreur. Maximum de 500 valeurs d’énumération.
    • Prend en charge les objets imbriqués à l’aide de "type": "object""properties"
    • Prend en charge les tableaux de primitives ou d’objets à l’aide de "type": "array""items"
    • Champ facultatif "description" pour chaque propriété pour guider la qualité de l’extraction

• 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 l’extraction. Doit être inférieur à 20 000 caractères.

Édition 1

• content STRING: expression contenant le texte brut.

• labels : Un ARRAY<STRING> littéral. Chaque élément est un type d’entité à extraire.

• 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

Version 2.1 (recommandé)

Retourne un VARIANT conteneur :

{
  "response": {...},       // Extracted data matching the provided schema. Each leaf is returned as a Field object (see below).
  "error_message": null,   // null on success, or error message on failure
  "metadata": { ... }      // Metadata about the response, including unfurled citation ids.
}

Le response champ contient les données structurées extraites en fonction du schéma :

• Les noms et types de champs correspondent à la définition de schéma
• La structure du schéma est conservée dans la réponse : les objets imbriqués et les tableaux conservent leur forme d’origine. Chaque champ « scalaire » du schéma d’extraction a un objet de sortie avec les champs suivants :
  • value: valeur extraite, typée en fonction du schéma. Null si le champ ne peut pas être extrait.
  • citation_ids: présent uniquement quand est enableCitationstrue. Tableau d’ID indexés en metadata.citations.
  • confidence_score: présent uniquement quand est enableConfidenceScorestrue. Un nombre flottant compris entre 0 et 1.
• La validation de type est appliquée pour les types entier, nombre, booléen et énumération
• Si content est NULL, le résultat est NULL.

Le metadata champ contient les métadonnées relatives à la réponse. Quand enableCitations c’est truele cas, le metadata champ contient des détails sur chaque ID de citation dans le response champ qui trace la valeur extraite à son emplacement dans l’entrée.

Selon le type d’entrée, les citations peuvent être de l’un des deux types suivants :

• Pour les entrées de texte brut (STRING), une citation est une étendue de texte dans l’entrée d’origine. Chaque objet dans metadata.citations contient :
  • id: entier correspondant à une entrée citation_ids sur un champ.
  • start: décalage de caractère inclusif basé sur 0 dans la chaîne d’entrée.
  • stop: décalage de caractères exclusif de 0 dans la chaîne d’entrée.
• Pour les documents et images PDF (lors de l’utilisation ai_extract en aval de ai_parse_document), une citation est un cadre englobant dans l’entrée d’origine. Chaque objet dans metadata.citations contient :
  • id: entier correspondant à une citation_ids entrée sur un champ.
  • bbox: Tableau d’objets {coord, page_id} , identique à la forme à element.bbox dans la ai_parse_document sortie. coord est des coordonnées de pixels sur l’image de page, comme [x0, y0, x1, y1]; page_id il s’agit d’un index de page basé sur 0.

Version 2

Retourne un VARIANT conteneur :

{
  "response": { ... },   // Extracted data matching the provided schema
  "error_message": null          // null on success, or error message on failure
}

Le response champ contient les données structurées extraites en fonction du schéma :

• Les noms et types de champs correspondent à la définition de schéma
• Les objets et tableaux imbriqués sont conservés dans la structure
• Les champs peuvent être null introuvables
• La validation de type est appliquée pour integer, number, booleanet enum les types

Si content est NULL, le résultat est NULL.

Édition 1

Retourne un STRUCT champ où chaque champ correspond à un type d’entité spécifié dans labels. Chaque champ contient une chaîne représentant l’entité extraite. Si la fonction trouve plusieurs candidats pour n’importe quel type d’entité, elle ne retourne qu’une seule.

Exemples

Version 2.1 (recommandé)

Schéma simple - Noms de champs uniquement

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '["invoice_id", "vendor_name", "total_amount", "invoice_date"]',
    options => map('version', '2.1')
  );
 {
   "response": {
     "invoice_id":   {"value": "12345"},
     "vendor_name":  {"value": "Acme Corp"},
     "total_amount": {"value": "1250.00"},
     "invoice_date": {"value": "2024-01-15"}
   },
   "error_message": null
 }

Schéma avancé - avec types et descriptions

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '{
      "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
      "vendor_name": {"type": "string", "description": "Legal business name"},
      "total_amount": {"type": "number", "description": "Total invoice amount"},
      "invoice_date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
    }',
    options => map('version', '2.1')
  );
 {
   "response": {
     "invoice_id":   {"value": "12345"},
     "vendor_name":  {"value": "Acme Corp"},
     "total_amount": {"value": 1250.00},
     "invoice_date": {"value": "2024-01-15"}
   },
   "error_message": null
 }

Objets et tableaux imbriqués

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp
     Line 1: Widget A, qty 10, $50.00 each
     Line 2: Widget B, qty 5, $100.00 each
     Subtotal: $1,000.00, Tax: $80.00, Total: $1,080.00',
    '{
      "invoice_header": {
        "type": "object",
        "properties": {
          "invoice_id": {"type": "string"},
          "vendor_name": {"type": "string"}
        }
      },
      "line_items": {
        "type": "array",
        "description": "List of invoiced products",
        "items": {
          "type": "object",
          "properties": {
            "description": {"type": "string"},
            "quantity": {"type": "integer"},
            "unit_price": {"type": "number"}
          }
        }
      },
      "totals": {
        "type": "object",
        "properties": {
          "subtotal": {"type": "number"},
          "tax_amount": {"type": "number"},
          "total_amount": {"type": "number"}
        }
      }
    }',
    options => map('version', '2.1')
  );
 {
   "response": {
     "invoice_header": {
       "invoice_id":  {"value": "12345"},
       "vendor_name": {"value": "Acme Corp"}
     },
     "line_items": [
       {"description": {"value": "Widget A"}, "quantity": {"value": 10}, "unit_price": {"value": 50.00}},
       {"description": {"value": "Widget B"}, "quantity": {"value": 5},  "unit_price": {"value": 100.00}}
     ],
     "totals": {
       "subtotal":     {"value": 1000.00},
       "tax_amount":   {"value": 80.00},
       "total_amount": {"value": 1080.00}
     }
   },
   "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/finance/invoices/', format => 'binaryFile')
  )
  SELECT
    path,
    ai_extract(
      parsed_content,
      '["invoice_id", "vendor_name", "total_amount"]',
      MAP('version', '2.1', 'instructions', 'These are vendor invoices.')
    ) AS invoice_data
  FROM parsed_docs;

Utilisation des énumérations

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp, amount: $1,250.00 USD',
    '{
      "invoice_id": {"type": "string"},
      "vendor_name": {"type": "string"},
      "total_amount": {"type": "number"},
      "currency": {
        "type": "enum",
        "labels": ["USD", "EUR", "GBP", "CAD", "AUD"],
        "description": "Currency code"
      },
      "payment_terms": {"type": "string"}
    }',
    options => map('version', '2.1')
  );
 {
   "response": {
     "invoice_id":     {"value": "12345"},
     "vendor_name":    {"value": "Acme Corp"},
     "total_amount":   {"value": 1250.00},
     "currency":       {"value": "USD"},
     "payment_terms":  {"value": null}
   },
   "error_message": null
 }

Citations (entrée STRING, citations SPAN)

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '{
      "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
      "vendor_name": {"type": "string", "description": "Legal business name"},
      "total_amount": {"type": "number", "description": "Total invoice amount"},
      "invoice_date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
    }',
   options => map(
     'version', '2.1',
     'enableCitations', 'true'
   )
  );
 {
   "response": {
     "invoice_id": {"citation_ids": [0], "value": "12345"},
     "vendor_name": {"citation_ids": [0], "value": "Acme Corp"},
     "total_amount": {"citation_ids": [1], "value": 1250.00},
     "invoice_date": {"citation_ids": [1], "value": "2024-01-15"}
   },
   "metadata": {
     "chunk_type": "span",
     "citations": [
       {"id": 0, "start": 0, "stop": 29},
       {"id": 1, "start": 29, "stop": 60}
     ]
   },
   "error_message": null
 }

Citations (VARIANT de ai_parse_document, citations BBOX)

> WITH parsed AS (
    SELECT ai_parse_document(
             content,
             map('imageOutputPath', '/Volumes/main/default/parsed_images/')  // necessary for rendering bboxes
           ) AS doc
    FROM READ_FILES('/Volumes/main/default/invoices/invoice.pdf', format => 'binaryFile')
  )
  SELECT ai_extract(
    doc,
    '{"invoice_id":{"type":"string"}, "total_amount":{"type":"number"}}',
    options => map('version','2.1','enableCitations','true')
  ) AS extracted
  FROM parsed;
{
  "response": {
    "invoice_id":   {"citation_ids": [0], "value": "12345"},
    "total_amount": {"citation_ids": [1], "value": 1250.00}
  },
  "metadata": {
    "chunk_type": "bbox",
    "citations": [
      {"id": 0, "bbox": [{"coord": [120, 80,  240, 110], "page_id": 0}]},
      {"id": 1, "bbox": [{"coord": [400, 500, 560, 530], "page_id": 0}]}
    ],
    "pages": [{"id": 0, "image_uri": "/Volumes/main/default/parsed_images/6077ca79...f8efdb2ed05.jpg"}]
  },
  "error_message": null
}

Scores de confiance

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '{
      "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
      "vendor_name": {"type": "string", "description": "Legal business name"},
      "total_amount": {"type": "number", "description": "Total invoice amount"},
      "invoice_date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
    }',
   options => map(
    'version', '2.1',
    'enableConfidenceScores', 'true'
   )
  );
{
  "response": {
    "invoice_id": {"confidence_score": 0.95, "value": "12345"},
    "vendor_name": {"confidence_score": 0.62, "value": "Acme Corp"},
    "total_amount": {"confidence_score": 1.0, "value": 1250.00},
    "invoice_date": {"confidence_score": 0.99, "value": "2024-01-15"}
  },
  "error_message": null
}

Exemple de notebook

Le notebook suivant fournit une interface de débogage visuelle permettant d’analyser les sorties de citation de la ai_extract fonction. Il montre comment restituer des métadonnées de citation sous forme d’extraits de sous-chaîne (entrée STRING) ou de superpositions englobantes (entrée VARIANT) et de joindre ai_extract des citations à ai_parse_document des éléments dans SQL afin de pouvoir marquer des extractions à faible confiance pour la révision manuelle.

Bloc-notes de rendu de citation

Obtenir un ordinateur portable

Version 2

Schéma simple - Noms de champs uniquement

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '["invoice_id", "vendor_name", "total_amount", "invoice_date"]'
  );
 {
   "response": {
     "invoice_id": "12345",
     "vendor_name": "Acme Corp",
     "total_amount": "1250.00",
     "invoice_date": "2024-01-15"
   },
   "error_message": null
 }

Schéma avancé - avec types et descriptions

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '{
      "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
      "vendor_name": {"type": "string", "description": "Legal business name"},
      "total_amount": {"type": "number", "description": "Total invoice amount"},
      "invoice_date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
    }'
  );
 {
   "response": {
     "invoice_id": "12345",
     "vendor_name": "Acme Corp",
     "total_amount": 1250.00,
     "invoice_date": "2024-01-15"
   },
   "error_message": null
 }

Objets et tableaux imbriqués

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp
     Line 1: Widget A, qty 10, $50.00 each
     Line 2: Widget B, qty 5, $100.00 each
     Subtotal: $1,000.00, Tax: $80.00, Total: $1,080.00',
    '{
      "invoice_header": {
        "type": "object",
        "properties": {
          "invoice_id": {"type": "string"},
          "vendor_name": {"type": "string"}
        }
      },
      "line_items": {
        "type": "array",
        "description": "List of invoiced products",
        "items": {
          "type": "object",
          "properties": {
            "description": {"type": "string"},
            "quantity": {"type": "integer"},
            "unit_price": {"type": "number"}
          }
        }
      },
      "totals": {
        "type": "object",
        "properties": {
          "subtotal": {"type": "number"},
          "tax_amount": {"type": "number"},
          "total_amount": {"type": "number"}
        }
      }
    }'
  );
 {
   "response": {
     "invoice_header": {
       "invoice_id": "12345",
       "vendor_name": "Acme Corp"
     },
     "line_items": [
       {"description": "Widget A", "quantity": 10, "unit_price": 50.00},
       {"description": "Widget B", "quantity": 5, "unit_price": 100.00}
     ],
     "totals": {
       "subtotal": 1000.00,
       "tax_amount": 80.00,
       "total_amount": 1080.00
     }
   },
   "error": 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/finance/invoices/', format => 'binaryFile')
  )
  SELECT
    path,
    ai_extract(
      parsed_content,
      '["invoice_id", "vendor_name", "total_amount"]',
      MAP('instructions', 'These are vendor invoices.')
    ) AS invoice_data
  FROM parsed_docs;

Utilisation des énumérations

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp, amount: $1,250.00 USD',
    '{
      "invoice_id": {"type": "string"},
      "vendor_name": {"type": "string"},
      "total_amount": {"type": "number"},
      "currency": {
        "type": "enum",
        "labels": ["USD", "EUR", "GBP", "CAD", "AUD"],
        "description": "Currency code"
      },
      "payment_terms": {"type": "string"}
    }'
  );
 {
   "response": {
     "invoice_id": "12345",
     "vendor_name": "Acme Corp",
     "total_amount": 1250.00,
     "currency": "USD",
     "payment_terms": null
   },
   "error": null
 }

Édition 1

> SELECT ai_extract(
    'John Doe lives in New York and works for Acme Corp.',
    array('person', 'location', 'organization')
  );
 {"person": "John Doe", "location": "New York", "organization": "Acme Corp."}

> SELECT ai_extract(
    'Send an email to jane.doe@example.com about the meeting at 10am.',
    array('email', 'time')
  );
 {"email": "jane.doe@example.com", "time": "10am"}

Limites

Version 2.1 (recommandé)

• Cette fonction n’est pas disponible sur Azure Databricks SQL Classic.
• Cette fonction ne peut pas être utilisée avec des vues.
• Le schéma prend en charge un maximum de 128 champs.
• Les noms de champs peuvent contenir jusqu’à 150 caractères.
• Les schémas prennent en charge jusqu’à sept niveaux d’imbrication pour les champs imbriqués.
• Les champs d’énumération prennent en charge un maximum de 500 valeurs.
• La validation de type est appliquée pour integer, number, booleanet enum les types. Si une valeur ne correspond pas au type spécifié, la fonction retourne une erreur.
• La taille totale maximale du contexte est de 128 000 jetons.

Version 2

• Cette fonction n’est pas disponible sur Azure Databricks SQL Classic.
• Cette fonction ne peut pas être utilisée avec des vues.
• Le schéma prend en charge un maximum de 128 champs.
• Les noms de champs peuvent contenir jusqu’à 150 caractères.
• Les schémas prennent en charge jusqu’à sept niveaux d’imbrication pour les champs imbriqués.
• Les champs d’énumération prennent en charge un maximum de 500 valeurs.
• La validation de type est appliquée pour integer, number, booleanet enum les types. Si une valeur ne correspond pas au type spécifié, la fonction retourne une erreur.
• La taille totale maximale du contexte est de 128 000 jetons.

Édition 1

• Cette fonction n’est pas disponible sur Azure Databricks SQL Classic.
• Cette fonction ne peut pas être utilisée avec views.
• Si plusieurs candidats pour un type d’entité se trouvent dans le contenu, une seule valeur est retournée.

Fonctions connexes

• Fonction ai_parse_document
• Fonction ai_classify
• Fonction ai_prep_search