Использование доверенных ресурсов в пространствах AI/BI Genie

В этой статье определяются доверенные ресурсы и объясняется, как использовать их для предоставления проверенных ответов в пространстве Genie.

Что такое доверенные ресурсы?

Доверенные ресурсы — это определяемые пользователем функции таблиц, которые можно написать, чтобы ответить на определенные вопросы, которые вы ожидаете от пользователей. Их можно использовать для определения проверенных параметризованных функций SQL, которые действуют в качестве рецептов для ответов на распространенные вопросы. Когда пользователь отправляет вопрос, вызывающий доверенный ресурс, он указан в ответе, добавив дополнительный уровень гарантии к точности результатов.

Зачем создавать доверенные ресурсы?

При использовании любого средства ИИ пользователи должны оценить точность созданных ответов. Как правило, они делают это, учитывая, имеет ли ответ смысл и эффективно решает их вопрос. При использовании Genie ответ предоставляется в виде таблицы результатов. Пользователи могут просматривать созданный sql, который создает результирующий набор, но не технические пользователи могут иметь фон для интерпретации инструкции SQL или оценки правильности ответа. Доверенные ресурсы помогают снизить вероятность того, что эти пользователи сталкиваются с ответами, которые вводят в заблуждение, неправильно или трудно интерпретировать.

Когда пользователь получает ответ, использующий доверенный ресурс, он может быть уверен, что эксперт по домену рассмотрел инструкцию SQL, заполняющую результаты.

Какова разница между доверенными ресурсами и примерами запросов SQL?

Доверенные ресурсы предоставляют проверенные ответы на вопросы, которые вы ожидаете, что пользователи пространства Genie будут задавать. Когда доверенный ресурс может ответить на вопрос пользователя, определяемая пользователем функция таблицы, хранящейся в качестве доверенного ресурса, выполняется и возвращает указанный результирующий набор. Таким образом, вы знаете, что ваши пользователи получают правильные сведения, которые отвечают на их вопросы, и бизнес-пользователи предоставляют дополнительную гарантию того, что они получают проверенный ответ. Genie не учитывает содержимое SQL доверенного ресурса при ответе на вопросы.

Примеры запросов SQL предлагают другой вариант настройки пространства Genie. Они предоставляют контекст для обучения Genie обработке других вопросов и написанию инструкций SQL, которые он создает. Точные примеры, приведенные в разделе "Примеры запросов SQL" набора инструкций, не обязательно возвращаются, когда бизнес-пользователь задает связанный вопрос.

Определение доверенного ресурса

Определение доверенного ресурса начинается с определения вероятного вопроса. Например, предположим, что вы работаете с набором данных конвейера продаж, и распространенный вопрос о том, что менеджер по продажам может задать: "Каковы открытые возможности продаж в моем конвейере?"

Ниже описаны шаги по созданию доверенного ресурса, который отвечает на этот вопрос:

1. Определите и проверьте SQL-запрос, который отвечает на этот вопрос.

   Этот запрос присоединяет две таблицы и возвращает набор открытых возможностей, перечисленных в категории прогноза "Конвейер". На этом шаге цель — написать базовый запрос, возвращающий ожидаемые результаты.

   SELECT
     o.id AS `OppId`,
     a.region__c AS `Region`,
     o.name AS `Opportunity Name`,
     o.forecastcategory AS `Forecast Category`,
     o.stagename,
     o.closedate AS `Close Date`,
     o.amount AS `Opp Amount`
   FROM
   users.user_name.opportunity o
   JOIN catalog.schema.accounts a ON o.accountid = a.id
   WHERE
   o.forecastcategory = 'Pipeline'
   AND o.stagename NOT LIKE '%closed%';
   

