Embeddings de texto para RAG e busca — Python, Ollama, APIs compatíveis com OpenAI

Se você está estudando geração aumentada por recuperação (RAG), esta seção explica embeddings de texto de forma simples — o que são, como se encaixam na pesquisa e recuperação, e como chamar duas configurações locais comuns em Python usando Ollama ou uma API HTTP compatível com OpenAI (como muitos servidores baseados em llama.cpp expõem).

Para clientes em Go e comparações de SDKs para Ollama, consulte SDKs em Go para Ollama — comparação com exemplos.

O que é um embedding de texto?

Um embedding de texto é um vetor (uma lista de floats) produzido por um modelo de embedding. O modelo mapeia texto de comprimento variável para um espaço de dimensão fixa, de modo que textos com significado semelhante tendem a ficar próximos sob uma medida de distância ou similaridade (frequentemente similaridade de cosseno em vetores normalizados L2).

Embeddings não são o mesmo que IDs de tokens e nem são o mesmo que uma conclusão de chat. Eles são uma camada de representação que você usa para pesquisa, agrupamento, deduplicação e — em RAG — recuperação.

Casos de uso comuns

Para configurações multimodais (imagem-texto e ideias relacionadas), consulte Embeddings multimodais.

Embeddings dentro de um pipeline RAG

Um caminho offline típico é:

1. Divida documentos (tamanho, sobreposição e estrutura importam — veja Estratégias de chunking em RAG).
2. Embed cada trecho; opcionalmente armazene metadados (ID de origem, seção, ACL).
3. Indexe vetores na memória, em um índice de biblioteca ou em um banco de dados vetorial (tradeoffs em Armazenamentos vetoriais para RAG — comparação).

No momento da consulta:

1. Embed a consulta do usuário (uma string curta ou um pequeno lote).
2. Recupere os top‑k trechos mais similares por busca vetorial (opcionalmente mais pesquisa por palavras-chave / híbrida).
3. Crie um prompt a partir dos trechos de texto simples recuperados e chame seu modelo de chat.

Nuance importante — modelos de linguagem grandes em APIs de chat consomem texto (e ferramentas), não tensores de embedding arbitrários. Você usa embeddings para escolher qual texto injetar. Se você vir “consultar o LLM com embeddings pré-calculados”, na prática isso significa recuperar com embeddings, depois enviar o texto selecionado ao LLM.

Obter embeddings com Ollama (Python)

O Ollama expõe uma API HTTP. Para embeddings, chame POST /api/embed no seu host Ollama (padrão http://127.0.0.1:11434). O corpo JSON inclui um nome de model e um input (uma string ou uma lista de strings). A resposta inclui embeddings, uma lista de vetores alinhados com suas entradas.

Instale httpx (ou use requests da mesma forma).

import httpx

OLLAMA = "http://127.0.0.1:11434"
MODEL = "nomic-embed-text"  # substitua por um modelo de embedding que você tenha puxado

def embed_ollama(texts: list[str]) -> list[list[float]]:
    r = httpx.post(
        f"{OLLAMA}/api/embed",
        json={"model": MODEL, "input": texts},
        timeout=120.0,
    )
    r.raise_for_status()
    data = r.json()
    return data["embeddings"]

if __name__ == "__main__":
    q = "O que é geração aumentada por recuperação?"
    chunks = [
        "RAG combina recuperação com geração.",
        "Embeddings mapeiam texto para espaço vetorial para busca de similaridade.",
    ]
    qv = embed_ollama([q])[0]
    doc_vs = embed_ollama(chunks)
    print(len(qv), len(doc_vs), len(doc_vs[0]))

Notas operacionais

• Puxe o modelo primeiro (ollama pull … para a tag escolhida). Para modelos de classe Qwen3 no Ollama, consulte Modelos de Embedding e Reordenamento Qwen3 no Ollama.
• Sob carga, a taxa de transferência de embeddings interage com como o Ollama agenda o trabalho — veja Como o Ollama lida com solicitações paralelas.

Obter embeddings com um servidor compatível com OpenAI (Python)

Muitos servidores locais (incluindo configurações HTTP comuns de llama.cpp) expõem rotas compatíveis com OpenAI, como POST /v1/embeddings. Você pode usar o pacote oficial openai em Python e apontar base_url para a raiz …/v1 do seu servidor.

from openai import OpenAI

# Exemplo — substitua host, porta e ID do modelo pelos valores do seu servidor
client = OpenAI(
    base_url="http://127.0.0.1:8080/v1",
    api_key="not-needed",  # muitos servidores locais ignoram isso
)

def embed_openai_compatible(text: str, model: str) -> list[float]:
    r = client.embeddings.create(model=model, input=text)
    return r.data[0].embedding

if __name__ == "__main__":
    v = embed_openai_compatible("hello from llama.cpp", "your-embedding-model-id")
    print(len(v))

Por que manter ambos os padrões em uma página? Os conceitos (chunk, embed, index, query, recuperar texto) são idênticos; apenas a superfície HTTP muda. Um artigo estilo workshop evita duplicar a mesma narrativa sob duas URLs.

Persistir vetores e consultá-los

No mínimo, você deve armazenar três coisas por trecho — vetor, texto e metadados (ID de origem, offsets, ACL). Para um protótipo rápido, você pode manter tudo em uma lista Python e usar similaridade de cosseno com NumPy ou scikit-learn. Para dados em crescimento, use um banco de dados vetorial ou um índice de biblioteca (FAISS, etc.); veja Armazenamentos vetoriais para RAG — comparação para tradeoffs em nível de produto.

Loop de consulta conceitual:

1. query_vec = embed(query)
2. neighbors = index.search(query_vec, k)
3. context = "\n\n".join(chunk.text for chunk in neighbors)
4. Envie context e a pergunta do usuário para sua API de chat.

Reordenamento após recuperação

Um reordenador (frequentemente um cross-encoder ou um segundo modelo de pontuação) pode reordenar os principais candidatos após a recuperação vetorial. Este site tem exemplos em Python e Go, incluindo Reordenamento com modelos de embedding e Reordenamento com Ollama e Qwen3 Embedding em Go.

Neste site — artigos relacionados

Links úteis

• Ollama — modelos e runtime
• API Ollama — embed — referência de API upstream para /api/embed
• Biblioteca Python OpenAI — funciona com qualquer base_url compatível com OpenAI