Funzione ai_extract

Si applica a: Databricks SQL Databricks Runtime

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

Il modello che alimenta questa funzione viene reso disponibile tramite le API Model Serving Foundation Model. Vedere Condizioni per sviluppatori di modelli 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.

Versione 2 (scelta consigliata)

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

Versione 2 (scelta consigliata)

• 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 del tipo, i valori non validi genereranno 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 eseguirà 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

Versione 2 (scelta consigliata)

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

Versione 2 (scelta consigliata)

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

Versione 2 (scelta consigliata)

• Questa funzione non è disponibile in Azure Databricks SQL classico.
• Questa funzione non può essere utilizzata con Views.
• Lo schema supporta un massimo di 128 campi.
• I nomi dei campi possono contenere fino a 150 caratteri.
• Gli schemi supportano fino a 7 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.

Funzioni correlate

• ai_classify Funzione
• ai_parse_document Funzione