funktion ai_extract

Gäller för:markerad ja Databricks SQL markerad ja Databricks Runtime

Viktigt!

Den här funktionen är i offentlig förhandsversion och HIPAA-kompatibel.

Under förhandsversionen:

Funktionen ai_extract() extraherar strukturerade data från text och dokument enligt ett schema som du anger. Du kan använda enkla fältnamn för grundläggande extrahering eller definiera komplexa scheman med kapslade objekt, matriser, typvalidering och fältbeskrivningar för affärsdokument som fakturor, kontrakt och ekonomiska arkiveringar.

Funktionen accepterar text eller VARIANT utdata från andra AI-funktioner som ai_parse_document, vilket aktiverar komposterbara arbetsflöden för dokumentbearbetning från slutpunkt till slutpunkt.

Ett visuellt användargränssnitt som verifierar och itererar resultatet av finns i ai_extract av information.

Krav

Apache 2.0-licens

De underliggande modeller som kan användas just nu är licensierade under Apache 2.0-licensen, Copyright © Apache Software Foundation. Kunderna ansvarar för att säkerställa efterlevnaden av tillämpliga modelllicenser.

Databricks rekommenderar att du granskar dessa licenser för att säkerställa efterlevnad av tillämpliga villkor. Om modeller dyker upp i framtiden som presterar bättre enligt Databricks interna riktmärken kan Databricks ändra modellen (och listan över tillämpliga licenser som tillhandahålls på den här sidan).

Den modell som driver den här funktionen görs tillgänglig med hjälp av API:er för Modellserver foundation-modell. Se Tillämpliga modellvillkor för information om vilka modeller som är tillgängliga på Databricks och de licenser och principer som styr användningen av dessa modeller.

Om modeller dyker upp i framtiden som presterar bättre enligt Databricks interna riktmärken kan Databricks ändra modellerna och uppdatera dokumentationen.

  • Den här funktionen är endast tillgänglig i vissa regioner, se TILLGÄNGLIGHET för AI-funktioner.
  • Den här funktionen är inte tillgänglig på Azure Databricks KLASSISK SQL.
  • Kontrollera prissättningssidan för Databricks SQL.
  • I Databricks Runtime 15.1 och senare stöds den här funktionen i Databricks-notebooks, inklusive notebooks som körs som en uppgift i ett Databricks-arbetsflöde.
  • Batch-slutsatsdragningsarbetsbelastningar kräver Databricks Runtime 15.4 ML LTS för bättre prestanda.

Syntax

Databricks rekommenderar att du använder version 2 av den här funktionen eftersom den stöder kapslad fältextrahering och beskrivningar.

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

Version 1

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

Argument

  • content: Ett VARIANT eller STRING uttryck. Accepterar antingen:

    • Råtext som en STRING
    • En VARIANT som produceras av en annan AI-funktion (till exempel ai_parse_document)

  • schema: En STRING literal som definierar JSON-schemat för extrahering. Schemat kan vara:

    • Enkelt schema: En JSON-matris med fältnamn (antas vara strängar) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Avancerat schema: Ett JSON-objekt med typinformation, beskrivningar och kapslade strukturer
      • Stöder string, integer, number, booleanoch enum typer. Utför typverifiering. Värden som inte är giltiga resulterar i ett fel. Maximalt 500 uppräkningsvärden.
      • Stöder kapslade objekt med hjälp av "type": "object" med "properties"
      • Stöder matriser med primitiver eller objekt som använder "type": "array" med "items"
      • Valfritt "description" fält för varje egenskap för att vägleda extraheringskvaliteten

  • options: Ett valfritt MAP<STRING, STRING> som innehåller konfigurationsalternativ:

    • version: Versionsväxling för att stödja migrering ("2.1", "2.0", "1.0"). Standardvärdet baseras på indatatyper.
    • instructions: Global beskrivning av uppgiften och domänen för att förbättra extraheringskvaliteten. Måste vara mindre än 20 000 tecken.
    • enableCitations: När trueinnehåller utdata för varje fält i extraheringsschemat en lista med noll eller fler citat, vilket i dokumentet anger vilka utdata som extraherats.
    • enableConfidenceScores: När trueinnehåller utdata för varje fält i extraheringsschemat en konfidenspoäng mellan 0 och 1, vilket anger hur säker modellen är på det värdet. Det lämpliga tröskelvärdet för konfidens beror på ditt specifika användningsfall och du bör välja en gräns som överensstämmer med din tolerans för risk och fel.

