Além do básico: aprimorando a API Kotlin Ktor com pesquisa vetorial

Ricardo Mello8 min read • Published Sep 18, 2024 • Updated Sep 18, 2024

IA Pesquisa vetorial Kotlin Atlas

Avalie esse Tutorial

Neste artigo, abordaremos técnicas avançadas do MongoDB em conjunto com a API Kotlin Ktor, desenvolvendo sobre a base estabelecida em nosso artigo anterior, Mestre emKotlin: Criando uma API com Ktor e MongoDB Atlas. Nosso foco será a integração de funcionalidades robustas, como o Abraçar o Face, o Vector Search e as Atlas Triggers para aumentar a funcionalidade e o desempenho da nossa API.

Começaremos fornecendo uma visão geral dessas técnicas avançadas do MongoDB e seu papel crítico no desenvolvimento de API atual. Posteriormente, abordaremos implementações práticas, mostrando como você pode integrar perfeitamente o Hugging Face para o processamento de linguagem natural, aproveitar o Vector Atlas Search para recuperação rápida de dados e automatizar processos de banco de dados usando as funções e os gatilhos do Atlas.

Pré-requisitos

Conta do MongoDB Atlas
- Observação: Comece a usar o MongoDB Atlas gratuitamente! Se você ainda não tiver uma conta, o MongoDB oferece um cluster Atlas gratuito para sempre.
Abraçando a contado Face
Código fonte do artigo anterior
Ferramentas do MongoDB

Demonstração

Começaremos importando um conjunto de dados de exercícios de condicionamento físico para o MongoDB Atlas como documentos. Em seguida, criaremos um trigger que será ativado na inserção. Para cada documento do conjunto de dados, uma função será invocada para solicitar a API do Hugging Face. Esta função enviará a descrição do exercício para conversão em um array incorporado, que será salvo na coleção de exercícios como descEmbedding:

Na segunda parte, modificaremos o aplicativo Kotlin Ktor para incorporar chamadas de clientes HTTP, permitindo a interação com a API Hugging Face. Além disso, criaremos um endpoint /exercises/processRequest. Esse endpoint aceitará uma entrada de texto, que será processada usando a API Hugging Face para gerar uma matriz incorporada. Posteriormente, compararemos essa array com o descEmbedding gerado na primeira parte. Utilizando a pesquisa vetorial, retornaremos os três resultados mais próximos (neste caso, os exercícios de condicionamento físico mais relevantes para minha pesquisa):

Configuração do MongoDB e integração do face do Abraço

1. Criando a coleção de exercícios

A primeira etapa para atingir nosso objetivo é criar uma collection vazia chamada "exercícios" que posteriormente armazenará nosso conjunto de dados. Comece fazendo login em sua conta MongoDB Atlas. No dashboard do Atlas, navegue até seu cluster e selecione o banco de dados onde você deseja criar a collection. Clique na aba "Coleções" para gerenciar suas collections dentro desse banco de dados e criar um campo vazio collection deexercícios:

2. Criação de um gatilho e função

Em seguida, precisamos criar um trigger que será ativado sempre que um novo documento for inserido na collection deexercícios. Navegue até a guiaTriggers e crie um trigger chamado "Trigger_Exercises", conforme mostrado nas imagens abaixo:

Lembre-se de escolher a coleção " exercises ", selecionar " Inserir documento " para o tipo de operação e ativar " Documento completo.”

Por fim, cole o seguinte código de função no campo "Função" e clique em "Salvar":

Trecho de código

exports = async function(changeEvent) {
    const doc = changeEvent.fullDocument;

const url = 'https://api-inference.huggingface.co/pipeline/feature-extraction/sentence-transformers/all-MiniLM-L6-v2';
    const hf_key = context.values.get("HF_value");
    try {
        console.log(`Processing document with id: ${doc._id}`);

let response = await context.http.post({
            url: url,
            headers: {
                'Authorization': [`Bearer ${hf_key}`],
                'Content-Type': ['application/json']
            },

body: JSON.stringify({               
                inputs: [doc.description]               
            })
        });

let responseData = EJSON.parse(response.body.text());

if(response.statusCode === 200) {
            console.log("Successfully received embedding.");

const embedding = responseData[0];

const collection = context.services.get("Cluster0").db("my_database").collection("exercises");

const result = await collection.updateOne(
                { _id: doc._id },
                { $set: { descEmbedding: embedding }}
            );

if(result.modifiedCount === 1) {
                console.log("Successfully updated the document.");
            } else {
                console.log("Failed to update the document.");
            }
        } else {
            console.log(`Failed to receive embedding. Status code: ${response.statusCode} plus ${response}`);
        }

} catch(err) {
        console.error(err);
    }
};

