Vector Search Native: documentação completa

Apresentação

O Vector Search Native transforma a pesquisa de produtos do WooCommerce num motor semântico. Em vez de comparar palavras-chave letra a letra, o plugin converte cada produto e cada consulta em vetores numéricos (embeddings) através de um modelo de IA, e depois calcula a similaridade de sentido. Resultado: um cliente que escreve «casaco verão algodão leve» encontra o seu «blazer estival em linho», mesmo sem qualquer palavra em comum.

O plugin suporta três fornecedores de embeddings, OpenAI, Voyage AI e Cohere, intercambiáveis num clique, com uma indexação incremental que só chama a API quando o conteúdo de um produto mudou realmente, e um recurso automático à pesquisa por palavras-chave nativa quando a pesquisa vetorial não chega.

Requisitos

• WordPress 6.2 ou superior
• WooCommerce 7.0 ou superior (testado até à 9.4)
• PHP 8.0 ou superior
• Uma chave de API num dos três fornecedores: OpenAI, Voyage AI ou Cohere
• WP-Cron funcional (ou um cron de sistema que chame o wp-cron.php)

Instalação

1. No back-office do WordPress, vá a Plugins → Adicionar → Carregar plugin.
2. Selecione o ficheiro vector-search-native.zip e clique em Instalar agora.
3. Clique em Ativar. O plugin cria automaticamente as suas duas tabelas (wp_vsn_embeddings e wp_vsn_index_queue) e agenda a tarefa cron.
4. Aparece um novo menu Vector Search por baixo de WooCommerce.

Configuração do fornecedor

Vá a WooCommerce → Vector Search. A secção «Embedding provider» lista os três fornecedores disponíveis. Selecione o que quiser no menu pendente «Active provider», cole a sua chave de API no bloco correspondente, escolha um modelo e clique em Test connection. Uma mensagem verde a confirmar a dimensão do vetor (por exemplo «Connection OK. Embedding dimension: 1536») valida a configuração.

Que modelo escolher

• OpenAI text-embedding-3-small (1536d): a melhor relação qualidade/preço, recomendado por predefinição.
• OpenAI text-embedding-3-large (3072d): qualidade máxima, cerca de 6 vezes mais caro.
• Voyage voyage-3 (1024d): excelente recuperação, treinado para pesquisa.
• Cohere embed-multilingual-v3.0 (1024d): a escolha para catálogos multilingues em PT/FR/EN/ES/DE/IT.

Indexação inicial

1. Ainda na página Vector Search, clique em Queue all products for reindex. Todos os produtos publicados entram na fila de espera.
2. Clique em Auto-process until done. O plugin trata a fila por lotes (25 produtos por predefinição) até a esgotar, em direto a partir do seu navegador.
3. Os contadores «Indexed», «Queued» e «Stuck» atualizam-se em tempo real.

Também pode deixar o WP-Cron fazer o trabalho em segundo plano: a tarefa vsn_process_queue corre conforme o intervalo configurado (5 minutos por predefinição) e vai esvaziando a fila.

Funcionamento da pesquisa

Concluída a indexação, a pesquisa de produtos do WooCommerce (front-end e widgets padrão) é intercetada automaticamente. O plugin:

1. Converte a consulta do visitante num vetor através do fornecedor ativo (com cache de 10 minutos).
2. Calcula a similaridade por cosseno contra todos os vetores de produto guardados.
3. Retém os produtos que ultrapassam o limiar mínimo de similaridade (0,30 por predefinição), dentro do número máximo de candidatos (200 por predefinição).
4. Injeta os IDs ordenados por pertinência na consulta do WordPress.

Se o número de resultados for inferior ao limiar de recurso (3 por predefinição), o plugin afasta-se e deixa a pesquisa por palavras-chave nativa do WooCommerce funcionar normalmente. Os seus visitantes nunca veem uma página vazia por causa de um problema do lado da IA.

Definições avançadas

Conteúdo indexado

A secção «Content to index» permite escolher os campos incluídos no embedding: descrição curta, descrição longa, SKU, categorias, etiquetas e atributos. O título do produto é sempre indexado. Reduzir os campos pode afinar a pertinência em certos catálogos; incluí-los todos maximiza a abrangência.

Limiares e candidatos

• Minimum similarity (0,0 a 1,0): abaixo deste valor de cosseno, um produto não é retido. Suba para 0,4 ou 0,5 para filtrar de forma agressiva, desça para 0,2 para alargar.
• Max candidates: número de produtos devolvidos ao WooCommerce após a ordenação. A paginação aplica-se depois normalmente.
• Fallback threshold: número mínimo de resultados vetoriais antes de passar às palavras-chave.

