图片算子概述：图片探测、格式转换、缩放裁剪、OCR 与图片向量化-云原生数据仓库AnalyticDB(AnalyticDB)-阿里云帮助中心

算子列表

算子	用途	默认顶层结果列
probe_image	探测尺寸、颜色与帧信息。	`width`、`height`、`format`、`mode`、`has_alpha`、`frame_count`、`is_animated`
normalize_image	标准化为模型可用的图片字节。	`data_base64`、`format`
convert_image	转为 PNG、JPEG 或 WebP。	`image_uri`、`width`、`height`、`format`
resize_image	等比缩放。	`image_uri`、`width`、`height`、`format`
crop_image	按明确的矩形框裁剪。	`image_uri`、`width`、`height`、`format`、`source_bbox_px`
ocr	识别图片或 PDF 中的文字。	`text`、`pages`
caption_image	根据提示词生成图片描述。	`text`
embed_image	生成图片向量。	`embedding`

输入与参数

不同图片算子使用的输入列如下：

输入列	类型	说明
`image_uri`	str 或 struct	默认由 `image_column` 选择的列，值可以是图片 URI、图片对象（ImageRef）或 Base64 对象。
`bbox`	list[number]	crop_image 的 `bbox_column` 所选列，为 xyxy 格式的四项矩形框。
`sources`	str 或 struct 或 list	ocr 的 `sources_column` 所选列，可以是独立的 PDF URI，或图片 URI、图片对象（ImageRef 或 Base64 对象）及其列表。列表只能包含图片，PDF 必须单独传入，不得放入或混入列表。

normalize_image 只读取图片 URI。除该算子外，其他图片算子还可以接收 ImageRef 和 Base64 对象两种 struct。URI 和 Base64 不能放在同一个对象中，声明的格式与尺寸必须与真实文件一致。

struct 字段	类型	使用条件
`image_uri`	str	ImageRef 必需，指向当前图片。
`width`	int	ImageRef 可选，EXIF 方向校正后的可见宽度。
`height`	int	ImageRef 可选，EXIF 方向校正后的可见高度。
`format`	str	ImageRef 可选；Base64 对象必需，必须与字节的实际格式一致。
`data_base64`	str	Base64 对象的规范字节字段，不含 data URI 前缀；也可以使用兼容别名 `image_base64`。
`image_base64`	str，可选	兼容别名，用于适配文档内嵌图片的结果。与 `data_base64` 同时提供时，二者必须相同。

图片算子的通用参数如下：

通用参数	类型	默认值	说明
`image_column`	str	`"image_uri"`	图片算子读取每行图片的列名。OCR 使用 `sources_column`。
`output_dir`	str	写文件的算子必填	产物的共享目录或对象存储前缀。SDK 自动为每行生成互不冲突的文件名。
`output_format`	str	`"png"`	输出格式，取值为 png、jpeg、jpg 或 webp。适用于 `convert_image`、`resize_image` 和 `crop_image`。
`keep_columns`	list[str] \| None	`None`	需要追加保留的原输入列。与标准结果列重名时报错，需先用 Ray Data 原生的 `rename_columns` 改名。
`batch_size`	int	`1`	Ray 批处理大小。
`concurrency`	int	`1`	Ray 执行并发度，取值为正整数。
`num_cpus`	float	`1`	每个执行任务申请的 Ray CPU 资源，取值须大于 0。

*_column 参数指定从每行读取数据的列名；prompt、width、coordinate_system 等普通参数是本次调用的全局常量。基础处理算子默认单行总超时时间为 60 秒，调用模型的算子默认为 180 秒；单张图片默认上限为 32 MiB、8000 万像素。OCR 读取 PDF 的默认上限为 256 MiB。详细的可调参数以对应算子的接口文档为准。

输出与图片语义

转换、缩放和裁剪算子将每项元数据作为独立的顶层列输出，后续算子可直接通过 image_column="image_uri" 读取产物 URI。其他输入列不会自动透传，需要业务标识时请使用 keep_columns。normalize_image 输出的两列可以用原生 map 打包为图片 struct，再交给视觉模型。

图片产物列	类型	说明
`image_uri`	str	已写出的图片地址。
`width`	int	输出图片的可见宽度，单位为像素。
`height`	int	输出图片的可见高度，单位为像素。
`format`	str	实际编码格式，取值为 png、jpeg 或 webp。
`source_bbox_px`	list[int]	仅裁剪算子输出，表示在当前输入图片上实际使用的 xyxy 像素框。

图片输入支持 PNG、JPEG、WebP、GIF、BMP 和 TIFF 格式，处理时的语义如下：

先按 EXIF 信息校正方向，尺寸与裁剪坐标都以校正后的可见图片为准。
静态处理只取首帧，多页 TIFF 只取第一页。
输出 PNG、WebP 时保留透明信息；输出 JPEG 时使用 background 铺底。
输出不会覆盖输入文件。

完整示例：裁剪后描述局部

说明

示例中的 /shared 是集群所有 Worker 节点均可读写的共享挂载目录，需预先放置输入素材。视觉模型默认读取 MMOPS_VISION_MODEL、MMOPS_VISION_BASE_URL（未配置时回退 MMOPS_MODEL_BASE_URL）和 MMOPS_MODEL_API_KEY 环境变量，密钥请配置在执行节点环境中。环境变量说明，请参见离线算子概述。

import ray
from mmops.ray import enable_accessor

ray.init()
enable_accessor()

ds = ray.data.from_items([{
    "asset_id": "demo-001", "image_uri": "/shared/input/sample.png",
    "bbox": [0.1, 0.1, 0.8, 0.9],
}])
crops = ds.mmops.crop_image(
    image_column="image_uri", bbox_column="bbox", coordinate_system="normalized",
    output_dir="/shared/output/image_crops", output_format="png",
    keep_columns=["asset_id"],
)
result = crops.mmops.caption_image(
    image_column="image_uri", prompt="描述裁剪区域内可见的物品、颜色和文字。",
    keep_columns=["asset_id", "image_uri"],
)
result.select_columns(["asset_id", "image_uri", "text"]).write_parquet(
    "/shared/metadata/crop_captions"
)

output_dir 保存图片二进制产物，write_parquet() 保存元数据与描述结果。

图片向量默认使用 DashScope 多模态协议，模型变量为 MMOPS_IMAGE_EMBEDDING_MODEL 和 MMOPS_IMAGE_EMBEDDING_BASE_URL，可以在 model_config 中按任务覆盖模型、地址和协议。读取、渲染、解码或模型失败时算子会报错；OCR 遇到空白页时正常返回空文本，请勿将二者混淆。

示例返回结果

以下为与上述调用对应的返回结构示例，媒体内容、模型结果和生成的文件名以实际输入及配置为准。算子返回 Dataset，take() 仅取少量行到本地查看；多行结果不保证跨分区的顺序。

import json

rows = result.take(1)
print(json.dumps(rows, ensure_ascii=False, indent=2))

[
  {
    "text": "裁剪区域内是一只白色杯子。",
    "asset_id": "demo-001",
    "image_uri": "/shared/output/image_crops/crop_image-demo/image.png"
  }
]