Essa função serve como uma ponte entre o MongoDB e a API Hugging Face, aprimorando documentos armazenados em uma coleção do MongoDB com incorporações geradas pela API. A função é acionada por um evento de alteração na coleção MongoDB, especificamente quando um novo documento é inserido ou um documento existente é atualizado.

Agora, vamos explorar a funcionalidade desta função:

Tratamento de eventos: a função extrai o documento completo do evento de alteração do MongoDB paraser processado.
Interação da API Hugging Face: ela interage com a API Hugging Face para obter uma incorporação para a descrição do documento. Isso envolve o envio de uma solicitação HTTP POST para o endpoint de extração de recursos da API, com a descrição do documento como entrada.
Atualização do MongoDB: ao receber uma resposta bem-sucedida da API Hugging Face, a função atualiza o documento na collection MongoDB com a incorporação extraída. Isso Enriquece o documento com informações adicionais úteis para várias tarefas de processamento de linguagem natural.

3. Renomear a função

Para alinhar nosso ambiente com a imagem de demonstração, vamos alterar o nome da nossa função para Function_Exercises. Para fazer isso, acesse o menu "Functions" e edite a função:

Em seguida, digite o novo nome e clique em “Save:

4. Obtendo o token de acesso Hugging Face

A função que criamos anteriormente requer um token para acessar o Hugging Face. Precisamos obtê-lo e configurá-lo no Atlas. Para fazer isso, faça login na sua conta Hugging Face e acesse as configurações para criar sua chave:

Depois de copiar sua chave, vamos retornar ao MongoDB Atlas e configurar nossa chave para acesso. Clique no botão "Valores" no menu lateral e selecione "Create New Value":

Agora, precisamos criar um segredo e um valor que será associado a este segredo.

Primeiro, crie o segredo inserindo a chave a partir do Abraço do Face:

Em seguida, crie um valor chamado HF_value (que será usado em nossa função) e associe-o ao segredo, como mostra a imagem:

Se tudo tiver corrido perfeitamente, nossos valores ficarão assim:

Terminamos de configurar nosso ambiente. Para recapitular:

Criando a coleção vazia:

Criamos uma coleção vazia denominada "exercícios" no MongoDB Atlas. Esta coleção receberá dados de entrada, acionando um processo para converter a descrição dos exercícios em valores incorporados.

** Configurando gatilhos e funções:

Um trigger chamado "Trigger_Exercises" foi criado para ser ativado após a inserção do documento.
O trigger chama uma função chamada "Function_Exercises" para cada documento inserido.
A função processa a descrição usando a API Hugging Face para gerar valores incorporados, que são então adicionados à collection " exercises ".

Configuração final:

Para concluir a configuração, associamos um segredo e um valor à chave Abraçando a face no MongoDB Atlas.

5. Importando um conjunto de dados

Nesta etapa, importaremos um conjunto de dados de documentos 50 contendo informações sobre exercícios:

Para atingir esse objetivo, usarei asferramentas do MongoDB para importar o arquivoconcerns.json por meio da linha de comando. Após instalar o MongoDB Tools, basta colar o arquivo "exercises.json" na pasta "bin" e executar o comando, conforme mostrado na imagem abaixo:

Trecho de código

Aviso: lembre-se de alterar seu usuário, senha e cluster.

Se tudo correr bem, veremos que importamos os exercícios 50.

Agora, vamos verificar os registros de nossa função para garantir que tudo correu bem. Para fazer isso, navegue até a aba "App Services" e clique em "Logs":

E agora, vamos ver nossa coleção:

