Поделиться через

Функция ai_query

  • Статья

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

Внимание

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

Вызывает существующую конечную точку обслуживания модели Azure Databricks и анализирует ее и возвращает ответ.

Ознакомьтесь со следующими руководствами по использованию ai_query различных вариантов использования:

Требования

Примечание.

  • В Databricks Runtime 14.2 и более поздних версиях эта функция поддерживается в записных книжках Databricks, включая записные книжки, выполняемые в качестве задачи в рабочем процессе Databricks.
  • В Databricks Runtime 14.1 и ниже эта функция не поддерживается в записных книжках Databricks.

Синтаксис

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

ai_query(endpoint, request)

Сделать запрос к конечной точке обслуживания пользовательской модели с использованием схемы модели .

ai_query(endpoint, request)

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

ai_query(endpoint, request, returnType, failOnError)

Аргументы

  • endpoint: литерал STRING, имя конечной точки сервиса модели Databricks Foundation, внешней конечной точки сервиса модели или пользовательской конечной точки модели в той же рабочей области для вызовов. Определитель должен иметь CAN QUERY разрешение на доступ к конечной точке.
  • request: выражение, запрос, используемый для вызова конечной точки.
    • Если конечная точка является внешним интерфейсом для обслуживания моделей или интерфейсом API модели Databricks Foundation, запрос должен быть STRING.
    • Если конечная точка является пользовательской конечной точкой обслуживания модели, запрос может быть одним столбцом или выражением структуры. Имена полей структуры должны совпадать с именами входных функций, ожидаемыми конечной точкой.
  • returnType: выражение ожидаемого returnType от конечной точки. Это аналогично параметру схемы в from_json функции, которая принимает как выражение STRING, так и вызов функции schema_of_json.
    • В Databricks Runtime 14.2 и более поздних версий, если это выражение не указано, ai_query() автоматически выводит тип возврата из схемы модели пользовательской конечной точки обслуживания модели.
    • В Databricks Runtime 14.1 и ниже это выражение требуется для запроса конечной точки обслуживания пользовательской модели.
  • failOnError: (необязательно) Логический литерал по умолчанию имеет значение true. Этот флаг указывает, следует ли включать состояние ошибки в ai_query ответ.
  • modelParameters (необязательно): поле структуры, содержащее параметры чата, завершения и внедрения моделей для обслуживания базовых моделей или внешних моделей. Эти параметры модели должны быть постоянными параметрами, а не зависимыми от данных. Если эти параметры модели не указаны или заданы для null, используется значение по умолчанию. За исключением , которая имеет значение по умолчанию , значения по умолчанию для этих параметров модели совпадают со значениями, перечисленными всправочнике по REST API модели Foundation.
  • responseFormat (необязательно): строковое поле JSON, указывающее формат ответа, который требуется выполнить модель. Поддерживаются три типа строк ответа:
    • text
    • json_object
    • json_schema

Возвраты

Проанализированный ответ от конечной точки.

  • Если failOnError => trueфункция возвращает тот же результат, что и существующее поведение, то есть синтаксический ответ от конечной точки. Тип данных синтаксического ответа выводится из типа модели, конечной точки схемы модели или параметра returnType в функции ai_query.
  • Если failOnError => false, функция возвращает проанализированный ответ и строку состояния ошибки в виде объекта STRUCT.
    • Если интерпретация строки прошла успешно, поле errorStatus — null.
    • Если вывод данных строки завершился неудачей из-за ошибки конечной точки модели, поле response равно null.
    • Если вывод строки завершился ошибкой из-за других ошибок, весь запрос завершается ошибкой.
  • В зависимости от типа строки JSON, указанного в responseFormat, возвращается следующий ответ:
    • Для responseFormat => '{“type”, “text”}'ответ представляет собой строку, например “Here is the response”.
    • Для responseFormat => '{“type”, “json_object”}'ответ представляет собой строку JSON пары "ключ-значение", например {“key”: “value”}.
    • Для responseFormat => '{“type”, “json_schema”...}'ответ представляет собой строку JSON. См. примеры .
  • Если failOnError => false и вы указали responseFormat, функция возвращает проанализированный ответ и строку состояния ошибки в виде объекта STRUCT.

