ai_extract Função

Aplica-se a:marcado como sim Databricks SQL marcado como sim Databricks Runtime

Importante

Esta funcionalidade está em Pré-visualização Pública e em conformidade com a HIPAA.

Durante a antevisão:

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

Licença Apache 2.0

Os modelos subjacentes que poderão ser usados atualmente estão licenciados sob a Licença Apache 2.0, Direitos de Autor © da Apache Software Foundation. Os clientes são responsáveis por garantir a conformidade com as licenças de modelo aplicáveis.

A Databricks recomenda a revisão dessas licenças para garantir a conformidade com quaisquer termos aplicáveis. Se surgirem modelos no futuro com melhor desempenho de acordo com os benchmarks internos da Databricks, a Databricks poderá alterar o modelo (e a lista de licenças aplicáveis fornecida nesta página).

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.

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

  • 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. Realiza validação de tipo. Valores que não são válidos resultam 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 ("2.1", "2.0", "1.0"). O padrão baseia-se nos 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 quão certo o modelo é sobre esse valor. O limiar de confiança adequado depende do seu caso de uso específico, e deve escolher um limite que esteja alinhado com a sua tolerância ao risco e ao erro.

Versão 2

  • 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. Realiza validação de tipo. Valores que não são válidos resultam 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 volta a "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 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

Devolve 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 dos campos correspondem à definição do esquema
  • A estrutura do esquema é preservada na resposta: os objetos aninhados e os arrays mantêm a 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, tipado de acordo com o esquema. Null se o campo não puder ser extraído.
    • citation_ids: Presente apenas quando enableCitations é true. Um array de IDs indexados em metadata.citations.
    • confidence_score: Presente apenas quando enableConfidenceScores é true. Um flutuador entre 0 e 1.
  • A validação de tipos é aplicada para tipos inteiros, numéricos, booleanos e enum
  • Se content estiver NULL, o resultado é NULL.

O metadata campo contém os metadados sobre a resposta. Quando enableCitations é , o metadata campo contém detalhes sobre cada ID de citação no response campo que traçam o valor extraído até à sua truelocalização na entrada.

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

  • Para entradas de texto bruto (STRING), uma citação é um espaço de texto na entrada original. Cada objeto em metadata.citations contém:
    • id: Inteiro que corresponde a uma citation_ids entrada num campo.
    • start: Inclui o deslocamento de caracteres baseado em 0 na cadeia de entrada.
    • stop: Deslocamento exclusivo de caracteres baseado em 0 na cadeia de entrada.
  • Para documentos e imagens PDF (quando usado ai_extract a jusante de ai_parse_document), uma citação é uma caixa delimitadora na entrada original. Cada objeto em metadata.citations contém:
    • id: Inteiro que corresponde a uma citation_ids entrada num corpo.
    • bbox: Array de {coord, page_id} objetos, idênticos em forma a element.bbox na ai_parse_document saída. coord são coordenadas de píxeis na imagem da página, assim como [x0, y0, x1, y1]; page_id um índice de página baseado em 0.

Versão 2

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

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

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

Utilização 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"}
    }',
    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 (VARIANTE de ai_parse_document, citações 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 caderno

O caderno seguinte fornece uma interface visual de depuração para analisar os resultados das citações da ai_extract função. Demonstra como renderizar metadados de citação como excertos de substring (entrada STRING) ou sobreposições de caixa delimitadora (entrada VARIANTE), e juntar ai_extract citações de volta a ai_parse_document elementos em SQL para que possas sinalizar extrações de baixa confiança para revisão manual.

Caderno de renderização de citações

Obter caderno

Versão 2

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;

Utilização 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

  • Esta função não está disponível no Azure Databricks SQL Classic.
  • Esta função não pode ser usada com vistas.
  • O esquema suporta um máximo de 128 campos.
  • Os nomes dos campos podem conter até 150 caracteres.
  • Os esquemas suportam até sete 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 2

  • Esta função não está disponível no Azure Databricks SQL Classic.
  • Esta função não pode ser usada com vistas.
  • O esquema suporta um máximo de 128 campos.
  • Os nomes dos campos podem conter até 150 caracteres.
  • Os esquemas suportam até sete 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.
  • Last updated on