Version 2

  • content: Ett VARIANT eller STRING uttryck. Accepterar antingen:

    • Råtext som en STRING
    • En VARIANT som produceras av en annan AI-funktion (till exempel ai_parse_document)

  • schema: En STRING literal som definierar JSON-schemat för extrahering. Schemat kan vara:

    • Enkelt schema: En JSON-matris med fältnamn (antas vara strängar) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Avancerat schema: Ett JSON-objekt med typinformation, beskrivningar och kapslade strukturer
      • Stöder string, integer, number, booleanoch enum typer. Utför typverifiering. Värden som inte är giltiga resulterar i ett fel. Maximalt 500 uppräkningsvärden.
      • Stöder kapslade objekt med hjälp av "type": "object" med "properties"
      • Stöder matriser med primitiver eller objekt som använder "type": "array" med "items"
      • Valfritt "description" fält för varje egenskap för att vägleda extraheringskvaliteten

  • options: Ett valfritt MAP<STRING, STRING> som innehåller konfigurationsalternativ:

    • version: Versionsväxling för att stödja migrering ("1.0" för v1-beteende, "2.0" för v2-beteende). Standardvärdet baseras på indatatyper, men återgår till "1.0".
    • instructions: Global beskrivning av uppgiften och domänen för att förbättra extraheringskvaliteten. Måste vara mindre än 20 000 tecken.

Version 1

  • content: Ett STRING uttryck som innehåller råtexten.

  • labels: En ARRAY<STRING> literal. Varje element är en typ av entitet som ska extraheras.

  • options: Ett valfritt MAP<STRING, STRING> som innehåller konfigurationsalternativ:

    • version: Versionsväxling för att stödja migrering ("1.0" för v1-beteende, "2.0" för v2-beteende). Standardvärdet baseras på indatatyper, men återgår till "1.0".

Returer

Returnerar en VARIANT innehållande:

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

Fältet response innehåller strukturerade data som extraherats enligt schemat:

  • Fältnamn och typer matchar schemadefinitionen
  • Schemats struktur bevaras i svaret: kapslade objekt och matriser behåller sin ursprungliga form. Varje "skalär" fält i extraheringsschemat har ett utdataobjekt med följande fält:
    • value: Det extraherade värdet, skrivet enligt schemat. Null om fältet inte kan extraheras.
    • citation_ids: Endast närvarande när enableCitations är true. En matris med ID:er som indexerats till metadata.citations.
    • confidence_score: Endast närvarande när enableConfidenceScores är true. En float mellan 0 och 1.
  • Typverifiering tillämpas för heltals-, tal-, boolesk- och uppräkningstyper
  • Om content är NULL, är NULL resultatet.

Fältet metadata innehåller metadata om svaret. När enableCitations är trueinnehåller fältet metadata information om varje källhänvisnings-ID i fältet response som spårar det extraherade värdet tillbaka till dess plats i indata.

