File size: 10,307 Bytes

720fce7

---
language:
- es
- en
license: apache-2.0
tags:
- feature-extraction
- sentence-similarity
- stateful-embeddings
- nested-learning
- rag
- industrial-rag
- cpu-optimized
- sherman-morrison
- low-rank-svd
pipeline_tag: feature-extraction
library_name: transformers
---

# TóarimEmbedder: Motor de Embeddings Continuos con Estado para RAG Industrial

<div align="center">

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/Python-3.12%2B-brightgreen.svg)](https://www.python.org/)
[![Hardware](https://img.shields.io/badge/Hardware-Exclusively_CPU-orange.svg)](#requisitos-de-hardware-y-despliegue-en-cpu)
[![Format](https://img.shields.io/badge/Format-Safetensors-blueviolet.svg)](#seguridad-y-soberania-de-datos)
[![Air-Gapped](https://img.shields.io/badge/Air--Gapped-100%25_Offline-success.svg)](#soporte-nativo-air-gapped-redes-aisladas)

</div>

**TóarimEmbedder** es una arquitectura algorítmica de embeddings con estado (*stateful*) diseñada específicamente para resolver la **amnesia contextual y la pérdida de continuidad** en sistemas de Recuperación Aumentada por Generación (RAG) aplicados a **corpus técnicos extensos y altamente regulados** (manuales de maquinaria pesada, compendios normativos, bitácoras operativas y expedientes legales).

A diferencia de los modelos basados en Transformers convencionales con atención densa cuadrática $O(n^2)$, TóarimEmbedder opera con **complejidad lineal $O(n)$ en procesadores convencionales (CPU)**, permitiendo a las organizaciones indexar internamente su propiedad intelectual de forma ágil, blindando sus secretos comerciales y abatiendo los costos de infraestructura hasta en un **70.6%**.

---

## 🏭 El Desafío en Sectores Industriales y Regulados

En entornos industriales complejos, los expedientes técnicos presentan una **elevada interdependencia secuencial** y superan fácilmente decenas de miles de tokens. Las premisas de diseño o advertencias de seguridad suelen formularse en los capítulos iniciales, mientras que las secuencias de mitigación ante emergencias o excepciones operativas se detallan cientos de páginas después.

Las implementaciones RAG tradicionales fracasan en este escenario:
1. **Amnesia por Fragmentación Estática (*Chunking*):** Al cortar los textos en bloques atómicos de 256 a 512 tokens sin estado dinámico, se destruye la continuidad sintáctica y la correferencia anafórica de largo alcance.
2. **Fenómeno *Lost in the Middle*:** Los motores de búsqueda semántica ignoran activamente información crucial situada en regiones intermedias del documento.
3. **Colapso en Razonamiento de Múltiples Saltos (*Multi-hop Reasoning*):** Los fragmentos recuperados carecen de la inercia semántica que vincula los parámetros de origen con las acciones correctivas, elevando riesgos de no conformidad en auditorías o accidentes operativos.

---

## ⚡ La Solución Tóarim: Aprendizaje Anidado y Memoria Continua

TóarimEmbedder sustituye los pesados cálculos matriciales por formulaciones algebraicas lineales que integran tres núcleos algorítmicos:

```mermaid
flowchart TD
    A["Texto Documental (Secuencia de Chunks)"] --> B["Tokenizador WordPiece Rust (Local, ~711 KB)"]
    B --> C["Base Embeddings (dim: 768)"]
    C --> D["DocumentGraphEnricher: Convolución GNN O(L)"]
    D --> E["TitanMemoryLayer: Bucle HOPE con Sherman-Morrison"]
    C -. "Conexión Residual" .-> F["Residual Sum + LayerNorm"]
    E --> F
    F --> G["Mean Pooling Vectorial"]
    G --> H["Normalización Esférica L2"]
    H --> I["Vector Unitario (768 dimensiones)"]
    E -. "Estado M_t persistente" .-> E
```

1. **Enriquecimiento Estructural $O(L)$ (`DocumentGraphEnricher`):** Aplica una convolución de grafos (GCN) con normalización espectral tridiagonal que modela dependencias topológicas locales inmediatas sin requerir matrices densas $O(L^2)$.
2. **Compresión Latente SVD (`LowRankLinear`):** Descompone las proyecciones en factores de bajo rango ($W \approx U \cdot V$), reduciendo la complejidad paramétrica a $O(d \cdot k)$.
3. **Memoria Continua Titan (`TitanMemoryLayer`):** Bucle de *Nested Learning* con una matriz de memoria interna $M \in \mathbb{R}^{k \times k}$. La actualización de rango 1 se estabiliza mediante el **Lema de Sherman-Morrison**:
   $$\text{factor} = \frac{\eta_t}{1 + \eta_t \|k_t\|^2}$$
   $$M_t = \alpha_t M_{t-1} + \text{factor} \cdot (e_t \otimes k_t^T)$$
   Esto desacopla la memoria contextual del tamaño del documento: la memoria es plana y constante, independientemente de si el documento contiene 500 o 500,000 tokens.

---

## 📊 Tabla Comparativa de Rendimiento y Costes

Resultados obtenidos en pruebas empíricas sobre documentos normativos extensos (+500 páginas):

| Métrica / Dimensión | TóarimEmbedder (Local) | OpenAI text-emb-3-large | Cohere embed-v3.0 | BGE-M3 (BAAI) |
| :--- | :--- | :--- | :--- | :--- |
| **Complejidad Asintótica** | **$O(n)$ Lineal** | $O(n^2)$ Cuadrática | $O(n^2)$ Cuadrática | $O(n^2)$ Cuadrática |
| **Límite de Contexto** | **Teóricamente $\infty$ (Stateful)** | 8,191 tokens | 512 tokens | 8,192 tokens |
| **Hardware Requerido** | **CPU Convencional** | API en la Nube | API en la Nube | GPU Dedicada (>5.5 GB VRAM) |
| **Consumo de VRAM** | **0 MB (Libre de GPU)** | N/A (Propietario) | N/A (Propietario) | 5,500+ MB VRAM |
| **RAM Incremental** | **~101.8 MB** | N/A | N/A | ~2,500 MB |
| **TCO (500M Tokens)** | **~$22.22 USD (VPS CPU)** | ~$65.00 USD | Facturación por llamada | Coste mensual GPU cloud ($$$) |
| **Privacidad / Soberanía** | **100% On-Premise Local** | Terceros (Nube pública) | Terceros (Nube pública) | On-Premise (Requiere GPU) |

---

## 🚀 Inicio Rápido (Quickstart)

### Instalación de Dependencias

```bash
pip install torch tokenizers safetensors numpy
# O utilizando UV:
uv add torch tokenizers safetensors numpy
```

### 1. Ingesta Continua con Inercia Semántica (Python Nativo)

```python
from toarim_embedder import TóarimEmbedder

# Inicialización segura (carga automática de safetensors y tokenizador local)
embedder = TóarimEmbedder()

# Chunks secuenciales de un manual técnico
chunks_manual = [
    "Capítulo 1: Especificaciones de diseño y límites de presión en calderas de vapor...",
    "Capítulo 2: Configuración del circuito cerrado de refrigeración secundaria...",
    "Capítulo 18: Procedimiento de actuación ante fallo por sobrepresión crítica..."
]

# maintain_state=True arrastra la memoria Titan M_t a lo largo del documento
embeddings_documento = embedder.embed_documents(chunks_manual, maintain_state=True)
print(f"Chunks procesados: {len(embeddings_documento)} (Dimensión: {len(embeddings_documento[0])})")

# Consulta de búsqueda (Siempre opera en modo STATELESS para evitar sesgos)
query = "¿Cuál es el protocolo ante sobrepresión en la caldera?"
query_embedding = embedder.embed_query(query)
```

---

## 🔗 Integraciones con Frameworks RAG

### Integración con LangChain y ChromaDB

```python
from langchain_community.vectorstores import Chroma
from toarim_embedder import TóarimEmbedder

toarim = TóarimEmbedder()

# Ingesta en base de datos vectorial local
vectorstore = Chroma.from_texts(
    texts=chunks_manual,
    embedding=toarim,
    persist_directory="./chroma_db_industrial"
)

# Recuperación semántica contextualizada
resultados = vectorstore.similarity_search("fallo en refrigeración secundaria", k=3)
for doc in resultados:
    print(f"Contenido recuperado: {doc.page_content[:120]}...")
```

### Integración con LlamaIndex

```python
from llama_index.core.embeddings import BaseEmbedding
from toarim_embedder import TóarimEmbedder

class ToarimLlamaIndexEmbedding(BaseEmbedding):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self._model = TóarimEmbedder()

    def _get_query_embedding(self, query: str):
        return self._model.embed_query(query)

    def _get_text_embedding(self, text: str):
        return self._model.embed_query(text)

    def _get_text_embeddings(self, texts: list[str]):
        return self._model.embed_documents(texts, maintain_state=True)
```

---

## 🛡️ Ciberseguridad y Soberanía Tecnológica

TóarimEmbedder ha sido diseñado bajo estándares estrictos de ciberseguridad industrial:

1. **Serialización Segura con `safetensors`:** Se elimina por completo el uso de `pickle` / `torch.load` desprotegido, erradicando la vulnerabilidad de Ejecución Remota de Código (RCE).
2. **Soporte Nativo Air-Gapped (Redes Aisladas):** Incorpora el archivo compilado `tokenizer.json` (711 KB, motor Rust), permitiendo inicializaciones y ejecuciones en infraestructuras SCADA o plantas sin conexión a Internet (`local_files_only=True`).
3. **Higienización de Memoria Multi-Inquilino (`reset_state()`):** Para evitar la fuga de información confidencial entre diferentes manuales o clientes (*Cross-Tenant State Leakage*), el orquestador puede purgar el estado residual:
   ```python
   embedder.reset_state()  # Limpia de inmediato la memoria Titan M
   ```
4. **Protección contra Denegación de Servicio (DoS):** Sanitización y validación estricta de entradas y acotamiento de longitud de secuencias.

---

## ⚡ Aceleración en CPU y Cuantización INT8

Para estaciones de trabajo o servidores con procesadores estándar (Intel Core / Xeon, AMD Ryzen / EPYC):

```python
embedder = TóarimEmbedder()

# Aceleración mediante Cuantización Dinámica INT8 (AVX-512 VNNI / AMX)
embedder.quantize()

# Reduce la huella en memoria en ~50% (~47 MB) y duplica el rendimiento por núcleo
vector = embedder.embed_query("Verificación de válvulas")
```

---

## 📋 Requisitos de Hardware y Despliegue en CPU

- **Procesador:** Cualquier CPU moderna x86_64 o ARM64 (Intel 10ª gen+, AMD Zen 2+, Apple Silicon, AWS Graviton).
- **Memoria RAM:** Mínimo 512 MB de RAM disponibles (~100 MB ocupados por el modelo).
- **Almacenamiento:** ~100 MB para pesos (`model.safetensors`) y tokenizador (`tokenizer.json`).
- **Aceleradores:** **No requiere GPU** (0 MB de VRAM).

---

## 📄 Licencia

Este proyecto está distribuido bajo la licencia **Apache 2.0**. Consulte el archivo de licencia para obtener más detalles.