Redis®*: Pesquisa vetorial e RAG

Pesquisa semântica, recomendações e retrieval-augmented generation com Redis

👋 Bem-vindo à documentação da Stackhero!

A Stackhero disponibiliza uma solução Redis cloud pronta a usar, que oferece várias vantagens, incluindo:

• Interface web Redis Commander incluída.
• Tamanho e transferências de mensagens ilimitados.
• Atualizações fáceis com apenas um clique.
• Performance otimizada e segurança reforçada, graças a uma infraestrutura privada e dedicada.

Poupe tempo e simplifique a sua vida: bastam 5 minutos para experimentar a solução de alojamento Redis cloud da Stackhero!

Se está a desenvolver uma pesquisa semântica, um motor de recomendações ou um pipeline de retrieval-augmented generation (RAG), precisa de uma solução fiável para armazenar embeddings e encontrar rapidamente as correspondências mais próximas de uma consulta. A sua instância Redis na Stackhero oferece esta funcionalidade de forma nativa: o motor de pesquisa indexa os vetores e responde a pesquisas de similaridade em milissegundos. Não é necessário adicionar uma base de dados vetorial separada ao lado do Redis: tudo funciona num único local.

Esta abordagem é produtiva e eficiente graças a duas funcionalidades principais:

• Consultas híbridas. Pode combinar a pesquisa por similaridade vetorial com filtros tradicionais como intervalos numéricos, tags ou texto integral, tudo num único pedido. Por exemplo: "os 5 segmentos mais próximos desta pergunta, mas apenas de documentos que este utilizador tem permissão para ler, publicados após janeiro" podem ser obtidos numa única consulta, sem necessidade de múltiplos pedidos.
• Arquitetura simplificada. Embeddings, cache e sessões coexistem, partilhando credenciais, backups e monitorização. Isto reduz a complexidade e o overhead.

Antes de começar

Ative o módulo Search (e JSON se pretender armazenar documentos em formato JSON) na secção Modules da configuração do seu serviço no dashboard da Stackhero. Para detalhes passo a passo, consulte o guia de Search e JSON.

Criar um índice vetorial

Para declarar um campo vetorial, indique a sua dimensão e a métrica de distância. A dimensão deve corresponder ao seu modelo de embedding: por exemplo, 1536 para o OpenAI text-embedding-3-small, 768 para muitos modelos open source, etc.

FT.CREATE chunksIndex
  ON HASH
  PREFIX 1 chunk:
  SCHEMA
    content TEXT
    documentId TAG
    publishedAt NUMERIC
    embedding VECTOR HNSW 6
      TYPE FLOAT32
      DIM 1536
      DISTANCE_METRIC COSINE

HNSW cria um índice em grafo que mantém as consultas rápidas à medida que a sua coleção cresce, sendo uma boa escolha para coleções com mais de alguns milhares de vetores. Para coleções pequenas onde a precisão exata é prioritária, pode usar FLAT para pesquisa exaustiva.

COSINE é a métrica recomendada para a maioria dos modelos de embeddings de texto. Também pode optar por L2 ou IP se o seu caso de uso o exigir.

Consultas

Uma consulta K nearest neighbors (KNN) tem o seguinte formato. O vetor é fornecido como bytes float32 little-endian brutos:

FT.SEARCH chunksIndex "*=>[KNN 5 @embedding $queryVector AS score]"
  PARAMS 2 queryVector "<rawBytes>"
  SORTBY score
  RETURN 2 content score
  DIALECT 2

Para combinar pesquisa por similaridade com filtros, basta substituir * por uma expressão de filtro:

FT.SEARCH chunksIndex "(@documentId:{doc42} @publishedAt:[1735689600 +inf])=>[KNN 5 @embedding $queryVector AS score]"
  PARAMS 2 queryVector "<rawBytes>"
  SORTBY score
  DIALECT 2

As consultas vetoriais requerem DIALECT 2. Se omitir este parâmetro, a consulta utiliza a sintaxe antiga e devolve um erro.

Um pipeline RAG em Node.js

import { createClient, SCHEMA_FIELD_TYPE, SCHEMA_VECTOR_FIELD_ALGORITHM } from 'redis';

const client = createClient({ url: process.env.STACKHERO_REDIS_URL_TLS });
await client.connect();

const DIMENSIONS = 1536;
const toBytes = embedding => Buffer.from(new Float32Array(embedding).buffer);

// 1. Crie o índice uma vez, no arranque
try {
  await client.ft.create(
    'chunksIndex',
    {
      content: SCHEMA_FIELD_TYPE.TEXT,
      documentId: SCHEMA_FIELD_TYPE.TAG,
      embedding: {
        type: SCHEMA_FIELD_TYPE.VECTOR,
        ALGORITHM: SCHEMA_VECTOR_FIELD_ALGORITHM.HNSW,
        TYPE: 'FLOAT32',
        DIM: DIMENSIONS,
        DISTANCE_METRIC: 'COSINE'
      }
    },
    { ON: 'HASH', PREFIX: 'chunk:' }
  );
}
catch (error) {
  if (!error.message.includes('Index already exists')) {
    throw error;
  }
}

