O que são plug-ins de pesquisa de texto do kernel semântico?

Artigo
11/03/2024

O Semantic Kernel usa plug-ins para conectar APIs existentes com IA. Esses plug-ins têm funções que podem ser usadas para adicionar dados ou exemplos relevantes aos prompts ou para permitir que a IA execute ações automaticamente.

Para integrar a Pesquisa de Texto com o Kernel Semântico, precisamos transformá-la em um Plugin. Assim que tivermos um plug-in de pesquisa de texto, podemos usá-lo para adicionar informações relevantes aos prompts ou recuperar informações conforme necessário. Criar um plugin a partir da Pesquisa de Texto é um processo simples, que explicaremos a seguir.

Dica

Para executar os exemplos mostrados nesta página, acesse GettingStartedWithTextSearch/Step2_Search_For_RAG.cs.

Plugin de pesquisa básica

O Kernel Semântico fornece uma implementação de modelo padrão que dá suporte à substituição de variáveis e à chamada de função. Ao incluir uma expressão como {{MyPlugin.Function $arg1}} em um modelo de prompt, a função especificada, ou seja, MyPlugin.Function será invocada com o argumento arg1 fornecido (que é resolvido a partir de KernelArguments). O valor retornado da invocação da função é inserido no prompt. Essa técnica pode ser usada para injetar informações relevantes em um prompt.

O exemplo abaixo mostra como criar um plug-in nomeado SearchPlugin a partir de uma instância do BingTextSearch. O uso CreateWithSearch cria um novo plug-in com uma única Search função que chama a implementação de pesquisa de texto subjacente. O SearchPlugin é adicionado ao que o torna disponível para ser chamado durante a Kernel renderização imediata. O modelo de prompt inclui uma chamada para {{SearchPlugin.Search $query}} a qual invocará o SearchPlugin para recuperar resultados relacionados à consulta atual. Os resultados são inseridos no prompt renderizado antes de serem enviados para o modelo de IA.

using Microsoft.SemanticKernel.Data;
using Microsoft.SemanticKernel.Plugins.Web.Bing;

// Create a kernel with OpenAI chat completion
IKernelBuilder kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddOpenAIChatCompletion(
        modelId: "gpt-4o",
        apiKey: "<Your OpenAI API Key>");
Kernel kernel = kernelBuilder.Build();

// Create a text search using Bing search
var textSearch = new BingTextSearch(apiKey: "<Your Bing API Key>");

// Build a text search plugin with Bing search and add to the kernel
var searchPlugin = textSearch.CreateWithSearch("SearchPlugin");
kernel.Plugins.Add(searchPlugin);

// Invoke prompt and use text search plugin to provide grounding information
var query = "What is the Semantic Kernel?";
var prompt = "{{SearchPlugin.Search $query}}. {{$query}}";
KernelArguments arguments = new() { { "query", query } };
Console.WriteLine(await kernel.InvokePromptAsync(prompt, arguments));

Plugin de pesquisa com citações

O exemplo abaixo repete o padrão descrito na seção anterior com algumas alterações notáveis:

CreateWithGetTextSearchResults é usado para criar um SearchPlugin que chama o GetTextSearchResults método da implementação de pesquisa de texto subjacente.
O modelo de prompt usa a sintaxe Handlebars. Isso permite que o modelo itere sobre os resultados da pesquisa e renderize o nome, o valor e o link para cada resultado.
O prompt inclui uma instrução para incluir citações, portanto, o modelo de IA fará o trabalho de adicionar citações à resposta.

using Microsoft.SemanticKernel.Data;
using Microsoft.SemanticKernel.PromptTemplates.Handlebars;
using Microsoft.SemanticKernel.Plugins.Web.Bing;

// Create a kernel with OpenAI chat completion
IKernelBuilder kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddOpenAIChatCompletion(
        modelId: "gpt-4o",
        apiKey: "<Your OpenAI API Key>");
Kernel kernel = kernelBuilder.Build();

// Create a text search using Bing search
var textSearch = new BingTextSearch(apiKey: "<Your Bing API Key>");

