> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-es/plataformas-y-agentes-de-ia/haystack.md).

# 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.

{% hint style="success" %}
Todos los ejemplos se ejecutan en servidores GPU alquilados a través de [Marketplace de CLORE.AI](https://clore.ai/marketplace).
{% endhint %}

{% hint style="info" %}
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](https://docs.haystack.deepset.ai/docs/migration).
{% endhint %}

## Descripción general

| Propiedad                  | Detalles                                                                                       |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| **Proyecto**               | [deepset-ai/haystack](https://github.com/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](https://clore.ai/bare-metal) |

{% hint style="info" %}
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.
{% endhint %}

### 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](https://clore.ai/marketplace), 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

```bash
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:

```bash
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](https://github.com/deepset-ai/hayhooks) convierte automáticamente cualquier pipeline de Haystack en una API REST:

```bash
# 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:

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

### 5. Crea tu primer pipeline RAG

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

```bash
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:

```bash
# 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

```bash
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:

```bash
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:

```bash
# 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:

```bash
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:

```bash
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:

```bash
# 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:

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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](https://docs.haystack.deepset.ai/) — documentación oficial de v2
* [GitHub de Hayhooks](https://github.com/deepset-ai/hayhooks) — servicio de API REST para pipelines
* [Libro de recetas de Haystack](https://haystack.deepset.ai/cookbook) — tutoriales de extremo a extremo (RAG, agentes, búsqueda)
* [deepset-ai/haystack en GitHub](https://github.com/deepset-ai/haystack) — código fuente, incidencias, versiones
* [Integraciones de Haystack](https://haystack.deepset.ai/integrations) — lista completa de almacenes vectoriales, LLM y herramientas compatibles
* [Ollama en Clore.ai](/guides/guides_v2-es/modelos-de-lenguaje/ollama.md) — combine Haystack con Ollama para inferencia local de LLM
* [vLLM en Clore.ai](/guides/guides_v2-es/modelos-de-lenguaje/vllm.md) — backend de servicio de LLM de alto rendimiento para Haystack
* [Guía de comparación de GPU](/guides/guides_v2-es/primeros-pasos/gpu-comparison.md) — elija la GPU de Clore.ai adecuada para su carga de trabajo
* [Marketplace de CLORE.AI](https://clore.ai/marketplace) — alquile servidores GPU


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-es/plataformas-y-agentes-de-ia/haystack.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.