Passa al contenuto principale

Introduzione

Il Node Worker è il componente responsabile dell'esecuzione di tutte le attività in background della piattaforma Tidiko AI. Utilizza il sistema di code Hatchet per gestire operazioni asincrone complesse come l'elaborazione di documenti, la generazione di embedding e il salvataggio delle conversazioni.

Architettura del Worker​

Componenti Principali​

Il worker è strutturato in due worker specializzati che gestiscono tipi specifici di attività:

1. Embeddings Worker​

  • Scopo: Gestione di tutte le operazioni relative agli embedding e al vector store
  • Capacità: 300 task concorrenti
  • Workflow principali:
    • resource-embedding-workflow: Elaborazione completa di risorse (file, URL, prodotti)
    • embed-resource-task: Generazione e salvataggio embedding
    • query-embedding-task: Generazione embedding per query di ricerca

2. Chat Logger Worker​

  • Scopo: Salvataggio dei messaggi delle conversazioni su Laravel
  • Capacità: 100 task concorrenti
  • Workflow principali:
    • chat-logger-task: Salvataggio messaggi chat su database Laravel

Tecnologie Utilizzate​

  • Hatchet: Sistema di code per gestione task asincroni
  • Qdrant: Vector database per storage degli embedding
  • Jina AI: Servizio per generazione embedding
  • Crawlee + Playwright: Sistema di crawling interno avanzato (sostituisce Crawl4AI)
  • MinIO: Object storage per risultati crawling e file temporanei
  • LangChain: Framework per elaborazione documenti
  • Express: Server HTTP per API endpoints

Funzionalità Principali​

1. Elaborazione Documenti​

  • File Supportati: PDF, DOCX, TXT, CSV, Excel, XML, JSON
  • Processo:
    1. Caricamento e parsing del documento
    2. Suddivisione in chunk ottimali
    3. Generazione embedding tramite Jina AI
    4. Salvataggio su Qdrant con metadati strutturati

2. Elaborazione URL e Crawling Avanzato​

  • Crawler Interno: Sistema Crawlee + Playwright per crawling robusto
  • Tipi Supportati:
    • URL singoli
    • URL multipli
    • Sitemap XML ricorsive (multi-livello)
  • Caratteristiche Avanzate:
    • Batching Automatico: Divisione in batch da 10 URL per ottimizzazione
    • Pipeline HTML → Markdown: Conversione intelligente con rimozione elementi non utili
    • SPA Support: Gestione automatica di Single Page Applications
    • Framework Detection: Rilevamento automatico di React, Vue, Angular, etc.
    • MinIO Storage: Salvataggio persistente dei risultati crawling
  • Processo:
    1. Parsing sitemap ricorsivo (se applicabile)
    2. Crawling con Playwright headless
    3. Estrazione contenuto basata su framework rilevato
    4. Conversione HTML → Markdown pulito
    5. Salvataggio su MinIO per persistenza
    6. Suddivisione in chunk ottimali
    7. Generazione e salvataggio embedding

3. Elaborazione Prodotti E-commerce​

  • Integrazione: WooCommerce REST API
  • Processo:
    1. Estrazione prodotti, categorie e attributi
    2. Generazione embedding per ricerca semantica
    3. Salvataggio strutturato su Qdrant

4. Gestione Rate Limiting​

  • TPM (Tokens Per Minute): 50,000,000 token/minuto
  • Controllo automatico: Bucket system per gestione limiti
  • Retry intelligente: Backoff esponenziale per fallimenti

5. Salvataggio Conversazioni​

  • Integrazione Laravel: API REST per persistenza dati
  • Metadati completi: Token usage, timestamp, modello utilizzato
  • Gestione errori: Retry automatico con backoff

Flusso di Lavoro​

Elaborazione Risorse​

Gestione Code​

  1. Ricezione Task: Il worker riceve task dal Node Agent
  2. Rate Limiting: Controllo automatico dei limiti API
  3. Elaborazione Batch: Processamento in batch di 30 task per volta
  4. Retry Logic: Gestione automatica dei fallimenti
  5. Cleanup: Pulizia risorse temporanee

Configurazione e Deployment​

Variabili d'Ambiente Richieste​

  • QDRANT_URL: URL del cluster Qdrant
  • QDRANT_API_KEY: Chiave API per Qdrant
  • JINA_API_KEY: Chiave API per Jina AI
  • LARAVEL_API_URL: URL dell'API Laravel
  • HATCHET_CLIENT_TOKEN: Token per connessione Hatchet
  • MINIO_ENDPOINT: URL endpoint MinIO (es. http://minio:9000)
  • MINIO_ACCESS_KEY: Chiave accesso MinIO
  • MINIO_SECRET_KEY: Chiave segreta MinIO
  • MINIO_BUCKET_NAME: Nome bucket per storage risultati

Avvio Worker​

# Embeddings Worker
pnpm run start workers/embeddingsWorker.ts

# Chat Logger Worker
pnpm run start workers/chatLoggerWorker.ts

Monitoraggio e Logging​

  • Winston Logger: Sistema di logging strutturato
  • Metriche Hatchet: Monitoraggio performance task
  • Health Check: Endpoint /health per verifica stato
  • Error Tracking: Log dettagliati per debugging

Sicurezza​

  • JWT Authentication: Autenticazione per API endpoints
  • CORS Configuration: Controllo accessi cross-origin
  • File Validation: Controllo tipi file e dimensioni
  • Rate Limiting: Protezione da abusi API