Como podemos ver, transformamos as descrições dos exercícios 50 em valores vetoriais e os atribuímos ao campo "descEmbedding".

Melhorando o Kotlin Ktor com API de Face Abraços e Vector Search

Vamos prosseguir com as alterações em nosso aplicativo Kotlin. Se ainda não fez isso, você pode baixar o aplicativo. Nosso objetivo é criar um endpoint /processRequest para enviar uma entrada para o HuggingFace, como:

"Preciso de um exercício para os meus quadris e para perder a gordu ras da abdome."

Converteremos essas informações em dadosincorporados e utilizaremos o Vector Search para retornar os três exercícios que mais se aproximam dessa entrada. Para começar, vamos incluir duas dependências no arquivo build.gradle.kts que nos permitirão fazer chamadas HTTP para o Hugging Face:

build.gradle.kts

Trecho de código

No pacoteports, criaremos um repositório que recuperará exercícios do banco de dados:

domain/ports/ExercisesRepository

Trecho de código

Criaremos uma resposta para exibir algumas informações ao usuário:

application/response/ExercisesResponse

Trecho de código

Agora, crie a classeExercícios:

domínio/entidade/Exercícios

Trecho de código

Em seguida, implementaremos nossa interface que se comunicará com o banco de dados executando uma query agregada usando a pesquisa vetorial que criaremos posteriormente.

infrastructure/ExercisesRepositoryImpl

Trecho de código

package com.mongodb.infrastructure

import com.mongodb.domain.entity.Exercises
import com.mongodb.domain.ports.ExercisesRepository
import com.mongodb.kotlin.client.coroutine.MongoDatabase
import kotlinx.coroutines.flow.toList
import org.bson.Document

class ExercisesRepositoryImpl(
    private val mongoDatabase: MongoDatabase
) : ExercisesRepository {

companion object {
        const val EXERCISES_COLLECTION = "exercises"
    }

override suspend fun findSimilarExercises(embedding: List<Double>): List<Exercises> {
        val result =
        mongoDatabase.getCollection<Exercises>(EXERCISES_COLLECTION).withDocumentClass<Exercises>().aggregate(
            listOf(
                Document(
                    "\$vectorSearch",
                    Document("queryVector", embedding)
                    .append("path", "descEmbedding")
                    .append("numCandidates", 3L)
                    .append("index", "vector_index")
                    .append("limit", 3L)
                )
            )
        )

return result.toList()
    }
}

Agora, vamos criar nosso endpoint para acessar o Hugging Face e chamar o método criado anteriormente:

application/routes/ExercisesRoutes (aplicativos/rotas/ExercíciosRotas)

Trecho de código

package com.mongodb.application.routes

import com.mongodb.application.request.SentenceRequest
import com.mongodb.domain.ports.ExercisesRepository
import com.mongodb.huggingFaceApiUrl
import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.cio.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.http.content.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import org.koin.ktor.ext.inject

fun Route.exercisesRoutes() {
   val repository by inject<ExercisesRepository>()

route("/exercises/processRequest") {
       post {
           val sentence = call.receive<SentenceRequest>()

val response = requestSentenceTransform(sentence.input, call.huggingFaceApiUrl())

if (response.status.isSuccess()) {
               val embedding = sentence.convertResponse(response.body())
               val similarDocuments = repository.findSimilarExercises(embedding)

call.respond(HttpStatusCode.Accepted, similarDocuments.map { it.toResponse() })
           }
       }
   }
}

suspend fun requestSentenceTransform(input: String, huggingFaceURL: String): HttpResponse {

println(huggingFaceURL)

return HttpClient(CIO).use { client ->

val response = client.post(huggingFaceURL) {
           val content = TextContent(input, ContentType.Text.Plain)
           setBody(content)
       }

response
   }
}

Em seguida, vamos criar a solicitação que enviaremos para Abraçando a face. Nesta classe, além da entrada, temos um conversor para converter o retorno de String para Double:

application/request/SentenceRequest

Trecho de código

Vamos incluir a rota criada anteriormente e um métodohuggingFaceApiUrl em nossa classe Aplicativo. Aqui está o código completo:

Application.kt

Trecho de código

package com.mongodb

