ai_extractFunción

Se aplica a:marcado sí Databricks SQL marcado sí Databricks Runtime

Importante

Esta funcionalidad está en versión preliminar pública y compatible con HIPAA.

Durante la versión preliminar:

La ai_extract() función extrae datos estructurados de texto y documentos según un esquema que proporcione. Puede usar nombres de campo simples para la extracción básica o definir esquemas complejos con objetos anidados, matrices, validación de tipos y descripciones de campos para documentos empresariales como facturas, contratos y presentaciones financieras.

La función acepta texto o VARIANT salida de otras funciones de IA como ai_parse_document, lo que permite flujos de trabajo que se pueden componer para el procesamiento de documentos de un extremo a otro.

Para que una interfaz de usuario visual valide e itera en los resultados de , vea ai_extract información.

Requisitos

Licencia de Apache 2.0

Los modelos subyacentes que se pueden usar en este momento tienen licencia bajo la licencia de Apache 2.0, Copyright © The Apache Software Foundation. Los clientes son responsables de garantizar el cumplimiento de las licencias de modelo aplicables.

Databricks recomienda revisar estas licencias para garantizar el cumplimiento de los términos aplicables. Si los modelos surgen en el futuro que funcionan mejor según las pruebas comparativas internas de Databricks, Databricks podría cambiar el modelo (y la lista de licencias aplicables proporcionadas en esta página).

El modelo que alimenta esta función está disponible mediante las API de modelo de Model Serving Foundation. Consulte Términos de modelo aplicables para obtener información sobre qué modelos están disponibles en Databricks y las licencias y directivas que rigen el uso de esos modelos.

Si los modelos surgen en el futuro que funcionan mejor según las pruebas comparativas internas de Databricks, Databricks puede cambiar los modelos y actualizar la documentación.

  • Esta función solo está disponible en algunas regiones, consulte Disponibilidad de funciones de IA.
  • Esta función no está disponible en Azure Databricks SQL Clásico.
  • Consulte la página de precios de Databricks SQL.
  • En Databricks Runtime 15.1 y versiones posteriores, esta función se admite en cuadernos de Databricks, incluidos los cuadernos que se ejecutan como una tarea en un flujo de trabajo de Databricks.
  • Las cargas de trabajo de inferencia por lotes requieren Databricks Runtime 15.4 ML LTS para mejorar el rendimiento.

Sintaxis

Databricks recomienda usar la versión 2 de esta función porque admite la extracción y descripciones de campos anidados.

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

Versión 2

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

Versión 1

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

Argumentos

  • content: una expresión VARIANT o STRING. Acepta cualquiera de:

    • Texto sin formato como STRING
    • Objeto VARIANT generado por otra función de IA (por ejemplo ai_parse_document, )

  • schema: literal STRING que define el esquema JSON para la extracción. El esquema puede ser:

    • Esquema simple: matriz JSON de nombres de campo (se supone que son cadenas) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Esquema avanzado: un objeto JSON con información de tipo, descripciones y estructuras anidadas
      • Admite stringlos tipos , integer, number, booleany enum . Realiza la validación de tipos. Los valores que no son válidos producen un error. Máximo de 500 valores de enumeración.
      • Admite objetos anidados mediante "type": "object" con "properties"
      • Admite matrices de primitivos o objetos mediante "type": "array" con "items"
      • Campo opcional "description" para cada propiedad para guiar la calidad de extracción

  • options: una opción que MAP<STRING, STRING> contiene las opciones de configuración:

    • version: cambio de versión para admitir la migración ("2.1", "2.0", "1.0"). El valor predeterminado se basa en los tipos de entrada.
    • instructions: descripción global de la tarea y el dominio para mejorar la calidad de la extracción. Debe tener menos de 20 000 caracteres.
    • enableCitations: cuando true, la salida de cada campo del esquema de extracción incluye una lista de cero o más citas, que indica en el documento la salida extraída.
    • enableConfidenceScores: cuando true, la salida de cada campo del esquema de extracción incluye una puntuación de confianza entre 0 y 1, lo que indica cómo está el modelo sobre ese valor. El umbral de confianza adecuado depende de su caso de uso específico y debe elegir un límite que se alinee con la tolerancia a riesgos y errores.

Versión 2

  • content: una expresión VARIANT o STRING. Acepta cualquiera de:

    • Texto sin formato como STRING
    • Objeto VARIANT generado por otra función de IA (por ejemplo ai_parse_document, )

  • schema: literal STRING que define el esquema JSON para la extracción. El esquema puede ser:

    • Esquema simple: matriz JSON de nombres de campo (se supone que son cadenas) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Esquema avanzado: un objeto JSON con información de tipo, descripciones y estructuras anidadas
      • Admite stringlos tipos , integer, number, booleany enum . Realiza la validación de tipos. Los valores que no son válidos producen un error. Máximo de 500 valores de enumeración.
      • Admite objetos anidados mediante "type": "object" con "properties"
      • Admite matrices de primitivos o objetos mediante "type": "array" con "items"
      • Campo opcional "description" para cada propiedad para guiar la calidad de extracción

  • options: una opción que MAP<STRING, STRING> contiene las opciones de configuración:

    • version: cambio de versión para admitir la migración ("1.0" para el comportamiento de la versión 1, "2.0" para el comportamiento de la versión 2). El valor predeterminado se basa en los tipos de entrada, pero vuelve a "1.0".
    • instructions: descripción global de la tarea y el dominio para mejorar la calidad de la extracción. Debe tener menos de 20 000 caracteres.