Примеры

В следующем примере указывается формат ответа json_schema:


SELECT
  ai_query(
    "llama-3-1-70b",
    <request>,
    responseFormat =>'{
                        "type": "json_schema",
                        "json_schema":
                          {
                           "name": "research_paper_extraction",
                           "schema":
                             {
                              "type": "object",
                              "properties":
                               {
                                "title": { "type": "string" }
                               }
                             },
                            "strict": true
                          }
                      }'
  )

Ниже приведен пример выходных данных для указанного формата ответа json_schema:

{"title": "<the title of the paper>"}

Ниже приведен пример вывода пакетной службы с помощью failOnError и modelParameters с max_tokens ним temperature. В этом примере также показано, как объединить запрос модели и столбец вывода с помощью concat(). Существует несколько способов объединения, таких как использование ||, concat()или format_string().


CREATE OR REPLACE TABLE ${output_table_name} AS (
  SELECT
      ${input_column_name},
      AI_QUERY(
        "${endpoint}",
        CONCAT("${prompt}", ${input_column_name}),
        failOnError => false,
        modelParameters => named_struct('max_tokens', ${num_output_tokens},'temperature', ${temperature})
      ) as response
    FROM ${input_table_name}
    LIMIT ${input_num_rows}
)

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

> SELECT ai_query(
    'my-external-model-openai-chat',
    'Describe Databricks SQL in 30 words.'
  ) AS summary

  "Databricks SQL is a cloud-based platform for data analytics and machine learning, providing a unified workspace for collaborative data exploration, analysis, and visualization using SQL queries."

Чтобы запросить базовую модель, поддерживаемую API модели Databricks Foundation:

> SELECT *,
  ai_query(
    'databricks-meta-llama-3-1-70b-instruct',
    "Can you tell me the name of the US state that serves the provided ZIP code? zip code: " || pickup_zip
    )
  FROM samples.nyctaxi.trips
  LIMIT 10

При необходимости можно также упаковать вызов ai_query() в UDF для вызова функции следующим образом:

> CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-1-70b-instruct',
    CONCAT('Correct this to standard English:\n', text));
> GRANT EXECUTE ON correct_grammar TO ds;
- DS fixes grammar issues in a batch.
> SELECT
    * EXCEPT text,
    correct_grammar(text) AS text
  FROM articles;

Запрос конечной точки обслуживания пользовательской модели:


> SELECT text, ai_query(
    endpoint => 'spam-classification-endpoint',
    request => named_struct(
      'timestamp', timestamp,
      'sender', from_number,
      'text', text),
    returnType => 'BOOLEAN') AS is_spam
  FROM messages
  LIMIT 10

> SELECT ai_query(
    'weekly-forecast',
    request => struct(*),
    returnType => 'FLOAT') AS predicted_revenue
  FROM retail_revenue

> SELECT ai_query(
    'custom-llama-2-7b-chat',
    request => named_struct("messages",
        ARRAY(named_struct("role", "user", "content", "What is ML?"))),
    returnType => 'STRUCT<candidates:ARRAY<STRING>>')

  {"candidates":["ML stands for Machine Learning. It's a subfield of Artificial Intelligence that involves the use of algorithms and statistical models to enable machines to learn from data, make decisions, and improve their performance on a specific task over time."]}

Пример запроса для настройки канала DLT для предварительной версии:

> create or replace materialized view
    ai_query_mv
    TBLPROPERTIES('pipelines.channel' = 'PREVIEW') AS
  SELECT
    ai_query("databricks-dbrx-instruct", text) as response
  FROM
    messages
  LIMIT 10;