Fila de espera e cron

• Cron interval: frequência de processamento da fila (1, 5, 15 minutos ou horária).
• Batch size (1 a 100): produtos tratados por passagem. Aumente com prudência para evitar os limites de débito do fornecedor.
• Cada produto que falhe é repetido até 5 vezes, com a última mensagem de erro guardada na base de dados. O contador «Stuck» assinala os produtos que esgotaram as tentativas.

API REST

São expostos cinco endpoints em /wp-json/vsn/v1/, todos reservados aos utilizadores com a permissão manage_woocommerce:

• POST /reindex: coloca todos os produtos na fila de espera.
• POST /process: trata um lote de imediato.
• GET /stats: devolve os contadores (total, indexados, em fila, bloqueados).
• POST /test: testa uma chave de API (parâmetros: provider, api_key, model).
• POST /clear: esvazia por completo o índice de embeddings.

Exemplo de reindexação completa a partir de um script de implantação:

curl -X POST https://a-sua-loja.pt/wp-json/vsn/v1/reindex 
  -u admin:PALAVRA_PASSE_DE_APLICACAO

Hooks para programadores

vsn_indexed_text

Personaliza o texto enviado ao fornecedor para cada produto. Ideal para injetar campos ACF ou metas de negócio:

add_filter( 'vsn_indexed_text', function ( $text, $product ) {
    $material = get_post_meta( $product->get_id(), 'material', true );
    if ( $material ) {
        $text .= "nMaterial: " . $material;
    }
    return $text;
}, 10, 2 );

vsn_should_engage

Controla com precisão quando a pesquisa vetorial se ativa:

// Desativar a pesquisa vetorial nas consultas de uma só palavra.
add_filter( 'vsn_should_engage', function ( $engage, $query ) {
    $s = (string) $query->get( 's' );
    if ( str_word_count( $s ) < 2 ) {
        return false;
    }
    return $engage;
}, 10, 2 );

Lojas multilingues

Com o WPML ou o Polylang, cada tradução é um produto WordPress distinto: cada uma é portanto convertida em embedding em separado, no seu próprio idioma. Duas recomendações:

• Use um modelo multilingue (Cohere embed-multilingual-v3.0 ou Voyage voyage-multilingual-2) para que as consultas e as fichas sejam projetadas no mesmo espaço semântico, seja qual for o idioma.
• Depois de acrescentar um novo idioma ou de uma campanha de tradução em massa, lance uma reindexação completa para cobrir os novos produtos.

Resolução de problemas

Há produtos que ficam em «Stuck»

Um produto passa a «Stuck» após 5 falhas consecutivas. As causas frequentes: chave de API inválida ou expirada, limite de débito do fornecedor, ou tempo limite de rede. Verifique a chave com Test connection, corrija, e clique em Queue all products for reindex, o que repõe a zero os contadores de tentativas.

A pesquisa parece inalterada

• Verifique que a caixa Enabled está assinalada nas definições gerais.
• Verifique que o contador «Indexed» corresponde ao seu número de produtos.
• Se usar um plugin de pesquisa de terceiros (FiboSearch, SearchWP…), esse plugin pode contornar a consulta padrão do WordPress antes da interceção. Desative-o ou contacte-nos para um ajuste de integração.

A fila não se esvazia sozinha

O WP-Cron só dispara com as visitas. Num site de baixo tráfego, configure um cron de sistema:

*/5 * * * * curl -s https://a-sua-loja.pt/wp-cron.php > /dev/null 2>&1

Desinstalação

A desativação do plugin suspende o cron mas conserva os dados. A remoção do plugin a partir da página de Plugins aciona o uninstall.php, que elimina as duas tabelas MySQL, a opção de definições e as tarefas agendadas. Sem qualquer resíduo na base de dados.

FAQ

Posso usar o plugin sem chave de API?

Não, a pesquisa semântica precisa de um fornecedor. Sem chave, o plugin fica inerte e a pesquisa nativa do WooCommerce continua a funcionar normalmente.

As chaves de API ficam expostas do lado do cliente?

Não. Todas as chamadas aos fornecedores são feitas no servidor, a partir do PHP. A chave nunca aparece no HTML nem nos pedidos do navegador.

Que volume de catálogo é suportado?

A análise por cosseno em PHP mantém-se muito eficiente até cerca de 50 000 produtos num alojamento partilhado padrão. Acima disso, contacte-nos para falarmos de uma integração com um índice dedicado de vizinhos aproximados (approximate nearest neighbor).