--- 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
[![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)
**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.