Funções de IA: Transforme dados à escala com LLMs

As Funções de IA no Microsoft Fabric aplicam transformações de uma linha, alimentadas por LLM, a grandes pandas ou DataFrames PySpark com uma única linha de códigodf.ai.<function_name>(). Funcionam com elevada concorrência ao fazer centenas de chamadas de inferência assíncronas, mantendo o isolamento de conteúdo ao nível da linha. Esta abordagem permite-lhe enriquecer, classificar, resumir e extrair dados rapidamente de textos e documentos não estruturados em grande escala.

Use esta tabela para saltar para exemplos nesta visão geral ou para documentação detalhada do pandas e do PySpark.

Function Description Documentação detalhada
ai.analyze_sentiment Detetar o estado emocional do texto de entrada. Exemplo. pandas, PySpark
ai.classify Categoriza o texto de entrada de acordo com os teus rótulos. Exemplo. pandas, PySpark
ai.embed Gerar embeddings vetoriais para texto de entrada. Exemplo. pandas, PySpark
ai.extract Extrair campos como localizações, nomes ou entidades personalizadas. Exemplo. pandas, PySpark
ai.fix_grammar Ortografia, gramática e pontuação corretas. Exemplo. pandas, PySpark
ai.generate_response Gera respostas com base nas tuas instruções. Exemplo. pandas, PySpark
ai.similarity Compare o significado do texto com um valor ou outra coluna. Exemplo. pandas, PySpark
ai.summarize Resume texto, ficheiros ou dados de linhas. Exemplo. pandas, PySpark
ai.translate Traduz o texto de entrada para outra língua. Exemplo. pandas, PySpark

Podes usar Funções de IA em cadernos com pandas ou PySpark, em consultas SQL e no Dataflow Gen2. O Fabric gere a configuração do ponto final para o modelo integrado.

Utilize Funções de IA em todas as experiências do Fabric

As funcionalidades de IA estão disponíveis em múltiplas experiências do Fabric:

Use funções de IA multimodais

As Funções de IA Multimodais processam imagens, PDFs e ficheiros de texto além dos valores de texto. Use-os para resumir PDFs, classificar imagens, extrair campos de documentos ou gerar respostas baseadas no conteúdo do ficheiro.

Os tipos de ficheiros suportados incluem JPG/JPEG, PNG, GIF estático, WebP, PDF, MD, TXT, CSV, TSV, JSON, XML, PY, e outros ficheiros de texto. Defina column_type="path" em pandas, ou input_col_type ou col_types em PySpark. Para exemplos, veja Usar entrada multimodal com Funções de IA.

Prerequisites

Note

  • As Funções de IA são suportadas em Fabric Runtime 1.3 e versões posteriores.
  • As Funções de IA [pandas, PySpark, Dataflow Gen2 e Datawarehouse SQL] utilizam por predefinição gpt-5-mini com reasoning_effort definido como low. Este modelo tem uma janela de contexto de 400.000 tokens e uma saída máxima de 128.000 tokens. Para limites e taxas dos modelos, consulte a tabela dos modelos de linguagem.
  • As Funções de IA não registam nem armazenam prompts do utilizador, dados de entrada ou saídas.

Modelos e fornecedores

As Funções de IA usam o endpoint Fabric incorporado por defeito. Também pode configurar o pandas e o PySpark AI Functions para utilizar qualquer LLM que suporte a API chat_completions ou a responses, incluindo:

  • Modelos Azure OpenAI.
  • Modelos Microsoft Foundry como Qwen, Kimi, Grok, LLaMA, Mistral e outros.

Para opções de configuração, consulte Personalizar Funções de IA com pandas e Personalizar Funções de IA com PySpark.

Configurar Funções de IA

As funções de IA suportam pandas nos ambientes de execução Python e PySpark, e PySpark no ambiente de execução do PySpark. Instala apenas os pacotes que o teu tempo de execução precisa.

Instalar dependências

