Работают ровно две настройки:
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. Это обычная схема 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
[DONE] и кадр со списанием — в гайде Потоковая передача.
Инструменты
Массивtools передаётся в генератор как список объектов Tool из haystack.tools (Haystack 2.x). Формат схемы и цикл возврата результата — в гайде Вызов функций.
Python
Структурированный вывод
Передаётся черезgeneration_kwargs: {"response_format": {"type": "json_schema", "json_schema": {...}}} — компонент подставит поле в тело запроса как есть. Схемы и валидация результата — в гайде Структурированный вывод.
Медиа-задачи
Генерация изображений, видео и музыки в SpeShu.AI идёт через отдельный асинхронный API, и в Haystack нет готового компонента под него. Создавайте задачу напрямую и опрашивайте статус — контракт разобран в разделе Создание задачи. Идентификаторы медиа-моделей публичны и стабильны, их можно писать литералом:Python
Типичные проблемы
401 invalid_api_key при первом же run
401 invalid_api_key при первом же run
Проверьте, что компонент получает ключ:
Secret.from_env_var("SPESHU_API_KEY", strict=True) падает на старте с пустой переменной, а Secret.from_token(os.environ[...]) падает позже и менее понятно. Значение должно начинаться с sk- и не содержать кавычек и переносов строки. Подробнее — в разделе Аутентификация.404 model_not_found — а каталог /models отвечает
404 model_not_found — а каталог /models отвечает
Идентификатор устарел или вы скопировали его с префиксом провайдера (
openai/...). Подставляйте id из data[] ровно как есть, без префикса и обрезки. Разбор ответа — в разделе Каталог моделей.404 на пути, который вы точно не ошибались
404 на пути, который вы точно не ошибались
Проверьте адрес: он должен быть
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-клиента.402 insufficient_quota и всё прочее
402 insufficient_quota и всё прочее
Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки.
Что дальше
Начало работы
Ключ, баланс и первый запрос по шагам
Модели и цены
Контекст, зрение и стоимость в рублях
Потоковая передача
SSE,
[DONE] и кадр со списаниемВызов функций
Полный цикл вызова инструмента
