Integre inventário de hardware com busca por similaridade vetorial no n8n

O que é e por que usar

Gerenciar um inventário de hardware, seja de computadores, servidores, componentes de rede ou dispositivos IoT, é uma tarefa crítica para departamentos de TI, operações e manutenção. Tradicionalmente, essa gestão depende de planilhas ou sistemas de banco de dados relacionais onde as buscas são baseadas em correspondências exatas de texto ou IDs. No entanto, essa abordagem falha quando você precisa encontrar um item com base em uma descrição textual vaga, incompleta ou escrita de forma diferente do registro oficial.

A busca por similaridade vetorial, ou vector similarity search, resolve esse problema. Em vez de comparar strings diretamente, ela converte textos (como a descrição de um laptop ou as especificações de um roteador) em representações numéricas chamadas embeddings ou vetores. Esses vetores capturam o significado semântico do texto. Dois itens semanticamente similares, como “Notebook Dell Latitude com 16GB RAM” e “Laptop Dell Lat. 16GB de memória”, terão vetores muito próximos no espaço multidimensional, mesmo que as strings sejam diferentes. Integrar essa tecnologia ao seu fluxo de inventário no n8n permite criar sistemas inteligentes de busca, classificação automática de entradas e reconciliação de dados a partir de fontes desestruturadas.

O uso prático é imediato: imagine um técnico de campo enviando uma mensagem pelo Teams descrevendo um problema com “o switch da sala 301, modelo antigo Cisco”. Um fluxo n8n pode pegar essa descrição, convertê-la em um vetor, buscar no banco de vetores do inventário e retornar o ativo exato (ex: “Switch Cisco Catalyst 2960-X na Sala 301, ID: NET-045”), acelerando a resolução do chamado em mais de 70% do tempo de busca manual.

Pré-requisitos

Acesso a uma instância do n8n (cloud ou self-hosted).
Uma conta de serviço em um provedor de modelos de embeddings. Recomenda-se OpenAI (GPT), Cohere, ou modelos locais via Hugging Face.
Um banco de dados que suporte busca vetorial ou um serviço dedicado. Opções viáveis incluem:
- PostgreSQL com a extensão pgvector (custo zero, ideal para começar).
- Pinecone, Weaviate ou Qdrant (serviços especializados em nuvem).
- Redis com o módulo RedisSearch.
Seu inventário de hardware em um formato acessível, como uma tabela CSV, uma planilha Google Sheets, ou um banco de dados SQL.
Conhecimento básico de como criar workflows no n8n e conectar nós.

Exemplo Prático: Busca Inteligente de Ativos a Partir de Descrições de Chamados

Detailed macro shot of a red circuit board, highlighting electronic components and microchips.

Cenário concreto: Sua equipe de suporte recebe dezenas de chamados por dia via email, formulário web ou Microsoft Teams. Muitas vezes, o usuário final descreve o equipamento com problemas de forma coloquial e imprecisa (ex: “meu monitor da Dell está piscando”, “o notebook novo travou”). O técnico precisa identificar, no sistema de inventário com 2000+ itens, qual é o ativo exato para registrar a manutenção, verificar a garantia e agendar a visita. A busca manual por termos parciais em um banco de dados consome em média 5-10 minutos por chamado.

O que será automatizado: Vamos construir um workflow no n8n que será acionado por um novo chamado (via webhook). O fluxo irá:

Extrair a descrição do equipamento do corpo do chamado.
Converter essa descrição em um vetor (embedding) usando a API da OpenAI.
Realizar uma busca por similaridade vetorial em um banco PostgreSQL com pgvector que contém o inventário já vetorizado.
Retornar os 3 ativos de hardware mais similares, com seus IDs, localizações e especificações, para o técnico ou para o sistema de tickets.

