Функция ai_extract

Область применения:отмечено Databricks SQL отмечено Databricks Runtime

Внимание

Эта функция доступна в общедоступной предварительной версии и соответствии HIPAA.

Во время предварительной версии:

Функция ai_extract() извлекает структурированные данные из текста и документов в соответствии с предоставленной схемой. Вы можете использовать простые имена полей для базового извлечения или определить сложные схемы с вложенными объектами, массивами, проверкой типов и описаниями полей для бизнес-документов, таких как счета, контракты и финансовые заявки.

Функция принимает текст или VARIANT выходные данные из других функций ИИ, например ai_parse_documentвключение составных рабочих процессов для комплексной обработки документов.

Визуальный пользовательский интерфейс для проверки и итерации результатов ai_extractсм. в разделе "Извлечение информации".

Требования

Лицензия Apache 2.0

Базовые модели, которые могут использоваться в настоящее время, лицензируются в соответствии с лицензией Apache 2.0, авторским правом © Apache Software Foundation. Клиенты отвечают за обеспечение соответствия применимым лицензиям модели.

Databricks рекомендует просматривать эти лицензии, чтобы обеспечить соответствие любым применимым условиям. Если модели появляются в будущем, которые лучше работают в соответствии с внутренними тестами Databricks, Databricks может изменить модель (и список применимых лицензий, предоставленных на этой странице).

Модель, работающая с этой функцией, становится доступной с помощью API модели обслуживания модели. Сведения о моделях, доступных в Databricks, и лицензиях и политиках, которые управляют использованием этих моделей, см. в применимых условиях модели.

Если модели появляются в будущем, которые лучше работают в соответствии с внутренними тестами Databricks, Databricks может изменить модели и обновить документацию.

  • Эта функция доступна только в некоторых регионах, см. сведения о доступности функций ИИ.
  • Эта функция недоступна в Azure Databricks классической версии SQL.
  • Проверьте страницу цен на Databricks SQL.
  • В Databricks Runtime 15.1 и более поздних версиях эта функция поддерживается в записных книжках Databricks, включая записные книжки, которые выполняются как задача в рабочем процессе Databricks.
  • Для повышения производительности рабочих нагрузок пакетного вывода требуется Среда выполнения Databricks Runtime 15.4 ML LTS.

Синтаксис

Databricks рекомендует использовать версию 2 этой функции, так как она поддерживает извлечение и описание вложенных полей.

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

Версия 2

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

Версия 1

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

Аргументы

  • content: ВыражениеVARIANT или STRING. Принимает любую из них:

    • Необработанный текст в виде STRING
    • Создается VARIANT другой функцией ИИ (например ai_parse_document)

  • schema: литерал STRING , определяющий схему JSON для извлечения. Схема может быть следующей:

    • Простая схема: массив JSON имен полей (предполагается, что это строки) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Расширенная схема: объект JSON с сведениями о типах, описаниями и вложенными структурами
      • Поддерживает string, , integernumberbooleanи enum типы. Выполняет проверку типа. Недопустимые значения приводят к ошибке. Не более 500 значений перечисления.
      • Поддерживает вложенные объекты с помощью "type": "object""properties"
      • Поддерживает массивы примитивов или объектов, использующихся "type": "array" с "items"
      • Необязательное "description" поле для каждого свойства для руководства по качеству извлечения

  • options: необязательный, MAP<STRING, STRING> содержащий параметры конфигурации:

    • version: параметр версии для поддержки миграции ("2.1", "2.0", ). "1.0" Значение по умолчанию основано на типах входных данных.
    • instructions: глобальное описание задачи и домена для повышения качества извлечения. Должно быть меньше 20 000 символов.
    • enableCitations: если trueвыходные данные для каждого поля в схеме извлечения содержат список нулевых или более ссылок, который указывает в документе извлеченные выходные данные.
    • enableConfidenceScores: если trueвыходные данные для каждого поля в схеме извлечения включают оценку достоверности от 0 до 1, указывая, как определенная модель относится к такому значению. Соответствующее пороговое значение достоверности зависит от конкретного варианта использования, и вы должны выбрать отрезок, соответствующий вашей терпимости к риску и ошибке.

Версия 2

  • content: ВыражениеVARIANT или STRING. Принимает любую из них:

    • Необработанный текст в виде STRING
    • Создается VARIANT другой функцией ИИ (например ai_parse_document)

  • schema: литерал STRING , определяющий схему JSON для извлечения. Схема может быть следующей:

    • Простая схема: массив JSON имен полей (предполагается, что это строки) 
      "[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
    • Расширенная схема: объект JSON с сведениями о типах, описаниями и вложенными структурами
      • Поддерживает string, , integernumberbooleanи enum типы. Выполняет проверку типа. Недопустимые значения приводят к ошибке. Не более 500 значений перечисления.
      • Поддерживает вложенные объекты с помощью "type": "object""properties"
      • Поддерживает массивы примитивов или объектов, использующихся "type": "array" с "items"
      • Необязательное "description" поле для каждого свойства для руководства по качеству извлечения

  • options: необязательный, MAP<STRING, STRING> содержащий параметры конфигурации:

    • version: параметр версии для поддержки миграции ("1.0" для поведения "2.0" версии 1 для поведения версии 2). Значение по умолчанию основано на типах входных данных, но возвращается обратно "1.0".
    • instructions: глобальное описание задачи и домена для повышения качества извлечения. Должно быть меньше 20 000 символов.

