ai_extract Função

Aplica-se a: Databricks SQL Databricks Runtime

A ai_extract() função extrai dados estruturados de texto e documentos de acordo com um esquema que fornece. Pode usar nomes simples de campos para extração básica, ou definir esquemas complexos com objetos aninhados, arrays, validação de tipos e descrições de campos para documentos empresariais como faturas, contratos e submissões financeiras.

A função aceita texto ou VARIANT saída de outras funções de IA, como ai_parse_document, permitindo fluxos de trabalho componíveis para processamento de documentos de ponta a ponta.

Para uma interface visual que valide e itere sobre os resultados de ai_extract, veja Extração de Informação.

Requisitos

O modelo que alimenta esta função está disponível através das APIs Model Serving Foundation Model Model. Consulte Termos de modelo Aplicável para informações sobre quais modelos estão disponíveis nos Databricks e as licenças e políticas que regem a utilização desses modelos.

Se surgirem no futuro modelos com melhor desempenho de acordo com os benchmarks internos da Databricks, a Databricks poderá alterar os modelos e atualizar a documentação.

• Esta função está disponível apenas em algumas regiões, veja disponibilidade de funções de IA.
• Esta função não está disponível no Azure Databricks SQL Classic.
• Verifique a página de preços do Databricks SQL.
• No Databricks Runtime 15.1 e superior, essa função é suportada em blocos de anotações Databricks, incluindo blocos de anotações que são executados como uma tarefa em um fluxo de trabalho Databricks.
• As cargas de trabalho de inferência em lote exigem o Databricks Runtime 15.4 ML LTS para melhorar o desempenho.

Sintaxe

O Databricks recomenda a utilização da versão 2 desta função porque suporta extração e descrições de campos aninhados.

Versão 2 (recomendada)

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

Versão 1

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

Argumentos

Versão 2 (recomendada)

• content: Uma expressão VARIANT ou STRING. Aceita um:

  • Texto bruto como um STRING
  • A produzido VARIANT por outra função de IA (como ai_parse_document)

• schema: Um literal que STRING define o esquema JSON para extração. O esquema pode ser:

  • Esquema simples: Um array JSON de nomes de campos (assumidos como strings)

    ["vendor_name", "invoice_id", "total_amount"]
    

  • Esquema avançado: Um objeto JSON com informação de tipo, descrições e estruturas aninhadas
    • Suporta string, integer, number, boolean, e enum tipos. Realizar a validação do tipo, valores inválidos resultarão num erro. Máximo de 500 valores de enum.
    • Suporta objetos aninhados usando "type": "object" com "properties"
    • Suporta arrays de primitivas ou objetos usando "type": "array" com "items"
    • Campo opcional "description" para cada propriedade para orientar a qualidade da extração

• options: Um opcional MAP<STRING, STRING> contendo opções de configuração:

  • version: Mudança de versão para suportar migração ("1.0" para comportamento v1, "2.0" para comportamento v2). O padrão baseia-se nos tipos de entrada, mas voltará a "1.0"ser .
  • instructions: Descrição global da tarefa e do domínio para melhorar a qualidade da extração. Deve ter menos de 20.000 caracteres.

Versão 1

• content: Uma expressão contendo STRING o texto bruto.

• labels: Um ARRAY<STRING> literal. Cada elemento é um tipo de entidade a ser extraída.

• options: Um opcional MAP<STRING, STRING> contendo opções de configuração:

  • version: Mudança de versão para suportar migração ("1.0" para comportamento v1, "2.0" para comportamento v2). O padrão baseia-se nos tipos de entrada, mas voltará a "1.0"ser .

Devoluções

Versão 2 (recomendada)

Devolve um VARIANT que contém:

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

O response campo contém os dados estruturados extraídos de acordo com o esquema:

• Os nomes e tipos dos campos correspondem à definição do esquema
• Objetos aninhados e arrays são preservados na estrutura
• Os campos podem ser null se não forem encontrados
• A validação de tipos é imposta para integer, number, boolean, e enum tipos

Se content estiver NULL, o resultado é NULL.

Versão 1

Devolve a STRUCT onde cada campo corresponde a um tipo de entidade especificado em labels. Cada campo contém uma cadeia de caracteres que representa a entidade extraída. Se a função encontrar mais do que um candidato para qualquer tipo de entidade, devolve apenas um.

Exemplos

Versão 2 (recomendada)

Esquema simples - apenas nomes de campos

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

Esquema avançado - com tipos e descrições:

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

Objetos aninhados e arrays:

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

Composabilidade com 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 de enums:

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

Versão 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"}

Limitações

Versão 2 (recomendada)

• Esta função não está disponível no Azure Databricks SQL Classic.
• Esta função não pode ser usada com as Vistas.
• O esquema suporta um máximo de 128 campos.
• Os nomes dos campos podem conter até 150 caracteres.
• Os esquemas suportam até 7 níveis de aninhamento para campos aninhados.
• Os campos enum suportam um máximo de 500 valores.
• A validação de tipos é aplicada para integer, number, boolean, e enum tipos. Se um valor não corresponder ao tipo especificado, a função devolve um erro.
• O tamanho máximo total de contexto é de 128.000 tokens.

Versão 1

• Esta função não está disponível no Azure Databricks SQL Classic.
• Esta função não pode ser usada com as Vistas.
• Se forem encontrados mais do que um candidato para um tipo de entidade no conteúdo, apenas um valor é devolvido.

Funções relacionadas

• ai_parse_document Função
• ai_classify Função
• ai_prep_search Função