ai_extract functie

Van toepassing op:aangevinkt bij ja Databricks SQL aangevinkt bij ja Databricks Runtime

Belangrijk

Deze functionaliteit bevindt zich in de openbare preview-fase en is HIPAA-compatibel.

Tijdens de preview:

Met de ai_extract() functie worden gestructureerde gegevens geëxtraheerd uit tekst en documenten volgens een schema dat u opgeeft. U kunt eenvoudige veldnamen gebruiken voor basisextractie of complexe schema's definiëren met geneste objecten, matrices, typevalidatie en veldbeschrijvingen voor zakelijke documenten, zoals facturen, contracten en financiële archivering.

De functie accepteert tekst of VARIANT uitvoer van andere AI-functies, zoals ai_parse_documenthet inschakelen van composable werkstromen voor end-to-end documentverwerking.

Zie ai_extract voor een visuele gebruikersinterface voor het valideren en herhalen van de resultaten van.

Vereisten

Apache 2.0-licentie

De onderliggende modellen die op dit moment kunnen worden gebruikt, hebben een licentie onder de Apache 2.0-licentie, Copyright © The Apache Software Foundation. Klanten zijn verantwoordelijk voor het garanderen van naleving van toepasselijke modellicenties.

Databricks raadt aan deze licenties te controleren om ervoor te zorgen dat alle toepasselijke voorwaarden worden nageleefd. Als modellen in de toekomst beter presteren volgens de interne benchmarks van Databricks, kan Databricks het model (en de lijst met toepasselijke licenties op deze pagina) wijzigen.

Het model dat deze functie mogelijk maakt, wordt beschikbaar gesteld met behulp van Model Serving Foundation Model-API's. Zie Toepasselijke modelvoorwaarden voor informatie over welke modellen beschikbaar zijn in Databricks en de licenties en beleidsregels die het gebruik van deze modellen bepalen.

Als er in de toekomst modellen ontstaan die beter presteren volgens de interne benchmarks van Databricks, kan Databricks de modellen wijzigen en de documentatie bijwerken.

  • Deze functie is alleen beschikbaar in sommige regio's, zie beschikbaarheid van AI-functies.
  • Deze functie is niet beschikbaar in Azure Databricks SQL Classic.
  • Controleer de pagina met prijzen voor Databricks SQL.
  • In Databricks Runtime 15.1 en hoger wordt deze functie ondersteund in Databricks-notebooks, waaronder notebooks die worden uitgevoerd als een taak in een Databricks-werkstroom.
  • Batch-inferentieworkloads vereisen Databricks Runtime 15.4 ML LTS voor betere prestaties.

Syntaxis

Databricks raadt aan om versie 2 van deze functie te gebruiken omdat deze ondersteuning biedt voor geneste veldextractie en beschrijvingen.

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

Versie 2

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

Versie 1

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

Argumenten

  • content: Een VARIANT- of STRING-expressie. Accepteert ofwel:

    • Onbewerkte tekst als een STRING
    • Een VARIANT functie die wordt geproduceerd door een andere AI-functie (zoals ai_parse_document)

  • schema: Een STRING letterlijke definitie van het JSON-schema voor extractie. Het schema kan het volgende zijn:

    • Eenvoudig schema: een JSON-matrix met veldnamen (ervan uitgegaan dat het tekenreeksen zijn) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Geavanceerd schema: een JSON-object met typegegevens, beschrijvingen en geneste structuren
      • Ondersteunt string, integer, , numberen booleanenum typen. Voert typevalidatie uit. Waarden die ongeldig zijn, resulteren in een fout. Maximum van 500 enumwaarden.
      • Ondersteunt geneste objecten die worden gebruikt "type": "object" met "properties"
      • Ondersteunt matrices van primitieven of objecten die worden gebruikt "type": "array" met "items"
      • Optioneel "description" veld voor elke eigenschap om extractiekwaliteit te begeleiden

  • options: Een optioneel MAP<STRING, STRING> met configuratieopties:

    • version: Versieswitch voor ondersteuning van migratie ("2.1", "2.0", "1.0"). De standaardwaarde is gebaseerd op invoertypen.
    • instructions: Globale beschrijving van de taak en het domein om de extractiekwaliteit te verbeteren. Moet kleiner zijn dan 20.000 tekens.
    • enableCitations: Wanneer truebevat de uitvoer voor elk veld in het extractieschema een lijst met nul of meer bronvermeldingen, wat aangeeft in het document dat de uitvoer is geëxtraheerd.
    • enableConfidenceScores: Wanneer truebevat de uitvoer voor elk veld in het extractieschema een betrouwbaarheidsscore tussen 0 en 1, waarmee wordt aangegeven hoe bepaald het model over die waarde gaat. De juiste betrouwbaarheidsdrempel is afhankelijk van uw specifieke use-case en u moet een grens kiezen die overeenkomt met uw tolerantie voor risico's en fouten.