Runtime Dependencies
pandas (runtime em Python) Instale os ficheiros wheel synapseml_internal e synapseml_core. Instale openai a versão 1.99.5 ou posterior apenas se precisar de comportamentos nativos do cliente SDK ou exemplos de formatos de resposta Pydantic.
pandas (Fabric Runtime 2.0 com PySpark 4.1 e Python 3.13) Instalar temporariamente nest_asyncio. Instale openai a versão 1.99.5 ou posterior apenas se precisar de comportamentos nativos do cliente SDK ou exemplos de formatos de resposta Pydantic.
pandas (outros tempos de execução PySpark) Não é necessária qualquer instalação para a maioria dos usos. Instale openai a versão 1.99.5 ou posterior apenas se precisar de comportamentos nativos do cliente SDK ou exemplos de formatos de resposta Pydantic.
PySpark (tempo de execução PySpark) Nenhuma instalação é necessária.

Note

  • Instalar nest_asyncio é uma correção temporária de compatibilidade para as funções de IA do pandas no Fabric Runtime 2.0. Este requisito será removido numa atualização futura.
  • As funções de IA do PySpark não requerem passos adicionais de instalação nos runtimes do Fabric Spark.

O Fabric Runtime 2.0, que é baseado em Python 3.13 e PySpark 4.1, não inclui nativamente o nest_asyncio pacote. Para usar as funções de IA do pandas neste tempo de execução, instale nest_asyncio como um patch de compatibilidade temporário. Nas futuras atualizações, este requisito será removido porque as Funções de IA do pandas podem usar o pacote nest_asyncio2, mais recente, que está pré-instalado no Fabric Runtime 2.0.

# Temporary compatibility patch for Fabric Runtime 2.0.
%pip install -q nest_asyncio 2>/dev/null

# Optional: install openai version 1.99.5 or later for SDK-native client behavior.
%pip install -q openai 2>/dev/null

Importar bibliotecas necessárias

Importe a biblioteca Funções de IA para o seu ambiente de execução.

# Required imports
import synapse.ml.aifunc as aifunc
import pandas as pd

Usar funções auxiliares para ficheiros e esquemas

As Funções de IA incluem auxiliares para fluxos de trabalho multimodais:

  • aifunc.load: Ingerir ficheiros de uma pasta para uma tabela estruturada. Podes fornecer um prompt ou esquema.
  • aifunc.list_file_paths: Enumerar URLs e caminhos de ficheiros a partir de uma pasta para serem usados como entrada em qualquer função de IA.
  • ai.infer_schema: Deduzir um esquema de extração a partir dos conteúdos do ficheiro para utilizar com ai.extract.

Para exemplos, veja Usar entrada multimodal com Funções de IA.

Aplicar Funções de IA

Os exemplos seguintes mostram as funções principais de IA para pandas e PySpark. As Funções de IA do PySpark funcionam como transformações Spark distribuídas entre clusters Fabric Spark.

Note

A maioria das funções de IA suporta caminhos de ficheiros com column_type="path" em pandas ou input_col_type/col_types="path" no PySpark. Para exemplos, veja Usar entrada multimodal com Funções de IA.

Tip

O modelo Python padrão é gpt-5-mini com reasoning_effort="low". Para alterar modelos ou configurações de afinação, veja configuração do pandas ou configuração do PySpark.

ai.analyze_sentiment: Detetar sentimento

A ai.analyze_sentiment função rotula cada entrada como positiva, negativa, mista ou neutra. Também pode fornecer etiquetas personalizadas.

# This code uses AI. Always review output for mistakes. 

df = pd.DataFrame([
        "The cleaning spray permanently stained my beautiful kitchen counter. Never again!",
        "I used this sunscreen on my vacation to Florida, and I didn't get burned at all. Would recommend.",
        "I'm torn about this speaker system. The sound was high quality, though it didn't connect to my roommate's phone.",
        "The umbrella is OK, I guess."
    ], columns=["reviews"])

df["sentiment"] = df["reviews"].ai.analyze_sentiment()
display(df)

Captura de ecrã de um quadro de dados com colunas

ai.classify: Categorizar texto

A ai.classify função categoriza o texto de entrada usando os rótulos que fornece.

# This code uses AI. Always review output for mistakes. 

df = pd.DataFrame([
        "This duvet, lovingly hand-crafted from all-natural fabric, is perfect for a good night's sleep.",
        "Tired of friends judging your baking? With these handy-dandy measuring cups, you'll create culinary delights.",
        "Enjoy this *BRAND NEW CAR!* A compact SUV perfect for the professional commuter!"
    ], columns=["descriptions"])

df["category"] = df['descriptions'].ai.classify("kitchen", "bedroom", "garage", "other")
display(df)

