Função ai_extract

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 você fornece. Você pode usar nomes de campo simples para extração básica ou definir esquemas complexos com objetos aninhados, matrizes, validação de tipo e descrições de campo para documentos comerciais, como faturas, contratos e arquivos financeiros.

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

Para obter uma interface do usuário visual para validar e iterar nos resultados, consulte ai_extract de Informações.

Requisitos

O modelo que alimenta essa função é disponibilizado usando AS APIs de modelo do Model Serving Foundation. Consulte os termos de modelo aplicáveis para obter informações sobre quais modelos estão disponíveis no Databricks e as licenças e políticas que regem o uso desses modelos.

Se surgirem modelos no futuro com melhor desempenho de acordo com os parâmetros de comparação internos do Databricks, o Databricks poderá alterar os modelos e atualizar a documentação.

• Essa função só está disponível em algumas regiões, consulte a disponibilidade da função de IA.
• Essa função não está disponível no Azure Databricks SQL Classic.
• Confira a página de preços do SQL do Databricks.
• No Databricks Runtime 15.1 e superior, essa função tem suporte nos notebooks do Databricks, incluindo os notebooks que são executados como uma tarefa em um fluxo de trabalho do Databricks.
• Os trabalhos de inferência em lote exigem o Databricks Runtime 15.4 ML LTS para melhor desempenho.

Sintaxe

O Databricks recomenda o uso da versão 2 dessa função porque dá suporte à extração e descrições de campo aninhados.

Versão 2.1 (recomendado)

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

Versão 2

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.1 (recomendado)

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

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

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

  • Esquema simples: uma matriz JSON de nomes de campo (presumidamente cadeias de caracteres)

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

  • Esquema avançado: um objeto JSON com informações de tipo, descrições e estruturas aninhadas
    • stringDá suporte, integer, , numbere booleanenum tipos. Executa a validação de tipo. Valores que não são válidos resultam em um erro. Máximo de 500 valores de enumeração.
    • Dá suporte ao uso "type": "object" de objetos aninhados com "properties"
    • Dá suporte a matrizes de primitivos 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> que contém opções de configuração:

  • version: opção de versão para dar suporte à migração ("2.1", "2.0", "1.0"). O padrão é baseado em tipos de entrada.
  • instructions: descrição global da tarefa e do domínio para melhorar a qualidade da extração. Deve ter menos de 20.000 caracteres.
  • enableCitations: Quando true, a saída para cada campo no esquema de extração inclui uma lista de zero ou mais citações, que indica no documento a saída extraída.
  • enableConfidenceScores: quando true, a saída para cada campo no esquema de extração inclui uma pontuação de confiança entre 0 e 1, indicando a certeza de que o modelo é sobre esse valor. O limite de confiança apropriado depende de seu caso de uso específico e você deve escolher um corte que se alinhe à sua tolerância a riscos e erros.

Versão 2

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

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

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

  • Esquema simples: uma matriz JSON de nomes de campo (presumidamente cadeias de caracteres)

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

  • Esquema avançado: um objeto JSON com informações de tipo, descrições e estruturas aninhadas
    • stringDá suporte, integer, , numbere booleanenum tipos. Executa a validação de tipo. Valores que não são válidos resultam em um erro. Máximo de 500 valores de enumeração.
    • Dá suporte ao uso "type": "object" de objetos aninhados com "properties"
    • Dá suporte a matrizes de primitivos 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> que contém opções de configuração:

  • version: opção de versão para dar suporte à migração ("1.0" para comportamento v1, "2.0" para comportamento v2). O padrão é baseado em tipos de entrada, mas volta para "1.0".
  • 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 STRING expressão que contém o texto bruto.

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

• options: um opcional MAP<STRING, STRING> que contém opções de configuração:

  • version: opção de versão para dar suporte à migração ("1.0" para comportamento v1, "2.0" para comportamento v2). O padrão é baseado em tipos de entrada, mas retornará para "1.0".

Retornos

Versão 2.1 (recomendado)

Retorna um VARIANT que contém:

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

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

• Os nomes e tipos de campo correspondem à definição de esquema
• A estrutura do esquema é preservada na resposta: objetos aninhados e matrizes mantêm sua forma original. Cada campo "escalar" no esquema de extração tem um objeto de saída com os seguintes campos:
  • value: o valor extraído, digitado de acordo com o esquema. Null se o campo não puder ser extraído.
  • citation_ids: presente apenas quando enableCitations for true. Uma matriz de IDs indexadas em metadata.citations.
  • confidence_score: presente apenas quando enableConfidenceScores for true. Um número em ponto flutuante entre 0 e 1.
