Функция `ai_query`

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

Important

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

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

Базовая языковая модель может обрабатывать несколько языков, но эта функция ИИ настраивается для английского языка.
См. сведения о функциях с ограниченной региональной доступностью для региона "Функции ИИ".

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

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

См. раздел "Поддерживаемые модели " для поддерживаемых моделей и необходимых конфигураций конечных точек.
Вы также можете запросить ai_query агент ИИ, развернутый в конечной точке обслуживания модели машинного обучения, см. статью "Запрос агента, развернутого в Azure Databricks"
Сведения об использовании ai_query в производственных рабочих процессах см. в разделе "Развертывание пакетных конвейеров вывода".

Требования

Эта функция недоступна в Классической версии SQL Azure Databricks.
Необходимо включить Приватный канал Azure, чтобы использовать эту функцию в pro SQL хранилищах.
Рекомендуется использовать Databricks Runtime 15.4 LTS или более поздней версии. Использование Databricks Runtime 15.3 или ниже может привести к снижению скорости производительности.
Рабочая область должна находиться в поддерживаемом регионе обслуживания моделей.
Существующую конечную точку обслуживания модели с загруженной моделью. Если вы используете базовую модель Databricks, для вас создается конечная точка. В противном случае см. статью Создание пользовательских конечных точек модели или Создание базовой модели обслуживания конечных точек.
По умолчанию api модели запросов к модели Foundation включена. Чтобы выполнить запрос конечных точек, которые обслуживают пользовательские модели или внешние модели:
- Включите AI_Query для пользовательских моделей и внешних моделей в пользовательском интерфейсе Databricks Previews.
Текущаяканальная структура хранилища для декларативных конвейеров Lakeflow Spark не использует последнюю версию среды выполнения 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-meta-llama-3-3-70b-instruct", text) as response
  FROM
    messages
  LIMIT 10;
```

Syntax

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

ai_query(endpoint, request)

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

ai_query(endpoint, request)

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

ai_query(endpoint, request, returnType, failOnError)

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

Argument	Description	Returns
`endpoint`	Имя конечной точки обслуживания модели Databricks Foundation, внешней конечной точки обслуживания модели или пользовательской конечной точки модели в той же рабочей области для вызовов в качестве `STRING` литерала. Определитель должен иметь `CAN QUERY` разрешение на доступ к конечной точке.
`request`	Запрос, используемый для вызова конечной точки в качестве выражения. Если конечная точка является внешним интерфейсом для обслуживания моделей или интерфейсом API модели Databricks Foundation, запрос должен быть `STRING`. Если конечная точка является пользовательской конечной точкой обслуживания модели, запрос может быть одним столбцом или выражением STRUCT. Имена полей STRUCT должны совпадать с именами входных признаков, ожидаемыми конечной точкой.
`returnType`	(Необязательно для Databricks Runtime 15.2 и более поздних версий) Ожидаемое `returnType` от конечной точки в качестве выражения. Это аналогично параметру схемы в `from_json` функции, которая принимает как выражение `STRING`, так и вызов функции `schema_of_json`. Для Databricks Runtime 15.2 и более поздних версий это выражение является необязательным. Если он не указан, `ai_query()` автоматически выводит тип возвращаемого значения из схемы модели пользовательской конечной точки обслуживания модели. Для Databricks Runtime 15.1 и ниже это выражение требуется для запроса конечной точки обслуживания пользовательской модели. `responseFormat` Используйте параметр, чтобы указать форматы ответов для моделей основы чата.
`failOnError`	(Необязательно) Логический литерал, который по умолчанию имеет значение true. Требуется Databricks Runtime 15.3 или более поздней версии. Этот флаг указывает, нужно ли включать статус ошибки в ответ `ai_query`. Пример см. в разделе Обработка ошибок с помощью `failOnError`.	Ниже описано поведение возврата в зависимости от сценария `failOnError`. Если `failOnError => true`функция возвращает тот же результат, что и существующее поведение, то есть синтаксический ответ от конечной точки. Тип данных синтаксического ответа выводится из типа модели, конечной точки схемы модели или параметра `returnType` в функции `ai_query`. Если `failOnError => false`, функция возвращает объект `STRUCT`, содержащий проанализированный ответ и строку состояния ошибки. Если выведение строки выполнено успешно, поле `errorStatus` является `null`. Если вывод строки завершается сбоем из-за ошибок конечной точки модели, поле `responsenull`. Если вывод данных строки не удается из-за других ошибок, весь запрос завершается ошибкой.
`modelParameters`	(Необязательно) Поле структуры, содержащее параметры моделей чата, моделей завершения и моделей встраивания для поддержки базовых моделей или внешних моделей. Эти параметры модели должны быть постоянными параметрами, а не зависимыми от данных. Требуется Databricks Runtime 15.3 или более поздней версии. Если эти параметры модели не указаны или заданы для `null`, используется значение по умолчанию. За исключением , которая имеет значение по умолчанию , значения по умолчанию для этих параметров модели совпадают со значениями, перечисленными всправочнике по REST API модели Foundation. Пример см. в статье Настройка модели путем передачи параметров модели.
`responseFormat`	(Необязательно) Определите формат ответа, который вы хотите чтобы использовала базовая модель чата. Требуется Databricks Runtime 15.4 LTS или более поздней версии. Доступно только для запросов моделей основы чата. Поддерживаются два стиля формата ответа. Строка JSON стиля DDL Строка JSON. Поддерживаются три типа строк JSON формата ответа:`text`, `json_objectjson_schema` Примеры см. в разделе "Принудительное применение схемы выходных данных с структурированными выходными данными ".	Ниже описано, что происходит, когда параметр `failOnError` также установлен при задании `responseFormat`: Если `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.
`files`	(Необязательно) Укажите, какие файлы и содержимое следует использовать в многомодальных запросах ввода с помощью `files=>content`. `files` — это имя параметра, ожидаемое моделью для многомодальных входных данных, и `content` ссылается на столбец в Кадре данных, содержащий двоичное содержимое файлов изображений, которые вы хотите использовать в запросе. Требуется для многомодальных запросов. Только входные данные изображения: `JPEG` или `PNG` поддерживаются. Пример см. в разделе "Многомодальные входные данные ". Как показано в этом примере, можно указать столбец `content` результата `read_files` в параметр `files`.

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

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

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