Beroende på typ av indata kan citat vara av en av två typer:

  • För råtextindata (STRING) är en källhänvisning ett textintervall i den ursprungliga inmatningen. Varje objekt i metadata.citations innehåller:
    • id: Heltal som matchar en citation_ids post i ett fält.
    • start: Inkluderande 0-baserad teckenförskjutning i indatasträngen.
    • stop: Exklusiv 0-baserad teckenförskjutning i indatasträngen.
  • För PDF-dokument och bilder (när du använder ai_extract nedströms ai_parse_document) är en källhänvisning en avgränsningsruta i den ursprungliga inmatningen. Varje objekt i metadata.citations innehåller:
    • id: Heltal som matchar en citation_ids post i ett fält.
    • bbox: Matris med {coord, page_id} objekt, identisk i form med element.bbox i ai_parse_document utdata. coord är pixelkoordinater på sidbilden, liksom [x0, y0, x1, y1]; page_id ett 0-baserat sidindex.

Version 2

Returnerar en VARIANT innehållande:

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

Fältet response innehåller strukturerade data som extraherats enligt schemat:

  • Fältnamn och typer matchar schemadefinitionen
  • Kapslade objekt och matriser bevaras i strukturen
  • Fält kan vara null om de inte hittas
  • Typverifiering tillämpas för integer, number, booleanoch enum typer

Om content är NULL, är NULL resultatet.

Version 1

Returnerar en STRUCT plats där varje fält motsvarar en entitetstyp som anges i labels. Varje fält innehåller en sträng som representerar den extraherade entiteten. Om funktionen hittar fler än en kandidat för någon entitetstyp returnerar den bara en.

Exempel

Enkelt schema – endast fältnamn

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

Avancerat schema – med typer och beskrivningar

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

Kapslade objekt och matriser

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

Komposterbarhet med 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;

Använda uppräkningar

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

Citat (STRING-indata, SPAN-citat)

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

Citat (VARIANT från ai_parse_document, BBOX-citat)

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

Konfidenspoäng


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

Notebook-exempel

Följande notebook-fil innehåller ett visuellt felsökningsgränssnitt för analys av ai_extract funktionens källhänvisningsutdata. Den visar hur du återger källhänvisningsmetadata som understrängsfragment (STRING-indata) eller överlägg för avgränsningsrutor (VARIANT-indata) och kopplar ai_extract källhänvisningar tillbaka till element i SQL så att ai_parse_document du kan flagga extrahering med låg konfidens för manuell granskning.

Notebook-fil för källhänvisningsåtergivning

Hämta anteckningsbok

Version 2

Enkelt schema – endast fältnamn

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

Avancerat schema – med typer och beskrivningar

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

Kapslade objekt och matriser

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

Komposterbarhet med 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;

Använda uppräkningar

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

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

Begränsningar

  • Den här funktionen är inte tillgänglig på Azure Databricks KLASSISK SQL.
  • Den här funktionen kan inte användas med vyer.
  • Schemat stöder högst 128 fält.
  • Fältnamn kan innehålla upp till 150 tecken.
  • Scheman stöder upp till sju kapslingsnivåer för kapslade fält.
  • Uppräkningsfält stöder högst 500 värden.
  • Typverifiering tillämpas för integertyperna , number, booleanoch enum . Om ett värde inte matchar den angivna typen returnerar funktionen ett fel.
  • Den maximala totala kontextstorleken är 128 000 token.

Version 2

  • Den här funktionen är inte tillgänglig på Azure Databricks KLASSISK SQL.
  • Den här funktionen kan inte användas med vyer.
  • Schemat stöder högst 128 fält.
  • Fältnamn kan innehålla upp till 150 tecken.
  • Scheman stöder upp till sju kapslingsnivåer för kapslade fält.
  • Uppräkningsfält stöder högst 500 värden.
  • Typverifiering tillämpas för integertyperna , number, booleanoch enum . Om ett värde inte matchar den angivna typen returnerar funktionen ett fel.
  • Den maximala totala kontextstorleken är 128 000 token.

Version 1

  • Den här funktionen är inte tillgänglig på Azure Databricks KLASSISK SQL.
  • Den här funktionen kan inte användas med Vyer.
  • Om mer än en kandidat för en entitetstyp hittas i innehållet returneras endast ett värde.
  • Last updated on