2. Определите функцию каталога Unity.

   Функция каталога Unity должна параметризовать запрос и создать результаты, соответствующие определенным условиям, о которых должен спрашивать пользователь. Предположим, менеджер по продажам хочет сузить результирующий набор, фокусируясь на определенном регионе или группе регионов.

   В следующем примере определяется функция каталога Unity, которая принимает список регионов в качестве параметра и возвращает таблицу. Возврат функции почти идентичен инструкции SQL на предыдущем шаге, за исключением WHERE того, что предложение было изменено, чтобы отфильтровать результаты по регионам, если был предоставлен регион. Комментарии, предоставленные в определениях функций, критически важны для указания пространства Genie о том, когда и как вызвать эту функцию.

   • Примечания параметров. Функция open_opps_in_region ожидает массив строк в качестве параметра. Комментарий содержит пример ожидаемых входных данных. Если параметр не указан, значение по умолчанию равно NULL. Советы по написанию функций для включения дополнительных параметров и комментариев.
   • Примечания функций. Комментарий в функции таблицы SQL содержит подробное описание того, что выполняет функция. Это важно, так как оно сообщает Genie, когда следует использовать функцию в качестве ответа на вопросы пользователя. Комментарий должен описать назначение функции как можно точнее. Эта информация позволяет Genie распознавать релевантность функции для конкретных вопросов.

   
   CREATE
   OR REPLACE FUNCTION users.user_name.open_opps_in_region (
     regions ARRAY < STRING >
     COMMENT 'List of regions.  Example: ["APAC", "EMEA"]' DEFAULT NULL
   ) RETURNS TABLE
   COMMENT 'Addresses questions about the pipeline in the specified regions by returning
    a list of all the open opportunities. If no region is specified, returns all open opportunities.
    Example questions: "What is the pipeline for APAC and EMEA?", "Open opportunities in
    APAC"'
   RETURN
     SELECT
     o.id AS `OppId`,
     a.region__c AS `Region`,
     o.name AS `Opportunity Name`,
     o.forecastcategory AS `Forecast Category`,
     o.stagename,
     o.closedate AS `Close Date`,
     o.amount AS `Opp Amount`
     FROM
     catalog.schema.opportunity o
     JOIN catalog.schema.accounts a ON o.accountid = a.id
     WHERE
     o.forecastcategory = 'Pipeline'
     AND o.stagename NOT LIKE '%closed%'
     AND (
       isnull(open_opps_in_region.regions)
       OR array_contains(open_opps_in_region.regions, region__c)
     );
   

   При запуске кода для создания функции он зарегистрирован в текущей активной схеме по умолчанию. Дополнительные функции SQL см . в каталоге Unity. См. статью "Создание функции таблицы SQL" для синтаксиса и примеров.

3. Добавьте доверенный ресурс.

   После создания функции в каталоге Unity пользователь с по крайней мере разрешением CAN EDIT в пространстве Genie может добавить его на вкладке "Инструкции " пространства Genie.

Необходимые разрешения

Пользователи, имеющие по крайней мере разрешение CAN EDIT в пространстве Genie, могут добавлять или удалять доверенные ресурсы.

Пользователи пространства Genie должны иметь CAN USE разрешение на каталог и схему, содержащую функцию. Чтобы вызвать доверенный ресурс, они должны иметь EXECUTE разрешение на функцию в каталоге Unity. Защищаемые объекты каталога Unity наследуют разрешения от родительских контейнеров. См. сведения о защищаемых объектах в каталоге Unity.

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

Советы по написанию функций

Ознакомьтесь со следующими примерами, чтобы узнать, как создавать динамические функции для доверенных ресурсов.

Включение значения параметра по умолчанию

Можно указать значение параметра по умолчанию. DEFAULT Используйте предложение в сигнатуре функции, как показано в следующем примере:

countries ARRAY<STRING> COMMENT 'List of countries' DEFAULT ARRAY()

Включение примеров значений параметров

Для столбцов с перечислением наборов значений увеличьте точность путем их четкого определения в комментарии. В следующем примере представлен пример списка значений:

regions ARRAY < STRING > COMMENT 'List of regions. Values: ["AF","AN","AS", "EU", "NA", "OC", "SA", NULL]'

Создание необязательного параметра

Чтобы создать необязательный параметр, задайте для параметра NULL по умолчанию значение, как показано в следующем примере:

min_date STRING DEFAULT NULL

Указание форматирования с комментариями

Вы можете указать точный формат параметра, включив его в комментарий, как показано в следующем примере:

min_date STRING COMMENT 'minimum date (included) for a transaction, in `yyyy-mm-dd` format'

Explictly check for NULL values

Если вы включаете необязательный параметр, следует ожидать NULLодно из возможных значений. Так как сравнение с NULL непредсказуемыми результатами может дать непредсказуемые результаты, необходимо явно создать проверку значений NULL в функции. В следующем примере приведен пример синтаксиса:

WHERE (isnull(min_date) OR created_date >= min_date)