// Build a text search plugin with Bing search and add to the kernel
var searchPlugin = textSearch.CreateWithGetTextSearchResults("SearchPlugin");
kernel.Plugins.Add(searchPlugin);

// Invoke prompt and use text search plugin to provide grounding information
var query = "What is the Semantic Kernel?";
string promptTemplate = """
{{#with (SearchPlugin-GetTextSearchResults query)}}  
    {{#each this}}  
    Name: {{Name}}
    Value: {{Value}}
    Link: {{Link}}
    -----------------
    {{/each}}  
{{/with}}  

{{query}}

Include citations to the relevant information where it is referenced in the response.
""";
KernelArguments arguments = new() { { "query", query } };
HandlebarsPromptTemplateFactory promptTemplateFactory = new();
Console.WriteLine(await kernel.InvokePromptAsync(
    promptTemplate,
    arguments,
    templateFormat: HandlebarsPromptTemplateFactory.HandlebarsTemplateFormat,
    promptTemplateFactory: promptTemplateFactory
));

Plugin de pesquisa com filtro

As amostras mostradas até agora usarão os resultados de pesquisa na web mais bem classificados para fornecer os dados de base. Para fornecer mais confiabilidade nos dados, a pesquisa na web pode ser restrita a retornar apenas resultados de um site especificado.

O exemplo abaixo se baseia no anterior para adicionar filtragem dos resultados da pesquisa. Uma TextSearchFilter cláusula com uma igualdade é usada para especificar que somente os resultados do site Microsoft Developer Blogs (site == 'devblogs.microsoft.com') devem ser incluídos nos resultados da pesquisa.

O exemplo usa KernelPluginFactory.CreateFromFunctions para criar o SearchPlugin. Uma descrição personalizada é fornecida para o plug-in. O ITextSearch.CreateGetTextSearchResults método de extensão é usado para criar o KernelFunction que invoca o serviço de pesquisa de texto.

Dica

O site filtro é específico do Bing. Para pesquisa na web do Google, use siteSearch.

using Microsoft.SemanticKernel.Data;
using Microsoft.SemanticKernel.Plugins.Web.Bing;

// Create a kernel with OpenAI chat completion
IKernelBuilder kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddOpenAIChatCompletion(
        modelId: "gpt-4o",
        apiKey: "<Your OpenAI API Key>");
Kernel kernel = kernelBuilder.Build();

// Create a text search using Bing search
var textSearch = new BingTextSearch(apiKey: "<Your Bing API Key>");

// Create a filter to search only the Microsoft Developer Blogs site
var filter = new TextSearchFilter().Equality("site", "devblogs.microsoft.com");
var searchOptions = new TextSearchOptions() { Filter = filter };

// Build a text search plugin with Bing search and add to the kernel
var searchPlugin = KernelPluginFactory.CreateFromFunctions(
    "SearchPlugin", "Search Microsoft Developer Blogs site only",
    [textSearch.CreateGetTextSearchResults(searchOptions: searchOptions)]);
kernel.Plugins.Add(searchPlugin);

// Invoke prompt and use text search plugin to provide grounding information
var query = "What is the Semantic Kernel?";
string promptTemplate = """
{{#with (SearchPlugin-GetTextSearchResults query)}}  
    {{#each this}}  
    Name: {{Name}}
    Value: {{Value}}
    Link: {{Link}}
    -----------------
    {{/each}}  
{{/with}}  

{{query}}

Include citations to the relevant information where it is referenced in the response.
""";
KernelArguments arguments = new() { { "query", query } };
HandlebarsPromptTemplateFactory promptTemplateFactory = new();
Console.WriteLine(await kernel.InvokePromptAsync(
    promptTemplate,
    arguments,
    templateFormat: HandlebarsPromptTemplateFactory.HandlebarsTemplateFormat,
    promptTemplateFactory: promptTemplateFactory
));

Dica

Siga o link para obter mais informações sobre como filtrar as respostas que o Bing retorna.

Plugin de pesquisa personalizado

