npm package: @lacanna/n8n-nodes-google-vertex-vector-search
Description: n8n node for Google Vertex AI Vector Search operations
Author: lacanna
Latest version: 1.0.0

# 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**:
```bash
cd n8n
npm install
```

2. **Compilar o projeto**:
```bash
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

```json
{
  "resource": "index",
  "operation": "create",
  "location": "us-central1",
  "indexName": "documentos-empresa",
  "dimensions": 768,
  "distanceMeasureType": "COSINE_DISTANCE"
}
```

### 2. Inserir Embeddings

```json
{
  "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

```json
{
  "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

```json
{
  "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! 🎉**