Como Usar o Semantic Kernel: Um Guia Prático com Padrões, Prompts e Plugins
Já tentou conectar um LLM ao seu aplicativo e acabou com um emaranhado frágil de prompts, funções auxiliares e estado? O Semantic Kernel (SK) existe para corrigir exatamente isso. É um framework de orquestração leve e de código aberto da Microsoft para construir aplicativos com prioridade em IA que combinam linguagem natural, ferramentas e memória—sem transformar sua base de código em um emaranhado de prompts.
Neste guia, faremos um tour prático e orientado para soluções sobre como usar o Semantic Kernel do zero aos padrões de produção. Você aprenderá como estruturar prompts, conectar ferramentas, adicionar memória, chamar vários modelos e implantar agentes que atuam de forma consistente. Manteremos os exemplos fundamentados e mostraremos o que importa.
O Que É Semantic Kernel—e Por Que Usá-lo?
O Semantic Kernel é um SDK que ajuda você a:
- Compor prompts e funções ("skills"/plugins) em pipelines.
- Chamar vários modelos (OpenAI, Azure OpenAI, modelos locais) de forma intercambiável.
- Adicionar memória para contexto e recordação de longo prazo via embeddings.
- Planejar e orquestrar tarefas de várias etapas com estado confiável.
- Integrar ferramentas (APIs, bancos de dados, E/S de arquivo) com segurança e deterministicamente.
Pense no SK como o controlador que coordena LLMs, a lógica do seu aplicativo e os dados do usuário. Em vez de codificar prompts longos e chamadas de ferramentas ad hoc, você define funções semânticas reutilizáveis e funções nativas com entradas/saídas claras.
Casos de uso comuns:
- Copilotos de suporte ao cliente com geração aumentada por recuperação (RAG)
- Agentes de fluxo de trabalho (resumir → classificar → tomar medidas)
- Q&A de documentos com memória e citações
- Pipelines de geração de conteúdo criativo e código
Início Rápido: Seu Primeiro Aplicativo Semantic Kernel
Abaixo está um fluxo mínimo para mostrar como usar o Semantic Kernel com um modelo de chat e um prompt simples. Usaremos C# para clareza; você pode fazer o mesmo em Python ou Java.
1) Instale os pacotes
# .NET
dotnet add package Microsoft.SemanticKernel
# Opcional: conectores e planejadores variam de acordo com a versão
2) Configure o kernel e o modelo
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
var builder = Kernel.CreateBuilder;
// Escolha seu provedor: OpenAI ou Azure OpenAI
builder.AddOpenAIChatCompletion(
modelId: "gpt-4o-mini", // ou seu modelo preferido
apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")
);
var kernel = builder.Build;
3) Defina uma função semântica (prompt)
using Microsoft.SemanticKernel.SemanticFunctions;
var prompt = @"Você é um explicador conciso.
Explique o conceito de '{topic}' em 3 tópicos para um iniciante.";
var explainFunc = kernel.CreateFunctionFromPrompt(prompt);
var result = await explainFunc.InvokeAsync(kernel, new { ["topic"] = "vector embeddings" });
Console.WriteLine(result);
Este é o núcleo: um kernel, um modelo e um prompt transformado em uma função reutilizável com entradas.
Funções Semânticas vs. Funções Nativas
- Funções semânticas: Impulsionadas por prompt. Você as cria a partir de templates, passa variáveis e obtém texto ou saídas estruturadas.
- Funções nativas: Funções de código regulares que o SK expõe ao LLM para uso de ferramentas.
Exemplo de função nativa que busca o clima da sua API e o expõe ao modelo:
public class WeatherPlugin
{
[KernelFunction, Description("Obter o clima para uma cidade")]
public async Task<string> GetWeatherAsync(
[Description("Nome da cidade")] string city)
{
// Chame sua API de clima aqui
var temp = 22; // placeholder
return $"Clima em {city}: {temp}°C e claro";
}
}
// Registrar plugin
var weather = new WeatherPlugin;
kernel.Plugins.AddFromObject(weather, pluginName: "weather");
Agora seus prompts podem chamar weather.GetWeatherAsync como uma ferramenta, permitindo que o modelo baseie as respostas em dados reais.
Padrões de Prompt Que Realmente Funcionam
Ao aprender como usar o Semantic Kernel, as vitórias mais rápidas vêm de padrões de prompt disciplinados:
- Sistema primeiro: Use uma mensagem de sistema forte para bloquear tom, persona, segurança e formato de saída.
- Slots de variáveis: Nomeie os placeholders claramente (por exemplo,
{topic}, {audience}) e valide a entrada.
- Contratos de saída: Peça formatos estruturados como JSON; inclua um schema no prompt.
- Few-shot: Forneça exemplos concisos para estilo e formato, não inchaço de conteúdo.
- Guardrails: Inclua restrições (“Se faltarem dados, faça uma pergunta esclarecedora primeiro”).
Exemplo de prompt estruturado dentro do SK:
var prompt = @"
Você é um motor de classificação.
Tarefa: Classifique a `message` em um de [Faturamento, Suporte Técnico, Vendas].
Retorne JSON estrito: { \"label\": string, \"confidence\": number }
message: {message}
";
var classify = kernel.CreateFunctionFromPrompt(prompt);
var output = await classify.InvokeAsync(kernel, new { ["message"] = "Não consigo fazer login na minha conta." });
Console.WriteLine(output); // {"label":"Tech Support","confidence":0.89}
Adicionando Memória: Embeddings, RAG e Janelas de Contexto
LLMs esquecem. A memória os torna úteis.
- Contexto de curto prazo: Automático via histórico de conversas.
- Memória de longo prazo: Armazene embeddings de notas de usuário, documentos ou eventos e recupere chunks relevantes para contexto.
- RAG: Antes de chamar uma função de geração, consulte seu armazenamento de vetores e injete os resultados no prompt.
Exemplo: adicione memória de texto com embeddings e recupere o contexto.
using Microsoft.SemanticKernel.Memory;
var memory = new MemoryBuilder
.WithMemoryStore(new VolatileMemoryStore) // troque por um DB de vetores (Qdrant, Pinecone, Azure AI Search)
.WithTextEmbeddingGeneration(
new OpenAITextEmbeddingGeneration("text-embedding-3-small", Environment.GetEnvironmentVariable("OPENAI_API_KEY")))
.Build;
await memory.SaveInformationAsync(
collection: "policies", id: "refund-policy",
text: "Clientes podem solicitar um reembolso dentro de 30 dias da compra com comprovante de recebimento."
);
// Mais tarde: recuperar e inserir no prompt
var results = memory.SearchAsync("refund window", collection: "policies", limit: 3, minRelevanceScore: 0.7);
await foreach (var item in results)
{
Console.WriteLine($"Relevante: {item.Metadata.Text}");
}
Em seguida, alimente as principais correspondências em sua função semântica como variáveis de contexto. Dica: mantenha os chunks pequenos (200–400 tokens) e deduplique.
Uso de Ferramentas e Planejamento: Fluxos de Trabalho de Várias Etapas
O Semantic Kernel suporta planejadores que podem dividir um objetivo do usuário em etapas e escolher quais funções chamar. Isso é perfeito quando você tem uma caixa de ferramentas de funções nativas e semânticas.
Padrão:
- Colete o objetivo e as restrições do usuário.
- Elabore um plano (sequência de chamadas de função com argumentos).
- Execute passo a passo, verifique as saídas e recupere-se de erros.
Exemplo de pseudocódigo:
// 1) Defina plugins (semânticos + nativos) como antes
// 2) Use um planejador (a superfície da API pode variar de acordo com a versão)
var goal = "Resuma a política anexada, classifique o risco e envie um relatório por e-mail";
// Suponha que temos plugins: arquivos, resumir, classificar, e-mail
// O planejador montará um plano: files.Load → summarize.Run → classify.Run → email.Send
// Execute o plano sequencialmente, valide as saídas JSON entre as etapas
Melhores práticas:
- Torne as etapas idempotentes e testáveis.
- Defina schemas de saída explícitos entre as etapas.
- Use repetições/backoff em ferramentas de rede.
- Registre entradas/saídas para observabilidade (mas limpe PII).
Estratégia Multi-Modelo: Escolha o Modelo Certo para o Trabalho
Usando o Semantic Kernel, você pode rotear tarefas para diferentes modelos:
- Rascunhos rápidos → modelos pequenos e baratos
- Etapas com uso intensivo de raciocínio → modelos maiores
- Embeddings → modelo de embedding especializado
- Código → modelos otimizados para código
Na prática:
var kernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey)
.Build;
var fastKernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey) // otimizado para velocidade
.Build;
// Roteie prompts mais simples para fastKernel; tarefas complexas para kernel
Ou, configure vários serviços no mesmo kernel e selecione por função.
Do Protótipo à Produção: Guardrails e Testes
À medida que você aprende como usar o Semantic Kernel em aplicativos reais, a confiabilidade é importante:
- Saídas com schema primeiro: Use schemas JSON e gates
TryParse.
- Determinismo quando necessário: Defina a temperatura baixa e restrinja as saídas.
- Filtros de segurança: Adicione filtros de conteúdo e prompts de red-team.
- Caching: Faça cache dos resultados do RAG e das gerações estáveis.
- Observabilidade: Registre templates de prompt, variáveis, latência, uso de tokens.
- Testes de unidade: Teste prompts dourados com comparações de snapshot.
Exemplo: valide a saída JSON.
record Classification(string label, double confidence);
bool TryParseClassification(string text, out Classification cls)
{
try { cls = System.Text.Json.JsonSerializer.Deserialize<Classification>(text)!; return true; }
catch { cls = default!; return false; }
}
Padrões do Mundo Real Que Você Pode Reutilizar
- Chatbot RAG:
retrieve(context) → answer(question, context) com citações.
- Fluxos de trabalho de aprovação: classificar → gerar rascunho → revisão humana → enviar.
- Operações de conteúdo: delinear → rascunhar → verificar fatos → ajustar o tom → publicar.
- Agente com ferramentas: calendar.lookup, docs.search, email.send; com planejamento e memória.
Dica: Encapsule cada etapa como uma função (semântica ou nativa) e componha-as em pipelines.
Exemplo: Q&A de Documentos com Citações
Vamos conectar um pipeline de Q&A simples que cita fontes usando RAG.
// 1) Ingerir documentos na memória
await memory.SaveInformationAsync("handbook", "vacation-policy",
"Funcionários acumulam 1,5 dias de PTO por mês e podem transferir 5 dias.");
// 2) Recuperar o contexto para uma pergunta
var top = memory.SearchAsync("carry over PTO", "handbook", limit: 3, minRelevanceScore: 0.75);
var contexts = new List<string>;
await foreach (var r in top) contexts.Add(r.Metadata.Text);
// 3) Pergunte com contexto e solicite citações
var qaPrompt = @"
Você responde estritamente a partir do contexto fornecido. Se estiver faltando, diga que não sabe.
Inclua citações inline como [fonte i] usando o índice de itens de contexto começando em 1.
Contexto:
1) {{ctx1}}
2) {{ctx2}}
Pergunta: {{q}}
";
var qa = kernel.CreateFunctionFromPrompt(qaPrompt);
var variables = new KernelArguments
{
["ctx1"] = contexts.ElementAtOrDefault(0) ?? "",
["ctx2"] = contexts.ElementAtOrDefault(1) ?? "",
["q"] = "Quantos dias de PTO posso transferir?"
};
var answer = await qa.InvokeAsync(kernel, variables);
Console.WriteLine(answer);
Armadilhas Comuns (e Como Evitá-las)
- Prompt gigante único: Divida em funções; passe apenas o contexto que você precisa.
- Sem contratos de saída: Sempre defina schemas para etapas legíveis por máquina.
- RAG sem higiene: Divida bem, deduplique e classifique por relevância e atualidade.
- Proliferação de ferramentas: Mantenha as interfaces de plugin pequenas e documentadas.
- Sem humano no circuito: Adicione aprovações para ações de alto risco.
Como Usar o Semantic Kernel com Frontends
- Aplicativos web: Hospede sua orquestração SK em uma camada de API; transmita tokens para a UI.
- UIs de chat: Mantenha o estado da conversa no lado do servidor; poda e resuma.
- Autenticação: Chamadas seguras de representação—nunca deixe o modelo cunhar tokens. Controle as chamadas de ferramentas através do seu backend.
Lista de Verificação de Implantação
- Variáveis de ambiente para chaves e endpoints
- Limitação de taxa e repetições para chamadas de modelo/ferramenta
- Controle de versão do template de prompt
- Backups do armazenamento de vetores e tratamento de PII
- Painéis de observabilidade (latência, custo, erros)
- Testes A/B para prompts e roteamento
Solução de Problemas no Estilo FAQ
- “O modelo alucina mesmo com RAG.” Aperte as instruções: "Responda apenas do contexto" e inclua um exemplo de recusa. Aumente a especificidade da recuperação e reduza a temperatura.
- “O JSON continua quebrando.” Adicione um mini exemplo de JSON válido e proíba comentários. Pós-valide e reformule em caso de falha.
- “A latência está alta.” Recupere menos chunks, mais relevantes; troque etapas simples para modelos menores; paralelize etapas independentes.
- “Os custos estão disparando.” Faça cache, comprima o contexto e roteie tarefas fáceis para modelos mais baratos.
Vale a Pena Notar: Construa Mais Rápido com Sider.AI
Se você estiver prototipando prompts, testando fluxos de ferramentas ou comparando respostas entre modelos, um companheiro como Sider.ai pode acelerar a iteração. Você pode elaborar prompts, executar comparações A/B e capturar snippets reutilizáveis antes de movê-los para templates do Semantic Kernel—ótimo para aprimorar instruções e schemas de saída. Próximos Passos: Transforme Isso em um Agente de Trabalho
- Comece com uma tarefa clara (por exemplo, classificar e-mails de suporte).
- Defina funções semânticas/nativas com entradas/saídas estritas.
- Adicione memória apenas onde ela melhora mensuravelmente as respostas.
- Instrumente tudo; teste com amostras do mundo real.
- Itere nos prompts usando um sandbox, então codifique no SK.
Principais conclusões:
- O Semantic Kernel ajuda você a compor prompts, ferramentas e memória em fluxos de trabalho confiáveis.
- Use schemas de saída, planejadores e roteamento multi-modelo para robustez e controle de custos.
- RAG mais guardrails vence prompts gigantes todas as vezes.
Depois de dominar como usar o Semantic Kernel com esses padrões, você enviará recursos de IA que não são apenas demos impressionantes—mas sistemas confiáveis.
FAQ
Q1: Para que é usado o Semantic Kernel em aplicativos de IA?
O Semantic Kernel é um SDK de orquestração para construir fluxos de trabalho de IA que combinam prompts LLM, ferramentas (funções nativas) e memória. Ele ajuda você a estruturar tarefas, adicionar RAG e chamar vários modelos de forma confiável.
Q2: Como uso o Semantic Kernel para RAG com meus documentos?
Ingira seus documentos em um armazenamento de vetores por meio das APIs de memória do SK, então recupere os chunks mais relevantes por consulta e injete-os em seu prompt. Isso melhora a precisão e reduz as alucinações.
Q3: O Semantic Kernel pode chamar APIs e serviços externos?
Sim. Envolva APIs como funções nativas em um plugin e registre-as no kernel para que o modelo possa usá-las como ferramentas. Mantenha as interfaces pequenas e aplique a validação de entrada/saída.
Q4: Quais modelos funcionam com o Semantic Kernel?
O Semantic Kernel suporta OpenAI, Azure OpenAI e outros conectores. Você pode rotear tarefas para diferentes modelos—por exemplo, modelos menores para rascunhos e modelos maiores para etapas com uso intensivo de raciocínio.
Q5: Como torno as saídas do Semantic Kernel consistentes (por exemplo, JSON)?
Use prompts estruturados que exigem JSON estrito e inclua um exemplo ou schema mínimo. Defina uma temperatura baixa, valide as saídas pós-chamada e repita ou repare quando a análise falhar.