Funkce ai_extract

Platí pro:zaškrtnuto ano Databricks SQL zaškrtnuto ano Databricks Runtime

Funkce ai_extract() extrahuje strukturovaná data z textu a dokumentů podle vámi zadaného schématu. Pro základní extrakci můžete použít jednoduché názvy polí nebo definovat složitá schémata s vnořenými objekty, poli, ověřováním typů a popisy polí pro obchodní dokumenty, jako jsou faktury, kontrakty a finanční zařazování.

Funkce přijímá text nebo VARIANT výstup z jiných funkcí umělé inteligence, jako je ai_parse_documentnapříklad povolení kompozovatelných pracovních postupů pro komplexní zpracování dokumentů.

Vizuální uživatelské rozhraní k ověření a iteraci výsledků ai_extractnajdete v tématu Extrakce informací.

Požadavky

Licence Apache 2.0

Základní modely, které lze v tuto chvíli použít, jsou licencované v rámci licence Apache 2.0, Copyright © Apache Software Foundation. Zákazníci zodpovídají za dodržení platných modelových licencí.

Databricks doporučuje zkontrolovat tyto licence, abyste zajistili soulad s platnými podmínkami. Pokud se modely objeví v budoucnu, které fungují lépe podle interních srovnávacích testů Databricks, může Databricks změnit model (a seznam použitelných licencí uvedených na této stránce).

The model powering this function is made available using Model Serving Foundation Model APIs. Informace o modelech dostupných v Databricks a licencích a zásadách, které řídí používání těchto modelů, najdete v příslušných podmínkách modelu .

Pokud se modely objeví v budoucnu, které fungují lépe podle interních srovnávacích testů Databricks, může Databricks změnit modely a aktualizovat dokumentaci.

Tip

Databricks doporučuje pro použití verze 2.0 nebo novějšíai_extract. Verze 1.0 je starší rozhraní, které tyto funkce nepodporuje a nedoporučuje se pro nové nebo produkční úlohy.

Verze 2.0 a novější podporuje

  • Bohaté schémata JSON s vnořenými objekty, poli, ověřováním typů a popisy polí
  • Přijímá funkce upstreamové AI i STRINGVARIANT vstupy jako ai_parse_document

Verze 2.1 také přidává citace a skóre spolehlivosti.

Pokud chcete verzi připnout explicitně, předejte options => map('version', '2.1')ji .

Syntaxe

ai_extract(content, schema [, options])

Verze 2

ai_extract(content, schema [, options])

Verze 1 (starší verze)

ai_extract(content, labels [, options])

Argumenty

  • content: VARIANT nebo STRING výraz. Přijímá buď:

    • Nezpracovaný text jako STRING
    • A VARIANT vytvořené jinou funkcí umělé inteligence (například ai_parse_document)

  • schema STRING: Literál definující schéma JSON pro extrakci. Schéma může být následující:

    • Jednoduché schéma: Pole názvů polí JSON (předpokládá se jako řetězce) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Pokročilé schéma: Objekt JSON s informacemi o typu, popisy a vnořenými strukturami
      • Podporuje string, , integernumber, boolean, a enum typy. Provede ověření typu. Hodnoty, které nejsou platné, způsobí chybu. Maximálně 500 hodnot výčtu.
      • Podporuje vnořené objekty používající s "type": "object""properties"
      • Podporuje pole primitiv nebo objektů používajících s "type": "array""items"
      • Volitelné "description" pole pro každou vlastnost pro vodítko kvality extrakce

  • options: Volitelné MAP<STRING, STRING> obsahující možnosti konfigurace:

    • version: Přepnutí verze na podporu migrace ("2.1", "2.0", "1.0"). Výchozí hodnota je založená na vstupních typech.
    • instructions: Globální popis úlohy a domény, aby se zlepšila kvalita extrakce. Musí být kratší než 20 000 znaků.
    • enableCitations: Když true, výstup pro každé pole ve schématu extrakce obsahuje seznam nula nebo více citací, které v dokumentu extrahovaný výstup.
    • enableConfidenceScores: Když true, výstup pro každé pole ve schématu extrakce zahrnuje skóre spolehlivosti mezi 0 a 1, které indikuje, jak určitý model je o této hodnotě. Odpovídající prahová hodnota spolehlivosti závisí na vašem konkrétním případu použití a měli byste zvolit omezení, které odpovídá vaší toleranci pro riziko a chybu.