Resultado esperado: Em menos de 3 segundos, o técnico recebe uma lista priorizada dos ativos mais prováveis relacionados à descrição do usuário. Para a descrição “notebook preto da Apple com touch bar”, o sistema pode retornar: 1. “MacBook Pro 13′ (2023), Prateado, ID: IT-7843, Usuário: João Silva”; 2. “MacBook Air M2 (2022), Cinza-espacial, ID: IT-9912”. Isso elimina a ambiguidade e acelera drasticamente o processo de triagem.

Configuração Passo a Passo

Vamos construir o workflow em duas partes: (A) A Criação do Banco de Dados Vetorial e (B) O Fluxo de Busca em Tempo Real.

Parte A: Preparando o Banco de Dados de Inventário com Embeddings

Configurar PostgreSQL com pgvector:

Instale a extensão no seu banco: CREATE EXTENSION IF NOT EXISTS vector;

Crie uma tabela para o inventário:

CREATE TABLE hardware_inventory (
  id SERIAL PRIMARY KEY,
  asset_id VARCHAR(50) UNIQUE,
  description TEXT,
  category VARCHAR(100),
  location VARCHAR(100),
  specifications JSONB,
  embedding vector(1536) -- Dimensão para text-embedding-ada-002 da OpenAI
);

Criar um workflow n8n de “População Inicial”:
- Nó 1: “Google Sheets” ou “CSV File”: Para ler sua lista de ativos existente. Configure para extrair as colunas: asset_id, description, category, etc.
- Nó 2: “OpenAI” (tipo Embeddings):
  - Model: text-embedding-ada-002.
  - No campo “Text”, mapeie a descrição do item do nó anterior (ex: {{$json["description"]}}).
  - Este nó gerará um array de números (o vetor) para cada item.
- Nó 3: “PostgreSQL” (tipo Insert):
  - Conecte-se ao seu banco com pgvector.
  - Mode de operação: Insert.
  - Mapeie os campos da tabela. O campo embedding é crítico. Use a seguinte sintaxe no modo “Specify below”:
```
INSERT INTO hardware_inventory (asset_id, description, category, embedding)
VALUES ($1, $2, $3, $4::vector);
```
    E defina os valores:
    - Parameter 1 (asset_id): {{$json["asset_id"]}}
    - Parameter 2 (description): {{$json["description"]}}
    - …
    - Parameter 4 (embedding): {{$json["openai"]["data"][0]["embedding"]}}
Execute este fluxo uma vez para processar todo o seu inventário histórico.

Parte B: Fluxo de Busca em Tempo Real (Webhook → Busca → Resposta)

Nó 1: “Webhook” (n8n Trigger):
- Configure um webhook único (ex: find-hardware).
- Este será o endpoint que seu sistema de tickets ou bot do Teams chamará.
Nó 2: “OpenAI” (tipo Embeddings):
- Model: text-embedding-ada-002.
- Text: {{$json.body.query}} (assumindo que o webhook envia {"query": "descrição do usuário"}).

Nó 3: “Function” ou “Code” (para formatar a consulta SQL):

Precisamos criar uma consulta SQL que use a função de similaridade do pgvector. Use o nó “Code” (Python) ou “Function” (JavaScript).

// Modo JavaScript no nó Function
const queryEmbedding = $input.first().json.openai.data[0].embedding;
const sqlQuery = `
  SELECT 
    asset_id,
    description,
    location,
    1 - (embedding <=> '[${queryEmbedding}]') as similarity
  FROM hardware_inventory
  ORDER BY embedding <=> '[${queryEmbedding}]'
  LIMIT 3;
`;
return [{ json: { sql: sqlQuery, embedding: queryEmbedding } }];

Nó 4: “PostgreSQL” (tipo Execute Query):
- Mode: Execute Query.
- Query: {{$json["sql"]}} (mapeado a partir do nó Function).
- Este nó retornará os 3 itens mais similares, com uma pontuação de similaridade (onde 1 é idêntico).

Nó 5: “HTTP Request” ou “Respond to Webhook”:

Formate a resposta em JSON para o sistema solicitante.

