Sentence Transformers : os embeddings em local

#O que é um embedding e o que faz a biblioteca

Um modelo de embedding transforma um texto em uma lista de números, um vetor, de modo que dois textos com significados próximos tenham vetores próximos. A documentação de Sentence Transformers descreve esses modelos, chamados de bi-encoders, como modelos que calculam uma representação de tamanho fixo para um texto, com um cálculo de embedding geralmente eficiente e um cálculo de similaridade muito rápido. É o componente inicial do RAG: você codifica a pergunta, busca os trechos cujos vetores são mais próximos e entrega esses trechos ao modelo de linguagem. Duas consequências devem ser lembradas: o modelo que codifica os documentos deve ser o mesmo que codifica as perguntas, e sua noção de "próximo" vem do treinamento. Um modelo treinado principalmente em inglês é um juiz pouco confiável do francês.

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
sentences = [
    "The weather is lovely today.",
    "It's so sunny outside!",
    "He drove to the stadium.",
]
embeddings = model.encode(sentences)
print(embeddings.shape)  # [3, 384]
similarities = model.similarity(embeddings, embeddings)

O modelo gera vetores de 384 dimensões e serve como ponto de partida, mas foi projetado para o inglês: para um corpus francês, substitua-o conforme indicado abaixo. A biblioteca coloca automaticamente o modelo no melhor dispositivo disponível (cuda, mps ou cpu) e você pode forçar a escolha com o parâmetro device.

#Instalar e codificar um corpus francês

1. 01
   Instalar a biblioteca

   Use pip install -U sentence-transformers em um ambiente Python. A versão 6.1.0 foi lançada em 18 de setembro de 2026 e exige Python 3.10 ou posterior, de acordo com o PyPI.
2. 02
   Escolher um modelo multilíngue

   Escolha um modelo anunciado como multilíngue (ver a tabela abaixo), não um modelo all-*, treinado para o inglês.
3. 03
   Codificar documentos em lote

   Passe uma lista de textos para encode: a biblioteca os processa em lotes, o que aproveita muito melhor o hardware do que uma chamada por texto.
4. 04
   Codificar a pergunta com o mesmo modelo

   Use o mesmo modelo e os mesmos prefixos dos documentos, depois compare com similarity.
5. 05
   Manter o nome do modelo com o índice

   Registre-o nos metadados: se você trocar de modelo, será necessário recodificar todo o corpus.

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("intfloat/multilingual-e5-large")

docs = [
    "Le contrat peut être résilié avec un préavis de trois mois.",
    "La facture est payable à trente jours fin de mois.",
]
question = "Quel est le délai pour mettre fin au contrat ?"

doc_emb = model.encode(docs, prompt="passage: ", normalize_embeddings=True)
q_emb = model.encode(question, prompt="query: ", normalize_embeddings=True)
print(model.similarity(q_emb, doc_emb))

O prefixo query: para perguntas e passage: para documentos é o citado na documentação do Sentence Transformers para este modelo. Sem ele, a recuperação piora sem mensagem de erro. O parâmetro prompt de encode aplica o prefixo a cada texto.

#Escolher um modelo que entenda o francês

A documentação apresenta modelos originais e sugere consultar o ranking MTEB como fonte de inspiração, com duas ressalvas: excluir os modelos grandes demais para o seu hardware e experimentar, pois modelos bem classificados não necessariamente têm bons resultados nas suas próprias tarefas. A tabela a seguir reproduz o que a documentação diz sobre os modelos citados.

#Erros que destroem um corpus sem mensagem de erro

Um modelo anglófono aplicado a textos em francês

Tudo funciona, e a recuperação ainda assim está errada. É o erro mais comum.

Trechos mais longos do que o limite do modelo

A documentação especifica que os textos mais longos são truncados, mantendo apenas os primeiros tokens até o limite definido por max_seq_length: o final de cada passagem longa fica invisível.

Modelo diferente para documentos e perguntas

Os vetores não falam mais da mesma coisa: resultados anômalos, geralmente introduzidos ao atualizar apenas parte da cadeia.

Prefixos esquecidos

Alguns modelos exigem um prefixo diferente para perguntas e documentos; omitir esse prefixo degrada a recuperação.

Vetores não normalizados com uma pontuação ruim

Se o modelo espera similaridade por cosseno, normalize os vetores ou use a medida adequada, caso contrário, a classificação piora.

#Medir a proximidade: normalização e cosseno

Dois vetores são comparados por uma medida de similaridade, geralmente o cosseno. A documentação do Ollama indica que seu endpoint retorna vetores normalizados e recomenda o cosseno para a maioria das buscas semânticas. Com vetores normalizados, o cosseno e o produto escalar produzem a mesma classificação, o que permite usar um índice otimizado para o produto escalar. O ponto que exige atenção é a consistência: a medida do banco de dados vetorial deve corresponder à que o modelo espera, e ela está indicada na ficha do modelo.