import com.mongodb.application.routes.exercisesRoutes
import com.mongodb.application.routes.fitnessRoutes
import com.mongodb.domain.ports.ExercisesRepository
import com.mongodb.domain.ports.FitnessRepository
import com.mongodb.infrastructure.ExercisesRepositoryImpl
import com.mongodb.infrastructure.FitnessRepositoryImpl
import com.mongodb.kotlin.client.coroutine.MongoClient
import io.ktor.serialization.gson.*
import io.ktor.server.application.*
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.server.plugins.swagger.*
import io.ktor.server.routing.*
import io.ktor.server.tomcat.*
import org.koin.dsl.module
import org.koin.ktor.plugin.Koin
import org.koin.logger.slf4jLogger

fun main(args: Array<String>): Unit = EngineMain.main(args)
fun Application.module() {

install(ContentNegotiation) {
       gson {
       }
   }

// Other code..
  
   routing {
      // Other code..
     
      exercisesRoutes() 
   }
}

fun ApplicationCall.huggingFaceApiUrl(): String {
   return application.environment.config.propertyOrNull("ktor.huggingface.api.url")?.getString()
       ?: throw RuntimeException("Failed to access Hugging Face API base URL.")

}

Por fim, vamos incluir o ponto de extremidade do Hugging Face no arquivo application.conf.

application.conf

Trecho de código

Criando pesquisa vetorial

Agora, precisamos Go ao Atlas e criar nosso índice de pesquisa vetorial. Acompanhe as imagens abaixo:

Selecione o Atlas Vector Search:

Se estiver tudo bem, você verá uma mensagem de sucesso como a abaixo, indicando que o índice foi criado com sucesso no MongoDB Atlas:

Este trecho de código define um índice vetorial no campo descEmbedding em nossa collection de exercícios. O campo de tipo especifica que este é um índice de vetor. O campo de caminho indica o caminho para o campo que contém os dados do vetor. Neste caso, estamos usando o campo descEmbedding. O campo numDimensions especifica o número de dimensões

dos vetores, que é 384 neste caso. Por fim, o campo de similaridade especifica a métrica de similaridade a ser usada para comparar vetores, que é a distância euclidiana.

Trecho de código

Depois de implementar as atualizações e configurações mais recentes, é hora de testar o aplicativo. Vamos começar executando o aplicativo. Abra o Application.kt e clique no botão Executar:

Quando o aplicativo estiver instalado e funcionando, você poderá prosseguir com o teste usando o seguinte comando curl:

Trecho de código

Conclusão

Este artigo mostrou como enriquecer documentos do MongoDB com incorporações da API Hugging Face, aproveitando seus poderosos recursos de processamento de linguagem natural. A função fornecida demonstra o tratamento de eventos de mudança em uma coleção do MongoDB e a interação com uma API externa. Essa integração oferece aos desenvolvedores oportunidades de aprimorar seus aplicativos com recursos de NLP, destacando o potencial de combinar tecnologias para aplicativos mais inteligentes.

O código-fonte de exemplo está disponível no GitHub.

Se você tiver alguma dúvida ou quiser discutir outras implementações, fique à vontade para entrar em contato com o fórum dacomunidade de desenvolvedores do MongoDB para obter suporte e orientação.

Principais comentários nos fóruns

Ainda não há comentários sobre este artigo.

Iniciar a conversa

Avalie esse Tutorial

Relacionado

Tutorial

Tutorial RAG dos módulos MongoDB Atlas Vector Search e AWS Bedrock

Aug 09, 2024 | 10 min read

Tutorial

Como otimizar aplicativos LLM com compactação de prompts usando LLMLingua e LangChain

Jun 18, 2024 | 13 min read

Tutorial

RAG interativo com MongoDB Atlas + API de chamada de função

Sep 18, 2024 | 16 min read

Tutorial

Como implementar fluxos de trabalho do Databricks e o Atlas Vector Search para melhorar a precisão da pesquisa de comércio eletrônico

Sep 18, 2024 | 6 min read

Sumário

Pré-requisitos
Demonstração
Configuração do MongoDB e integração do face do Abraço
Melhorando o Kotlin Ktor com API de Face Abraços e Vector Search
Conclusão