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

As funções de IA no Microsoft Fabric aplicam transformações de uma linha alimentadas por LLM em grandes pandas ou DataFrames PySpark com uma única linha de códigodf.ai.<function_name>(). Operam com alta concorrência, fazendo centenas de chamadas de inferência assíncronas e mantendo o isolamento de conteúdo no nível da linha. Essa abordagem permite que você enriqueça, classifique, resuma e extraia dados rapidamente de textos e documentos não estruturados em larga escala.

Use esta tabela para ir diretamente aos exemplos nesta visão geral ou na documentação detalhada do pandas e do PySpark.

Function Descrição Documentação detalhada
ai.analyze_sentiment Detecte o estado emocional do texto de entrada. Exemplo. pandas, PySpark
ai.classify Categorize o texto de entrada de acordo com seus rótulos. Exemplo. pandas, PySpark
ai.embed Gerar inserções de vetor para texto de entrada. Exemplo. pandas, PySpark
ai.extract Extraia campos como locais, nomes ou entidades personalizadas. Exemplo. pandas, PySpark
ai.fix_grammar Ortografia, gramática e pontuação corretas. Exemplo. pandas, PySpark
ai.generate_response Gere respostas com base em suas instruções. Exemplo. pandas, PySpark
ai.similarity Compare o significado do texto com um valor ou outra coluna. Exemplo. pandas, PySpark
ai.summarize Resumir texto, arquivos ou dados de linha. Exemplo. pandas, PySpark
ai.translate Traduza o texto de entrada em outro idioma. Exemplo. pandas, PySpark

Você pode usar as Funções de IA em notebooks com pandas ou PySpark, em consultas SQL e no Dataflow Gen2. O Fabric cuida da configuração do endpoint para o modelo integrado.

Use funções de IA em diferentes experiências do Fabric

As funções de IA estão disponíveis em várias experiências de Fabric:

Usar funções de IA multimodal

O Multimodal AI Functions processa imagens, PDFs e arquivos de texto, além de valores de texto. Use-os para resumir PDFs, classificar imagens, extrair campos de documento ou gerar respostas fundamentadas no conteúdo do arquivo.

Os tipos de arquivo com suporte incluem JPG/JPEG, PNG, GIF estático, WebP, PDF, MD, TXT, CSV, TSV, JSON, XML, PY e outros arquivos de texto. Defina column_type="path" no pandas, ou input_col_type ou col_types no PySpark. Para obter exemplos, consulte Usar entrada multimodal com o AI Functions.

Prerequisites

Note

  • As funções de IA têm suporte no Fabric Runtime 1.3 e posterior.
  • Funções de IA [pandas, PySpark, Dataflow Gen2 e Datawarehouse SQL] têm por padrão gpt-5-mini com reasoning_effort definido como low. Esse modelo tem uma janela de contexto de 400.000 tokens e uma saída máxima de 128.000 tokens. Para obter limites e taxas de modelo, consulte a tabela de modelos de linguagem.
  • As Funções de IA não registram nem armazenam prompts de usuário, dados de entrada ou saídas.

Modelos e provedores

As Funções de IA usam o endpoint interno do Fabric por padrão. Você também pode configurar o pandas e o PySpark AI Functions para usar qualquer LLM compatível com a API chat_completions ou responses, incluindo:

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

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

Configurar funções de IA

O AI Functions oferece suporte ao pandas nos ambientes de execução Python e PySpark, e ao PySpark no ambiente de execução PySpark. Instale apenas os pacotes necessários para o runtime.

Instalar dependências

