docs(README): instrucciones de instalación completas (Ollama / llama.cpp / Transformers+LoRA) + troubleshooting + RAG pattern

README.md

@@ -72,39 +72,247 @@ NO destinado para:
 - Análisis forense sin contexto RAG (el modelo se apoya fuertemente en
   hallazgos recuperados; las respuestas standalone son más débiles).
 
-## Cómo usar
+## Cómo instalar y ejecutar darkforensic-7b en local
 
-### Con Ollama (recomendado para despliegue VPS)
+Hay tres formas, según tu hardware. Si no sabes cuál elegir, usa la
+**Opción A (Ollama)**: es la más rápida y funciona en cualquier laptop
+con 8 GB de RAM o más.
+
+### Requisitos por opción
+
+| Opción | RAM mínima | GPU | Disco | Velocidad típica |
+|---|---|---|---|---|
+| A. Ollama (Q4_K_M) | 8 GB | no necesaria | ~5 GB | 5–15 tok/s en CPU; 30–60 con GPU |
+| B. llama.cpp (Q4_K_M) | 8 GB | no necesaria | ~5 GB | igual que Ollama, sin server |
+| C. Transformers + LoRA | 24 GB GPU | sí, A100/H100 ideal | ~16 GB | 20–40 tok/s en H100 |
+
+---
+
+### Opción A — Ollama (recomendada)
+
+Funciona en Linux, macOS, Windows. Es lo que usamos en producción en el
+VPS de Neural Ghost.
+
+**1. Instala Ollama** (1 comando):
+
+```bash
+# Linux / macOS
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Windows: descarga el instalador desde https://ollama.com/download
+```
+
+Verifica que está instalado:
+
+```bash
+ollama --version       # debe imprimir "ollama version is X.Y.Z"
+```
+
+**2. Descarga el GGUF Q4_K_M y el Modelfile** de este repo:
+
+```bash
+mkdir darkforensic && cd darkforensic
+
+# Descarga el modelo (4.7 GB) y el Modelfile
+curl -L -o darkforensic-7b-v2-q4_k_m.gguf \
+  https://huggingface.co/neuralghost/darkforensic-7b/resolve/main/darkforensic-7b-v2-q4_k_m.gguf
+curl -L -o Modelfile \
+  https://huggingface.co/neuralghost/darkforensic-7b/raw/main/Modelfile
+```
+
+(Alternativa: con `huggingface-cli download neuralghost/darkforensic-7b` —
+te baja todo el repo de golpe. Más cómodo si tienes la CLI instalada.)
+
+**3. Importa el modelo a Ollama**:
 
 ```bash
-# Importa el GGUF Q4_K_M desde el archivo local
 ollama create darkforensic-7b -f Modelfile
+```
+
+Esto tarda 30 s – 2 min la primera vez (Ollama indexa el GGUF y lo deja
+listo). Verifica que está:
 
-# Ejemplo
-ollama run darkforensic-7b "¿Qué hacer si detectamos credenciales nuestras en un combo-list?"
+```bash
+ollama list
+# debe aparecer "darkforensic-7b" con el tag latest
 ```
 
-### Con Transformers + LoRA (inferencia HF)
+**4. Pruébalo**:
+
+```bash
+ollama run darkforensic-7b "Hemos detectado credenciales de empleados \
+nuestros en un combo-list publicado en RaidForums. ¿Qué hago en las \
+próximas 24 horas?"
+```
+
+Te debería responder en castellano con un plan estructurado:
+resumen → acciones inmediatas → IOCs → marco regulatorio (RGPD/NIS2).
+
+**5. Para usarlo desde tu aplicación** (Python, etc.) — Ollama expone una
+API REST en `http://localhost:11434`:
 
 ```python
+import httpx, json
+
+resp = httpx.post(
+    "http://localhost:11434/api/generate",
+    json={
+        "model": "darkforensic-7b",
+        "prompt": "Pregunta operativa CISO/DPO aquí…",
+        "stream": False,
+    },
+    timeout=120,
+)
+print(resp.json()["response"])
+```
+
+**6. Detenerlo / liberar memoria** cuando no lo uses:
+
+```bash
+ollama stop darkforensic-7b
+```
+
+---
+
+### Opción B — llama.cpp (sin servidor, ideal si quieres scriptear)
+
+Si prefieres no levantar el daemon de Ollama, puedes cargar el GGUF
+directamente con `llama.cpp`:
+
+```bash
+# Instalar llama-cpp-python con soporte CUDA (omite CMAKE_ARGS si no tienes GPU)
+CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python --upgrade --force-reinstall --no-cache-dir
+```
+
+Y úsalo así desde Python:
+
+```python
+from llama_cpp import Llama
+
+llm = Llama(
+    model_path="darkforensic-7b-v2-q4_k_m.gguf",
+    n_ctx=8192,
+    n_gpu_layers=-1,      # -1 = todas las capas en GPU; 0 = solo CPU
+    chat_format="chatml", # Qwen2.5 usa ChatML
+)
+
+response = llm.create_chat_completion(
+    messages=[
+        {"role": "system", "content":
+            "Eres darkforensic, asistente threat-intel dark-web para CISOs/DPOs "
+            "europeos. Responde en castellano, conciso, con acciones operativas y "
+            "el marco regulatorio (RGPD/NIS2/DORA) si aplica."},
+        {"role": "user", "content":
+            "¿Qué IOCs debo extraer de este finding y cómo los cruzo con mi SIEM?"},
+    ],
+    temperature=0.3,
+    max_tokens=1024,
+)
+print(response["choices"][0]["message"]["content"])
+```
+
+---
+
+### Opción C — Transformers + LoRA (necesitas GPU)
+
+Esta opción carga el **modelo base** (Qwen2.5-7B-Instruct, ~16 GB en
+bfloat16) **y aplica el LoRA adapter encima** (162 MB). Útil si quieres
+seguir entrenando, mergear con otro adapter, o tener máxima precisión.
+
+**1. Instalar dependencias**:
+
+```bash
+pip install transformers peft accelerate bitsandbytes torch
+```
+
+**2. Cargar y usar**:
+
+```python
+import torch
 from transformers import AutoModelForCausalLM, AutoTokenizer
 from peft import PeftModel
 
+# Base model en bf16 (16 GB VRAM) — o en 4-bit con bnb si tienes menos
 base = AutoModelForCausalLM.from_pretrained(
-    "Qwen/Qwen2.5-7B-Instruct", torch_dtype="bfloat16", device_map="auto"
+    "Qwen/Qwen2.5-7B-Instruct",
+    torch_dtype=torch.bfloat16,
+    device_map="auto",
 )
 model = PeftModel.from_pretrained(base, "neuralghost/darkforensic-7b")
 tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B-Instruct")
 
 messages = [
     {"role": "system", "content": "Eres darkforensic, asistente threat-intel..."},
-    {"role": "user", "content": "..."},
+    {"role": "user", "content": "Tu pregunta aquí"},
 ]
-inputs = tokenizer.apply_chat_template(messages, return_tensors="pt").to(model.device)
-out = model.generate(inputs, max_new_tokens=300)
-print(tokenizer.decode(out[0], skip_special_tokens=True))
+inputs = tokenizer.apply_chat_template(
+    messages, return_tensors="pt", add_generation_prompt=True
+).to(model.device)
+out = model.generate(inputs, max_new_tokens=600, do_sample=True, temperature=0.3)
+print(tokenizer.decode(out[0][inputs.shape[-1]:], skip_special_tokens=True))
+```
+
+**Si tienes menos de 24 GB de VRAM** — carga el base en 4-bit:
+
+```python
+from transformers import BitsAndBytesConfig
+bnb = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_compute_dtype=torch.bfloat16)
+base = AutoModelForCausalLM.from_pretrained(
+    "Qwen/Qwen2.5-7B-Instruct", quantization_config=bnb, device_map="auto",
+)
+# (el resto igual)
 ```
 
