Funzione ai_extract

Si applica a:segno di spunta sì Databricks SQL segno di spunta sì Databricks Runtime

Importante

Questa funzionalità è disponibile in anteprima pubblica e conforme a HIPAA.

Durante l'anteprima:

La ai_extract() funzione estrae dati strutturati da testo e documenti in base a uno schema specificato. È possibile usare nomi di campo semplici per l'estrazione di base o definire schemi complessi con oggetti annidati, matrici, convalida dei tipi e descrizioni dei campi per documenti aziendali come fatture, contratti e archivi finanziari.

La funzione accetta testo o VARIANT output da altre funzioni di intelligenza artificiale, ad ai_parse_documentesempio , consentendo flussi di lavoro componibili per l'elaborazione di documenti end-to-end.

Per un'interfaccia utente visiva da convalidare e scorrere i risultati di ai_extract, vedere Estrazione di informazioni.

Requisiti

Licenza di Apache 2.0

I modelli sottostanti che potrebbero essere usati in questo momento sono concessi in licenza con la licenza Apache 2.0, Copyright © The Apache Software Foundation. I clienti sono tenuti a garantire la conformità con i modelli di licenza applicabili.

Databricks consiglia di esaminare queste licenze per garantire la conformità con le condizioni applicabili. Se i modelli emergono in futuro che offrono prestazioni migliori in base ai benchmark interni di Databricks, Databricks potrebbe modificare il modello (e l'elenco delle licenze applicabili fornite in questa pagina).

Il modello che alimenta questa funzione viene reso disponibile tramite le API Model Serving Foundation Model. Vedere Condizioni del modello applicabili per informazioni sui modelli disponibili in Databricks e sulle licenze e i criteri che regolano l'uso di tali modelli.

Se i modelli emergono in futuro che offrono prestazioni migliori in base ai benchmark interni di Databricks, Databricks potrebbe modificare i modelli e aggiornare la documentazione.

  • Questa funzione è disponibile solo in alcune aree, vedere Disponibilità delle funzioni di intelligenza artificiale.
  • Questa funzione non è disponibile in Azure Databricks sql classico.
  • Controllare la pagina dei prezzi di Databricks SQL.
  • In Databricks Runtime 15.1 e versioni successive questa funzione è supportata nei notebook di Databricks, inclusi i notebook eseguiti come attività in un flusso di lavoro di Databricks.
  • Per migliorare le prestazioni, i carichi di lavoro di inferenza batch richiedono Databricks Runtime 15.4 ML LTS.

Sintassi

Databricks consiglia di usare la versione 2 di questa funzione perché supporta l'estrazione e le descrizioni dei campi annidati.

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

Versione 2

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

Versione 1

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

Argomenti

  • content: espressione VARIANT o STRING . Accetta una:

    • Testo non elaborato come STRING
    • Oggetto VARIANT prodotto da un'altra funzione di intelligenza artificiale (ad esempio ai_parse_document)

  • schema: valore STRING letterale che definisce lo schema JSON per l'estrazione. Lo schema può essere:

    • Schema semplice: matrice JSON di nomi di campo (si presuppone che siano stringhe) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Schema avanzato: oggetto JSON con informazioni sul tipo, descrizioni e strutture annidate
      • Supporta stringi tipi , integernumber, boolean, e enum . Esegue la convalida dei tipi. I valori non validi generano un errore. Massimo 500 valori di enumerazione.
      • Supporta gli oggetti annidati usando "type": "object" con "properties"
      • Supporta matrici di primitive o oggetti usando "type": "array" con "items"
      • Campo facoltativo "description" per ogni proprietà per guidare la qualità dell'estrazione

  • options: facoltativo MAP<STRING, STRING> contenente le opzioni di configurazione:

    • version: opzione versione per supportare la migrazione ("2.1", "2.0", "1.0"). Il valore predefinito è basato sui tipi di input.
    • instructions: descrizione globale dell'attività e del dominio per migliorare la qualità dell'estrazione. Deve essere minore di 20.000 caratteri.
    • enableCitations: quando true, l'output per ogni campo nello schema di estrazione include un elenco di zero o più citazioni, che indica nel documento l'output estratto.
    • enableConfidenceScores: quando true, l'output per ogni campo nello schema di estrazione include un punteggio di confidenza compreso tra 0 e 1, che indica il modo in cui il modello riguarda tale valore. La soglia di attendibilità appropriata dipende dal caso d'uso specifico ed è consigliabile scegliere un cutoff allineato alla tolleranza per il rischio e l'errore.

Versione 2

  • content: espressione VARIANT o STRING . Accetta una:

    • Testo non elaborato come STRING
    • Oggetto VARIANT prodotto da un'altra funzione di intelligenza artificiale (ad esempio ai_parse_document)

  • schema: valore STRING letterale che definisce lo schema JSON per l'estrazione. Lo schema può essere:

    • Schema semplice: matrice JSON di nomi di campo (si presuppone che siano stringhe) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Schema avanzato: oggetto JSON con informazioni sul tipo, descrizioni e strutture annidate
      • Supporta stringi tipi , integernumber, boolean, e enum . Esegue la convalida dei tipi. I valori non validi generano un errore. Massimo 500 valori di enumerazione.
      • Supporta gli oggetti annidati usando "type": "object" con "properties"
      • Supporta matrici di primitive o oggetti usando "type": "array" con "items"
      • Campo facoltativo "description" per ogni proprietà per guidare la qualità dell'estrazione

  • options: facoltativo MAP<STRING, STRING> contenente le opzioni di configurazione:

    • version: opzione versione per supportare la migrazione ("1.0" per il comportamento v1, "2.0" per il comportamento v2). Il valore predefinito è basato sui tipi di input, ma esegue il fallback a "1.0".
    • instructions: descrizione globale dell'attività e del dominio per migliorare la qualità dell'estrazione. Deve essere minore di 20.000 caratteri.

Versione 1

  • content STRING: espressione contenente il testo non elaborato.

  • labels: un valore letterale ARRAY<STRING>. Ogni elemento è un tipo di entità da estrarre.

  • options: facoltativo MAP<STRING, STRING> contenente le opzioni di configurazione:

    • version: opzione versione per supportare la migrazione ("1.0" per il comportamento v1, "2.0" per il comportamento v2). Il valore predefinito è basato sui tipi di input, ma eseguirà il fallback a "1.0".

Restituzioni

Restituisce un oggetto VARIANT contenente:

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

Il response campo contiene i dati strutturati estratti in base allo schema:

  • I nomi dei campi e i tipi corrispondono alla definizione dello schema
  • La struttura dello schema viene mantenuta nella risposta: gli oggetti annidati e le matrici mantengono la forma originale. Ogni campo "scalare" nello schema di estrazione ha un oggetto di output con i campi seguenti:
    • value: valore estratto, tipizzato in base allo schema. Null se il campo non può essere estratto.
    • citation_ids: presente solo quando enableCitations è true. Matrice di ID indicizzati in metadata.citations.
    • confidence_score: presente solo quando enableConfidenceScores è true. Un numero float compreso tra 0 e 1.
  • La convalida dei tipi viene applicata per i tipi integer, number, boolean ed enum
  • Se content è NULL, il risultato è NULL.

Il metadata campo contiene i metadati relativi alla risposta. Quando enableCitations è true, il metadata campo contiene informazioni dettagliate su ogni ID di citazione nel response campo che traccia il valore estratto nella posizione nell'input.

A seconda del tipo di input, le citazioni possono essere di uno dei due tipi seguenti:

  • Per gli input di testo non elaborato (STRING), una citazione è un intervallo di testo nell'input originale. Ogni oggetto in metadata.citazionions contiene:
    • id: numero intero corrispondente a una voce citation_ids in un campo.
    • start: offset di caratteri in base 0 inclusivo nella stringa di input.
    • stop: offset di caratteri in base 0 esclusivo nella stringa di input.
  • Per i documenti e le immagini PDF (quando si usa ai_extract downstream di ai_parse_document), una citazione è un rettangolo di selezione nell'input originale. Ogni oggetto in metadata.citations contiene:
    • id: numero intero corrispondente a una citation_ids voce in un campo.
    • bbox: matrice di {coord, page_id} oggetti, identica nella forma a element.bbox nell'output ai_parse_document . coord è coordinate pixel sull'immagine della pagina così come [x0, y0, x1, y1]; page_id è un indice di pagina basato su 0.

Versione 2

Restituisce un oggetto VARIANT contenente:

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

Il response campo contiene i dati strutturati estratti in base allo schema:

  • I nomi dei campi e i tipi corrispondono alla definizione dello schema
  • Gli oggetti annidati e le matrici vengono mantenuti nella struttura
  • I campi possono essere null se non sono stati trovati
  • La convalida dei tipi viene applicata per integeri tipi , numberboolean, e enum

Se content è NULL, il risultato è NULL.

Versione 1

Restituisce un oggetto STRUCT in cui ogni campo corrisponde a un tipo di entità specificato in labels. Ogni campo contiene una stringa che rappresenta l'entità estratta. Se la funzione trova più candidati per qualsiasi tipo di entità, restituisce solo uno.

Esempi

Schema semplice - solo nomi di campo

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

Schema avanzato: con tipi e descrizioni

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

Oggetti annidati e matrici

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

Componibilità con 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;

Uso delle enumerazioni

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

Citazioni (input STRING, citazioni 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
 }

Citazioni (VARIANT da ai_parse_document, citazioni 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
}

Punteggi di attendibilità


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

Esempio di notebook

Il notebook seguente fornisce un'interfaccia di debug visivo per l'analisi degli output di citazione della ai_extract funzione. Viene illustrato come eseguire il rendering dei metadati della citazione come frammenti di sottostringa (input STRING) o sovrapposizioni di rettangoli delimitatore (input VARIANT) e unire ai_extract le citazioni agli ai_parse_document elementi in SQL in modo da poter contrassegnare le estrazioni a bassa confidenza per la revisione manuale.

Notebook per il rendering delle citazioni

Ottieni il notebook

Versione 2

Schema semplice - solo nomi di campo

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

Schema avanzato: con tipi e descrizioni

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

Oggetti annidati e matrici

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

Componibilità con 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;

Uso delle enumerazioni

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

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

Limitazioni

  • Questa funzione non è disponibile in Azure Databricks sql classico.
  • Questa funzione non può essere usata con le visualizzazioni.
  • Lo schema supporta un massimo di 128 campi.
  • I nomi dei campi possono contenere fino a 150 caratteri.
  • Gli schemi supportano fino a sette livelli di annidamento per i campi annidati.
  • I campi enumerazione supportano un massimo di 500 valori.
  • La convalida dei tipi viene applicata per integeri tipi , numberboolean, e enum . Se un valore non corrisponde al tipo specificato, la funzione restituisce un errore.
  • La dimensione totale massima del contesto è 128.000 token.

Versione 2

  • Questa funzione non è disponibile in Azure Databricks sql classico.
  • Questa funzione non può essere usata con le visualizzazioni.
  • Lo schema supporta un massimo di 128 campi.
  • I nomi dei campi possono contenere fino a 150 caratteri.
  • Gli schemi supportano fino a sette livelli di annidamento per i campi annidati.
  • I campi enumerazione supportano un massimo di 500 valori.
  • La convalida dei tipi viene applicata per integeri tipi , numberboolean, e enum . Se un valore non corrisponde al tipo specificato, la funzione restituisce un errore.
  • La dimensione totale massima del contesto è 128.000 token.

Versione 1

  • Questa funzione non è disponibile in Azure Databricks sql classico.
  • Questa funzione non può essere utilizzata con Views.
  • Se nel contenuto vengono trovati più candidati per un tipo di entità, viene restituito un solo valore.
  • Last updated on