• A validação de tipo é imposta para tipos inteiros, números, boolianos e enumerados
• Se content é NULL, o resultado é NULL.

O metadata campo contém os metadados sobre a resposta. Quando enableCitations é true, o metadata campo contém detalhes sobre cada ID de citação no response campo que rastreia o valor extraído de volta ao seu local na entrada.

Dependendo do tipo de entrada, as citações podem ser de um dos dois tipos:

• Para entradas de texto bruto (STRING), uma citação é um intervalo de texto na entrada original. Cada objeto em metadata.citations contém:
  • id: inteiro que corresponde a uma entrada de citation_ids em um campo.
  • start: deslocamento de caractere baseado em 0 inclusivo para a cadeia de caracteres de entrada.
  • stop: deslocamento exclusivo de caractere baseado em 0 para a cadeia de caracteres de entrada.
• Para documentos e imagens PDF (ao usar ai_extract downstream de ai_parse_document), uma citação é uma caixa delimitadora na entrada original. Cada objeto contém metadata.citations :
  • id: inteiro que corresponde a uma citation_ids entrada em um campo.
  • bbox: matriz de {coord, page_id} objetos, idêntica em forma a element.bbox na ai_parse_document saída. coord é coordenadas de pixel na imagem da página, assim como [x0, y0, x1, y1]; page_id um índice de página baseado em 0.

Versão 2

Retorna 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 de campo correspondem à definição de esquema
• Objetos aninhados e matrizes são preservados na estrutura
• Os campos poderão ser null encontrados se não forem encontrados
• A validação de tipo é imposta parainteger, , numberbooleane enum tipos

Se content é NULL, o resultado é NULL.

Versão 1

Retorna um STRUCT local em que 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 de um candidato para qualquer tipo de entidade, ela retornará apenas um.

Exemplos

Versão 2.1 (recomendado)

Esquema simples – somente nomes de 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
 }

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

Objetos e matrizes aninhados

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

Composição 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('version', '2.1', 'instructions', 'These are vendor invoices.')
    ) AS invoice_data
  FROM parsed_docs;

Usando enumerações

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

Citações (entrada STRING, citações 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
 }

Citações (VARIANT de ai_parse_document, citações de 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
}

Pontuações de confiança

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

Exemplo de notebook

O notebook a seguir fornece uma interface de depuração visual para analisar as saídas de citação da ai_extract função. Ele demonstra como renderizar metadados de citação como snippets de subcadeia de caracteres (entrada STRING) ou sobreposições de caixa delimitadora (entrada VARIANT) e unir ai_extract citações de volta aos elementos no SQL para ai_parse_document que você possa sinalizar extrações de baixa confiança para revisão manual.

Bloco de anotações de renderização de citação

Obter laptop

Versão 2

Esquema simples – somente nomes de 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
 }

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 e matrizes aninhados

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

Composição 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;

Usando enumerações

> 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.1 (recomendado)

• Essa função não está disponível no Azure Databricks SQL Classic.
• Essa função não pode ser usada com exibições.
• O esquema dá suporte a um máximo de 128 campos.
• Os nomes de campo podem conter até 150 caracteres.
• Os esquemas dão suporte a até sete níveis de aninhamento para campos aninhados.
• Os campos de enumeração dão suporte a um máximo de 500 valores.
• A validação de tipo é imposta para integer, numbere booleanenum tipos. Se um valor não corresponder ao tipo especificado, a função retornará um erro.
• O tamanho máximo total do contexto é de 128.000 tokens.

Versão 2

• Essa função não está disponível no Azure Databricks SQL Classic.
• Essa função não pode ser usada com exibições.
• O esquema dá suporte a um máximo de 128 campos.
• Os nomes de campo podem conter até 150 caracteres.
• Os esquemas dão suporte a até sete níveis de aninhamento para campos aninhados.
• Os campos de enumeração dão suporte a um máximo de 500 valores.
• A validação de tipo é imposta para integer, numbere booleanenum tipos. Se um valor não corresponder ao tipo especificado, a função retornará um erro.
• O tamanho máximo total do contexto é de 128.000 tokens.

Versão 1

• Essa função não está disponível no Azure Databricks SQL Classic.
• Essa função não pode ser usada com Exibições.
• Se mais de um candidato para um tipo de entidade for encontrado no conteúdo, apenas um valor será retornado.

Funções relacionadas

• ai_parse_document função
• ai_classify função
• ai_prep_search função