Версия 1

  • content STRING: выражение, содержащее необработанный текст.

  • labels: это литерал ARRAY<STRING>. Каждый элемент — это тип извлекаемой сущности.

  • options: необязательный, MAP<STRING, STRING> содержащий параметры конфигурации:

    • version: параметр версии для поддержки миграции ("1.0" для поведения "2.0" версии 1 для поведения версии 2). Значение по умолчанию основано на типах входных данных, но будет возвращаться к "1.0".

Возвраты

VARIANT Возвращает содержащийся:

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

Поле response содержит структурированные данные, извлеченные в соответствии со схемой:

  • Имена полей и типы соответствуют определению схемы
  • Структура схемы сохраняется в ответе: вложенные объекты и массивы сохраняют исходную форму. Каждое поле скалярного поля в схеме извлечения имеет выходной объект со следующими полями:
    • value: извлеченное значение, типизированное в соответствии со схемой. Значение , если поле не может быть извлечено.
    • citation_ids: присутствует только в том trueслучаеenableCitations. Массив идентификаторов, индексированных в metadata.citations.
    • confidence_score: присутствует только в том trueслучаеenableConfidenceScores. Плавающее значение от 0 до 1.
  • Проверка типов применяется для целых чисел, чисел, логических и перечислений
  • Если content равно NULL, то результат – NULL.

Поле metadata содержит метаданные ответа. Если enableCitations есть true, metadata поле содержит сведения о каждом идентификаторе ссылки в response поле, которое трассирует извлеченное значение обратно в его расположение в входных данных.

В зависимости от типа входных данных ссылки могут иметь один из двух типов:

  • Для входных данных необработанного текста (STRING) ссылка — это диапазон текста в исходном вводе. Каждый объект в metadata.citations содержит следующее:
    • id: целое число, соответствующее citation_ids записи в поле.
    • start: инклюзивное смещение символов на основе 0 в входную строку.
    • stop: эксклюзивное смещение символов на основе 0 в входную строку.
  • Для PDF-документов и изображений (при использовании ai_extract ниже ai_parse_document) ссылка является ограничивающим полем в исходном входном коде. Каждый объект в metadata.citations нем:
    • id: целое число, соответствующее citation_ids записи в поле.
    • bbox: массив объектов, идентичный фигуре элемента.bbox в ai_parse_document выходных {coord, page_id} данных. coord — координаты пикселей на изображении страницы, как [x0, y0, x1, y1]; page_id и индекс страницы на основе 0.

Версия 2

VARIANT Возвращает содержащийся:

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

Поле response содержит структурированные данные, извлеченные в соответствии со схемой:

  • Имена полей и типы соответствуют определению схемы
  • Вложенные объекты и массивы сохраняются в структуре
  • Поля могут быть null не найдены.
  • Проверка типов применяется для integerтипов , numberbooleanи enum типов

Если content равно NULL, то результат – NULL.

Версия 1

Возвращает место, где каждое STRUCT поле соответствует типу сущности, указанному в labels. Каждое поле содержит строку, представляющую извлеченную сущность. Если функция находит несколько кандидатов для любого типа сущности, она возвращает только одну.

Примеры

Простая схема — только имена полей

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

Расширенная схема — с типами и описаниями

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

Вложенные объекты и массивы

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

Возможность создания с помощью 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;

Использование перечислений

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

Ссылки (входные данные STRING, ссылки 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
 }

Ссылки (VARIANT из ai_parse_document, ссылки 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
}

Оценки достоверности


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

Пример записной книжки

Следующая записная книжка предоставляет визуальный интерфейс отладки для анализа выходных ai_extract данных ссылки функции. В нем показано, как отображать метаданные ссылки в виде фрагментов фрагментов подстроки (строковые входные данные) или ограничивающих прямоугольных наложений (входных данных VARIANT), а также присоединять ai_extract ссылки обратно к ai_parse_document элементам в SQL, чтобы можно было пометить извлечение с низкой достоверностью для ручной проверки.

Записная книжка для отрисовки ссылок

Получите ноутбук

Версия 2

Простая схема — только имена полей

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

Расширенная схема — с типами и описаниями

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

Вложенные объекты и массивы

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

Возможность создания с помощью 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;

Использование перечислений

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

Версия 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"}

Ограничения

  • Эта функция недоступна в Azure Databricks классической версии SQL.
  • Эту функцию нельзя использовать с представлениями.
  • Схема поддерживает не более 128 полей.
  • Имена полей могут содержать до 150 символов.
  • Схемы поддерживают до семи уровней вложения для вложенных полей.
  • Поля перечисления поддерживают не более 500 значений.
  • Проверка типов применяется для integerтипов , numberbooleanи enum типов. Если значение не соответствует указанному типу, функция возвращает ошибку.
  • Максимальный общий размер контекста составляет 128 000 маркеров.

Версия 2

  • Эта функция недоступна в Azure Databricks классической версии SQL.
  • Эту функцию нельзя использовать с представлениями.
  • Схема поддерживает не более 128 полей.
  • Имена полей могут содержать до 150 символов.
  • Схемы поддерживают до семи уровней вложения для вложенных полей.
  • Поля перечисления поддерживают не более 500 значений.
  • Проверка типов применяется для integerтипов , numberbooleanи enum типов. Если значение не соответствует указанному типу, функция возвращает ошибку.
  • Максимальный общий размер контекста составляет 128 000 маркеров.

Версия 1

  • Эта функция недоступна в Azure Databricks классической версии SQL.
  • Эту функцию нельзя использовать с представлениями.
  • Если в содержимом найдено несколько кандидатов для типа сущности, возвращается только одно значение.
  • Last updated on