// 2. Indexe os seus segmentos (o embedding vem do seu fornecedor de modelo)
async function indexChunk({ id, documentId, content, embedding }) {
  await client.hSet(`chunk:${id}`, {
    content,
    documentId,
    embedding: toBytes(embedding)
  });
}

// 3. Recupere os segmentos mais próximos de uma pergunta, restritos a um documento
async function retrieve({ questionEmbedding, documentId, count = 5 }) {
  const results = await client.ft.search(
    'chunksIndex',
    `(@documentId:{${documentId}})=>[KNN ${count} @embedding $queryVector AS score]`,
    {
      PARAMS: { queryVector: toBytes(questionEmbedding) },
      SORTBY: 'score',
      RETURN: [ 'content', 'score' ],
      DIALECT: 2
    }
  );

  return results.documents.map(({ value }) => value.content);
}

// 4. Forneça-os ao seu modelo como contexto
const context = await retrieve({ questionEmbedding, documentId: 'doc42' });
const prompt = `Responda apenas utilizando este contexto:\n\n${context.join('\n\n')}\n\nPergunta: ${question}`;

O mesmo em Python

import os
import numpy as np
import redis
from redis.commands.search.field import TextField, TagField, VectorField
from redis.commands.search.index_definition import IndexDefinition, IndexType
from redis.commands.search.query import Query

DIMENSIONS = 1536

r = redis.from_url(os.environ['STACKHERO_REDIS_URL_TLS'])

# Crie o índice uma vez, no arranque
try:
    r.ft('chunksIndex').create_index(
        (
            TextField('content'),
            TagField('documentId'),
            VectorField(
                'embedding',
                'HNSW',
                {'TYPE': 'FLOAT32', 'DIM': DIMENSIONS, 'DISTANCE_METRIC': 'COSINE'},
            ),
        ),
        definition=IndexDefinition(prefix=['chunk:'], index_type=IndexType.HASH),
    )
except redis.ResponseError as error:
    if 'Index already exists' not in str(error):
        raise


def index_chunk(chunk_id, document_id, content, embedding):
    r.hset(
        f'chunk:{chunk_id}',
        mapping={
            'content': content,
            'documentId': document_id,
            'embedding': np.array(embedding, dtype=np.float32).tobytes(),
        },
    )


def retrieve(question_embedding, document_id, count=5):
    query = (
        Query(f'(@documentId:{{{document_id}}})=>[KNN {count} @embedding $queryVector AS score]')
        .sort_by('score')
        .return_fields('content', 'score')
        .dialect(2)
    )
    results = r.ft('chunksIndex').search(
        query,
        query_params={'queryVector': np.array(question_embedding, dtype=np.float32).tobytes()},
    )
    return [document.content for document in results.docs]

Dimensionar o seu serviço

Os vetores são armazenados em memória. Pode estimar as necessidades de memória com a seguinte fórmula:

numberOfVectors x dimensions x 4 bytes, mais cerca de 30–50% extra para o grafo HNSW.

Por exemplo, um milhão de vetores de 1536 dimensões utilizam cerca de 6 GB para os vetores brutos. Um plano de 20 GB é um ponto de partida confortável para esta escala. Pode reduzir o consumo de memória:

• Utilizando um modelo mais pequeno. Por exemplo, um modelo de 768 dimensões reduz para metade a memória utilizada em comparação com um modelo de 1536 dimensões.
• Armazenando em FLOAT16 em vez de FLOAT32 se o seu modelo o suportar, reduzindo novamente o espaço para metade.

Pode monitorizar o uso real com FT.INFO chunksIndex e a métrica used_memory na sua monitorização Prometheus. Se o seu consumo aumentar, pode atualizar o seu plano facilmente a partir do dashboard.

Informações úteis

• Os índices vetoriais só funcionam na base de dados 0, tal como todos os índices de pesquisa em Redis.
• Os conjuntos vetoriais oferecem uma alternativa mais simples sem necessidade de configuração. Os comandos VADD e VSIM estão integrados no Redis, permitindo utilizar a pesquisa por similaridade de imediato, sem ativar módulos. Isto é conveniente para cenários de recomendação simples num único conjunto. O motor de pesquisa é preferível quando necessita de filtros, paginação ou múltiplos campos.
• A construção de um índice sobre chaves existentes é feita em background. Pode acompanhar o progresso com FT.INFO. As pesquisas devolvem resultados parciais até a indexação estar concluída.

Para saber mais sobre pesquisa vetorial em Redis, consulte a documentação oficial Redis vector search.