| --- |
| 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"> |
|
|
| [](https://opensource.org/licenses/Apache-2.0) |
| [](https://www.python.org/) |
| [](#requisitos-de-hardware-y-despliegue-en-cpu) |
| [](#seguridad-y-soberania-de-datos) |
| [](#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. |
| |
