Google Vertex AI Vector Search Node for n8n

Este é um nó personalizado do n8n que oferece integração completa com o Google Vertex AI Vector Search.

🚀 Funcionalidades

Gerenciamento de Índices

• Criar Índice: Criar novos índices do Vector Search com dimensões e medidas de distância configuráveis
• Obter Índice: Recuperar detalhes do índice
• Listar Índices: Listar todos os índices disponíveis
• Deletar Índice: Remover índices

Gerenciamento de Endpoints

• Criar Endpoint: Criar novos endpoints de índice
• Implantar Índice: Implantar índices em endpoints para consultas
• Consultar Endpoint: Realizar pesquisas de similaridade contra índices implantados

Operações de Dados

• Upsert Data Points: Inserir ou atualizar embeddings com metadados
• Remover Data Points: Deletar embeddings específicos por ID

📋 Pré-requisitos

Configuração do Google Cloud

1. APIs Habilitadas: Habilitar a API do Vertex AI no seu projeto Google Cloud
2. Conta de Serviço: Criar uma conta de serviço com permissões do Vertex AI:
   • Vertex AI User
   • Storage Object Viewer (se acessando Cloud Storage)
3. Chave JSON: Baixar o arquivo de chave JSON da conta de serviço

⚙️ Instalação

1. Instalar dependências:

cd n8n
npm install

2. Compilar o projeto:

npm run build

3. Instalar no n8n:
   • Copie a pasta dist para o diretório de nós personalizados do n8n
   • Ou instale como um pacote npm

🔧 Configuração

Setup de Credenciais

1. No n8n, vá para Credentials e crie uma nova credencial Google Vertex AI API
2. Preencha:
   • Service Account Email: Seu email da conta de serviço
   • Private Key: A chave privada do arquivo JSON (incluindo cabeçalhos)
   • Project ID: Seu ID do projeto Google Cloud

📊 Exemplos de Uso

1. Criar um Índice Vector Search

{
  "resource": "index",
  "operation": "create",
  "location": "us-central1",
  "indexName": "documentos-empresa",
  "dimensions": 768,
  "distanceMeasureType": "COSINE_DISTANCE"
}

2. Inserir Embeddings

{
  "resource": "dataPoint",
  "operation": "upsert",
  "indexId": "seu-index-id",
  "dataPoints": "[{\"datapointId\": \"doc1\", \"featureVector\": [0.1, 0.2, ...], \"restricts\": [{\"namespace\": \"categoria\", \"allowList\": [\"documentos\"]}]}]"
}

3. Consultar Documentos Similares

{
  "resource": "indexEndpoint",
  "operation": "query", 
  "endpointId": "seu-endpoint-id",
  "queryVector": "[0.1, 0.2, 0.3, ...]",
  "neighborCount": 10
}

🔄 Integração com seu Workflow

Pipeline Cloud Storage → Vector Search

Este nó funciona perfeitamente com seu workflow atual:

Evento Cloud Storage → 
Pub/Sub → 
Download Documento → 
Extrair Texto → 
Gerar Embeddings (Google Vertex Embeddings) → 
Armazenar no Vector Search (Este Nó) → 
Consultar Documentos Similares (Este Nó)

📝 Formato dos Data Points

{
  "datapointId": "id-unico",
  "featureVector": [0.1, 0.2, 0.3, ...],
  "restricts": [{"namespace": "categoria", "allowList": ["tipo1"]}],
  "crowdingTag": "tag-opcional"
}

🛠️ Para Desenvolvimento

Estrutura do Projeto

n8n/
├── nodes/GoogleVertexVectorSearch/
│   ├── GoogleVertexVectorSearch.node.ts    # Lógica principal do nó
│   └── google-vertex-ai.svg                # Ícone do nó
├── credentials/
│   └── GoogleVertexAiApi.credentials.ts     # Configuração de autenticação
├── dist/                                    # Saída compilada
├── package.json                             # Dependências e configuração
├── tsconfig.json                           # Configuração TypeScript
└── gulpfile.js                             # Build config

Scripts Disponíveis

• npm run build - Compilar TypeScript e copiar ícones
• npm run dev - Modo de desenvolvimento com watch
• npm run lint - Verificar código
• npm run format - Formatar código

🔍 Troubleshooting

Problemas Comuns

1. Erros de Autenticação: Verificar permissões da conta de serviço e formato da chave
2. Incompatibilidade de Dimensões: Garantir que as dimensões dos embeddings correspondam à configuração do índice
3. Erros de Localização: Usar localizações consistentes para todos os recursos
4. Limites de Quota: Verificar quotas do Vertex AI no Console do Google Cloud

📄 Licença

MIT License - veja o arquivo LICENSE para detalhes.

🤝 Contribuição

Contribuições são bem-vindas! Este é um projeto open-source.

💡 Próximos Passos

1. Atualize o arquivo .env com suas credenciais reais do Google Cloud
2. Instale e configure o nó no seu n8n
3. Crie índices e endpoints do Vector Search no Google Cloud
4. Teste o pipeline completo com documentos reais
5. Configure bucket do Cloud Storage e triggers Pub/Sub

Pronto para integrar seus embeddings com Vector Search! 🎉