> ## Documentation Index
> Fetch the complete documentation index at: https://speshu.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Haystack: как сделать поиск по документам и Q&A-систему на RAG

> Обзор Haystack: pipeline-подход, RAG, retrievers, generators, плюсы и минусы, пример с SpeShu.AI.

Haystack — open-source фреймворк deepset для построения production-ready RAG, поиска по документам и AI-пайплайнов. Его используют, когда нужно не просто вызвать LLM, а явно собрать цепочку из retriever, prompt builder, generator и document store.

О Haystack говорят в контексте надёжных RAG-систем. Он хорошо подходит командам, которым важны понятные компоненты, явные входы и выходы, возможность тестировать pipeline и менять отдельные части без переписывания всего проекта.

В этой статье разберём, как работает Haystack и как направить OpenAI-компоненты на SpeShu.AI.

## Что такое haystack

Haystack — это framework для AI orchestration. В нём приложение собирается из компонентов: document store, retriever, prompt builder, generator, ranker, converter и других блоков.

Главная область применения — поиск и Q\&A по документам. Например: пользователь задаёт вопрос, retriever ищет релевантные фрагменты, prompt builder формирует контекст, generator отвечает через LLM.

Haystack полезен backend-командам, которые хотят видеть pipeline как инженерную систему, а не как набор скрытых магических вызовов.

## Как работает haystack

Haystack pipeline похож на граф компонентов. Каждый компонент объявляет входы и выходы. Вы добавляете их в `Pipeline`, соединяете через `connect`, а затем запускаете с данными.

Для RAG нужны минимум:

* `DocumentStore` для хранения документов;
* `Retriever` для поиска;
* `ChatPromptBuilder` для prompt;
* `OpenAIChatGenerator` для ответа модели.

OpenAI-компоненты поддерживают `api_base_url`, поэтому их можно направить на совместимый endpoint SpeShu.AI.

## Что умеет haystack

* строить явные RAG pipeline;
* подключать BM25, embeddings и hybrid retrieval;
* использовать разные document stores;
* вызывать chat generators;
* добавлять rankers, routers и evaluators;
* тестировать компоненты отдельно;
* собирать agents и tools поверх pipeline.

Мини-кейсы: Q\&A по документации, поиск по базе знаний, ассистент поддержки, юридический поиск, технический helpdesk, аналитика документов.

## haystack на практике

Пример ниже создаёт короткий RAG pipeline. Для простоты используется in-memory document store и BM25 retriever, а генерация ответа идёт через SpeShu.AI.

```python theme={null} theme={null}
import os
from haystack import Document, Pipeline
from haystack.components.builders import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
from haystack.dataclasses import ChatMessage
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.utils import Secret

document_store = InMemoryDocumentStore()
document_store.write_documents([
    Document(content="SpeShu.AI предоставляет OpenAI-compatible API."),
    Document(content="RAG отвечает по найденным документам, а не только по памяти модели."),
])

prompt_template = [
    ChatMessage.from_system("Отвечай кратко и только по документам."),
    ChatMessage.from_user(
        "Документы:\n{% for doc in documents %}{{ doc.content }}\n{% endfor %}\n"
        "Вопрос: {{ question }}"
    ),
]

pipeline = Pipeline()
pipeline.add_component("retriever", InMemoryBM25Retriever(document_store))
pipeline.add_component("prompt", ChatPromptBuilder(template=prompt_template))
pipeline.add_component(
    "llm",
    OpenAIChatGenerator(
        model="openai/gpt-5.5",
        api_key=Secret.from_token(os.environ["SPESHU_AI_API_KEY"]),
        api_base_url="https://speshu.ai/api/v1",
    ),
)
pipeline.connect("retriever.documents", "prompt.documents")
pipeline.connect("prompt.prompt", "llm.messages")

question = "Зачем нужен RAG?"
result = pipeline.run({
    "retriever": {"query": question},
    "prompt": {"question": question},
})

print(result["llm"]["replies"][0].text)
```

Для семантического поиска добавьте embedder и vector retriever. Для продакшена замените in-memory store на Elasticsearch, OpenSearch, Qdrant, Weaviate или другой supported backend.

## Преимущества и недостатки haystack

Плюсы:

* явная архитектура pipeline;
* сильный фокус на RAG и retrieval;
* компоненты удобно тестировать отдельно;
* есть поддержка custom OpenAI base URL.

Минусы:

* старт может быть чуть тяжелее, чем у простого LangChain-примера;
* нужно понимать связи компонентов;
* для маленьких одноразовых скриптов Haystack может быть избыточен.

## haystack vs альтернативы

Haystack vs LangChain: Haystack даёт более явный pipeline-подход. LangChain шире по интеграциям и быстрее для экспериментальных цепочек.

Haystack vs LlamaIndex: LlamaIndex удобен, когда вы начинаете с данных и query engine. Haystack лучше, когда нужна инженерная сборка pipeline с контролируемыми компонентами.

Haystack vs Dify: Dify даёт UI и no-code workflow. Haystack — кодовый framework для разработчиков.

## Кому подойдёт haystack

Haystack подойдёт backend-разработчикам, ML-инженерам, поисковым командам, AI-стартапам и компаниям, которые строят внутренний поиск по документам.

Если вам важны тестируемость, явные компоненты и production RAG, Haystack стоит рассмотреть одним из первых.

## Как попробовать haystack через SpeShu.AI

SpeShu.AI подключается к `OpenAIChatGenerator` через `api_base_url`:

* не нужен VPN;
* не нужна зарубежная карта;
* доступно несколько моделей;
* один API-ключ для разных проектов;
* быстрый старт через [speshu.ai/profile](https://speshu.ai/profile).

Модели смотрите в [каталоге](/docs/api-reference/models/list), формат chat-запросов — в [Chat Completions](/docs/api-reference/chat/completions).

## Заключение

Haystack — сильный выбор для RAG-систем, где важны pipeline, контроль и воспроизводимость. Главный инсайт: хороший Q\&A по документам строится не только на LLM, а на качественном retrieval и прозрачной сборке компонентов.

***

<Card title="Подключить API" icon="plug" type="tip" href="https://speshu.ai/profile">
  Запустите интеграцию через SpeShu.AI: единый доступ к AI-моделям, без VPN и зарубежной карты
</Card>