Framework de IA Haystack

Despliega Haystack de deepset en Clore.ai: crea canalizaciones RAG de producción, búsqueda semántica y flujos de trabajo de agentes LLM en infraestructura GPU asequible.

Haystack es el framework de orquestación de IA de código abierto de deepset para crear aplicaciones de LLM de nivel de producción. Con más de 18 mil estrellas en GitHub, ofrece una arquitectura basada en pipelines que conecta almacenes de documentos, recuperadores, lectores, generadores y agentes, todo en Python limpio y componible. Tanto si necesitas RAG sobre documentos privados, búsqueda semántica o flujos de trabajo de agentes de varios pasos, Haystack se encarga de la infraestructura para que puedas centrarte en la lógica de la aplicación.

En Clore.ai, Haystack brilla cuando necesitas una GPU para la inferencia local de modelos mediante Hugging Face Transformers o sentence-transformers. Si dependes únicamente de APIs externas (OpenAI, Anthropic), puedes ejecutarlo en instancias solo con CPU; pero para la generación de embeddings y los LLM locales, una GPU reduce drásticamente la latencia.

Todos los ejemplos se ejecutan en servidores GPU alquilados a través de Marketplace de CLORE.AI.

Esta guía cubre Haystack v2.x (haystack-ai paquete). La API v2 difiere significativamente de la v1 (farm-haystack). Si ya tienes pipelines v1 existentes, consulta la guía de migración.

Descripción general

Propiedad	Detalles
Proyecto	deepset-ai/haystack
Licencia	Apache 2.0
Estrellas en GitHub	18 mil+
Versión	v2.x (haystack-ai)
Caso de uso principal	RAG, búsqueda semántica, preguntas y respuestas sobre documentos, flujos de trabajo de agentes
Compatibilidad con GPU	Opcional — necesaria para embeddings locales / LLMs locales
Dificultad	Medio
Exposición de API	Hayhooks (basado en FastAPI, REST)
Integraciones clave	Ollama, OpenAI, Anthropic, HuggingFace, Elasticsearch, Pinecone, Weaviate, Qdrant

Lo que puedes crear

• Pipelines RAG — ingiere documentos, genera embeddings, recupera contexto, responde preguntas

• Búsqueda semántica — consulta documentos por su significado, no por palabras clave

• Procesamiento de documentos — analiza PDFs, HTML, documentos de Word; divide, limpia e indexa el contenido

• Flujos de trabajo de agentes — razonamiento en varios pasos con uso de herramientas (búsqueda web, calculadoras, APIs)

• Servicios REST API — expón cualquier pipeline de Haystack como un endpoint mediante Hayhooks

Requisitos

Requisitos de hardware

Caso de uso	GPU	VRAM	RAM	Disco	Precio de Clore.ai
Solo modo API (OpenAI/Anthropic)	Ninguna / CPU	—	4 GB	20 GB	~$0.01–0.05/h
Embeddings locales (sentence-transformers)	RTX 3060	8 GB	16 GB	30 GB	$0.03–0.07/h
Embeddings locales + LLM pequeño (7B)	RTX 3090	24 GB	16 GB	50 GB	$0.07–0.21/h
LLM local (13B–34B)	RTX 4090	24 GB	32 GB	80 GB	$0.14–0.42/h
LLM local grande (70B, cuantizado)	A100 80GB	80 GB	64 GB	150 GB	bare metal

Para la mayoría de los casos de uso de RAG, una RTX 3090 a $0.07–0.21/h es el punto ideal: 24 GB de VRAM permiten manejar a la vez embeddings con sentence-transformers + un LLM local de 7B–13B.

Requisitos de software

• Docker (preinstalado en los servidores de Clore.ai)

• Controladores NVIDIA + CUDA (preinstalados en los servidores GPU de Clore.ai)

• Python 3.10+ (dentro del contenedor)

• CUDA 11.8 o 12.x

Inicio rápido

1. Alquila un servidor de Clore.ai

En la Marketplace de Clore.ai, filtra por:

• VRAM: ≥ 8 GB para cargas de trabajo de embeddings, ≥ 24 GB para LLMs locales

• Docker: habilitado (predeterminado en la mayoría de las listas)

