通过

使用 PySpark 自定义 AI 函数

AI 函数设计为开箱即用，默认配置基础模型和设置。 但是，想要更灵活的配置的用户可以使用一些额外的代码行来自定义其解决方案。

重要

  • AI 函数用于 Fabric Runtime 1.3（Spark 3.5） 及更高版本。
  • 请查看此概述文章中 的先决条件，包括为了暂时使用 AI 功能而需要的库安装 。
  • 尽管基础模型可以处理多种语言，但大多数 AI 函数经过优化，可用于英语文本。

注释

  • 本文介绍如何使用 PySpark 自定义 AI 函数。 若要使用 pandas 自定义 AI 函数，请参阅 本文。
  • 请参阅 本概述文章中的所有 AI 函数。

配置

如果在 PySpark 中使用 AI 函数，则可以使用该 OpenAIDefaults 类来配置所有函数使用的基础 AI 模型。 在以下部分中指定了只能应用于每个函数调用的设置。

参数 Description 违约
concurrency 一个 int ，指定要与对模型的异步请求并行处理的最大行数。 较高的值可以加快处理时间（如果容量可以容纳）。 最多可以设置为 1,000。 必须根据单个 AI 函数调用设置此值。 在 spark 中，此并发值适用于每个工作节点。 50
deployment_name 一个指定基础模型名称的字符串值。 可以从 Fabric 支持的模型中进行选择。 此值还可以设置为 Azure OpenAI 或 Azure AI Foundry 中的自定义模型部署。 在 Azure 门户中，此值显示在 资源管理>模型部署下。 在 Azure AI Foundry 门户中，该值显示在 “部署 ”页上。 gpt-4.1-mini
embedding_deployment_name 一个字符串值，该值指定为 AI 函数提供支持的嵌入模型部署的名称。 text-embedding-ada-002
reasoning_effort OpenAIDefaults 的一部分。 用于 gpt-5 系列模型确定它们应使用的推理令牌数量。 可以设置为 None 或字符串值“minimal”、“low”、“medium”或“high”。 None
subscription_key 用于通过大型语言模型（LLM）资源进行身份验证的 API 密钥。 在 Azure 门户中，此值显示在 “密钥和终结点 ”部分中。 N/A
temperature 介于 0.0 和 1.0 之间的数值。 较高的温度会增加基础模型输出的随机性或创造力。 0.0
top_p OpenAIDefaults 的一部分。 介于 0 和 1 之间的 浮点 数。 较低的值（例如 0.1）将模型限制为仅考虑最可能令牌，从而使输出更具确定性。 更高的值（例如，0.9）允许通过包括更广泛的令牌，实现更多样化和创造性的输出。 None
URL 指定 LLM 资源的终结点的 URL。 在 Azure 门户中，此值显示在 “密钥和终结点 ”部分中。 例如： https://your-openai-endpoint.openai.azure.com/。 N/A
verbosity OpenAIDefaults 的一部分。 gpt-5 系列模型用于控制输出长度。 可以设置为 None 或者字符串值为“low”、“medium”或“high”。 None

下面的代码示例演示如何为单个函数调用配置 concurrency 。

df = spark.createDataFrame([
        ("There are an error here.",),
        ("She and me go weigh back. We used to hang out every weeks.",),
        ("The big picture are right, but you're details is all wrong.",),
    ], ["text"])

results = df.ai.fix_grammar(input_col="text", output_col="corrections", concurrency=200)
display(results)

下面的代码示例演示如何为所有函数配置 gpt-5 和其他推理模型。

from synapse.ml.services.openai import OpenAIDefaults
default_conf = OpenAIDefaults()

default_conf.set_deployment_name("gpt-5")
default_conf.set_temperature(1)  # gpt-5 only accepts default value of temperature
default_conf.set_top_p(1)  # gpt-5 only accepts default value of top_p
default_conf.set_verbosity("low")
default_conf.set_reasoning_effort("low")

可以使用以下代码示例检索和打印每个 OpenAIDefaults 参数：

print(default_conf.get_deployment_name())
print(default_conf.get_subscription_key())
print(default_conf.get_URL())
print(default_conf.get_temperature())

还可以像修改参数一样轻松重置参数。 下面的代码示例重置 AI 函数库，使其使用默认的 Fabric LLM 端点：

default_conf.reset_deployment_name()
default_conf.reset_subscription_key()
default_conf.reset_URL()
default_conf.reset_temperature()

自定义模型

选择另一个受支持的大型语言模型

请将 deployment_name 设置为 Fabric 支持的模型之一。

  • 在全局对象 OpenAIDefaults() 中：

    from synapse.ml.services.openai import OpenAIDefaults
default_conf = OpenAIDefaults()
default_conf.set_deployment_name("<model deployment name>")

  • 在每个 AI 函数调用中单独调用：

    results = df.ai.translate(
    to_lang="spanish",
    input_col="text",
    output_col="out",
    error_col="error_col",
    deploymentName="<model deployment name>",
)

选择另一个受支持的嵌入模型

使用embedding_deployment_name或函数时，将ai.embed设置为ai.similarity之一。

  • 全局在 OpenAIDefaults() 对象中：

    from synapse.ml.services.openai import OpenAIDefaults
default_conf = OpenAIDefaults()
default_conf.set_embedding_deployment_name("<embedding deployment name>")

  • 在每个 AI 函数调用中单独调用：

    results = df.ai.embed(
    input_col="english",
    output_col="out",
    deploymentName="<embedding deployment name>",
)

配置自定义模型终结点

默认情况下，AI 函数使用 Fabric LLM 终结点 API 进行统一计费和轻松设置。 可以选择使用自己的模型终结点，方法是使用终结点和密钥设置 Azure OpenAI 或 AsyncOpenAI 兼容的客户端。 以下代码示例使用占位符值来演示如何使用自己的 Microsoft AI Foundry（前 Azure OpenAI）资源的模型部署来替代内置 Fabric AI 终结点：

from synapse.ml.services.openai import OpenAIDefaults
default_conf = OpenAIDefaults()

default_conf.set_URL("https://<ai-foundry-resource>.openai.azure.com/")
default_conf.set_subscription_key("<API_KEY>")

以下代码示例使用占位符值来演示如何使用自定义Microsoft AI Foundry 资源替代内置 Fabric AI 终结点，以使用 OpenAI 以外的模型：

重要

  • 对 Microsoft AI Foundry 模型的支持仅限于支持 Chat Completions API 和接受 response_format JSON 架构参数的模型
  • 输出可能因所选 AI 模型的行为而异。 请谨慎探索其他模型的功能
  • 基于嵌入的 AI 函数 ai.embed ， ai.similarity 在使用 AI Foundry 资源时不受支持
import synapse.ml.spark.aifunc.DataFrameExtensions
from synapse.ml.services.openai import OpenAIDefaults

default_conf = OpenAIDefaults()
default_conf.set_URL("https://<ai-foundry-resource>.services.ai.azure.com")  # Use your AI Foundry Endpoint
default_conf.set_subscription_key("<API_KEY>")
default_conf.set_deployment_name("grok-4-fast-non-reasoning")

相关内容

  • Last updated on