{
  "query": "{{$node[\"Webhook\"].json[\"body\"][\"query\"]}}",
  "results": {{$json["PostgreSQL"]["rows"]}}
}

Dicas e Variações

Filtragem Híbrida: Combine a busca vetorial com filtros tradicionais. Por exemplo, antes da busca por similaridade, filtre apenas itens da category = 'laptop' ou location = 'São Paulo'. Isso aumenta a precisão e o desempenho.
Use Metadados Estruturados: Enriqueça o texto para geração do embedding concatenando campos. Em vez de usar apenas a descrição, crie um campo como: "{{category}}: {{asset_id}} - {{description}}. Local: {{location}}. Especificações: {{specifications}}". Isso dá mais contexto para o modelo.
Modelos de Embedding Alternativos: Para dados sensíveis ou para reduzir custos, use modelos locais. O nó “Hugging Face” no n8n pode executar modelos como all-MiniLM-L6-v2 diretamente, sem chamadas externas. A dimensão do vetor será diferente (ex: 384), ajuste sua tabela pgvector de acordo.
Atualização Contínua: Crie um sub-fluxo que seja acionado sempre que um novo item for adicionado ao inventário (via Google Forms, por exemplo). Esse fluxo gera o embedding e insere no banco automaticamente, mantendo o sistema sempre atualizado.
Interface Simples com Chatbot: Conecte o webhook inicial a um nó do Microsoft Teams, Slack ou Telegram. Os técnicos podem simplesmente digitar “procurar: switch sala 301” no chat e receber os resultados diretamente.

Erros Comuns e Como Evitá-los

Dimensão do Vetor Incompatível: O erro "vector must have dimension X" ocorre se você tentar inserir um vetor de 1536 dimensões em um campo definido como vector(384). Solução: Verifique a dimensão do modelo de embedding usado e declare a coluna da tabela com o mesmo tamanho.
Custo Inesperado da API OpenAI: Processar milhares de itens na população inicial pode gerar custos. Solução: Para inventários muito grandes, considere um modelo de embedding de custo fixo ou local. Sempre estime o custo usando o preço por token do modelo escolhido antes da execução em massa.
Baixa Qualidade dos Resultados: Se as buscas retornarem itens não relacionados, o problema está na qualidade do texto fonte. Solução: Padronize e limpe as descrições do inventário base. Remova siglas ambíguas, adicione sinônimos comuns e use a dica de enriquecimento de metadados.
Performance Lenta na Busca: Sem um índice, buscar similaridade em milhares de vetores é lento. Solução: No PostgreSQL, crie um índice HNSW para o campo embedding após a população inicial: CREATE INDEX ON hardware_inventory USING hnsw (embedding vector_cosine_ops);.
Falha no Parsing do JSON do Embedding: Ao passar o vetor do nó OpenAI para o SQL, ele deve ser formatado como um array. Solução: Use a função do nó “Code” ou “Function” para garantir a formatação correta, como mostrado no passo a passo, envolvendo o array em colchetes.

Próximos Passos

Agora que você tem a base para integrar inventário de hardware com busca vetorial no n8n, é hora de evoluir a automação. Comece com um piloto:

Implemente o Fluxo de População Inicial com um subconjunto pequeno do seu inventário (ex: 50 itens) para validar o pipeline de ponta a ponta.
Conecte uma Fonte de Chamados Real, como uma coluna específica de um Google Sheets de suporte ou um webhook de teste do Microsoft Power Automate.
Meça o Ganho de Tempo comparando o tempo médio de busca manual versus o resultado do seu fluxo. Use esses dados para justificar a expansão do projeto para toda a base de ativos.
Explore a Automação Proativa: Com o inventário vetorizado, você pode criar fluxos que monitoram descrições de compras futuras e sugerem itens similares já em estoque, evitando duplicações e otimizando custos.

A integração de busca por similaridade vetorial transforma seu inventário de um repositório passivo em um sistema de inteligência ativa, tornando a informação acessível não por como foi cadastrada, mas por como as pessoas naturalmente a buscam.