Quanto ao comprimento dos textos, a documentação fornece uma estimativa: 512 tokens para muitos modelos do tipo BERT, ou seja, 300 a 400 palavras em inglês, e 256 tokens para all-MiniLM-L6-v2. O francês consome mais tokens por palavra: divida seus textos em trechos que fiquem abaixo do limite, deixando uma margem, e verifique model.max_seq_length. Você pode reduzi-lo, mas não aumentá-lo além do que o modelo suporta. A documentação acrescenta que um modelo treinado com textos curtos representa menos bem os textos longos.

#Indexar rapidamente na sua máquina

Processador ou GPU

O modelo é executado no melhor dispositivo disponível. Uma GPU acelera a indexação em massa e faz pouca diferença para uma consulta isolada.

Precisão reduzida

No GPU, a conversão para float16 ou bfloat16 acelera a inferência com perda mínima de precisão, de acordo com a documentação.

Backends ONNX e OpenVINO

A documentação anuncia acelerações possíveis de até 2 a 3 vezes, dependendo do hardware e do backend; teste-as no seu computador.

Várias GPUs ou processos

encode aceita uma lista de dispositivos: útil em grandes corpus, menos em pequenos devido ao custo de inicialização.

Vetores mais compactos

A quantização binária ou em inteiros dos vetores e os modelos com dimensões truncáveis reduzem o armazenamento e o custo da busca.

Cache e indexação

Não reencode documentos inalterados: a chave de cache se refere ao conteúdo, não ao nome do arquivo. Em uma máquina que também executa um modelo de linguagem, indexe quando ninguém estiver usando.

#Quanto pesa um índice de vetores

O tamanho de um índice é calculado multiplicando o número de vetores por sua dimensão e por quatro bytes, caso os números estejam em float32. Um vetor de 384 dimensões ocupa 1.536 bytes: um milhão de trechos representa cerca de 1,5 GB. Com 1.024 dimensões, o mesmo milhão ocupa cerca de 4 GB. Esses valores excluem os metadados e as estruturas de índice da base vetorial. A escolha do modelo tem, portanto, uma consequência direta sobre a memória RAM necessária para a busca, e a quantização dos vetores mencionada acima pode reduzir esse consumo de memória.

#Sentence Transformers ou a API de embeddings do Ollama

Ollama também expõe embeddings: a documentação indica que o comando ollama run peut gera vetores e que o ponto de acesso api/embed retorna vetores normalizados em L2. Ela recomenda os modelos embeddinggemma, qwen3-embedding e all-minilm, com vetores tipicamente de 384 a 1.024 dimensões, e lembra duas regras: coseno para a maioria das pesquisas e mesmo modelo para indexação e consulta.

#O embedding é apenas um primeiro filtro

A documentação do Sentence Transformers descreve o bi-encoder como a primeira etapa de uma busca em duas fases, na qual um cross-encoder, ou reranker, reclassifica os melhores resultados. O cross-encoder lê a pergunta e cada passagem em conjunto: é mais lento, mas mais preciso para um pequeno grupo de candidatos. Recuperar cerca de vinte passagens por similaridade e depois reclassificá-las para manter apenas algumas é uma das melhorias menos custosas de uma cadeia RAG. O guia dedicado ao reranker detalha a implementação; meça o ganho em suas vinte perguntas antes de mantê-lo, pois ele adiciona latência a cada requisição, um segundo modelo a manter e um consumo adicional de memória.

Um bom hábito, antes mesmo de comparar os modelos, é verificar o conteúdo do seu corpus: frases curtas e autônomas ou longos parágrafos técnicos? Perguntas formuladas como palavras-chave ou frases inteiras? A resposta orienta a escolha do limite de comprimento, da divisão em trechos e do modelo. Um corpus jurídico denso exige configurações diferentes de uma base de perguntas e respostas curtas, e nenhum ranking público pode saber disso por você.

#Avaliar a escolha do modelo antes de indexar

1. 01
   Escrever vinte perguntas reais

   Use perguntas que seus usuários farão, formuladas com as palavras deles, não com as do documento.
2. 02
   Anotar o trecho esperado

   Para cada pergunta, identifique o trecho ou os trechos que contêm a resposta.
3. 03
   Comparar dois ou três modelos

   Codifique o mesmo corpus com cada modelo e veja se o trecho correto aparece entre os cinco primeiros resultados.
4. 04
   Executar novamente a cada mudança

   Se o modelo, a divisão em trechos ou o prefixo forem alterados, execute novamente este pequeno teste antes de reindexar.

#FAQ

#Para se aprofundar

• Melhores modelos de embeddings para o francês
• BGE-M3: embeddings que realmente falam francês
• Adicionar um reranker ao seu pipeline
• Estratégias de chunking
• Qdrant: o banco vetorial de um RAG local
• RAG local: introdução

• Fonte: Sentence Transformers, início rápido
• Fonte: Sentence Transformers, cálculo de embeddings
• Fonte: Sentence Transformers, modelos pré-treinados
• Fonte: Ollama, embeddings