Passa al contenuto principale

Gestione Embeddings

Il sistema di gestione embeddings è il cuore del worker, responsabile della generazione, elaborazione e salvataggio di embedding per la ricerca semantica.

Architettura del Sistema​

Componenti Principali​

  • Jina AI Service: Generazione embedding tramite API
  • Qdrant Client: Storage e retrieval degli embedding
  • Token Counter: Conteggio token per rate limiting
  • Text Splitter: Suddivisione documenti in chunk ottimali

Tecnologie Utilizzate​

  • Jina AI: Servizio cloud per generazione embedding
  • Qdrant: Vector database per storage
  • LangChain: Text splitting e processing
  • Tiktoken: Tokenization per conteggio preciso

Processo di Generazione Embeddings​

1. Preparazione Contenuto​

/src/services/jinaSimpleEmbeddingService.ts
// Suddivisione in chunk ottimali
const textSplitter = new RecursiveCharacterTextSplitter({
	chunkSize: 1000,
	chunkOverlap: 200,
	separators: ['\n\n', '\n', ' ', ''],
})

const chunks = await textSplitter.splitText(content)

2. Conteggio Token​

/src/services/jinaSimpleEmbeddingService.ts
// Conteggio token per rate limiting
const tokenCount = await getTextTokens(text)
await withdrawTPM(tokenCount)

3. Generazione Embedding​

/src/services/jinaSimpleEmbeddingService.ts
// Chiamata API Jina AI
const embeddings = await generateEmbeddings([{ text: chunk }], 'retrieval.passage', ctx)

4. Salvataggio su Qdrant​

/src/services/jinaSimpleEmbeddingService.ts
// Salvataggio con metadati strutturati
await qdrantClient.upsert(collectionName, {
	points: [
		{
			id: uuid(),
			vector: embedding,
			payload: {
				content: chunk,
				metadata: structuredMetadata,
			},
		},
	],
})

Tipi di Embedding​

Retrieval Passage​

  • Uso: Documenti e contenuti per ricerca
  • Modello: jina-embeddings-v3
  • Dimensione: 768 dimensioni

Retrieval Query​

  • Uso: Query di ricerca degli utenti
  • Modello: jina-embeddings-v3
  • Dimensione: 768 dimensioni

Rate Limiting e Performance​

Token Per Minute (TPM)​

  • Limite: 50,000,000 token/minuto
  • Gestione: Bucket system con reset automatico
  • Controllo: Mutex per operazioni thread-safe

Batch Processing​

  • Dimensione Batch: 30 task per volta
  • Concorrenza: 300 slot per embeddings worker
  • Timeout: 1 ora per task complessi

Metadati Strutturati​

Base Metadata Interface​

/src/types/embeddingsTypes.ts
interface BaseQdrantMetadata<T> {
	source: string
	type: T
	[key: string]: string | number | string[] | object
}

Tipi di Metadati​

Documento Standard​

/src/types/embeddingsTypes.ts
interface DocumentMetadata extends BaseQdrantMetadata<BaseQdrantMetadataType.DOCUMENT> {
	resource_uuid: string
	collection_name: string
	chunk_index: number
	total_chunks: number
	file_name?: string
	file_type?: string
	url?: string
}

Prodotto E-commerce​

/src/types/embeddingsTypes.ts
interface ProductMetadata extends BaseQdrantMetadata<BaseQdrantMetadataType.PRODUCT> {
	product_id: number | string
	slug: string
	sku: string
	categories: string[]
	variants: {
		attributes: { [key: string]: string }[]
	}[]
}

Workflow di Elaborazione​

Resource Embedding Workflow​

  1. Prepare Task: Elaborazione e suddivisione contenuto
  2. Embed Task: Generazione embedding per ogni chunk
  3. Cleanup Task: Pulizia file temporanei

Query Embedding Task​

  1. Ricezione Query: Query di ricerca utente
  2. Generazione Embedding: Conversione in vettore
  3. Ritorno Risultato: Embedding per ricerca semantica

Configurazione​

Variabili d'Ambiente​

# Jina AI Configuration
JINA_API_KEY=your_jina_api_key
JINA_API_RPM_KEY=jina_rpm_key

# Qdrant Configuration
QDRANT_URL=https://your-cluster.qdrant.tech
QDRANT_API_KEY=your_qdrant_api_key

Parametri di Configurazione​

/src/services/jinaSimpleEmbeddingService.ts
// Text Splitting Configuration
const SPLITTER_CONFIG = {
	chunkSize: 1000,
	chunkOverlap: 200,
	separators: ['\n\n', '\n', ' ', ''],
}

// Rate Limiting Configuration
const RATE_LIMITS = {
	tpmLimit: 50_000_000,
	resetInterval: 60_000, // 1 minuto
}

Monitoraggio e Debugging​

Logging Strutturato​

/src/utilities/loggerUtility.ts
// Log informazioni embedding
logInfo(ctx, 'Generated embeddings', {
	count: embeddings.length,
	collection: collectionName,
	resourceUuid: resourceUuid,
})

// Log errori
logError(ctx, 'Embedding generation failed', {
	error: error.message,
	resourceUuid: resourceUuid,
})

Metriche Importanti​

  • Token Usage: Consumo token per batch
  • Embedding Count: Numero embedding generati
  • Processing Time: Tempo elaborazione per documento
  • Error Rate: Percentuale errori per tipo

Gestione Errori​

Retry Logic​

/workflows/embetting.ts
// Configurazione retry
retries: 10,
backoff: {
	maxSeconds: 60,
	factor: 1.5
}

Error Handling​

  • Rate Limit Exceeded: Pausa automatica e retry
  • API Errors: Retry con backoff esponenziale
  • Network Issues: Retry con timeout progressivo
  • Abort Errors: Gestione cancellazione task

Best Practices​

Ottimizzazione Performance​

  1. Batch Size: Usare batch di 30 task per bilanciare performance e memoria
  2. Chunk Size: 1000 caratteri per chunk ottimale
  3. Overlap: 200 caratteri per continuità semantica
  4. Caching: Cache token count per documenti simili

Gestione Memoria​

  1. Streaming: Processare documenti grandi in streaming
  2. Cleanup: Pulizia immediata file temporanei
  3. Memory Limits: Monitoraggio uso memoria per batch
  4. Garbage Collection: Forzare GC dopo batch pesanti