共用方式為

使用 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 或字串值為「最小」、「低」、「中」或「高」。 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>",
)

選擇其他支援的內嵌模型

在使用ai.embed或ai.similarity函式時，將embedding_deployment_name設定為Fabric 支援的其中一個模型。

  • 物件的 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 相容的用戶端，並搭配您的端點與金鑰。 以下程式碼範例使用佔位符值，示範如何以您前身為 Azure OpenAI 的 Microsoft AI Foundry 資源中的模型部署取代內建的 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