Comece a usar a integração do Semantic Kernel C#
Nesta página
Observação
Este tutorial usa a biblioteca de C# do Semantic Kernel. Para um tutorial que usa a biblioteca Python, consulte Introdução à integração de python do Semantic Kernel.
Você pode integrar Atlas Vector Search o com Microsoft Semantic Kernel para criar AI aplicativos de e implementar geração aumentada por recuperação (RAG). Este tutorial demonstra como começar a usar o Atlas Vector Search com o Semantic Kernel para executar o Atlas Search semântica em seus dados e criar uma implementação deRAG . Especificamente, você executa as seguintes ações:
Configure o ambiente.
Armazene dados personalizados no Atlas.
Crie um índice de pesquisa do Atlas Vector Search em seus dados.
Execute uma consulta de pesquisa semântica em seus dados.
Implemente a RAG usando o Atlas Vector Search para responder a perguntas sobre seus dados.
Plano de fundo
O Semantic Kernel é um SDK de código aberto que permite combinar vários serviços e plug-ins de AI com seus aplicativos. Você pode usar o Semantic Kernel para uma variedade de casos de uso de AI , incluindo RAG.
Ao integrar o Atlas Vector Search com o Semantic Kernel, você pode usar o Atlas como um banco de dados vetorial e usar o Atlas Vector Search para implementar o RAG recuperando documentos semanticamente semelhantes de seus dados. Para saber mais sobre RAG, consulte Geração aumentada de recuperação (RAG) com Atlas Vector Search.
Pré-requisitos
Para concluir este tutorial, você deve ter o seguinte:
Uma conta do Atlas com um cluster executando o MongoDB versão 6.0.11, 7.0.2 ou posterior (incluindo RCs). Certifique-se de que seu endereço IP esteja incluído na lista de acesso do seu projeto Atlas. Para saber mais, consulte Criar um cluster.
Uma chave de API OpenAI. Você deve ter uma conta OpenAI com créditos disponíveis para solicitações de API. Para saber mais sobre como registrar uma conta OpenAI, consulte o site da API OpenAI.
Um terminal e editor de código para executar seu aplicativo .NET .
C#/ .NET instalado.
Configurar o ambiente
Você deve primeiro configurar o ambiente para este tutorial. Para configurar seu ambiente, conclua as etapas a seguir.
Instalar dependências.
Em seu terminal, execute os seguintes comandos para instalar os pacotes para este tutorial.
dotnet add package Microsoft.SemanticKernel dotnet add package Microsoft.SemanticKernel.Connectors.MongoDB --prerelease dotnet add package Microsoft.SemanticKernel.Connectors.OpenAI dotnet add package Microsoft.SemanticKernel.Memory dotnet add package Microsoft.SemanticKernel.Plugins.Memory --prerelease
Definir variáveis ambientais.
Em seu terminal, execute os seguintes comandos para adicionar a string de conexão SRV do cluster do Atlas e a chave de API da OpenAI ao seu ambiente.
export OPENAI_API_KEY="<Your OpenAI API Key>" export ATLAS_CONNECTION_STRING="<Your MongoDB Atlas SRV Connection String>"
Observação
Sua string de conexão deve usar o seguinte formato:
mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net
Armazenar dados personalizados no Atlas
Nesta seção, você inicializa o kernel, que é a interface principal usada para gerenciar os serviços e os plugins do seu aplicativo. Por meio do kernel, você configura seus serviços de IA, instancia o Atlas como um banco de dados vetorial (também chamado de armazenamento de memória) e carrega dados personalizados no cluster do Atlas.
Copie e cole o seguinte código no arquivo Program.cs
de seu aplicativo.
Este código executa as seguintes ações:
Importa o Semantic Kernel e todos os pacotes necessários.
Conecta-se ao cluster do Atlas recuperando sua string de conexão SRV do ambiente.
Recupera sua chave de API OpenAI do ambiente e cria uma instância do modelo de incorporação
text-embedding-ada-002
do OpenAI.Inicializa o Kernel e adiciona o seguinte serviço de AI ao Kernel:
O
gpt-3.5-turbo
da OpenAI como o modelo de bate-papo usado para gerar respostas para a seção Responder a perguntas sobre seus dados.
Instancia o Atlas como um armazenamento de memória e especifica os seguintes parâmetros:
semantic_kernel_db.test
como a coleção para armazenar os documentos.vector_index
como o índice a ser usado para consultar o armazenamento de memória.
Inicializa uma classe chamada
SemanticTextMemory
, que fornece um grupo de métodos nativos para ajudá-lo a armazenar e recuperar texto na memória.Preenche a coleção
semantic_kernel_db.test
com documentos de amostra chamando o métodoPopulateMemoryAsync
.
// Import Packages using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.Connectors.MongoDB; using Microsoft.SemanticKernel.Connectors.OpenAI; using Microsoft.SemanticKernel.Memory; using Microsoft.SemanticKernel.Plugins.Memory; class Program { static async Task Main(string[] args) { // Get connection string and OpenAI API Key var connectionString = Environment.GetEnvironmentVariable("ATLAS_CONNECTION_STRING"); if (connectionString == null) { Console.WriteLine("You must set your 'ATLAS_CONNECTION_STRING' environment variable."); Environment.Exit(0); } var openAIKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY"); if (openAIKey == null) { Console.WriteLine("You must set your 'OPENAPI_KEY' environment variable."); Environment.Exit(0); } // Create new OpenAI API Embedding Model var embeddingGenerator = new OpenAITextEmbeddingGenerationService("text-embedding-ada-002", openAIKey); // Initialize Kernel IKernelBuilder builder = Kernel.CreateBuilder(); // Add OpenAI Chat Completion to Kernel builder.AddOpenAIChatCompletion( modelId: "gpt-3.5-turbo", apiKey: openAIKey ); Kernel kernel = builder.Build(); // Instantiate Atlas as a memory store. MongoDBMemoryStore memoryStore = new(connectionString, "semantic_kernel_db", indexName: "vector_index"); SemanticTextMemory textMemory = new(memoryStore, embeddingGenerator); // Populate memory with sample data async Task PopulateMemoryAsync(Kernel kernel) { await textMemory.SaveInformationAsync(collection: "test", text: "I am a developer", id: "1"); await textMemory.SaveInformationAsync(collection: "test", text: "I started using MongoDB two years ago", id: "2"); await textMemory.SaveInformationAsync(collection: "test", text: "I'm using MongoDB Vector Search with Semantic Kernel to implement RAG", id: "3"); await textMemory.SaveInformationAsync(collection: "test", text: "I like coffee", id: "4"); } await PopulateMemoryAsync(kernel); } }
Salve o arquivo e execute o seguinte comando para carregar seus dados no Atlas:
dotnet run
Dica
Depois de executar o código de amostra, você pode visualizar suas incorporações vetoriais na Atlas navegando até a collection semantic_kernel_db.test
no seu cluster.
Criar o índice Atlas Vector Search Index
Para habilitar consultas de pesquisa de vetor no seu armazenamento de vetor, crie um índice do Atlas Vector Search na coleção semantic_kernel_db.test
.
Acesso necessário
Para criar um Atlas Vector Search índice de pesquisa, você deve ter acesso Project Data Access Admin
ou superior ao Atlas projeto.
Procedimento
No Atlas, VáGo para a Clusters página do seu projeto.
Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione o projeto desejado no menu Projects na barra de navegação.
Se ainda não estiver exibido, clique em Clusters na barra lateral.
A página Clusters é exibida.
Inicie a configuração do seu índice.
Faça as seguintes seleções na página e clique em Next.
Search Type | Selecione o tipo de índice Vector Search. |
Index Name and Data Source | Especifique as seguintes informações:
|
Configuration Method | For a guided experience, select Visual Editor. To edit the raw index definition, select JSON Editor. |
Defina o índice do Atlas Vector Search.
Esta definição de índice indexa o campo embedding
como o tipo vetor. O campo embedding
contém as incorporações criadas utilizando o modelo de incorporação text-embedding-ada-002
da OpenAI. A definição de índice especifica 1536
dimensões vetoriais e mede a similaridade usando cosine
.
O Atlas detecta automaticamente campos que contêm incorporações vetoriais, assim como suas dimensões correspondentes. Para a coleção semantic_kernel_db.test
, o campo embedding
é exibido.
Para configurar o índice, selecione Cosine no menu suspenso Similarity Method.
Cole a seguinte definição de índice no editor JSON:
1 { 2 "fields": [ 3 { 4 "type": "vector", 5 "path": "embedding", 6 "numDimensions": 1536, 7 "similarity": "cosine" 8 } 9 ] 10 }
Verifique o status.
O índice recém-criado é exibido na aba Atlas Search. Enquanto o índice está construindo, o campo Status lê Build in Progress. Quando o índice terminar de construir, o campo Status lê Active.
Observação
Collections maiores demoram mais tempo para indexar. Você receberá uma notificação por e-mail quando seu índice terminar a criação.
Executar queries no Vector Search
Depois que o Atlas criar seu índice, você poderá executar consultas vetoriais do Atlas Search em seus dados.
No final do arquivo Program.cs
, adicione o código a seguir para executar uma pesquisa semântica básica para a string What is my job title?
. Ele imprime o documento mais relevante e uma pontuação de relevância entre 0
e 1
.
1 var results = textMemory.SearchAsync(collection: "test", query: "What is my job title?"); 2 3 await foreach (var result in results) { 4 Console.WriteLine($"Answer: {result?.Metadata.Text}, {result?.Relevance}"); 5 } 6 Console.WriteLine("Search completed.");
Salve o arquivo e, em seguida, execute o seguinte comando para ver os resultados da pesquisa semântica:
dotnet run
Answer: I am a developer, 0.8913083076477051 Search completed.
Responda a perguntas sobre seus dados
Esta seção mostra um exemplo de implementação do RAG com Atlas Vector Search e Semantic Kernel. Agora que você usou o Atlas Vector Search para recuperar documentos semanticamente semelhantes, cole o seguinte exemplo de código no final do seu Program.cs
para solicitar que o LLM responda a perguntas com base nesses documentos.
Este código executa as seguintes ações:
Importa as funções da classe
TextMemoryPlugin
para otextMemory
do kernel.Cria um modelo de prompt que usa a função
recall
da classeTextMemoryPlugin
para realizar uma pesquisa semântica notextMemory
do kernel para a stringWhen did I start using MongoDB?
.Cria uma função chamada
settings
a partir do prompt de bate-papo usando a funçãoCreateFunctionFromPrompt
do kernel.Chama a função
InvokeAsync
do kernel para gerar uma resposta do modelo de chat usando os seguintes parâmetros:A função
settings
que configura o modelo de prompt eOpenAIPromptExecutionSettings
.A pergunta
When did I start using MongoDB?
como o valor da variável{{$input}}
no modelo de prompt.semantic_kernel_db.test
como a coleção para recuperar informações.
Imprime a pergunta e gera a resposta.
1 kernel.ImportPluginFromObject(new TextMemoryPlugin(textMemory)); 2 const string promptTemplate = @" 3 Answer the following question based on the given context. 4 Question: {{$input}} 5 Context: {{recall 'When did I start using MongoDB?'}} 6 "; 7 8 // Create and Invoke function from the prompt template 9 var settings = kernel.CreateFunctionFromPrompt(promptTemplate, new OpenAIPromptExecutionSettings()); 10 var ragResults = await kernel.InvokeAsync(settings, new() 11 { 12 ["When did I start using MongoDB?", ] = 13 ["test" ] = 14 }); 15 16 // Print RAG Search Results 17 Console.WriteLine("Question: When did I start using MongoDB?"); 18 Console.WriteLine($"Answer: {ragResults.GetValue<string>()}");
Salve o arquivo e execute o seguinte comando para gerar uma resposta:
dotnet run
Question: When did I start using MongoDB? Answer: You started using MongoDB two years ago.
Dica
Você pode adicionar seus próprios dados e substituir as seguintes partes do código para gerar respostas em uma pergunta diferente:
{{recall '<question>'}}
,[TextMemory.InputParam] = "<question>"
,Console.WriteLine("Question: <question>")
.
Próximos passos
O MongoDB também fornece os seguintes recursos para desenvolvedores: