ai_query 函数

适用于： Databricks SQL Databricks Runtime

调用现有的 Azure Databricks 模型服务终结点，然后分析并返回其响应。

ai_query 是一种常规用途 AI 函数 ，可用于查询现有终结点以获取实时推理或批处理推理工作负荷。

• 有关 支持的模型 和所需的终结点配置，请参阅支持的模型。
• 还可以用于 ai_query 查询在 ML 模型服务终结点上部署的 AI 代理，请参阅 查询在 Azure Databricks 上部署的代理
• 若要在生产工作流中使用 ai_query ，请参阅 部署批处理推理管道。

要求

• 此函数在 Azure Databricks SQL Classic 上不可用。
• 必须启用 Azure 专用链接才能在专业版 SQL 仓库上使用此功能。
• 建议使用 Databricks Runtime 15.4 LTS 或更高版本。 使用 Databricks Runtime 15.3 或更低版本可能会导致性能速度降低。
• 工作区必须位于受支持的 模型服务区域中。
• 已加载模型的现有模型服务终结点。 如果使用 Databricks 托管的基础模型，则会为你创建一个终结点。 否则，请参阅 “创建自定义模型服务终结点 ”或 “创建基础模型服务终结点”。
• 查询 自定义模型 终结点和 外部模型 终结点是在受支持的区域中默认启用的公共预览版。 如果 ai_query() 针对自定义或外部终结点返回权限错误，则工作区管理员可能已在 “管理预览”中禁用它。

Syntax

查询提供 基础模型的终结点：

ai_query(endpoint, request)

若要查询具有模型架构的自定义模型服务终结点，请执行以下操作：

ai_query(endpoint, request)

若要查询没有模型架构的自定义模型服务终结点，请执行以下操作：

ai_query(endpoint, request, returnType, failOnError)

参数和返回

示例：查询基础模型

若要查询外部模型服务终结点，请执行以下操作：

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

查询 Databricks Foundation 模型 API 支持的基础模型：

> 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

（可选）您还可以在 UDF 中将对 ai_query() 的调用封装起来，以便实现函数调用，如下所示：

 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

以下示例演示如何查询 Databricks Foundation 模型 API 支持的用于多模式输入的基础模型。 在此示例中，参数 files => content 用于将图像文件数据传递给 ai_query

• files：模型预期用于多模式输入的参数名称
• content：DataFrame 中返回的 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");

若要查询 Databricks Foundation 模型 API 支持的用于多模式输入的基础模型，并指定结构化输出：

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

以下示例使用ai_query格式read_filesbinaryFile对云存储中的图像文件运行推理。 子 WHERE 句按 _metadata 大小和名称筛选字段，以以特定文件为目标。

SELECT
  path AS file_path,
  ai_query(
    'databricks-llama-4-maverick',
    'Describe this image in ten words or less: ',
    files => content
  ) AS result
FROM read_files(
  's3://my-s3-bucket/path/to/images/',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size < 1000000
  AND _metadata.file_name LIKE '%robots%';

示例：查询传统的 ML 模型

若要查询自定义模型或传统的 ML 模型服务终结点，请执行以下作：

> 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 上的结构化输出。

以下示例强制实施 DDL 样式 JSON 字符串架构：

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

可以在 UDF 中包装对函数的调用 ai_query ，以便轻松地在不同的工作流中使用函数并共享它们。

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;