多模态函数使用最佳实践

ai_query

ai_query函数用于调用大语言模型进行推理，支持传入图片数据实现多模态理解。函数签名如下：

ai_query(prompt [, service_name] [, options][, data][, data_type])

参数说明：

命名参数调用示例：

ai_query(
  '提示词',
  service_name => '模型服务名',
  options => '{"temperature":0.1}',
  data => image_col,
  data_type => 'binary'
)

支持的命名参数：service_name、options、data、data_type。

ai_embedding_multimodal

ai_embedding_multimodal函数用于生成图片的embedding向量，可用于后续的相似度计算、检索等场景。函数签名如下：

ai_embedding_multimodal(data [, service_name] [, options] [, data_type])

参数说明：

命名参数调用示例：

ai_embedding_multimodal(
  image_col,
  service_name => 'tongyi-embedding-vision-plus',
  options => '{"dim":1024}',
  data_type => 'binary'
)

支持的命名参数：service_name、options、data_type。

场景一：基于图片路径进行多模态数据处理

当图片存储在OSS、HDFS或其他Hadoop兼容文件系统中，表中只保存图片路径时，可通过URI模式让函数内部读取文件内容。

示例：通过图片路径识别图片中的车牌号。

SELECT
  path,
  ai_query(
    '返回图中车牌号。IMPORTANT：只回复车牌信息；如果图片模糊无法辨认，回复''无法识别''。',
    service_name => 'qwen3.5-plus',
    data => path,
    data_type => 'uri'
  ) AS plate_number
FROM (
  SELECT /*+ REPARTITION(10) */ path
  FROM ccpd_1m_1000
) t;

如需显式控制thinking配置，可通过options参数设置：

SELECT
  path,
  ai_query(
    '返回图中车牌号。IMPORTANT：只回复车牌信息；如果图片模糊无法辨认，回复''无法识别''。',
    service_name => 'qwen3.5-plus',
    data => path,
    data_type => 'uri',
    options => '{"enable_thinking": false}'
  ) AS plate_number
FROM (
  SELECT /*+ REPARTITION(10) */ path
  FROM ccpd_1m_1000
) t;

场景二：基于图片二进制进行多模态数据处理

当需要直接从目录批量读取图片内容时，可使用read_files函数读取图片文件，将返回的content列（BINARY类型）作为多模态输入。

示例：从OSS目录批量读取图片并识别车牌号。

SELECT
  path,
  ai_query(
    '返回图中车牌号。IMPORTANT：只回复车牌信息。',
    service_name => 'qwen3.5-plus',
    data => content
  ) AS plate_number
FROM read_files(
  'oss://bucket/path/to/images/',
  suffix => 'jpg,jpeg,png'
);

场景三：生成图片Embedding向量

使用ai_embedding_multimodal函数可以将图片转换为embedding向量，用于后续的相似度检索、聚类分析等场景。支持URI模式和Binary模式两种方式。

方式一：通过图片路径生成embedding（URI模式）。

SELECT
  path,
  ai_embedding_multimodal(
    path,
    service_name => 'tongyi-embedding-vision-plus',
    data_type => 'uri'
  ) AS embedding
FROM image_paths_table;

方式二：通过图片二进制内容生成embedding（Binary模式）。

SELECT
  path,
  ai_embedding_multimodal(
    content,
    service_name => 'tongyi-embedding-vision-plus'
  ) AS embedding
FROM read_files(
  'oss://bucket/path/to/images/',
  suffix => 'jpg,png'
);

路径表场景使用内层子查询控制分区数

推荐把REPARTITION hint放到内层子查询，再在外层执行AI函数。也可以使用CTE或CREATE TEMPORARY VIEW的方式：

-- 方式一：子查询
SELECT
  path,
  ai_query('请描述图片内容', service_name => 'qwen3.5-plus', data => path, data_type => 'uri') AS result
FROM (
  SELECT /*+ REPARTITION(32) */ path FROM large_image_dataset
) t;

-- 方式二：CTE
WITH car_images AS (
  SELECT /*+ REPARTITION(32) */ path FROM ccpd_1m_1000
)
SELECT
  path,
  ai_query('请描述图片内容', service_name => 'qwen3.5-plus', data => path, data_type => 'uri') AS result
FROM car_images;

-- 方式三：临时视图
CREATE OR REPLACE TEMPORARY VIEW car_images AS
SELECT /*+ REPARTITION(32) */ path FROM ccpd_1m_1000;

SELECT
  path,
  ai_query('请描述图片内容', service_name => 'qwen3.5-plus', data => path, data_type => 'uri') AS result
FROM car_images;

read_files场景优先用文件扫描参数控制并行度

read_files直接扫描目录时，通常不需要先手动REPARTITION。如果希望提高并行度或减小单个输入分区大小，优先调整spark.sql.files.maxPartitionBytes：

SET spark.sql.files.maxPartitionBytes = 134217728;

读取时提前做后缀过滤

通过suffix参数过滤文件类型，可以减少无关文件扫描和下游AI请求量。需要递归读取子目录时，再显式加上recursive => true：

SELECT path, content
FROM read_files('oss://bucket/images/', suffix => 'jpg,jpeg,png');