Versie 2

  • content: Een VARIANT- of STRING-expressie. Accepteert ofwel:

    • Onbewerkte tekst als een STRING
    • Een VARIANT functie die wordt geproduceerd door een andere AI-functie (zoals ai_parse_document)

  • schema: Een STRING letterlijke definitie van het JSON-schema voor extractie. Het schema kan het volgende zijn:

    • Eenvoudig schema: een JSON-matrix met veldnamen (ervan uitgegaan dat het tekenreeksen zijn) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Geavanceerd schema: een JSON-object met typegegevens, beschrijvingen en geneste structuren
      • Ondersteunt string, integer, , numberen booleanenum typen. Voert typevalidatie uit. Waarden die ongeldig zijn, resulteren in een fout. Maximum van 500 enumwaarden.
      • Ondersteunt geneste objecten die worden gebruikt "type": "object" met "properties"
      • Ondersteunt matrices van primitieven of objecten die worden gebruikt "type": "array" met "items"
      • Optioneel "description" veld voor elke eigenschap om extractiekwaliteit te begeleiden

  • options: Een optioneel MAP<STRING, STRING> met configuratieopties:

    • version: Versieswitch voor ondersteuning van migratie ("1.0" voor v1-gedrag, "2.0" voor v2-gedrag). De standaardwaarde is gebaseerd op invoertypen, maar valt terug op "1.0".
    • instructions: Globale beschrijving van de taak en het domein om de extractiekwaliteit te verbeteren. Moet kleiner zijn dan 20.000 tekens.

Versie 1

  • content: Een STRING expressie die de onbewerkte tekst bevat.

  • labels: Een ARRAY<STRING> letterlijk object. Elk element is een type entiteit dat moet worden geëxtraheerd.

  • options: Een optioneel MAP<STRING, STRING> met configuratieopties:

    • version: Versieswitch voor ondersteuning van migratie ("1.0" voor v1-gedrag, "2.0" voor v2-gedrag). De standaardwaarde is gebaseerd op invoertypen, maar valt terug op "1.0".

Retouren

Retourneert een VARIANT met:

{
  "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.
}

Het response veld bevat de gestructureerde gegevens die zijn geëxtraheerd volgens het schema:

  • Veldnamen en -typen komen overeen met de schemadefinitie
  • De structuur van het schema blijft behouden in het antwoord: geneste objecten en matrices behouden hun oorspronkelijke vorm. Elk scalaire veld in het extractieschema heeft een uitvoerobject met de volgende velden:
    • value: De geëxtraheerde waarde, getypt volgens het schema. Null als het veld niet kan worden geëxtraheerd.
    • citation_ids: Alleen aanwezig wanneer enableCitations .true Een matrix van id's geïndexeerd in metadata.citations.
    • confidence_score: Alleen aanwezig wanneer enableConfidenceScores .true Een float tussen 0 en 1.
  • Typevalidatie wordt afgedwongen voor gehele getallen, getallen, booleaanse en opsommingstypen
  • Als contentNULL is, dan is het resultaat NULL.

Het metadata veld bevat de metagegevens over het antwoord. Wanneer enableCitations dat het is true, bevat het metadata veld details over elke bronvermeldings-id in het response veld die de geëxtraheerde waarde terug naar de locatie in de invoer traceren.

Afhankelijk van het type invoer kunnen bronvermeldingen van een van de volgende twee typen zijn:

  • Voor invoer van onbewerkte tekst (STRING) is een bronvermelding een reeks tekst in de oorspronkelijke invoer. Elk object in metadata.citations bevat:
    • id: Geheel getal dat overeenkomt met een citation_ids vermelding in een veld.
    • start: Inclusief tekenverschil op basis van 0 in de invoertekenreeks.
    • stop: Exclusieve tekenverschuiving op basis van 0 in de invoertekenreeks.
  • Voor PDF-documenten en -afbeeldingen (wanneer u ai_extract downstream of ai_parse_document) gebruikt, is een bronvermelding een begrenzingsvak in de oorspronkelijke invoer. Elk object in metadata.citations bevat:
    • id: Geheel getal dat overeenkomt met een citation_ids item in een veld.
    • bbox: Matrix van {coord, page_id} objecten, identiek in vorm aan element.bbox in ai_parse_document uitvoer. coord is pixelcoördinaten op de pagina-afbeelding, net als [x0, y0, x1, y1]; page_id een op 0 gebaseerde pagina-index.