Verze 2

  • content: VARIANT nebo STRING výraz. Přijímá buď:

    • Nezpracovaný text jako STRING
    • A VARIANT vytvořené jinou funkcí umělé inteligence (například ai_parse_document)

  • schema STRING: Literál definující schéma JSON pro extrakci. Schéma může být následující:

    • Jednoduché schéma: Pole názvů polí JSON (předpokládá se jako řetězce) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Pokročilé schéma: Objekt JSON s informacemi o typu, popisy a vnořenými strukturami
      • Podporuje string, , integernumber, boolean, a enum typy. Provede ověření typu. Hodnoty, které nejsou platné, způsobí chybu. Maximálně 500 hodnot výčtu.
      • Podporuje vnořené objekty používající s "type": "object""properties"
      • Podporuje pole primitiv nebo objektů používajících s "type": "array""items"
      • Volitelné "description" pole pro každou vlastnost pro vodítko kvality extrakce

  • options: Volitelné MAP<STRING, STRING> obsahující možnosti konfigurace:

    • version: Přepnutí verze na podporu migrace ("1.0" pro chování v1, "2.0" pro chování v2). Výchozí hodnota je založena na vstupních typech, ale vrátí se zpět na "1.0".
    • instructions: Globální popis úlohy a domény, aby se zlepšila kvalita extrakce. Musí být kratší než 20 000 znaků.

Verze 1 (starší verze)

  • content: Výraz STRING obsahující nezpracovaný text.

  • labels: Doslovný výraz ARRAY<STRING>. Každý prvek je typ entity, která se má extrahovat.

  • options: Volitelné MAP<STRING, STRING> obsahující možnosti konfigurace:

    • version: Přepnutí verze na podporu migrace ("1.0" pro chování v1, "2.0" pro chování v2). Výchozí hodnota je založená na vstupních typech, ale vrátí se zpět na "1.0".

Návraty

VARIANT Vrátí hodnotu obsahující:

{
  "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 version and citation details.
}

Pole response obsahuje strukturovaná data extrahovaná podle schématu:

  • Názvy a typy polí odpovídají definici schématu.
  • Struktura schématu je zachována v odpovědi: vnořené objekty a pole zachovávají původní tvar. Každé skalární pole ve schématu extrakce má výstupní objekt s následujícími poli:
    • value: Extrahovaná hodnota zadaná podle schématu. Null pokud pole nelze extrahovat.
    • citation_ids: Pouze tehdy, když enableCitations je true. Pole ID indexovaných do metadata.citations.
    • confidence_score: Pouze tehdy, když enableConfidenceScores je true. Plovák mezi 0 a 1.
  • Ověření typu se vynucuje pro celočíselné, číselné, logické a výčtové typy.
  • Pokud content je NULL, výsledek je NULL.

Pole metadata obsahuje metadata o odpovědi. Pokud enableCitations je true, obsahuje také podrobnosti o každém ID citace v response poli, které trasují extrahované hodnoty zpět do jeho umístění ve vstupu.

V závislosti na typu vstupu můžou být citace jednoho ze dvou typů:

  • U nezpracovaných textových vstupů (STRING) je citace rozsahem textu v původním vstupu. Každý objekt v metadata.citations obsahuje:
    • id: Celé číslo odpovídající citation_ids záznamu v poli.
    • start: Inkluzivní posun znaků založený na 0 do vstupního řetězce.
    • stop: Výhradní posun 0 znaků do vstupního řetězce.
  • U dokumentů a obrázků PDF (při použití ai_extract podřízeného textu ai_parse_document) je citace ohraničující rámeček v původním vstupu. Každý objekt obsahuje metadata.citations :
    • id: Celé číslo odpovídající citation_ids položce v poli.
    • bbox: Pole {coord, page_id} objektů, identické ve tvaru s element.bbox ve ai_parse_document výstupu. coord je souřadnice pixelů na obrázku stránky, jako [x0, y0, x1, y1]; page_id je index stránky založený na 0.