Versión 1

  • content STRING: expresión que contiene el texto sin formato.

  • labels: Un ARRAY<STRING> literal. Cada elemento es un tipo de entidad que se va a extraer.

  • options: una opción que MAP<STRING, STRING> contiene las opciones de configuración:

    • version: cambio de versión para admitir la migración ("1.0" para el comportamiento de la versión 1, "2.0" para el comportamiento de la versión 2). El valor predeterminado se basa en los tipos de entrada, pero se revertirá a "1.0".

Devoluciones

Devuelve un VARIANT objeto que contiene:

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

El response campo contiene los datos estructurados extraídos según el esquema:

  • Los nombres de campo y los tipos coinciden con la definición de esquema
  • La estructura del esquema se conserva en la respuesta: los objetos anidados y las matrices mantienen su forma original. Cada campo "escalar" del esquema de extracción tiene un objeto de salida con los campos siguientes:
    • value: valor extraído, escrito según el esquema. Null si no se puede extraer el campo.
    • citation_ids: solo está presente cuando enableCitations es true. Matriz de identificadores indexados en metadata.citations.
    • confidence_score: solo está presente cuando enableConfidenceScores es true. Un float entre 0 y 1.
  • Se aplica la validación de tipos para tipos enteros, números, booleanos y enumeración.
  • Si content es NULL, el resultado es NULL.

El metadata campo contiene los metadatos sobre la respuesta. Cuando enableCitations es true, el metadata campo contiene detalles sobre cada identificador de cita en el response campo que realiza el seguimiento del valor extraído de nuevo a su ubicación en la entrada.

Dependiendo del tipo de entrada, las citas pueden ser de uno de dos tipos:

  • Para las entradas de texto sin formato (STRING), una cita es un intervalo de texto en la entrada original. Cada objeto de metadata.citations contiene:
    • id: entero que coincide con una entrada de citation_ids en un campo.
    • start: desplazamiento de caracteres inclusivo basado en 0 en la cadena de entrada.
    • stop: desplazamiento exclusivo de caracteres basado en 0 en la cadena de entrada.
  • En el caso de los documentos e imágenes PDF (cuando se usa ai_extract el nivel inferior de ai_parse_document), una cita es un rectángulo de selección en la entrada original. Cada objeto de metadata.citations contiene:
    • id: entero que coincide con una citation_ids entrada en un campo.
    • bbox: matriz de {coord, page_id} objetos, idéntica en forma a element.bbox en ai_parse_document la salida. coord es coordenadas de píxeles en la imagen de página tal como [x0, y0, x1, y1]; page_id es un índice de página basado en 0.

Versión 2

Devuelve un VARIANT objeto que contiene:

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

El response campo contiene los datos estructurados extraídos según el esquema:

  • Los nombres de campo y los tipos coinciden con la definición de esquema
  • Los objetos y matrices anidados se conservan en la estructura
  • Los campos pueden ser si no se null encuentran
  • La validación de tipos se aplica para integerlos tipos , number, booleany enum

Si content es NULL, el resultado es NULL.

Versión 1

Devuelve un STRUCT objeto donde cada campo corresponde a un tipo de entidad especificado en labels. Cada campo contiene una cadena que representa la entidad extraída. Si la función encuentra más de un candidato para cualquier tipo de entidad, devuelve solo uno.

Ejemplos

Esquema simple: solo nombres 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 avanzado: con tipos y descripciones

> 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 anidados y matrices

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

Capacidad de redacción 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 de enumeraciones

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

Citas (entrada STRING, citas 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
 }

Citas (VARIANT de ai_parse_document, citas 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
}

Puntuaciones de confianza


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

Ejemplo de cuaderno

En el cuaderno siguiente se proporciona una interfaz de depuración visual para analizar las salidas de cita de la ai_extract función. Muestra cómo representar metadatos de cita como fragmentos de código de subcadena (entrada STRING) o superposiciones de rectángulo delimitador (entrada VARIANT) y combinar ai_extract citas a ai_parse_document elementos de SQL para poder marcar extracciones de confianza baja para la revisión manual.

Cuaderno de representación de citas

Obtener el cuaderno

Versión 2

Esquema simple: solo nombres 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 avanzado: con tipos y descripciones

> 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 anidados y matrices

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

Capacidad de redacción 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 de enumeraciones

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

Versión 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"}

Limitaciones

  • Esta función no está disponible en Azure Databricks SQL Clásico.
  • Esta función no se puede usar con vistas.
  • El esquema admite un máximo de 128 campos.
  • Los nombres de campo pueden contener hasta 150 caracteres.
  • Los esquemas admiten hasta siete niveles de anidamiento para campos anidados.
  • Los campos de enumeración admiten un máximo de 500 valores.
  • La validación de tipos se aplica para integerlos tipos , number, booleany enum . Si un valor no coincide con el tipo especificado, la función devuelve un error.
  • El tamaño de contexto total máximo es de 128 000 tokens.

Versión 2

  • Esta función no está disponible en Azure Databricks SQL Clásico.
  • Esta función no se puede usar con vistas.
  • El esquema admite un máximo de 128 campos.
  • Los nombres de campo pueden contener hasta 150 caracteres.
  • Los esquemas admiten hasta siete niveles de anidamiento para campos anidados.
  • Los campos de enumeración admiten un máximo de 500 valores.
  • La validación de tipos se aplica para integerlos tipos , number, booleany enum . Si un valor no coincide con el tipo especificado, la función devuelve un error.
  • El tamaño de contexto total máximo es de 128 000 tokens.

Versión 1

  • Esta función no está disponible en Azure Databricks SQL Clásico.
  • Esta función no se puede usar con Views.
  • Si se encuentra más de un candidato para un tipo de entidad en el contenido, solo se devuelve un valor.
  • Last updated on