Versie 2

Retourneert een VARIANT met:

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

Het response veld bevat de gestructureerde gegevens die zijn geëxtraheerd volgens het schema:

  • Veldnamen en -typen komen overeen met de schemadefinitie
  • Geneste objecten en matrices blijven behouden in de structuur
  • Velden kunnen worden gevonden als deze niet worden null gevonden
  • Typevalidatie wordt afgedwongen voor integer, numberen booleanenumtypen

Als contentNULL is, dan is het resultaat NULL.

Versie 1

Retourneert een STRUCT locatie waar elk veld overeenkomt met een entiteitstype dat is opgegeven in labels. Elk veld bevat een tekenreeks die de geëxtraheerde entiteit vertegenwoordigt. Als met de functie meer dan één kandidaat voor een entiteitstype wordt gevonden, wordt er slechts één geretourneerd.

Voorbeelden

Eenvoudig schema: alleen veldnamen

> 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
 }

Geavanceerd schema - met typen en beschrijvingen

> 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
 }

Geneste objecten en matrices

> 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
 }

Composabiliteit met 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;

Opsommingen gebruiken

> 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
 }

Bronvermeldingen (TEKENREEKS-invoer, SPAN-bronvermeldingen)

> 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
 }

Bronvermeldingen (VARIANT uit ai_parse_document, BBOX-bronvermeldingen)

> 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
}

Betrouwbaarheidsscores


> 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
}

Voorbeeld van notitieblok

Het volgende notebook biedt een visuele foutopsporingsinterface voor het analyseren van de bronvermeldingsuitvoer van de ai_extract functie. Het laat zien hoe u bronvermeldingsmetagegevens weergeeft als subtekenreeksfragmenten (STRING-invoer) of overlays van begrenzingsvakken (VARIANT-invoer) en bronvermeldingen weer kunt koppelen ai_extract aan ai_parse_document elementen in SQL, zodat u extracties met een lage betrouwbaarheid kunt markeren voor handmatige controle.

Notebook voor bronvermeldingsweergave

Notebook krijgen

Versie 2

Eenvoudig schema: alleen veldnamen

> 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
 }

Geavanceerd schema - met typen en beschrijvingen

> 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
 }

Geneste objecten en matrices

> 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
 }

Composabiliteit met 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;

Opsommingen gebruiken

> 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
 }

Versie 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"}

Beperkingen

  • Deze functie is niet beschikbaar in Azure Databricks SQL Classic.
  • Deze functie kan niet worden gebruikt met weergaven.
  • Het schema ondersteunt maximaal 128 velden.
  • Veldnamen mogen maximaal 150 tekens bevatten.
  • Schema's ondersteunen maximaal zeven geneste niveaus voor geneste velden.
  • Enum-velden ondersteunen maximaal 500 waarden.
  • Typevalidatie wordt afgedwongen voor integer, numberen booleanenumtypen. Als een waarde niet overeenkomt met het opgegeven type, retourneert de functie een fout.
  • De maximale totale contextgrootte is 128.000 tokens.

Versie 2

  • Deze functie is niet beschikbaar in Azure Databricks SQL Classic.
  • Deze functie kan niet worden gebruikt met weergaven.
  • Het schema ondersteunt maximaal 128 velden.
  • Veldnamen mogen maximaal 150 tekens bevatten.
  • Schema's ondersteunen maximaal zeven geneste niveaus voor geneste velden.
  • Enum-velden ondersteunen maximaal 500 waarden.
  • Typevalidatie wordt afgedwongen voor integer, numberen booleanenumtypen. Als een waarde niet overeenkomt met het opgegeven type, retourneert de functie een fout.
  • De maximale totale contextgrootte is 128.000 tokens.

Versie 1

  • Deze functie is niet beschikbaar in Azure Databricks SQL Classic.
  • Deze functie kan niet worden gebruikt met weergaven.
  • Als er meer dan één kandidaat voor een entiteitstype wordt gevonden in de inhoud, wordt slechts één waarde geretourneerd.
  • Last updated on