Перейти к основному содержанию
Haystack — open-source фреймворк deepset, в котором приложение собирается из явных компонентов: хранилище документов, retriever, prompt builder, генератор. Его выбирают, когда нужен не один вызов модели, а контролируемый конвейер, который можно тестировать по частям и менять по одному звену. SpeShu.AI подключается к нему как обычный OpenAI-совместимый эндпоинт: компонент генератора ничего не меняет в логике пайплайна.
Работают ровно две настройки: api_base_url = "https://speshu.ai/api/v1" и API-ключ. Haystack обращается к OpenAI-совместимым эндпоинтам, поэтому ничего, кроме адреса и ключа, менять не нужно — OpenAIChatGenerator сам бьёт в POST /api/v1/chat/completions. Ключ создаётся на speshu.ai/profile, разбор — в разделе Аутентификация.

Установка

Пакет ставится как haystack-ai; в версии 1.x он назывался farm-haystack. Все примеры ниже рассчитаны на ветку 2.x.

Возьмите идентификатор модели

Идентификаторы текстовых моделей не зашивайте в код: состав каталога меняется, и строка в коде устаревает молча, а запрос падает с 404 model_not_found. Прочитайте каталог один раз и положите значение в переменную окружения.
cURL
.data[0] — первый элемент, чтобы пример был запускаемым. В своём коде выбирайте по cost_completion, context_length и наличию зрения. Ответ разобран в разделе Каталог моделей, выбор — в Модели и цены.

Настройка генератора

Единственная точка, где задаётся адрес. Haystack 2.x принимает его в параметре инициализации api_base_url — вместе с ключом, который оборачивается в Secret:
Python
Secret.from_env_var("SPESHU_API_KEY", strict=True) заставит компонент упасть на старте, если переменная не задана — это дешевле, чем поймать 401 в проде. Таймаут поднимайте выше 300 секунд только для потоковых запусков: поток живёт до 15 минут.

Первый рабочий пример

RAG-конвейер без эмбеддингов: лексический поиск BM25 по in-memory хранилищу, сборка промпта, генерация ответа.
Python
Поля usage Haystack кладёт в meta сообщения-ответа — там же лежит usage.cost.total_cost, сумма в рублях. Подробнее — в гайде по учёту средств.

Эмбеддинги

SpeShu.AI не отдаёт эндпоинт эмбеддингов. Запрос к /api/v1/embeddings вернёт 404, а компонент OpenAITextEmbedder, настроенный на api_base_url = "https://speshu.ai/api/v1", упадёт на первом же документе. Лексический BM25-поиск, как в примере выше, эмбеддингов не требует и работает как есть. Семантический поиск требует отдельного провайдера.
Два честных варианта: (а) Эмбеддинги у другого провайдера, генерация в SpeShu.AI. Это обычная схема RAG-системы: векторы лежат в вашем хранилище, а платит и считает вызовы только генератор. Haystack позволяет задать адрес покомпонентно, поэтому два конфигурационных значения живут рядом.
Python
(а) — предпочтительный вариант: генерация остаётся в SpeShu.AI, стоимость векторизации вы контролируете отдельно, а InMemoryEmbeddingRetriever подставляет эмбеддер сам. (б) Без эмбеддингов. Оставьте InMemoryBM25Retriever и не добавляйте эмбеддер вообще. Это уже полноценный Q&A-конвейер; для продакшена замените in-memory хранилище на Elasticsearch, OpenSearch, Qdrant или Weaviate — все они поддерживают BM25.

Продвинутые сценарии

Haystack умеет всё, что поддерживает эндпоинт POST /api/v1/chat/completions — компонент генератора проксирует поля без изменений. Подробности формата — в канонических гайдах.

Потоковая передача

Включается флагом streaming=True при инициализации, а обработчик кусков передаётся в run (Haystack 2.x):
Python
Разбор кадров SSE, маркер [DONE] и кадр со списанием — в гайде Потоковая передача.

Инструменты

Массив tools передаётся в генератор как список объектов Tool из haystack.tools (Haystack 2.x). Формат схемы и цикл возврата результата — в гайде Вызов функций.
Python

Структурированный вывод

Передаётся через generation_kwargs: {"response_format": {"type": "json_schema", "json_schema": {...}}} — компонент подставит поле в тело запроса как есть. Схемы и валидация результата — в гайде Структурированный вывод.

Медиа-задачи

Генерация изображений, видео и музыки в SpeShu.AI идёт через отдельный асинхронный API, и в Haystack нет готового компонента под него. Создавайте задачу напрямую и опрашивайте статус — контракт разобран в разделе Создание задачи. Идентификаторы медиа-моделей публичны и стабильны, их можно писать литералом:
Python
Полный каталог медиа-моделей — в разделе Модели генерации.

Типичные проблемы

Проверьте, что компонент получает ключ: Secret.from_env_var("SPESHU_API_KEY", strict=True) падает на старте с пустой переменной, а Secret.from_token(os.environ[...]) падает позже и менее понятно. Значение должно начинаться с sk- и не содержать кавычек и переносов строки. Подробнее — в разделе Аутентификация.
Идентификатор устарел или вы скопировали его с префиксом провайдера (openai/...). Подставляйте id из data[] ровно как есть, без префикса и обрезки. Разбор ответа — в разделе Каталог моделей.
Проверьте адрес: он должен быть https://speshu.ai/api/v1 — с суффиксом /v1 и без слэша в конце. Строка "https://speshu.ai/api/v1/" в api_base_url даёт 404 на каждом запросе, и причина неочевидна. Проверьте это самым дешёвым способом: GET https://speshu.ai/api/v1/models с вашим ключом.
Вы задали api_base_url SpeShu.AI компоненту OpenAITextEmbedder. Эмбеддингов в этом API нет — переключите компонент на отдельный провайдер (см. раздел выше) либо уберите эмбеддер и оставьте BM25.
Обработчик не навешен: в Haystack 2.x streaming=True на компоненте недостаточно, нужно передать streaming_callback в run. Второй частый случай — буферизация на стороне вашего HTTP-клиента.
Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки.

Что дальше

Начало работы

Ключ, баланс и первый запрос по шагам

Модели и цены

Контекст, зрение и стоимость в рублях

Потоковая передача

SSE, [DONE] и кадр со списанием

Вызов функций

Полный цикл вызова инструмента