# 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…

- Página: <https://www.datafirefly.com/pt/documentation/vector-search-native/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/vector-search-native/index.md), [en](https://www.datafirefly.com/en/documentation/vector-search-native/index.md), [es](https://www.datafirefly.com/es/documentation/vector-search-native/index.md), [de](https://www.datafirefly.com/de/documentation/vector-search-native/index.md), [it](https://www.datafirefly.com/it/documentation/vector-search-native/index.md), [pl](https://www.datafirefly.com/pl/documentation/vector-search-native/index.md), [nl](https://www.datafirefly.com/nl/documentation/vector-search-native/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## 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](https://platform.openai.com/api-keys), [Voyage AI](https://dash.voyageai.com/) ou [Cohere](https://dashboard.cohere.com/api-keys)
- WP-Cron funcional (ou um cron de sistema que chame o wp-cron.php)

Não é exigida qualquer extensão MySQL específica, nem servidor Redis ou Elasticsearch. O cálculo de similaridade é feito em PHP puro, o que torna o plugin compatível com qualquer alojamento partilhado padrão.

## 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.

Mudar de fornecedor ou de modelo torna os vetores existentes incompatíveis (dimensões diferentes). Depois de uma mudança, lance sempre uma reindexação completa.

## 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.

Custo indicativo: cerca de 0,02 € por 1000 produtos com o OpenAI text-embedding-3-small. A indexação incremental por hash SHA-256 garante que um produto inalterado nunca desencadeia uma chamada à API, mesmo que a fila volte a percorrê-lo.

## 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).