> 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-ru/platformy-i-agenty-ii/haystack.md).

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

Разверните Haystack от deepset на Clore.ai — создавайте production RAG-пайплайны, семантический поиск и рабочие процессы LLM-агентов на доступной GPU-инфраструктуре.

Haystack — это open-source фреймворк deepset для оркестрации ИИ, предназначенный для создания LLM-приложений промышленного уровня. Имея более 18 тыс. звёзд на 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](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**                | 18 тыс.+                                                                          |
| **Версия**                          | 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 как конечную точку через Hayhooks

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

### Требования к оборудованию

| Сценарий использования                           | GPU        | VRAM  | ОЗУ   | Диск   | Цена Clore.ai                               |
| ------------------------------------------------ | ---------- | ----- | ----- | ------ | ------------------------------------------- |
| **Только режим API** (OpenAI/Anthropic)          | Нет / CPU  | —     | 4 ГБ  | 20 ГБ  | \~$0.01–0.05/час                            |
| **Локальные эмбеддинги** (sentence-transformers) | RTX 3060   | 8 ГБ  | 16 ГБ | 30 ГБ  | $0.03–0.07/час                              |
| **Локальные эмбеддинги + небольшая LLM** (7B)    | RTX 3090   | 24 ГБ | 16 ГБ | 50 ГБ  | $0.07–0.21/ч                                |
| **Локальная LLM** (13B–34B)                      | RTX 4090   | 24 ГБ | 32 ГБ | 80 ГБ  | $0.14–0.42/ч                                |
| **Большая локальная LLM** (70B, квантованная)    | A100 80 ГБ | 80 ГБ | 64 ГБ | 150 ГБ | [голое железо](https://clore.ai/bare-metal) |

{% hint style="info" %}
Для большинства сценариев RAG **RTX 3090** по цене $0.07–0.21/час — оптимальный вариант: 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](https://clore.ai/marketplace), отфильтруйте по:

* **VRAM**: ≥ 8 ГБ для задач эмбеддингов, ≥ 24 ГБ для локальных LLM
* **Docker**: Включено (по умолчанию в большинстве объявлений)
* **Образ**: `nvidia/cuda:12.8.1-devel-ubuntu22.04` или `pytorch/pytorch:2.11.0-cuda12.8-cudnn9-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.8.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 будет обслуживать как конечную точку:

```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": "Что такое Haystack?"}'
```

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

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

| Переменная                   | Описание                                | Пример                |
| ---------------------------- | --------------------------------------- | --------------------- |
| `OPENAI_API_KEY`             | API-ключ OpenAI для моделей GPT         | `sk-...`              |
| `ANTHROPIC_API_KEY`          | API-ключ Anthropic для 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"Проиндексировано фрагментов документов: {document_store.count_documents()}")
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
```

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

Для рабочих нагрузок в продакшене замените 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"Используемое устройство: {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} ГБ")

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

# Бенчмарк
docs = [Document(content=f"Пример документа {i} с некоторым текстовым содержимым.") for i in range(100)]

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

print(f"Встроено 100 документов за {elapsed:.2f} с ({100/elapsed:.0f} док./с)")
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="Ответьте на этот вопрос: {{ 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": "Что такое 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 ГБ | Самый быстрый | Хорошо      | Индексация с высокой пропускной способностью |
| `BAAI/bge-base-en-v1.5`        | \~1 ГБ   | Быстро        | Лучше       | Общий RAG                                    |
| `BAAI/bge-large-en-v1.5`       | \~2 ГБ   | Средне        | Лучше всего | Наивысшая точность                           |
| `nomic-ai/nomic-embed-text-v1` | \~1.5 ГБ | Быстро        | Отлично     | Длинные документы                            |

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

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

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

```bash
# Используйте на Clore.ai тарифы spot — выбирайте серверы с более низкой ценой $/час
# Для разработки/тестирования: RTX 3060 ($0.03–0.07/час) достаточно для эмбеддингов
# Для продакшен-эмбеддингов: RTX 3090 ($0.07–0.21/час) — 24 ГБ хватает для больших пакетов
# Для локальной LLM + эмбеддингов: A100 40GB ([bare metal](https://clore.ai/bare-metal)) — запас по мощности для одновременных пользователей

# Следите за использованием ресурсов
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 out of memory`                    | Модель эмбеддингов слишком велика             | Используйте `bge-small-en-v1.5` или уменьшите размер пакета                                                      |
| Hayhooks возвращает 404 на pipeline     | Файл YAML не найден                           | Проверьте подключение тома; файл pipeline должен быть в `/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 pipeline            | Недопустимый синтаксис                        | Проверьте 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

# Проверить API Hayhooks
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
* [GitHub Hayhooks](https://github.com/deepset-ai/hayhooks) — REST API для обслуживания pipeline
* [Книга рецептов Haystack](https://haystack.deepset.ai/cookbook) — полные руководства (RAG, агенты, поиск)
* [deepset-ai/haystack на GitHub](https://github.com/deepset-ai/haystack) — исходный код, issues, релизы
* [Интеграции 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](https://clore.ai/marketplace) — арендуйте 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-ru/platformy-i-agenty-ii/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.