Captura de ecrã de uma moldura de dados com colunas 'descrições' e 'categoria'. A coluna «categoria» indica o nome da categoria de cada descrição.

ai.embed: Gerar embeddings vetoriais

A ai.embed função converte texto em vetores numéricos que captam significado semântico. Utilize representações vetoriais para pesquisa por similaridade, recuperação de informação e fluxos de trabalho de aprendizagem automática.

# This code uses AI. Always review output for mistakes. 

df = pd.DataFrame([
        "This duvet, lovingly hand-crafted from all-natural fabric, is perfect for a good night's sleep.",
        "Tired of friends judging your baking? With these handy-dandy measuring cups, you'll create culinary delights.",
        "Enjoy this *BRAND NEW CAR!* A compact SUV perfect for the professional commuter!"
    ], columns=["descriptions"])
    
df["embed"] = df["descriptions"].ai.embed()
display(df)

Captura de ecrã de um data frame com colunas 'descrições' e 'embed'. A coluna 'embed' contém vetores embed para as descrições.

ai.extract: Extrair entidades

A ai.extract função extrai campos como nomes, localizações ou entidades personalizadas do texto de entrada.

Rótulos estruturados

Use ExtractLabel quando precisar de extração tipada. Suporta construções de esquema JSON como campos tipados, enums, arrays, objetos aninhados, valores anuláveis, propriedades obrigatórias e additionalProperties=false. Para exemplos, veja pandas ou PySpark.

# This code uses AI. Always review output for mistakes. 

df = pd.DataFrame([
        "MJ Lee lives in Tucson, AZ, and works as a software engineer for Microsoft.",
        "Kris Turner, a nurse at NYU Langone, is a resident of Jersey City, New Jersey."
    ], columns=["descriptions"])

df_entities = df["descriptions"].ai.extract("name", "profession", "city")
display(df_entities)

Captura de tela mostrando um novo quadro de dados com as colunas 'nome', 'profissão' e 'cidade', contendo os dados extraídos do quadro de dados original.

ai.fix_grammar: Corrigir a gramática

A ai.fix_grammar função corrige a ortografia, gramática e pontuação.

# This code uses AI. Always review output for mistakes. 

df = pd.DataFrame([
        "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."
    ], columns=["text"])

df["corrections"] = df["text"].ai.fix_grammar()
display(df)

Captura de ecrã a mostrar uma moldura de dados com uma coluna 'texto' e uma coluna 'correções', que tem o texto da coluna de texto com gramática corrigida.

ai.generate_response: Aplicar instruções personalizadas do utilizador

A função ai.generate_response cria texto personalizado com base no seu prompt e nos dados da linha.

Parâmetros opcionais

Use response_format quando precisar de saída estruturada, incluindo objetos JSON, Esquema JSON ou modelos Pydantic. Para exemplos, veja pandas ou PySpark.

# This code uses AI. Always review output for mistakes. 

df = pd.DataFrame([
        ("Scarves"),
        ("Snow pants"),
        ("Ski goggles")
    ], columns=["product"])

df["response"] = df.ai.generate_response("Write a short, punchy email subject line for a winter sale.")
display(df)

Captura de ecrã a mostrar uma moldura de dados com as colunas 'produto' e 'resposta'. A coluna

ai.similarity: Calcular a similaridade

A ai.similarity função compara cada valor de entrada com um valor de referência ou com um valor noutra coluna. As pontuações variam desde -1 significado oposto até 1 significado idêntico.

# This code uses AI. Always review output for mistakes. 

df = pd.DataFrame([ 
        ("Bill Gates", "Technology"), 
        ("Satya Nadella", "Healthcare"), 
        ("Joan of Arc", "Agriculture") 
    ], columns=["names", "industries"])
    
df["similarity"] = df["names"].ai.similarity(df["industries"])
display(df)

Captura de ecrã de um quadro de dados com colunas 'nomes', 'indústrias' e 'semelhança'. A coluna

ai.summarize: Resume o texto

A ai.summarize função resume o texto, o conteúdo do ficheiro, uma única coluna ou todas as colunas de cada linha.

Personalização de resumos com instruções

Use instructions para controlar o tom, a duração, o público ou o foco. Para exemplos, veja pandas ou PySpark.

# This code uses AI. Always review output for mistakes.