• Imagen: nvidia/cuda:12.8.1-devel-ubuntu22.04 o pytorch/pytorch:2.11.0-cuda12.8-cudnn9-runtime

Anota la IP pública y el puerto SSH del servidor en Mis pedidos.

2. Conéctate y verifica la GPU

ssh root@<clore-server-ip> -p <port>

# Verifica que la GPU esté disponible
nvidia-smi

# La salida esperada muestra tu GPU, versión del controlador y versión de CUDA

3. Construye la imagen Docker de Haystack

Haystack v2 recomienda la instalación con pip. Crea un Dockerfile personalizado:

mkdir -p /workspace/haystack-app && cd /workspace/haystack-app

cat > Dockerfile << 'EOF'
FROM nvidia/cuda:12.8.1-devel-ubuntu22.04

# Evita los avisos interactivos
ENV DEBIAN_FRONTEND=noninteractive
ENV PYTHONUNBUFFERED=1

# Instala Python y dependencias del sistema
RUN apt-get update && apt-get install -y \\
    python3.11 \\
    python3-pip \\
    python3.11-dev \\
    git \\
    curl \\
    && rm -rf /var/lib/apt/lists/*

# Establece python3.11 como predeterminado
RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1
RUN update-alternatives --install /usr/bin/python python python3.11 1

# Instala Haystack v2 y las dependencias principales
RUN pip install --no-cache-dir \\
    haystack-ai \
    hayhooks \
    sentence-transformers \
    transformers \
    torch \\
    accelerate \
    fastapi \\
    uvicorn

# Instala integraciones opcionales
RUN pip install --no-cache-dir \\
    ollama-haystack \
    haystack-experimental

WORKDIR /app

# Puerto predeterminado para Hayhooks
EXPOSE 1416

CMD ["hayhooks", "run", "--host", "0.0.0.0", "--port", "1416"]
EOF

# Compila la imagen
docker build -t haystack-clore:latest .

4. Ejecuta Haystack con Hayhooks

Hayhooks convierte automáticamente cualquier pipeline de Haystack en una API REST:

# Crea un directorio para tus pipelines
mkdir -p /workspace/haystack-pipelines

# Ejecuta Hayhooks con acceso a la GPU
docker run -d \\
  --name haystack \
  --gpus all \\
  -p 1416:1416 \
  -v /workspace/haystack-pipelines:/app/pipelines \
  -e OPENAI_API_KEY=${OPENAI_API_KEY:-""} \
  -e HF_TOKEN=${HF_TOKEN:-""} \
  haystack-clore:latest

# Comprueba que esté en ejecución
curl http://localhost:1416/status

Respuesta esperada:

{"status": "ok", "pipelines": []}

5. Crea tu primer pipeline RAG

Escribe un YAML de pipeline que Hayhooks servirá como endpoint:

cat > /workspace/haystack-pipelines/rag_pipeline.yml << 'EOF'
# Pipeline RAG usando Ollama para el LLM + embeddings locales para la recuperación
components:
  embedder:
    type: haystack.components.embedders.SentenceTransformersTextEmbedder
    init_parameters:
      model: BAAI/bge-small-en-v1.5

  retriever:
    type: haystack.components.retrievers.in_memory.InMemoryEmbeddingRetriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.in_memory.InMemoryDocumentStore

  prompt_builder:
    type: haystack.components.builders.PromptBuilder
    init_parameters:
      template: |
        Responde a la pregunta basándote en el contexto siguiente.
        Contexto: {% for doc in documents %}{{ doc.content }}{% endfor %}
        Pregunta: {{ question }}

  llm:
    type: haystack_integrations.components.generators.ollama.OllamaGenerator
    init_parameters:
      model: llama3
      url: http://host.docker.internal:11434

connections:
  - sender: embedder.embedding
    receiver: retriever.query_embedding
  - sender: retriever.documents
    receiver: prompt_builder.documents
  - sender: prompt_builder.prompt
    receiver: llm.prompt

inputs:
  query:
    - embedder.text
    - prompt_builder.question

outputs:
  answer: llm.replies
EOF

Hayhooks descubre y sirve automáticamente este pipeline. Pruébalo:

# Lista los pipelines desplegados
curl http://localhost:1416/pipelines

# Consulta el pipeline RAG
curl -X POST http://localhost:1416/rag_pipeline/run \
  -H "Content-Type: application/json" \\
  -d '{"query": "What is Haystack?"}'

Configuración

Variables de entorno

Variable	Descripción	Ejemplo
OPENAI_API_KEY	Clave API de OpenAI para modelos GPT	sk-...
ANTHROPIC_API_KEY	Clave API de Anthropic para Claude	sk-ant-...
HF_TOKEN	Token de Hugging Face para modelos restringidos	hf_...
HAYSTACK_TELEMETRY_ENABLED	Desactivar la telemetría de uso	false
CUDA_VISIBLE_DEVICES	Seleccionar GPU específica	0
TRANSFORMERS_CACHE	Ruta de caché para modelos HF	/workspace/hf-cache

Ejecuta con configuración completa

docker run -d \\
  --name haystack \
  --gpus '"device=0"' \
  -p 1416:1416 \
  -v /workspace/haystack-pipelines:/app/pipelines \
  -v /workspace/hf-cache:/root/.cache/huggingface \
  -e OPENAI_API_KEY="your-key-here" \
  -e HF_TOKEN="your-hf-token" \
  -e HAYSTACK_TELEMETRY_ENABLED=false \
  -e CUDA_VISIBLE_DEVICES=0 \
  --restart unless-stopped \\
  haystack-clore:latest

Pipeline de ingesta de documentos

Crea un pipeline de indexación separado para ingerir documentos:

cat > /workspace/index_documents.py << 'EOF'
import haystack
from haystack import Pipeline
from haystack.components.converters import PyPDFToDocument, TextFileToDocument
from haystack.components.preprocessors import DocumentSplitter, DocumentCleaner
from haystack.components.embedders import SentenceTransformersDocumentEmbedder
from haystack.components.writers import DocumentWriter
from haystack.document_stores.in_memory import InMemoryDocumentStore

# Inicializa el almacén de documentos
document_store = InMemoryDocumentStore()

# Construye el pipeline de indexación
indexing_pipeline = Pipeline()
indexing_pipeline.add_component("converter", PyPDFToDocument())
indexing_pipeline.add_component("cleaner", DocumentCleaner())
indexing_pipeline.add_component("splitter", DocumentSplitter(
    split_by="word",
    split_length=200,
    split_overlap=20
))
indexing_pipeline.add_component("embedder", SentenceTransformersDocumentEmbedder(
    model="BAAI/bge-small-en-v1.5"
))
indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))

# Conecta los componentes
indexing_pipeline.connect("converter", "cleaner")
indexing_pipeline.connect("cleaner", "splitter")
indexing_pipeline.connect("splitter", "embedder")
indexing_pipeline.connect("embedder", "writer")

# Ejecuta la indexación
from pathlib import Path
indexing_pipeline.run({"converter": {"sources": list(Path("/data/documents").glob("*.pdf"))}})

print(f"Indexados {document_store.count_documents()} fragmentos de documentos")
EOF

docker run --rm \\
  --gpus all \\
  -v /workspace:/workspace \
  -v /your/documents:/data/documents \
  -v /workspace/hf-cache:/root/.cache/huggingface \
  haystack-clore:latest \
  python3 /workspace/index_documents.py

Uso de bases de datos vectoriales (producción)

Para cargas de trabajo de producción, reemplaza el almacén en memoria por una base de datos vectorial persistente:

# Inicia Qdrant junto con Haystack
docker network create haystack-net

docker run -d \\
  --name qdrant \
  --network haystack-net \
  -p 6333:6333 \
  -v /workspace/qdrant-data:/qdrant/storage \
  qdrant/qdrant

# Instala la integración de Qdrant en el contenedor de Haystack
# Añádelo al Dockerfile:  RUN pip install qdrant-haystack
# Luego usa QdrantDocumentStore en lugar de InMemoryDocumentStore

Aceleración GPU

Haystack usa aceleración por GPU en dos escenarios principales:

1. Generación de embeddings (sentence transformers)

La GPU es muy beneficiosa para generar embeddings de grandes colecciones de documentos:

cat > /workspace/benchmark_embeddings.py << 'EOF'
import time
import torch
from haystack.components.embedders import SentenceTransformersDocumentEmbedder
from haystack import Document

# Verificar la disponibilidad de la GPU
device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"Dispositivo usado: {device}")
if device == "cuda":
    print(f"GPU: {torch.cuda.get_device_name(0)}")
    print(f"VRAM: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f} GB")

# Crea el embedder
embedder = SentenceTransformersDocumentEmbedder(
    model="BAAI/bge-base-en-v1.5"
)
embedder.warm_up()

# Benchmark
docs = [Document(content=f"Documento de muestra {i} con algo de contenido de texto.") for i in range(100)]

start = time.time()
result = embedder.run(documents=docs)
elapsed = time.time() - start

print(f"100 documentos incrustados en {elapsed:.2f}s ({100/elapsed:.0f} docs/s)")
EOF

docker run --rm --gpus all \
  -v /workspace:/workspace \
  haystack-clore:latest \
  python3 /workspace/benchmark_embeddings.py

2. Inferencia local de LLM (Hugging Face Transformers)

Para ejecutar LLMs directamente en Haystack sin Ollama:

cat > /workspace/local_llm_pipeline.py << 'EOF'
from haystack import Pipeline
from haystack.components.builders import PromptBuilder
from haystack.components.generators.hugging_face import HuggingFaceLocalGenerator

# Usa la GPU automáticamente cuando esté disponible
generator = HuggingFaceLocalGenerator(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    task="text-generation",
    generation_kwargs={
        "max_new_tokens": 512,
        "temperature": 0.7,
        "do_sample": True,
    }
)

prompt_builder = PromptBuilder(template="Responde a esta pregunta: {{ question }}")

pipeline = Pipeline()
pipeline.add_component("prompt_builder", prompt_builder)
pipeline.add_component("llm", generator)
pipeline.connect("prompt_builder.prompt", "llm.prompt")

result = pipeline.run({"prompt_builder": {"question": "¿Qué es RAG?"}})
print(result["llm"]["replies"][0])
EOF

docker run --rm --gpus all \
  -v /workspace:/workspace \
  -e HF_TOKEN="your-hf-token" \
  haystack-clore:latest \
  python3 /workspace/local_llm_pipeline.py

3. Combínalo con Ollama (enfoque recomendado)

Para la mejor combinación de facilidad y rendimiento, ejecuta Ollama para la inferencia del LLM y Haystack para la orquestación:

# Paso 1: Inicia Ollama (consulta la guía de Ollama)
docker run -d \\
  --name ollama \
  --gpus all \\
  -p 11434:11434 \
  -v /workspace/ollama:/root/.ollama \
  ollama/ollama

# Paso 2: Descarga un modelo de código/chat
docker exec ollama ollama pull llama3
docker exec ollama ollama pull nomic-embed-text  # Para embeddings mediante Ollama

# Paso 3: Inicia Haystack apuntando a Ollama
docker run -d \\
  --name haystack \
  --gpus '"device=0"' \
  -p 1416:1416 \
  --add-host=host.docker.internal:host-gateway \
  -v /workspace/haystack-pipelines:/app/pipelines \
  haystack-clore:latest

Supervisa el uso de la GPU en ambos contenedores:

watch -n 2 nvidia-smi

Consejos y mejores prácticas

Elige el modelo de embeddings adecuado

Modelo	VRAM	Velocidad	Calidad	Ideal para
BAAI/bge-small-en-v1.5	~0.5 GB	El más rápido	Bueno	Indexación de alto rendimiento
BAAI/bge-base-en-v1.5	~1 GB	Rápido	Mejor	RAG general
BAAI/bge-large-en-v1.5	~2 GB	Medio	Mejor	Máxima precisión
nomic-ai/nomic-embed-text-v1	~1.5 GB	Rápido	Excelente	Documentos largos

Consejos de diseño de pipelines

• Divide los documentos de forma inteligente — fragmentos de 200–400 palabras con 10–15% de solapamiento funcionan bien para la mayoría de los casos de uso de RAG

• Almacena en caché los embeddings — persiste tu almacén de documentos en disco; recalcular embeddings es costoso

• Usa warm_up() — llama a component.warm_up() antes del uso en producción para cargar los modelos en la memoria de la GPU

• Indexación por lotes — procesa documentos en lotes de 32–64 para un uso óptimo de la GPU

• Filtra con metadatos — usa el filtrado de metadatos de Haystack para acotar la recuperación (por ejemplo, por fecha, fuente, categoría)

Optimización de costos

# Usa precios tipo spot en Clore.ai — elige servidores con menor $/h
# Para desarrollo/pruebas: RTX 3060 ($0.03–0.07/h) es suficiente para embeddings
# Para embeddings en producción: RTX 3090 ($0.07–0.21/h) — 24 GB pueden manejar grandes lotes
# Para LLM local + embeddings: A100 40GB ([bare metal](https://clore.ai/bare-metal)) — margen para usuarios concurrentes

# Supervisa el uso de recursos
docker stats haystack
nvidia-smi dmon -s u -d 5  # utilización de la GPU cada 5 segundos

Protege Hayhooks para acceso externo

# Opción 1: túnel SSH (la más simple, para uso personal)
# Desde tu máquina local:
ssh -L 1416:localhost:1416 root@<clore-ip> -p <clore-ssh-port>
# Luego accede localmente a http://localhost:1416

# Opción 2: añade autenticación básica mediante un proxy inverso de nginx
docker run -d \\
  --name nginx-proxy \
  -p 80:80 \
  -v /workspace/nginx.conf:/etc/nginx/conf.d/default.conf \
  nginx:alpine

Solución de problemas

Problema	Causa probable	Solución
ModuleNotFoundError: haystack	Paquete no instalado	Reconstruye la imagen Docker; comprueba pip install haystack-ai Logrado
CUDA sin memoria	El modelo de incrustación es demasiado grande	Usa bge-small-en-v1.5 o reduzca el tamaño del lote
Hayhooks devuelve 404 en el pipeline	Archivo YAML no encontrado	Compruebe el montaje del volumen; el archivo del pipeline debe estar en /app/pipelines/
Incrustación lenta en CPU	GPU no detectada	Verifique --gpus all bandera; compruebe torch.cuda.is_available()
Conexión a Ollama rechazada	Nombre de host incorrecto	Usa --add-host=host.docker.internal:host-gateway; establezca la URL en http://host.docker.internal:11434
La descarga de HuggingFace falla	Falta el token o se alcanzó el límite de velocidad	Establece HF_TOKEN variable de entorno; asegúrese de que el modelo no esté restringido
Error al analizar YAML del pipeline	Sintaxis no válida	Valide el YAML; use python3 -c "import yaml; yaml.safe_load(open('pipeline.yml'))"
El contenedor se cierra inmediatamente	Error de inicio	Consulta docker logs haystack; asegúrese de que el CMD del Dockerfile sea correcto
El puerto 1416 no es accesible externamente	Firewall / reenvío de puertos	Exponga el puerto en la configuración del pedido de Clore.ai; compruebe los puertos abiertos del servidor

Comandos de depuración

# Compruebe los registros del contenedor
docker logs haystack --tail 50 -f

# Pruebe la API de Hayhooks
curl http://localhost:1416/status
curl http://localhost:1416/pipelines

# Sesión interactiva de depuración de Python
docker exec -it haystack python3

# Compruebe la GPU dentro del contenedor
docker exec haystack python3 -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

# Comprueba los paquetes instalados
docker exec haystack pip show haystack-ai hayhooks

Lecturas adicionales

• Documentación de Haystack — documentación oficial de v2

• GitHub de Hayhooks — servicio de API REST para pipelines

• Libro de recetas de Haystack — tutoriales de extremo a extremo (RAG, agentes, búsqueda)

• deepset-ai/haystack en GitHub — código fuente, incidencias, versiones

• Integraciones de Haystack — lista completa de almacenes vectoriales, LLM y herramientas compatibles

• Ollama en Clore.ai — combine Haystack con Ollama para inferencia local de LLM

• vLLM en Clore.ai — backend de servicio de LLM de alto rendimiento para Haystack

• Guía de comparación de GPU — elija la GPU de Clore.ai adecuada para su carga de trabajo

• Marketplace de CLORE.AI — alquile servidores GPU