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

Внимание

Эта функция предоставляется в режиме общедоступной предварительной версии. См. раздел "Включение пространств Genie" в учетной записи.

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

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

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

Доверенные ресурсы могут включать в себя следующее:

• Параметризованный пример запросов SQL: если параметризованный пример SQL-запроса используется для создания ответа, репонс помечен доверенным ресурсом. Ответ содержит значения, используемые в качестве аргументов в запросе.
• Определяемые пользователем функции таблиц (UDFS) — можно определить пользовательские функции и зарегистрировать их в каталоге Unity. Затем эти функции можно добавить в качестве доверенных ресурсов при настройке инструкций в пространстве Genie. См. статью "Создание функции таблицы SQL" и определяемых пользователем функций в каталоге Unity.

Примечание.

Доверенные ресурсы не являются заменой всех остальных инструкций. Databricks рекомендует использовать доверенные ресурсы для хорошо установленных повторяющихся вопросов. Они предоставляют точные ответы на конкретные вопросы.

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

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

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

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

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

• Функции SQL. Вы можете создавать пользовательские функции SQL, предназначенные для обработки данных и решения вопросов, относящихся к организации. Genie не учитывает содержимое SQL доверенных ресурсов при ответе на вопросы.
• Примеры запросов SQL (с параметрами) — если для создания ответа используется точный текст параметризованного примера запроса, ответ автоматически помечен как доверенный ресурс. Если точный текст запроса не используется, или пример запроса не использует параметры, запрос предоставляет контекст и руководства Genie при создании инструкций SQL для обработки других вопросов.

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

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

Пример. Использование UDF

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

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)
     );
   

   При запуске кода для создания функции он зарегистрирован в текущей активной схеме по умолчанию. См . определяемые пользователем функции в каталоге 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)