Tempo de execução Dependencies
pandas (ambiente de execução do Python) Instale os arquivos wheel synapseml_internal e synapseml_core. Instale a versão 1.99.5 ou posterior de openai somente se você precisar do comportamento nativo do cliente do SDK ou de exemplos de formato de resposta do Pydantic.
pandas (Fabric Runtime 2.0 com PySpark 4.1 e Python 3.13) Instale temporariamente nest_asyncio. Instale a versão 1.99.5 ou posterior de openai somente se você precisar do comportamento nativo do cliente do SDK ou de exemplos de formato de resposta do Pydantic.
pandas (outros tempos de execução do PySpark) Nenhuma instalação é necessária para a maioria dos usos. Instale a versão 1.99.5 ou posterior de openai somente se você precisar do comportamento nativo do cliente do SDK ou de exemplos de formato de resposta do Pydantic.
PySpark (runtime do 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. Esse requisito será removido em uma atualização futura.
  • As funções de IA do PySpark não exigem etapas adicionais de instalação nos runtimes do Fabric Spark.

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 temporário de compatibilidade. Em futuras atualizações, esse requisito será removido porque as Funções de IA do pandas podem usar o pacote mais novonest_asyncio2, 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 AI Functions para o ambiente de execução.

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

Usar funções auxiliares para arquivos e esquemas

As funções de IA incluem auxiliares para fluxos de trabalho multimodal:

  • aifunc.load: ingerir arquivos de uma pasta em uma tabela estruturada. Você pode fornecer um prompt ou esquema.
  • aifunc.list_file_paths: enumerar URLs de arquivo e caminhos de uma pasta para uso como entrada para qualquer função de IA.
  • ai.infer_schema: inferir um esquema de extração do conteúdo do arquivo para uso com ai.extract.

Para obter exemplos, consulte Usar entrada multimodal com o AI Functions.

Aplicar funções de IA

Os exemplos a seguir mostram as principais funções de IA para pandas e PySpark. PySpark AI Functions são executadas como transformações distribuídas do Spark em clusters do Fabric Spark.

Note

A maioria das funções de IA dá suporte a caminhos de arquivo com column_type="path" no Pandas ou input_col_type/col_types="path" no PySpark. Para obter exemplos, consulte Usar entrada multimodal com o AI Functions.

Tip

O modelo de Python padrão é gpt-5-mini com reasoning_effort="low". Para alterar modelos ou ajustar as configurações, consulte a configuração do Pandas ou a configuração do PySpark.

ai.analyze_sentiment: detectar sentimento

A ai.analyze_sentiment função rotula cada entrada como positiva, negativa, mista ou neutra. Você também pode fornecer rótulos personalizados.

# 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 tela 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 fornecidos.

# 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 tela de um quadro de dados com colunas

ai.embed: gerar inserções de vetor

A ai.embed função converte texto em vetores numéricos que capturam significado semântico. Use embeddings em buscas por similaridade, recuperação e fluxos de trabalho de aprendizado de máquina.

# 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 tela de um quadro de dados com as colunas 'descriptions' e 'inserção'. A coluna 'inserção' contém vetores de inserção para as descrições.

ai.extract: Extrair entidades

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

Rótulos estruturados

Use ExtractLabel quando precisar de extração tipada. Ele dá suporte a constructos de esquema JSON, como campos tipados, enumerações, matrizes, objetos aninhados, valores anuláveis, propriedades necessárias e additionalProperties=false. Para obter exemplos, consulte 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 'name', 'profession' e 'city', contendo os dados extraídos do quadro de dados original.

ai.fix_grammar: Corrigir gramática

A ai.fix_grammar função corrige 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 tela mostrando um quadro de dados com uma coluna 'text' e uma coluna 'correções', que tem o texto da coluna de texto com gramática corrigida.

ai.generate_response: Aplicar solicitações do usuário personalizadas

A função ai.generate_response cria texto personalizado a partir do seu prompt e dos dados da linha.

Parâmetros opcionais

Use response_format quando precisar de saída estruturada, incluindo objetos JSON, esquema JSON ou modelos Pydantic. Para obter exemplos, consulte 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 tela mostrando um quadro de dados com as colunas 'product' e 'response'. A coluna 'response' contém uma linha de assunto forte para o produto.

ai.similarity: Calcular similaridade

A ai.similarity função compara cada valor de entrada com um valor de referência ou com um valor em outra coluna. As pontuações variam de -1, para significado oposto, a 1, para 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 tela de um quadro de dados com as colunas 'names', 'industries' e 'similaridade'. A coluna

ai.summarize: resumir texto

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

Personalizando resumos com instruções

Use instructions para controlar o tom, o comprimento, a audiência ou o foco. Para obter exemplos, consulte 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 'summaries' tem apenas um resumo da coluna 'description', na linha correspondente.

ai.translate: traduzir texto

A ai.translate função converte o texto em outro idioma.

# 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 tela de um quadro de dados com as colunas 'text' e 'translations'. A coluna 'traduções' contém o texto traduzido para espanhol.

Encadear funções de IA do PySpark

As funções de IA do PySpark retornam DataFrames que mantêm o acessor df.ai vinculado ao esquema resultante. Transformações de cadeia sem materializar DataFrames intermediários.

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

Exibir estatísticas de uso com ai.stats

Use ai.stats em uma Série ou DataFrame gerada por IA para inspecionar as métricas de uso e execução.

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

  • num_successful: número de linhas processadas com êxito pela função de IA.
  • num_exceptions: número de linhas que encontraram uma exceção durante a execução. Essas 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 impossibilitaria continuar a avaliação. Essas linhas são representadas como instâncias de aifunc.NotEvaluatedResult.
  • num_harmful: número de linhas bloqueadas pelo filtro de conteúdo Azure OpenAI. Essas linhas são representadas como instâncias de aifunc.FilterResult.
  • cached_tokens: número total de tokens de entrada armazenados em cache.
  • input_tokens: número total de tokens de entrada usados para a chamada de função de 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 da implantação do modelo usado na chamada de função de IA.

A saída pode ser semelhante a esta tabela:

num_successful num_exceptions num_unevaluated num_harmful cached_tokens input_tokens output_tokens reasoning_tokens client_type input_types modelo
2 0 0 0 0 555 4 0 fabric_llm_endpoint {"text": 2} gpt-5-mini

Tip

Use ai.stats para controlar o uso, os padrões de erro e o consumo de token.

As linhas que atingem os limites de capacidade são exibidas como instâncias de aifunc.CapacityExceededResult. Nos fluxos de trabalho do pandas, use aifunc.split_results para separar saídas bem-sucedidas de resultados não obtidos, para que você possa inspecionar as linhas afetadas por limite de capacidade e tentar novamente depois que houver capacidade disponível ou que o limite tiver sido resolvido.

Transparência de custos

Pandas AI Functions pode mostrar contagens de tokens e estimativas de unidades de capacidade durante a execução usando progress_bar_mode="stats". Para o PySpark, use df.ai.stats no DataFrame de resultado.

O aplicativo Fabric Capacity Metrics informa o consumo de chamadas ao modelo como a operação AI Functions. Para obter detalhes, consulte Cobrança para funções de IA.

Avaliar e acelerar

Use os Starter Notebooks do AI Functions para exemplos completos com pandas e PySpark. Use os notebooks de avaliação das funções de IA para avaliar a qualidade dos resultados antes de entrar em produção.