Перейти к основному содержанию
LlamaIndex — открытый Python-фреймворк, который строит приложения вокруг данных: загружает документы, режет их на фрагменты, кладёт в индекс и отвечает на вопросы по найденному контексту. Им пользуются, когда задача формулируется не «позови модель», а «дай модели доступ к моим документам, PDF, базе знаний или выгрузке из CRM» — чат по базе знаний, поиск по внутренней документации, ассистент поддержки.
Настройка сводится к двум значениям: base_url = "https://speshu.ai/api/v1" и ваш API-ключ. Эндпоинт /api/v1/chat/completions совместим с OpenAI Chat Completions, поэтому нужен только клиент фреймворка с поддержкой OpenAI-совместимых провайдеров. Больше ничего менять не нужно.
В API SpeShu.AI нет эндпоинта /embeddings. Стандартный RAG-пайплайн LlamaIndex требует векторы, поэтому их нужно брать отдельно — у другого провайдера или локально. Через SpeShu.AI вызывается только генерация. Ниже показаны оба честных варианта: генерация через SpeShu.AI плюс векторы от отдельного провайдера, и пайплайн вообще без эмбеддингов.

Установка

Для RAG-варианта дополнительно нужен клиент эмбеддингов того провайдера, у которого вы берёте векторы:
Примеры ниже проверены по 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
Два флага в примере — не украшение. OpenAILike по умолчанию создаётся как completion-модель, которая не умеет ни формат сообщений, ни вызов функций. Без is_chat_model=True индекс уйдёт в неверный путь, а без is_function_calling_model=True инструменты будут молча игнорироваться.
Блоки кода ниже продолжают файл: Settings.llm уже настроен блоком выше, переменные SPESHU_API_KEY и SPESHU_MODEL заданы в окружении.

Вариант A. RAG с эмбеддингами другого провайдера

Все значения в блоке embed — отдельная конфигурация стороннего провайдера эмбеддингов. Это не SpeShu.AI: здесь нет эндпоинта, который отдал бы вам вектор. Генерация идёт через SpeShu.AI, векторы — через ваш собственный источник.
Python
Эмбеддинги можно считать и полностью локально, без ключа и без внешнего сервиса — тогда уйдёт только трафик к SpeShu.AI:
Python
В продакшене замените from_documents на загрузку файлов, страниц сайта или готового vector store — код выше меняется только в этой строке.

Вариант B. Без эмбеддингов

Если задача не в поиске по базе знаний, индекс не нужен: Settings.llm — обычный чат-клиент, и его можно использовать напрямую.
Python

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

as_query_engine(streaming=True) переводит query engine на stream: true. Ответ приходит фрагментами через response_gen:
Python
Списание приходит в последнем кадре потока, а не в финальном тексте. Если вы прервёте цикл чтения, деньги за уже сгенерированные токены всё равно спишутся. Формат кадров, маркер [DONE] и поведение при разрыве — в гайде Потоковая передача.

Инструменты

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 как вход: загрузите файл в хранилище и передайте полученную ссылку в блоке изображения. Типы блоков разобраны в гайде Медиаввод.

Если что-то не работает

Ключ не доехал: либо не задан api_key= в OpenAILike, либо в переменной окружения значение обрезано, либо ключ отозван. Отладочная проверка: echo "$SPESHU_API_KEY" | wc -c — в значении должен быть полный ключ с префиксом sk-, без кавычек и переносов строки.
Проблема в адресе, а не в ключе. Нужен ровно https://speshu.ai/api/v1 — с суффиксом /v1 и без слэша в конце. Вариант https://speshu.ai/api даст 404 на каждом запросе, а https://speshu.ai/api/v1/ с завершающим слэшем — двойной слэш в пути, который часть клиентов не нормализует. Разбор кодов — в разделе Ошибки.
Идентификатор модели устарел или скопирован с ошибкой. Возьмите его заново из 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, иначе вопрос вместе с найденным контекстом не поместится в окно.
Settings.embed_model указывает на https://speshu.ai/api/v1. Эндпоинта /embeddings в этом API нет. Переведите эмбеддинги на отдельного провайдера или на локальную модель, как показано в варианте A.
Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки. Таймауты, квоты и параллельные потоки — в разделе Лимиты.

Что дальше

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

Путь от создания ключа до работающего запроса

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

Кадры SSE, [DONE] и списание

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

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

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

JSON Schema и валидация результата

Каталог моделей

Откуда берётся model и что означает owned_by

Модели и цены

Контекстное окно, зрение и стоимость токенов