获取和解析 AI Function 原始响应

前提条件

• 已开通AI中心。

• 使用esr-4.10.0及之后的引擎版本。

• 作业提交、或创建会话时添加spark.emr.serverless.ai.function.enable true Spark 配置。

raw 函数清单

raw 函数的入参与对应的标准函数完全相同，区别仅在于返回值：标准函数返回解析后的结果，raw 函数返回模型服务的原始 JSON 响应。各函数的参数说明请参见AI Function 介绍。

ai_query_raw()

函数语法

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

返回类型为 STRING。生成文本、usage、请求标识等字段的位置由模型服务响应格式决定。

SQL 示例

SELECT ai_query_raw(
  '请将下面文本总结为一句话：AI Function 将模型能力集成到 Spark。',
  'my_qwen_service',
  '{"temperature":0.2}'
) AS raw_response;

PySpark 示例

from emr_serverless_spark_ai import ai_query_raw

result_df = source_df.select(
    ai_query_raw(
        "prompt",
        service_name="my_qwen_service",
        options='{"temperature":0.2}',
    ).alias("raw_response")
)

ai_embedding_raw()

函数语法

ai_embedding_raw(
    input,
    dimension=None,
    service_name=None,
    options=None,
)

参数 input 可以是 STRING 或 ARRAY<STRING>，返回类型固定为 STRING。文本向量 raw 结果使用统一 envelope，根节点包含 local_results 和 calls 两个字段：

{
  "local_results": [ ],
  "calls": [ ]
}

• local_results：未调用模型服务、在本地完成的输入元素，例如 NULL 和空字符串。其中 input_index 为元素在当前 Spark 行输入中的位置（标量输入为 0），embedding 为本地生成的结果（当前为空数组），reason 为原因（例如 null_input、empty_input）。

• calls：当前 Spark 行涉及的物理模型调用。其中 input_indices 为该调用结果对应当前行原始输入的位置，call_id 为 AI Function 引擎生成的物理调用标识，response 为模型服务原始 JSON 响应（保留 usage、dense、sparse 及未知扩展字段）。

SELECT ai_embedding_raw(
  array('第一段文本', NULL, '', '第四段文本'),
  service_name => 'qwen3.7-text-embedding'
);

SELECT ai_embedding_raw(
  text,
  dimension => 1024,
  service_name => 'qwen3.7-text-embedding',
  options => '{
    "api_mode":"dashscope",
    "text_type":"document",
    "output_type":"dense&sparse"
  }'
)
FROM source_table;

ai_embedding_multimodal_raw()

函数语法

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

返回类型为 STRING。图片输入方式与 ai_embedding_multimodal() 相同；响应保留模型服务返回的请求标识、usage、向量及扩展字段。

示例

SELECT ai_embedding_multimodal_raw(
  image_col,
  service_name => 'multimodal-embedding-model',
  data_type => 'binary'
) AS raw_response
FROM image_table;

解析原始响应

raw 函数的返回值为 STRING 类型的 JSON 文本，您可以使用 Spark SQL 的 JSON 函数按需取值。常用方式如下：

• 取单个字段：使用 get_json_object()，通过 JSON Path 定位目标字段。

• 按结构展开：使用 from_json()，为响应定义 STRUCT 结构后再访问各字段。

WITH result AS (
  SELECT ai_embedding_raw(
    text,
    service_name => 'qwen3.7-text-embedding',
    options => '{"api_mode":"dashscope"}'
  ) AS raw_response
  FROM source_table
)
SELECT
  get_json_object(raw_response, '$.calls[0].call_id') AS call_id,
  get_json_object(raw_response, '$.calls[0].response.request_id') AS request_id
FROM result;

import json
from emr_serverless_spark_ai import ai_embedding_raw

raw_df = source_df.select(
    ai_embedding_raw(
        "text",
        service_name="qwen3.7-text-embedding",
        options=json.dumps({"api_mode": "dashscope"}),
    ).alias("raw_response")
)

使用建议

• 业务计算优先使用标准函数；确实需要模型服务原始字段时再使用 raw 函数。

• 使用 raw 响应时保留完整 JSON，解析逻辑只读取所需字段，并允许出现未知扩展字段。

• 需要稳定 JSON 结构时显式设置 api_mode，避免 auto 模式因参数变化切换接口。

• Embedding 函数的 options 兼容 dimension 和 dimensions 两种指定维度的参数，请使用其中之一进行配置，避免同时使用。

相关文档

• AI Function 介绍

• 模型服务