Condividi tramite

Personalizzare le funzioni di intelligenza artificiale con PySpark

Le funzioni di intelligenza artificiale sono progettate per funzionare correttamente, con il modello e le impostazioni sottostanti configurati per impostazione predefinita. Gli utenti che vogliono configurazioni più flessibili, tuttavia, possono personalizzare le proprie soluzioni con alcune righe di codice aggiuntive.

Importante

  • Le funzioni di intelligenza artificiale sono destinate all'uso in Fabric Runtime 1.3 (Spark 3.5) e versioni successive.
  • Esamina i prerequisiti in in questo articolo introduttivo, incluse le installazioni delle librerie temporaneamente necessarie per l'uso delle funzioni di intelligenza artificiale.
  • Anche se il modello sottostante può gestire diverse lingue, la maggior parte delle funzioni di intelligenza artificiale è ottimizzata per l'uso nei testi in lingua inglese.

Annotazioni

  • Questo articolo illustra la personalizzazione delle funzioni di intelligenza artificiale con PySpark. Per personalizzare le funzioni di intelligenza artificiale con pandas, vedere questo articolo.
  • Vedere tutte le funzioni di intelligenza artificiale in questo articolo di panoramica.

Configurations

Se si usano le funzioni di intelligenza artificiale in PySpark, è possibile usare la OpenAIDefaults classe per configurare il modello di intelligenza artificiale sottostante usato da tutte le funzioni. Le impostazioni che possono essere applicate solo per ogni chiamata di funzione sono specificate nella sezione seguente.

Parametro Description Impostazione predefinita
concurrency Valore int che definisce il numero massimo di righe da elaborare in parallelo con richieste asincrone al modello. I valori più elevati consentono di velocizzare il tempo di elaborazione (se la capacità può supportarla). Può essere configurato fino a 1.000. Questo valore deve essere impostato per ogni singola chiamata di funzione di intelligenza artificiale. In Spark questo valore di concorrenza è per ogni ruolo di lavoro. 50
deployment_name Valore stringa che definisce il nome del modello sottostante. È possibile scegliere tra i modelli supportati da Fabric. Questo valore può anche essere impostato su una distribuzione di modelli personalizzata in Azure OpenAI o Azure AI Foundry. Nel portale di Azure questo valore viene visualizzato inDistribuzioni del modello> risorse. Nel portale di Azure AI Foundry, il valore viene visualizzato nella pagina distribuzioni. gpt-4.1-mini
embedding_deployment_name Valore di tipo stringa che designa il nome della distribuzione del modello di embedding che alimenta le funzioni di intelligenza artificiale. text-embedding-ada-002
reasoning_effort Parte di OpenAIDefaults. Usato dai modelli di serie gpt-5 per il numero di token di ragionamento che devono usare. Può essere impostato su Nessuno o su un valore stringa "minimale", "basso", "medio" o "alto". None
subscription_key Chiave API usata per l'autenticazione con la risorsa LLM (Large Language Model). Nel portale di Azure, questo valore viene visualizzato nella sezione Chiavi ed endpoint. N/A
temperature Valore numerico compreso tra 0,0 e 1,0. Temperature più elevate aumentano la casualità o la creatività degli output del modello sottostante. 0.0
top_p Parte di OpenAIDefaults. Un numero float compreso tra 0 e 1. Un valore inferiore (ad esempio, 0,1) limita il modello a considerare solo i token più probabili, rendendo l'output più deterministico. Un valore più alto (ad esempio, 0,9) consente output più diversificati e creativi includendo una gamma più ampia di token. None
URL Una URL che indica l'endpoint della risorsa LLM. Nel portale di Azure, questo valore viene visualizzato nella sezione Chiavi ed endpoint. Ad esempio: https://your-openai-endpoint.openai.azure.com/. N/A
verbosity Parte di OpenAIDefaults. Usato dai modelli della serie GPT-5 per la lunghezza dell'output. Può essere impostato su Nessuno o su un valore stringa "low", "medium" o "high". None

L'esempio di codice seguente illustra come configurare concurrency per una singola chiamata di funzione.

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)

Nell'esempio di codice seguente viene illustrato come configurare il gpt-5 e altri modelli di ragionamento per tutte le funzioni.

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")

È possibile recuperare e stampare ognuno dei OpenAIDefaults parametri con l'esempio di codice seguente:

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

È anche possibile reimpostare i parametri con la stessa facilità con cui sono stati modificati. L'esempio di codice seguente reimposta la libreria di funzioni di intelligenza artificiale in modo che usi l'endpoint LLM di Fabric predefinito:

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

Modelli personalizzati

Scegliere un altro modello linguistico di grandi dimensioni supportato

Impostare deployment_name su uno dei modelli supportati da Fabric.

  • Globalmente nell'oggetto OpenAIDefaults() :

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

  • Singolarmente in ogni chiamata di funzione di intelligenza artificiale:

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

Scegliere un altro modello di incorporamento supportato

Impostare embedding_deployment_name su uno dei modelli supportati da Fabric quando si utilizzano le funzioni ai.embed o ai.similarity.

  • Globalmente nell'oggetto OpenAIDefaults() :

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

  • Singolarmente in ogni chiamata di funzione di intelligenza artificiale:

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

Configurare un endpoint modello personalizzato

Per impostazione predefinita, le funzioni di intelligenza artificiale usano l'API endpoint LLM di Fabric per la fatturazione unificata e la configurazione semplificata. È possibile scegliere di usare un endpoint modello personalizzato configurando un client compatibile con Azure OpenAI o AsyncOpenAI con l'endpoint e la chiave. L'esempio di codice seguente usa i valori segnaposto per illustrare come eseguire l'override dell'endpoint di intelligenza artificiale predefinito di Fabric con le proprie distribuzioni di modelli di risorse di Microsoft AI Foundry (in precedenza Azure OpenAI):

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>")

L'esempio di codice seguente usa i valori segnaposto per illustrare come eseguire l'override dell'endpoint di intelligenza artificiale di Fabric predefinito con una risorsa personalizzata di Microsoft AI Foundry per utilizzare modelli diversi da OpenAI.

Importante

  • Il supporto per i modelli di Microsoft AI Foundry è limitato ai modelli che supportano Chat Completions l'API e accettano response_format il parametro con lo schema JSON
  • L'output può variare a seconda del comportamento del modello di intelligenza artificiale selezionato. Esaminare le funzionalità di altri modelli con cautela appropriata
  • Le funzioni ai.embed di intelligenza artificiale basate sull'incorporamento e ai.similarity non sono supportate quando si usa una risorsa di 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")

Contenuti correlati

  • Last updated on