Функция `ai_query`

Статья
03/11/2025

Применяется к: отмечено Databricks SQL Databricks Runtime

Внимание

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

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

Сведения об использовании ai_query в рабочих рабочих процессах см. в статье Выполнение пакетного вывода LLM с помощью функций ИИ.

Требования

Примечание.

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

Эта функция недоступна в Классической версии SQL Azure Databricks.
Необходимо включить Приватный канал Azure, чтобы использовать эту функцию в pro SQL хранилищах.
Рекомендуется использовать Databricks Runtime 15.3 или более поздней версии. Использование Databricks Runtime 15.2 или ниже может привести к снижению скорости производительности.
Рабочая область должна находиться в поддерживаемом регионе обслуживания моделей.
Существующую конечную точку обслуживания модели с загруженной моделью. Если вы используете базовую модель Databricks, для вас создается конечная точка. В противном случае см. статью Создание пользовательских конечных точек модели или Создание базовой модели обслуживания конечных точек.
По умолчанию api модели запросов к модели Foundation включена. Чтобы выполнить запрос конечных точек, которые обслуживают пользовательские модели или внешние модели:
- Включите AI_Query для пользовательских моделей и внешних моделей в пользовательском интерфейсе Databricks Previews.
Текущий канал хранилища DLT не использует последнюю версию среды выполнения Databricks, которая поддерживает ai_query(). Задайте pipelines.channel в свойствах таблицы как 'preview' для использования ai_query().
```
> 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;
```

Синтаксис

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

ai_query(endpoint, request)

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

ai_query(endpoint, request)

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

ai_query(endpoint, request, returnType, failOnError)

аргументы и возвращаемые значения

Аргумент	Описание	Возвраты
`endpoint`	`STRING` литерал, имя конечной точки сервиса Databricks Foundation Model, внешняя конечная точка сервиса модели или пользовательская конечная точка модели в той же рабочей области для отправки запросов. Определитель должен иметь `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`.	Если `failOnError => true`функция возвращает тот же результат, что и существующее поведение, то есть синтаксический ответ от конечной точки. Тип данных синтаксического ответа выводится из типа модели, конечной точки схемы модели или параметра `returnType` в функции `ai_query`. Если `failOnError => false`, функция возвращает объект `STRUCT`, содержащий проанализированный ответ и строку состояния ошибки. Если выведение строки выполнено успешно, поле `errorStatus` является `null`. Если вывод строки завершается сбоем из-за ошибок конечной точки модели, поле `responsenull`. Если вывод данных строки не удается из-за других ошибок, весь запрос завершается ошибкой. Пример см. в разделе Обработка ошибок с помощью `failOnError`.
`modelParameters`	(Необязательно) Поле структуры, содержащее параметры моделей чата, моделей завершения и моделей встраивания для поддержки базовых моделей или внешних моделей. Эти параметры модели должны быть постоянными параметрами, а не зависимыми от данных. Если эти параметры модели не указаны или заданы для `null`, используется значение по умолчанию. За исключением , которая имеет значение по умолчанию , значения по умолчанию для этих параметров модели совпадают со значениями, перечисленными всправочнике по REST API модели Foundation. Пример см. в статье Настройка модели путем передачи параметров модели.
`responseFormat`	(Необязательно) Строковое поле JSON, указывающее формат ответа, который требуется выполнить модели. Поддерживаются три типа строк ответа: `text` `json_object` `json_schema`	Если `failOnError => false` и вы указали `responseFormat`, функция возвращает проанализированный ответ и строку состояния ошибки в виде объекта `STRUCT`. В зависимости от типа строки JSON, указанного в `responseFormat`, возвращается следующий ответ: Для `responseFormat => '{"type": "text"}'`ответ представляет собой строку, например `“Here is the response”`. Для `responseFormat => '{"type": "json_object"}'`ответ представляет собой строку JSON пары "ключ-значение", например `{“key”: “value”}`. Для `responseFormat => '{"type": "json_schema", "json_schema"...}'`ответ представляет собой строку JSON. Пример см. в разделе Принудительное применение схемы вывода с структурированными выходными.

Настройка модели путем передачи параметров модели

Настройте поведение модели путем передачи определенных параметров, таких как максимальные маркеры и температура. Рассмотрим пример.

