# Фреймворк AI Haystack

Haystack — это open-source фреймворк оркестрации ИИ от deepset для создания промышленных приложений на базе LLM. С более чем 18K звёзд на GitHub он предоставляет гибкую **архитектуру на основе конвейеров** которая соединяет хранилища документов, ретриверы, ридеры, генераторы и агентов — всё в чистом, компонуемом Python. Независимо от того, нужен ли вам RAG по приватным документам, семантический поиск или многошаговые рабочие процессы агентов, Haystack решает инфраструктурные задачи, чтобы вы могли сосредоточиться на логике приложения.

На Clore.ai Haystack особенно полезен, когда вам нужен GPU для локального инференса моделей через Hugging Face Transformers или sentence-transformers. Если вы полностью полагаетесь на внешние API (OpenAI, Anthropic), вы можете запускать его на серверах только с CPU — но для генерации эмбеддингов и локальных LLM наличие GPU значительно снижает задержку.

{% hint style="success" %}
Все примеры запускаются на GPU-серверах, арендованных через [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

{% hint style="info" %}
Это руководство охватывает **Haystack v2.x** (`пакет haystack-ai` API v2 существенно отличается от v1 (`farm-haystack`). Если у вас есть существующие конвейеры v1, см.  [руководство по миграции](https://docs.haystack.deepset.ai/docs/migration).
{% endhint %}

## Обзор

| Свойство                | Детали                                                                            |
| ----------------------- | --------------------------------------------------------------------------------- |
| **Проект**              | [deepset-ai/haystack](https://github.com/deepset-ai/haystack)                     |
| **Лицензия**            | Apache 2.0                                                                        |
| **Звёзды на GitHub**    | 18K+                                                                              |
| **Версия**              | v2.x (`пакет haystack-ai`)                                                        |
| **Основное применение** | RAG, семантический поиск, документальный QA, рабочие потоки агентов               |
| **Поддержка GPU**       | Необязательно — требуется для локальных эмбеддингов / локальных LLM               |
| **Сложность**           | Средне                                                                            |
| **API-сервер**          | Hayhooks (на базе FastAPI, REST)                                                  |
| **Ключевые интеграции** | Ollama, OpenAI, Anthropic, HuggingFace, Elasticsearch, Pinecone, Weaviate, Qdrant |

### Что можно построить

* **RAG-конвейеры** — загружать документы, генерировать эмбеддинги, извлекать контекст, отвечать на вопросы
* **Семантический поиск** — искать документы по смыслу, а не по ключевым словам
* **Обработка документов** — парсить PDF, HTML, Word; разбивать, очищать и индексировать содержимое
* **Рабочие процессы агентов** — многошаговое рассуждение с использованием инструментов (веб-поиск, калькуляторы, API)
* **REST API сервисы** — выставлять любой конвейер Haystack как endpoint через Hayhooks

## Требования

### Требования к аппаратному обеспечению

| Случай использования                              | GPU              | VRAM  | ОЗУ   | Диск   | Clore.ai Цена    |
| ------------------------------------------------- | ---------------- | ----- | ----- | ------ | ---------------- |
| **Только режим API** (OpenAI/Anthropic)           | Нет / только CPU | —     | 4 ГБ  | 20 ГБ  | \~$0.01–0.05/час |
| **Локальные эмбеддинги** (sentence-transformers)  | RTX 3060         | 8 ГБ  | 16 ГБ | 30 GB  | \~$0.10–0.15/час |
| **Локальные эмбеддинги + небольшой LLM** (7B)     | RTX 3090         | 24 ГБ | 16 ГБ | 50 ГБ  | \~$0.20–0.25/час |
| **Локальный LLM** (13B–34B)                       | RTX 4090         | 24 ГБ | 32 ГБ | 80 ГБ  | \~$0.35–0.50/час |
| **Большой локальный LLM** (70B, квантизированный) | A100 80GB        | 80 ГБ | 64 ГБ | 150 ГБ | \~$1.10–1.50/час |

{% hint style="info" %}
Для большинства задач RAG оптимальным вариантом является **RTX 3090** сервер примерно за \~$0.20/час — 24 ГБ VRAM справляются с эмбеддингами sentence-transformer и локальным LLM 7B–13B одновременно.
{% endhint %}

### Требования к программному обеспечению

* Docker (предустановлен на серверах Clore.ai)
* Драйверы NVIDIA + CUDA (предустановлены на GPU-серверах Clore.ai)
* Python 3.10+ (внутри контейнера)
* CUDA 11.8 или 12.x

## Быстрый старт

### 1. Арендуйте сервер Clore.ai

В [Clore.ai Marketplace](https://clore.ai/marketplace)отфильтруйте по:

* **VRAM**: ≥ 8 ГБ для задач эмбеддинга, ≥ 24 ГБ для локальных LLM
* **Docker**: Включено (по умолчанию на большинстве предложений)
* **Образ**: `nvidia/cuda:12.1-devel-ubuntu22.04` или `pytorch/pytorch:2.2.0-cuda12.1-cudnn8-runtime`

Запомните публичный IP сервера и SSH-порт из **Моих заказах**.

### 2. Подключитесь и проверьте GPU

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

# Проверить доступность GPU
nvidia-smi

# Ожидаемый вывод показывает вашу GPU, версию драйвера, версию CUDA
```

### 3. Постройте Docker-образ Haystack

Haystack v2 рекомендует установку через pip. Создайте кастомный Dockerfile:

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

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

# Избегать интерактивных подсказок
ENV DEBIAN_FRONTEND=noninteractive
ENV PYTHONUNBUFFERED=1

# Установить Python и системные зависимости
RUN apt-get update && apt-get install -y \
    python3.11 \
    python3-pip \
    python3.11-dev \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Сделать python3.11 по умолчанию
RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1
RUN update-alternatives --install /usr/bin/python python python3.11 1

# Установить Haystack v2 и основные зависимости
RUN pip install --no-cache-dir \
    haystack-ai \
    hayhooks \
    sentence-transformers \
    transformers \
    torch \
    accelerate \
    fastapi \
    uvicorn

# Установить опциональные интеграции
RUN pip install --no-cache-dir \
    ollama-haystack \
    haystack-experimental

WORKDIR /app

# Порт по умолчанию для Hayhooks
EXPOSE 1416

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

# Постройте образ
docker build -t haystack-clore:latest .
```

### 4. Запустите Haystack с Hayhooks

[Hayhooks](https://github.com/deepset-ai/hayhooks) превращает любой конвейер Haystack в REST API автоматически:

```bash
# Создать директорию для ваших конвейеров
mkdir -p /workspace/haystack-pipelines

# Запустить Hayhooks с доступом к 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

# Проверить, что он запущен
curl http://localhost:1416/status
```

Ожидаемый ответ:

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

### 5. Создайте ваш первый RAG-конвейер

Напишите YAML конвейера, который Hayhooks будет обслуживать как endpoint:

```bash
cat > /workspace/haystack-pipelines/rag_pipeline.yml << 'EOF'
# RAG-конвейер с использованием Ollama для LLM + локальных эмбеддингов для поиска
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: |
        Ответьте на вопрос, основываясь на приведённом ниже контексте.
        Контекст: {% for doc in documents %}{{ doc.content }}{% endfor %}
        Вопрос: {{ 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 автоматически обнаружит и будет обслуживать этот конвейер. Протестируйте его:

```bash
# Список развернутых конвейеров
curl http://localhost:1416/pipelines

# Запрос к RAG-конвейеру
curl -X POST http://localhost:1416/rag_pipeline/run \
  -H "Content-Type: application/json" \
  -d '{"query": "What is Haystack?"}'
```

## Конфигурация

### Переменные окружения

| Переменная                   | Описание                                  | Пример                |
| ---------------------------- | ----------------------------------------- | --------------------- |
| `OPENAI_API_KEY`             | OpenAI API ключ для моделей GPT           | `sk-...`              |
| `ANTHROPIC_API_KEY`          | Anthropic API ключ для Claude             | `sk-ant-...`          |
| `HF_TOKEN`                   | Токен Hugging Face для защищённых моделей | `hf_...`              |
| `HAYSTACK_TELEMETRY_ENABLED` | Отключить телеметрию использования        | `false`               |
| `CUDA_VISIBLE_DEVICES`       | Выбрать конкретный GPU                    | `0`                   |
| `TRANSFORMERS_CACHE`         | Путь кеша для моделей HF                  | `/workspace/hf-cache` |

### Запуск с полной конфигурацией

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

### Конвейер индексирования документов

Создайте отдельный конвейер индексирования для загрузки документов:

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

# Инициализировать хранилище документов
document_store = InMemoryDocumentStore()

# Построить конвейер индексирования
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))

# Подключить компоненты
indexing_pipeline.connect("converter", "cleaner")
indexing_pipeline.connect("cleaner", "splitter")
indexing_pipeline.connect("splitter", "embedder")
indexing_pipeline.connect("embedder", "writer")

# Запустить индексирование
from pathlib import Path
indexing_pipeline.run({"converter": {"sources": list(Path("/data/documents").glob("*.pdf"))}})

print(f"Indexed {document_store.count_documents()} document chunks")
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
```

### Использование векторных баз данных (в продакшене)

Для продакшен-нагрузок замените in-memory хранилище на постоянную векторную базу данных:

```bash
# Запустить Qdrant вместе с 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

# Установить интеграцию Qdrant в контейнер Haystack
# Добавьте в Dockerfile:  RUN pip install qdrant-haystack
# Затем используйте QdrantDocumentStore вместо InMemoryDocumentStore
```

## Ускорение с помощью GPU

Haystack использует ускорение на GPU в двух основных сценариях:

### 1. Генерация эмбеддингов (Sentence Transformers)

GPU сильно полезен для эмбеддинга больших коллекций документов:

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

# Проверить доступность GPU
device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"Using device: {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")

# Создать embedder
embedder = SentenceTransformersDocumentEmbedder(
    model="BAAI/bge-base-en-v1.5"
)
embedder.warm_up()

# Бенчмарк
docs = [Document(content=f"Sample document {i} with some text content.") for i in range(100)]

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

print(f"Embedded 100 documents in {elapsed:.2f}s ({100/elapsed:.0f} docs/sec)")
EOF

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

### 2. Локальный инференс LLM (Hugging Face Transformers)

Для запуска LLM напрямую в Haystack без 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

# Автоматически использует GPU, если он доступен
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="Answer this question: {{ 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": "What is 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. Сочетание с Ollama (рекомендуемый подход)

Для лучшего сочетания простоты и производительности запускайте Ollama для инференса LLM, а Haystack для оркестрации:

```bash
# Шаг 1: Запустите Ollama (см. руководство по Ollama)
docker run -d \
  --name ollama \
  --gpus all \
  -p 11434:11434 \
  -v /workspace/ollama:/root/.ollama \
  ollama/ollama

# Шаг 2: Загрузить модель для кодинга/чата
docker exec ollama ollama pull llama3
docker exec ollama ollama pull nomic-embed-text  # Для эмбеддингов через Ollama

# Шаг 3: Запустить Haystack, указывая на 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
```

Мониторьте использование GPU в обоих контейнерах:

```bash
watch -n 2 nvidia-smi
```

## Подсказки и лучшие практики

### Выберите подходящую модель эмбеддингов

| Модель                         | VRAM     | Скорость      | Качество | Лучше всего для                       |
| ------------------------------ | -------- | ------------- | -------- | ------------------------------------- |
| `BAAI/bge-small-en-v1.5`       | \~0.5 GB | Самая быстрая | Хорошо   | Высокопроизводительное индексирование |
| `BAAI/bge-base-en-v1.5`        | \~1 GB   | Быстро        | Лучше    | Общий RAG                             |
| `BAAI/bge-large-en-v1.5`       | \~2 ГБ   | Средне        | Лучшее   | Максимальная точность                 |
| `nomic-ai/nomic-embed-text-v1` | \~1.5 GB | Быстро        | Отлично  | Длинные документы                     |

### Советы по проектированию конвейеров

* **Разбивайте документы разумно** — фрагменты по 200–400 слов с перекрытием 10–15% хорошо подходят для большинства задач RAG
* **Кэшируйте эмбеддинги** — сохраняйте хранилище документов на диск; переэмбеддинг дорогой
* **Используйте `warm_up()`** — вызовите `component.warm_up()` перед использованием в продакшене, чтобы загрузить модели в память GPU
* **Пакетное индексирование** — обрабатывайте документы партиями по 32–64 для оптимального использования GPU
* **Фильтрация по метаданным** — используйте фильтрацию по метаданным Haystack для ограничения области поиска (например, по дате, источнику, категории)

### Оптимизация затрат

```bash
# Используйте стиль ценообразования spot на Clore.ai — выбирайте серверы с меньшей стоимостью $/час
# Для разработки/тестирования: RTX 3060 (~$0.10/час) достаточно для эмбеддинга
# Для продакшен-эмбеддинга: RTX 3090 (~$0.20/час) — 24 ГБ справляются с большими батчами
# Для локального LLM + эмбеддинга: A100 40GB (~$0.60/час) — запас для одновременных пользователей

# Мониторьте использование ресурсов
docker stats haystack
nvidia-smi dmon -s u -d 5  # использование GPU каждые 5 секунд
```

### Защитите Hayhooks для внешнего доступа

```bash
# Вариант 1: SSH-туннель (проще всего, для личного использования)
# С вашей локальной машины:
ssh -L 1416:localhost:1416 root@<clore-ip> -p <clore-ssh-port>
# Затем обращайтесь к http://localhost:1416 локально

# Вариант 2: Добавить базовую аутентификацию через nginx reverse proxy
docker run -d \
  --name nginx-proxy \
  -p 80:80 \
  -v /workspace/nginx.conf:/etc/nginx/conf.d/default.conf \
  nginx:alpine
```

## Устранение неполадок

| Проблема                            | Вероятная причина                             | Решение                                                                                                           |
| ----------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `ModuleNotFoundError: haystack`     | Пакет не установлен                           | Пересоберите Docker-образ; проверьте `pip install haystack-ai` выполнено успешно                                  |
| `CUDA — недостаточно памяти`        | Модель эмбеддинга слишком большая             | Используйте `bge-small-en-v1.5` или уменьшите размер батча                                                        |
| Hayhooks возвращает 404 на pipeline | YAML файл не найден                           | Проверьте монтирование тома; файл конвейера должен находиться в `/app/pipelines/`                                 |
| Медленный эмбеддинг на CPU          | GPU не обнаружен                              | Проверьте `--gpus all` флаг; проверьте `torch.cuda.is_available()`                                                |
| Подключение к Ollama отклонено      | Неправильное имя хоста                        | Используйте `--add-host=host.docker.internal:host-gateway`; установите URL на `http://host.docker.internal:11434` |
| Скачивание с HuggingFace не удалось | Отсутствует токен или превышен лимит запросов | Установите `HF_TOKEN` переменная окружения; убедитесь, что модель не защищена                                     |
| Ошибка парсинга YAML конвейера      | Неверный синтаксис                            | Проверьте YAML; используйте `python3 -c "import yaml; yaml.safe_load(open('pipeline.yml'))"`                      |
| Контейнер сразу выходит             | Ошибка при запуске                            | Проверьте `docker logs haystack`; убедитесь, что CMD в Dockerfile корректна                                       |
| Порт 1416 недоступен извне          | Фаервол / проброс портов                      | Откройте порт в настройках заказа Clore.ai; проверьте открытые порты сервера                                      |

### Команды для отладки

```bash
# Просмотреть логи контейнера
docker logs haystack --tail 50 -f

# Протестировать Hayhooks API
curl http://localhost:1416/status
curl http://localhost:1416/pipelines

# Интерактивная сессия отладки Python
docker exec -it haystack python3

# Проверить GPU внутри контейнера
docker exec haystack python3 -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

# Проверить установленные пакеты
docker exec haystack pip show haystack-ai hayhooks
```

## Дополнительное чтение

* [Документация Haystack](https://docs.haystack.deepset.ai/) — официальная документация v2
* [Hayhooks на GitHub](https://github.com/deepset-ai/hayhooks) — REST API для обслуживания конвейеров
* [Haystack Cookbook](https://haystack.deepset.ai/cookbook) — пошаговые руководства (RAG, агенты, поиск)
* [deepset-ai/haystack на GitHub](https://github.com/deepset-ai/haystack) — исходники, issue, релизы
* [Интеграции Haystack](https://haystack.deepset.ai/integrations) — полный список поддерживаемых векторных хранилищ, LLM и инструментов
* [Ollama на Clore.ai](/guides/guides_v2-ru/yazykovye-modeli/ollama.md) — сочетайте Haystack с Ollama для локального инференса LLM
* [vLLM на Clore.ai](/guides/guides_v2-ru/yazykovye-modeli/vllm.md) — высокопроизводительный бэкенд для обслуживания LLM в Haystack
* [Руководство по сравнению GPU](/guides/guides_v2-ru/nachalo-raboty/gpu-comparison.md) — выберите подходящий GPU Clore.ai для вашей нагрузки
* [CLORE.AI Marketplace](https://clore.ai/marketplace) — арендуйте GPU-серверы


---

# Agent Instructions: 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:

```
GET https://docs.clore.ai/guides/guides_v2-ru/ai-platformy-i-agenty/haystack.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.