No exemplo anterior, um filtro de site estático foi aplicado às operações de pesquisa. E se você precisar que esse filtro seja dinâmico?

O próximo exemplo mostra como você pode executar mais personalização do SearchPlugin para que o valor do filtro possa ser dinâmico. O exemplo usa KernelFunctionFromMethodOptions para especificar o seguinte para o SearchPlugin:

FunctionName: A função de pesquisa é nomeada GetSiteResults porque aplicará um filtro de site se a consulta incluir um domínio.
Description: A descrição descreve como essa função de pesquisa especializada funciona.
Parameters: Os parâmetros incluem um parâmetro opcional adicional para o site para que o domínio possa ser especificado.

A personalização da função de pesquisa é necessária se você deseja fornecer várias funções de pesquisa especializadas. Nos prompts, você pode usar os nomes das funções para tornar o modelo mais legível. Se você usar a chamada de função, o modelo usará o nome e a descrição da função para selecionar a melhor função de pesquisa a ser invocada.

Quando esse exemplo for executado, a resposta usará techcommunity.microsoft.com como fonte de dados relevantes.

using Microsoft.SemanticKernel.Data;
using Microsoft.SemanticKernel.PromptTemplates.Handlebars;
using Microsoft.SemanticKernel.Plugins.Web.Bing;

// Create a kernel with OpenAI chat completion
IKernelBuilder kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.AddOpenAIChatCompletion(
        modelId: "gpt-4o",
        apiKey: "<Your OpenAI API Key>");
Kernel kernel = kernelBuilder.Build();

// Create a text search using Bing search
var textSearch = new BingTextSearch(apiKey: "<Your Bing API Key>");

// Build a text search plugin with Bing search and add to the kernel
var options = new KernelFunctionFromMethodOptions()
{
    FunctionName = "GetSiteResults",
    Description = "Perform a search for content related to the specified query and optionally from the specified domain.",
    Parameters =
    [
        new KernelParameterMetadata("query") { Description = "What to search for", IsRequired = true },
        new KernelParameterMetadata("top") { Description = "Number of results", IsRequired = false, DefaultValue = 5 },
        new KernelParameterMetadata("skip") { Description = "Number of results to skip", IsRequired = false, DefaultValue = 0 },
        new KernelParameterMetadata("site") { Description = "Only return results from this domain", IsRequired = false },
    ],
    ReturnParameter = new() { ParameterType = typeof(KernelSearchResults<string>) },
};
var searchPlugin = KernelPluginFactory.CreateFromFunctions("SearchPlugin", "Search specified site", [textSearch.CreateGetTextSearchResults(options)]);
kernel.Plugins.Add(searchPlugin);

// Invoke prompt and use text search plugin to provide grounding information
var query = "What is the Semantic Kernel?";
string promptTemplate = """
    {{#with (SearchPlugin-GetSiteResults query)}}  
        {{#each this}}  
        Name: {{Name}}
        Value: {{Value}}
        Link: {{Link}}
        -----------------
        {{/each}}  
    {{/with}}  

    {{query}}

    Only include results from techcommunity.microsoft.com. 
    Include citations to the relevant information where it is referenced in the response.
    """;
KernelArguments arguments = new() { { "query", query } };
HandlebarsPromptTemplateFactory promptTemplateFactory = new();
Console.WriteLine(await kernel.InvokePromptAsync(
    promptTemplate,
    arguments,
    templateFormat: HandlebarsPromptTemplateFactory.HandlebarsTemplateFormat,
    promptTemplateFactory: promptTemplateFactory
));

Em breve

Mais em breve.

Em breve

Mais em breve.

Próximas etapas

Função de pesquisa de texto chamando pesquisa de texto com armazenamentos vetoriais

Compartilhar via

O que são plug-ins de pesquisa de texto do kernel semântico?

Plugin de pesquisa básica

Plugin de pesquisa com citações

Plugin de pesquisa com filtro

Plugin de pesquisa personalizado

Em breve

Em breve

Próximas etapas

Recursos adicionais