Verze 2

VARIANT Vrátí hodnotu obsahující:

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

Pole response obsahuje strukturovaná data extrahovaná podle schématu:

  • Názvy a typy polí odpovídají definici schématu.
  • Vnořené objekty a pole se zachovají ve struktuře.
  • Pole můžou být null , pokud nebyla nalezena.
  • Ověření typu se vynucuje pro integer, numberboolean, a enum typy

Pole metadata obsahuje metadata o odpovědi.

Pokud content je NULL, výsledek je NULL.

Verze 1 (starší verze)

Vrátí, kde STRUCT každé pole odpovídá typu entity zadanému v labels. Každé pole obsahuje řetězec představující extrahovaná entita. Pokud funkce najde více než jednoho kandidáta pro jakýkoli typ entity, vrátí pouze jeden.

Příklady

Jednoduché schéma – pouze názvy polí

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

Pokročilé schéma – s typy a popisy

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

Vnořené objekty a pole

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

Kompozability with 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;

Použití výčtů

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

Citace (vstup STRING, citace 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": {
     "version": "2.1",
     "chunk_type": "span",
     "citations": [
       {"id": 0, "start": 0, "stop": 29},
       {"id": 1, "start": 29, "stop": 60}
     ]
   },
   "error_message": null
 }

Citace (VARIANT z ai_parse_document, citace 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": {
    "version": "2.1",
    "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
}

Skóre spolehlivosti


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

Příklad poznámkového bloku

Následující poznámkový blok poskytuje vizuální ladicí rozhraní pro analýzu výstupů ai_extract citace funkce. Ukazuje, jak vykreslit metadata citace jako fragmenty podřetězců (vstup STRING) nebo ohraničující překrytí rámečku (vstup VARIANT) a spojit ai_extract citace zpět k ai_parse_document prvkům v SQL, abyste mohli označit extrakce s nízkou spolehlivostí pro ruční kontrolu.

Vykreslovací poznámkový blok citace

Pořiďte si notebook

Verze 2

Jednoduché schéma – pouze názvy polí

> 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"
   },
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Pokročilé schéma – s typy a popisy

> 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"
   },
   "metadata": {
     "version": "2.0"
   },
   "error_message": null
 }

Vnořené objekty a pole

> 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
     }
   },
   "metadata": {
     "version": "2.0"
   },
   "error": null
 }

Kompozability with 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;

Použití výčtů

> 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
   },
   "metadata": {
     "version": "2.0"
   },
   "error": null
 }

Verze 1 (starší verze)

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

Omezení

  • Tato funkce není k dispozici v Azure Databricks SQL Classic.
  • Tuto funkci nelze použít se zobrazeními.
  • Schéma podporuje maximálně 128 polí.
  • Názvy polí můžou obsahovat až 150 znaků.
  • Schémata podporují až sedm úrovní vnoření pro vnořená pole.
  • Pole výčtu podporují maximálně 500 hodnot.
  • Ověření typu se vynucuje pro integer, numberboolean, a enum typy. Pokud hodnota neodpovídá zadanému typu, vrátí funkce chybu.
  • Maximální celková velikost kontextu je 128 000 tokenů.

Verze 2

  • Tato funkce není k dispozici v Azure Databricks SQL Classic.
  • Tuto funkci nelze použít se zobrazeními.
  • Schéma podporuje maximálně 128 polí.
  • Názvy polí můžou obsahovat až 150 znaků.
  • Schémata podporují až sedm úrovní vnoření pro vnořená pole.
  • Pole výčtu podporují maximálně 500 hodnot.
  • Ověření typu se vynucuje pro integer, numberboolean, a enum typy. Pokud hodnota neodpovídá zadanému typu, vrátí funkce chybu.
  • Maximální celková velikost kontextu je 128 000 tokenů.

Verze 1 (starší verze)

  • Tato funkce není k dispozici v Azure Databricks SQL Classic.
  • Tuto funkci nelze použít se zobrazeními.
  • Pokud je v obsahu nalezeno více než jeden kandidát na typ entity, vrátí se pouze jedna hodnota.
  • Last updated on