+Con 4-bit cabe en ~6 GB de VRAM (RTX 3060 12 GB, RTX 4060 8 GB con stretching).
+
+---
+
+## Troubleshooting
+
+| Síntoma | Causa probable | Solución |
+|---|---|---|
+| `ollama create` se queda colgado | El Modelfile referencia un GGUF que no existe en esa carpeta | Verifica que `darkforensic-7b-v2-q4_k_m.gguf` está en el mismo directorio que el `Modelfile` |
+| `Error: out of memory` al usarlo | Estás cargando fp16/bf16 en GPU pequeña, o varios modelos a la vez en Ollama | Usa Q4_K_M; `ollama stop` los otros modelos; o reduce `num_ctx` en el Modelfile (8192 → 4096) |
+| Respuestas muy lentas (< 2 tok/s) | Corriendo en CPU sin AVX2, o el modelo no cabe en RAM y está paginando a disco | Verifica `grep avx2 /proc/cpuinfo`; baja a 4 hilos con `OLLAMA_NUM_PARALLEL=1`; cierra otras apps con memoria pesada |
+| Responde en inglés cuando le hablas en castellano | Faltó el system prompt o el primer mensaje es muy corto | Asegúrate de pasar el system del Modelfile (Ollama lo aplica automáticamente con `ollama run`); con la API REST mándalo explícito |
+| "Permission denied" al ejecutar | Falta permisos en `~/.ollama` | `chmod -R u+rw ~/.ollama` |
+| El modelo alucina IOCs específicos (BTC addresses, hashes) | El modelo describe IOCs, NO los memoriza — por diseño | Es el comportamiento correcto, no un bug. Para IOCs verbatim necesitas el RAG sobre tu corpus indexado, no el LLM solo |
+
+## Integración con un pipeline RAG (recomendado para producción)
+
+DarkForensic-7B está pensado para responder **con contexto recuperado** de
+tu propio corpus de hallazgos. Sin RAG es un asistente; con RAG es una
+herramienta de análisis. El patrón básico:
+
+```python
+# 1. El usuario pregunta algo sobre un finding
+question = "¿Cómo respondo a este leak de credenciales?"
+
+# 2. Tu sistema RAG recupera los k findings más relevantes del corpus
+context_findings = your_rag.retrieve(question, k=5)
+context_text = "\n\n".join(
+    f"[finding {f.id}] {f.title}\n{f.snippet}" for f in context_findings
+)
+
+# 3. Se manda al modelo en el system o como contexto previo
+prompt = f"""CONTEXTO (5 findings relevantes de tu corpus dark-web):
+{context_text}
+
+PREGUNTA DEL ANALISTA: {question}
+
+Responde citando los finding IDs cuando uses información de ellos.
+Si los findings no contienen información suficiente, dilo explícitamente."""
+
+# 4. Llama al modelo (Ollama u otro)
+response = httpx.post("http://localhost:11434/api/generate",
+    json={"model": "darkforensic-7b", "prompt": prompt, "stream": False},
+    timeout=120).json()["response"]
+```
+
+La plataforma completa que envuelve esto (crawler Tor/I2P, scoring,
+RAG vectorial, alertas, UI) es **GhostNet Intelligence Platform** y se
+comercializa por separado. Contacto: hello@neural-ghost.com.
+
 ## Detalles del entrenamiento
 
 | | |