SELECT text, ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "Please summarize the following article: " || text,
    modelParameters => named_struct('max_tokens', 100, 'temperature', 0.7)
) AS summary
FROM uc_catalog.schema.table;

обработка ошибок с помощью `failOnError`

Используйте аргумент failOnError для ai_query обработки ошибок. В следующем примере показано, как убедиться, что если одна строка имеет ошибку, она не остановит весь запрос от выполнения. См. Аргументы и возвраты для ожидаемых действий в зависимости от задания аргумента.


SELECT text, ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "Summarize the given text comprehensively, covering key points and main ideas concisely while retaining relevant details and examples. Ensure clarity and accuracy without unnecessary repetition or omissions: " || text,
failOnError => false
) AS summary
FROM uc_catalog.schema.table;

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

Убедитесь, что выходные данные соответствуют определенной схеме для упрощения последующей обработки. Например, можно применить формат ответа схемы JSON:

SELECT ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "Extract research paper details from the following abstract: " || abstract,
    responseFormat => 'STRUCT<research_paper_extraction:STRUCT<title:STRING, authors:ARRAY<STRING>, abstract:STRING, keywords:ARRAY<STRING>>>'
)
FROM research_papers;

Кроме того, с помощью схемы JSON стиля DDL:

SELECT ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "Extract research paper details from the following abstract: " || abstract,
    responseFormat => '{
      "type": "json_schema",
      "json_schema": {
        "name": "research_paper_extraction",
        "schema": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "authors": {"type": "array", "items": {"type": "string"}},
            "abstract": {"type": "string"},
            "keywords": {"type": "array", "items": {"type": "string"}}
          }
        }
      },
      "strict": true
    }'
)
FROM research_papers;

Ожидаемые выходные данные могут выглядеть следующим образом:

{ "title": "Understanding AI Functions in Databricks", "authors": ["Alice Smith", "Bob Jones"], "abstract": "This paper explains how AI functions can be integrated into data workflows.", "keywords": ["Databricks", "AI", "LLM"] }

Использование `ai_query` в определяемых пользователем функциях

Вы можете упаковать вызов ai_query в UDF, что упрощает использование функций в разных рабочих процессах и совместное использование их.

CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-3-70b-instruct',
    CONCAT('Correct this to standard English:\n', text));

GRANT EXECUTE ON correct_grammar TO ds;

SELECT
    * EXCEPT text,
    correct_grammar(text) AS text
  FROM articles;

пример . Запрос базовой модели

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

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

Объедините столбцы подсказки и вывода

Существует несколько способов объединения запроса и столбца вывода, например использование ||, CONCAT()или format_string():

SELECT
CONCAT('${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

Еще один вариант:

SELECT
'${prompt}' || ${input_column_name} AS concatenated_prompt
FROM ${input_table_name};

Или с format_string():

SELECT
format_string('%s%s', '${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

Передача `failOnError` и `modelParameters` для базовых моделей

В следующем примере показано, как передать параметры failOnError и modelParameters, включая max_tokens и temperatureдля базовых моделей.

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

Пример: Вариант использования пакетного вывода

В следующем примере пакетного вывода используется 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 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-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."]}

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

Функция `ai_query`

Требования

Синтаксис

аргументы и возвращаемые значения

Настройка модели путем передачи параметров модели

обработка ошибок с помощью `failOnError`

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

Использование `ai_query` в определяемых пользователем функциях

пример . Запрос базовой модели

Объедините столбцы подсказки и вывода

Передача `failOnError` и `modelParameters` для базовых моделей

Пример: Вариант использования пакетного вывода

Пример. Запрос традиционной модели машинного обучения

Обратная связь

Дополнительные ресурсы

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

Функция ai_query

Требования

Синтаксис

аргументы и возвращаемые значения

Настройка модели путем передачи параметров модели

обработка ошибок с помощью failOnError

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

Использование ai_query в определяемых пользователем функциях

пример . Запрос базовой модели

Объедините столбцы подсказки и вывода

Передача failOnError и modelParameters для базовых моделей

Пример: Вариант использования пакетного вывода

Пример. Запрос традиционной модели машинного обучения

Обратная связь

Дополнительные ресурсы

Функция `ai_query`

обработка ошибок с помощью `failOnError`

Использование `ai_query` в определяемых пользователем функциях

Передача `failOnError` и `modelParameters` для базовых моделей