df= pd.DataFrame([
        ("Microsoft Teams", "2017",
        """
        The ultimate messaging app for your organization—a workspace for real-time 
        collaboration and communication, meetings, file and app sharing, and even the 
        occasional emoji! All in one place, all in the open, all accessible to everyone.
        """),
        ("Microsoft Fabric", "2023",
        """
        An enterprise-ready, end-to-end analytics platform that unifies data movement, 
        data processing, ingestion, transformation, and report building into a seamless, 
        user-friendly SaaS experience. Transform raw data into actionable insights.
        """)
    ], columns=["product", "release_year", "description"])

df["summaries"] = df["description"].ai.summarize()
display(df)

Captura de tela mostrando um quadro de dados. A coluna «resumos» contém apenas um resumo da coluna «descrição», na linha correspondente.

ai.translate: Traduzir texto

A ai.translate função traduz texto para outra língua.

# This code uses AI. Always review output for mistakes. 

df = pd.DataFrame([
        "Hello! How are you doing today?", 
        "Tell me what you'd like to know, and I'll do my best to help.", 
        "The only thing we have to fear is fear itself."
    ], columns=["text"])

df["translations"] = df["text"].ai.translate("spanish")
display(df)

Captura de ecrã de uma moldura de dados com colunas 'texto' e 'traduções'. A coluna «traduções» contém o texto traduzido para espanhol.

Funções de IA do Chain PySpark

As funções de IA do PySpark devolvem DataFrames que mantêm o acessor df.ai associado ao esquema resultante. Transformações em cadeia sem materializar os DataFrames intermédios.

# This code uses AI. Always review output for mistakes.

output = (
    df
    .ai.summarize(input_col="review_text", output_col="summary")
    .ai.classify(
        labels=["service", "cleanliness", "location", "other"],
        input_col="summary",
        output_col="category",
    )
)
display(output)

Veja estatísticas de utilização com ai.stats

Use ai.stats numa série ou DataFrame gerada por IA para inspecionar métricas de utilização e execução.

ai.stats devolve um DataFrame com estatísticas como:

  • num_successful: Número de linhas processadas com sucesso pela função de IA.
  • num_exceptions: Número de linhas que encontraram uma exceção durante a execução. Estas linhas são representadas como instâncias de aifunc.ExceptionResult.
  • num_unevaluated: Número de linhas que não foram processadas porque uma exceção anterior tornou impossível continuar a avaliação. Estas linhas são representadas como instâncias de aifunc.NotEvaluatedResult.
  • num_harmful: Número de linhas bloqueadas pelo filtro de conteúdo do Azure OpenAI. Estas linhas são representadas como instâncias de aifunc.FilterResult.
  • cached_tokens: Número total de tokens de entrada em cache.
  • input_tokens: Número total de tokens de entrada usados para a chamada da função IA.
  • output_tokens: Número total de tokens de saída gerados pelo modelo.
  • reasoning_tokens: Número total de tokens de raciocínio usados pelos modelos de raciocínio.
  • model: Nome de implementação do modelo usado para a chamada de função de IA.

A saída pode ser esta tabela:

num_successful num_exceptions num_unevaluated num_harmful cached_tokens input_tokens output_tokens fatores_de_razonamento tipo_de_cliente input_types modelo
2 0 0 0 0 555 4 0 fabric_llm_endpoint {"text": 2} GPT-5-Mini

Tip

Use ai.stats para acompanhar o uso, padrões de erro e consumo de tokens.

As linhas que atingem limites de capacidade são apresentadas como instâncias de aifunc.CapacityExceededResult. Nos fluxos de trabalho do pandas, utiliza-se aifunc.split_results para separar resultados bem-sucedidos dos não-resultados, para que possa inspecionar linhas limitadas por capacidade e tentá-las novamente depois de a capacidade estar disponível ou o limite ser corrigido.

Transparência de custos

As funções de IA do pandas podem mostrar a contagem de tokens e estimativas de unidades de capacidade durante a execução com progress_bar_mode="stats". Para o PySpark, use df.ai.stats no resultado DataFrame.

A aplicação Fabric Capacity Metrics apresenta o consumo das chamadas ao modelo na operação Funções de IA. Para mais detalhes, consulte Faturação para Funções de IA.

Avaliar e acelerar

Utilize os AI Functions Starter Notebooks para exemplos completos em pandas e PySpark. Use os Cadernos de Avaliação de Funções de IA para avaliar a qualidade da saída antes da produção.