Настройка сводится к двум значениям:
base_url = "https://speshu.ai/api/v1" и ваш API-ключ. Эндпоинт /api/v1/chat/completions совместим с OpenAI Chat Completions, поэтому нужен только клиент фреймворка с поддержкой OpenAI-совместимых провайдеров. Больше ничего менять не нужно.Установка
Примеры ниже проверены по
llama-index-core 0.11.x. В более ранних версиях класс назывался OpenAI, а response_gen у потокового ответа ещё не было. Если ваша версия отличается — сверяйтесь с документацией LlamaIndex, базовый адрес при этом не меняется.Шаг 1. Ключ и идентификатор модели
cURL
404 model_not_found. Возьмите его из каталога и положите в переменную окружения:
cURL
context_length, owned_by — в разделе Каталог моделей.
Настройка LLM
OpenAILike из пакета llama-index-llms-openai-like — обёртка LlamaIndex для любого OpenAI-совместимого эндпоинта. Она и есть полноценный OpenAI-совместимый провайдер.
Python
Блоки кода ниже продолжают файл:
Settings.llm уже настроен блоком выше, переменные SPESHU_API_KEY и SPESHU_MODEL заданы в окружении.Вариант A. RAG с эмбеддингами другого провайдера
Python
Python
from_documents на загрузку файлов, страниц сайта или готового vector store — код выше меняется только в этой строке.
Вариант B. Без эмбеддингов
Если задача не в поиске по базе знаний, индекс не нужен:Settings.llm — обычный чат-клиент, и его можно использовать напрямую.
Python
Потоковая передача
as_query_engine(streaming=True) переводит query engine на stream: true. Ответ приходит фрагментами через response_gen:
Python
Инструменты
FunctionTool превращает обычную Python-функцию в инструмент, а as_query_engine(tools=[...]) включает агентный цикл: модель сама решает, когда вызвать функцию.
Python
FunctionTool можно передать в агента, а не в query engine. Полный цикл вызова — схемы, tool_choice, параллельные вызовы, обработка ошибок инструмента — в гайде Вызов функций.
Структурированный вывод
as_structured_llm заставляет модель отдать Pydantic-модель вместо свободного текста:
Python
response_format на чат-эндпоинте. Форма JSON Schema, режимы json_object и json_schema и поведение при невалидном результате разобраны в гайде Структурированный вывод.
Медиа
Генерации изображений, видео и музыки в LlamaIndex нет — это отдельный REST API поверхPOST /api/v1/async/media/tasks, и вызывается он напрямую:
Python
nano-banana-2 — публичный идентификатор из GET /api/v1/media/models, он стабилен; текстовые идентификаторы в код не зашивайте. Форма запроса, Idempotency-Key и списание при создании — в разделе Создание задачи.
Изображения, наоборот, идут в LlamaIndex как вход: загрузите файл в хранилище и передайте полученную ссылку в блоке изображения. Типы блоков разобраны в гайде Медиаввод.
Если что-то не работает
401 invalid_api_key на первом же запросе
401 invalid_api_key на первом же запросе
Ключ не доехал: либо не задан
api_key= в OpenAILike, либо в переменной окружения значение обрезано, либо ключ отозван. Отладочная проверка: echo "$SPESHU_API_KEY" | wc -c — в значении должен быть полный ключ с префиксом sk-, без кавычек и переносов строки.404 на самом первом запросе, до всякой модели
404 на самом первом запросе, до всякой модели
Проблема в адресе, а не в ключе. Нужен ровно
https://speshu.ai/api/v1 — с суффиксом /v1 и без слэша в конце. Вариант https://speshu.ai/api даст 404 на каждом запросе, а https://speshu.ai/api/v1/ с завершающим слэшем — двойной слэш в пути, который часть клиентов не нормализует. Разбор кодов — в разделе Ошибки.404 model_not_found на первом же запросе чата
404 model_not_found на первом же запросе чата
Идентификатор модели устарел или скопирован с ошибкой. Возьмите его заново из
GET /api/v1/models и подставьте как есть — с префиксом, если он есть в id, и без обрезки. Почти всегда причина — зашитая в код строка вместо $SPESHU_MODEL.Инструменты не вызываются, модель отвечает текстом
Инструменты не вызываются, модель отвечает текстом
У
OpenAILike по умолчанию is_function_calling_model=False, и запрос с tools уходит, а модель его молча игнорирует. Проверьте, что флаг выставлен, и что FunctionTool передан в as_query_engine(tools=[...]). Поддержка вызовов различается между моделями — проверяется пробным запросом.Ответ обрезан на середине, индекс «не находит» документы
Ответ обрезан на середине, индекс «не находит» документы
context_window у OpenAILike по умолчанию равен 3900 токенам, и значение из каталога моделей не подтягивается автоматически. Задайте context_window явно, взяв context_length из GET /api/v1/models, иначе вопрос вместе с найденным контекстом не поместится в окно.404 на этапе построения индекса
404 на этапе построения индекса
Settings.embed_model указывает на https://speshu.ai/api/v1. Эндпоинта /embeddings в этом API нет. Переведите эмбеддинги на отдельного провайдера или на локальную модель, как показано в варианте A.Что дальше
Начало работы
Путь от создания ключа до работающего запроса
Потоковая передача
Кадры SSE,
[DONE] и списаниеВызов функций
Полный цикл вызова инструмента
Структурированный вывод
JSON Schema и валидация результата
Каталог моделей
Откуда берётся
model и что означает owned_byМодели и цены
Контекстное окно, зрение и стоимость токенов