Многомодальные входные данные

ai_query изначально поддерживает многомодальные входные данные изображения. Ознакомьтесь с типами базовых моделей для поддерживаемых моделей компьютерного зрения, хостингуемых в Databricks.

Ниже приведены поддерживаемые типы входных данных:

JPEG
PNG

В следующем примере показано, как запрашивать базовую модель, поддерживаемую API модели Databricks Foundation для многомодальных входных данных. В этом примере files => content параметр используется для передачи данных файла изображения в ai_query

files: имя параметра, ожидаемое моделью для многомодальных входных данных
content: столбец в кадре данных, возвращаемый READ_FILES, который содержит двоичное содержимое файла изображения.


> SELECT *, ai_query(
  'databricks-llama-4-maverick',
 'what is this image about?', files => content)
as output FROM READ_FILES("/Volumes/main/multimodal/unstructured/image.jpeg");

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

> SELECT *, ai_query(
  'databricks-llama-4-maverick', 'What is interesting or important about this image?',
    responseFormat => ‘{
      "type": "json_schema",
        "json_schema": {
          "name": "output",
          "schema": {
            "type": "object",
            "properties": {
              "summary": {"type": "string"},
              "num_people": {"type": "integer"},
              "num_animals": {"type": "integer"},
              "interesting_fact": {"type": "string"},
              "possible_context": {"type": "string"}
            }
        },
        "strict": true
      }
    }’,
    files => content
  )
  as output FROM READ_FILES("/Volumes/main/user/volume1/image.jpeg");

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

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


> 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

Примеры для расширенных сценариев

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

Передача массива сообщений

В следующем примере показано, как передать массив сообщений в программное приложение модели или агента с помощью ai_query.

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

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

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

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

Alternatively:

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

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

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

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;

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

Убедитесь, что выходные данные соответствуют определенной схеме для упрощения последующей обработки с помощью responseFormat. См. структурированные выходные данные в Azure Databricks.

В следующем примере применяется схема строки JSON стиля DDL:

SELECT ai_query(
    "databricks-gpt-oss-20b",
    "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:

SELECT ai_query(
    "databricks-gpt-oss-20b",
    "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;

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

Были ли сведения на этой странице полезными?

Last updated on 2026-03-27