LlamaIndex + NeuroAPI: OpenAILike и RAG

LlamaIndex — фреймворк для приложений с данными: индексация, поиск, RAG и агенты. Для NeuroAPI используются интеграционные пакеты llama-index-llms-openai-like и llama-index-embeddings-openai. Сначала создайте ключ в кабинете NeuroAPI, затем выпишите из /price ID чат-модели и embedding-модели: в каталоге на 19.10.2026 доступны text-embedding-3-small и text-embedding-3-large.

Установите нужные пакеты и зафиксируйте версии в зависимостях. Обратите внимание: OpenAILike — тонкая обёртка вокруг OpenAI-клиента для сторонних OpenAI-совместимых API, поэтому стандартные параметры запросов работают, а нестандартные поля провайдера могут быть недоступны.

• pip install llama-index-llms-openai-like llama-index-embeddings-openai
• Ключ NeuroAPI — в переменной окружения.
• ID моделей — из /price или GET /v1/models.
• Версии пакетов фиксируйте в проекте.

Базовый пример: OpenAILike(model=<ID>, api_base="https://neuroapi.host/v1", api_key=<ключ>, context_window=<из карточки>, is_chat_model=True, is_function_calling_model=<по модели>). Параметры api_base и api_key описаны в документации LlamaIndex; is_chat_model и is_function_calling_model зависят от возможностей выбранной модели.

Отдельно задайте context_window: в документации значение по умолчанию небольшое, и на реальных задачах его нужно поднять до характеристики модели, иначе длинные документы будут обрезаться. Если модель поддерживает вызов инструментов, включите is_function_calling_model; если не уверены — оставьте False и не строите агентные сценарии на этой модели.

• model — точный ID модели.
• api_base — https://neuroapi.host/v1.
• api_key — ключ NeuroAPI.
• context_window — из карточки модели.
• is_chat_model=True для чат-моделей.

Эмбеддинги настраиваются классом OpenAIEmbedding с параметрами model, api_base и api_key. Документы и запросы должны кодироваться одной моделью и с одной размерностью: если индекс собран одной моделью, а запрос кодируется другой, поиск теряет смысл. При смене embedding-модели переиндексируйте корпус.

Для больших наборов документов индексацию стоит запускать партиями и проверять размерность на небольшом примере. Стоимость эмбеддингов зависит от объёма текста, поэтому объём корпуса влияет на расход не меньше, чем запросы к чат-модели.

• OpenAIEmbedding(model=..., api_base=..., api_key=...).
• Одна модель для документов и запросов.
• Смена модели — переиндексация корпуса.
• Проверяйте размерность до полной загрузки.

Типовой сценарий: SimpleDirectoryReader загружает документы, VectorStoreIndex строит индекс на эмбеддингах, а query engine отвечает на вопросы, подмешивая найденные фрагменты в контекст. В LlamaIndex удобно задать общие настройки через Settings.llm и Settings.embed_model — тогда все компоненты используют один LLM и одну модель эмбеддингов.

Начните с небольшого корпуса и проверьте, что поиск действительно находит релевантные фрагменты до того, как добавлять сложные цепочки. Для production стоит ограничить размер передаваемого контекста и следить за usage: каждый вопрос с контекстом — это запрос к модели, а индексация — отдельный расход на эмбеддинги.

Для диалогов LlamaIndex предлагает chat engine с памятью: история удерживается в пределах заданного буфера. Помните, что каждый ход с историей увеличивает контекст и стоимость, поэтому ограничивайте глубину памяти и суммируйте старые сообщения, когда диалог становится длинным.

Если история не нужна, используйте query engine: он отвечает на отдельные вопросы без накопления контекста. Выбор между chat и query зависит от сценария, и его стоит зафиксировать до production-нагрузки, чтобы поведение и расход были предсказуемыми. Для тестовых прогонов держите отдельный ключ и небольшой корпус документов: так проверка не будет съедать рабочий баланс. Добавьте smoke-тест, который проверяет и ответ LLM, и размерность эмбеддингов. Так регрессия в интеграции обнаружится до того, как пользователи увидят пустые или нерелевантные ответы.

• SimpleDirectoryReader → VectorStoreIndex → query engine.
• Settings.llm и Settings.embed_model — единые настройки.
• Сначала проверьте качество поиска, потом усложняйте.
• Контролируйте размер контекста и объём индексации.
• Chat engine хранит историю — следите за глубиной.
• Query engine не накапливает контекст.
• Суммируйте старые сообщения в длинных диалогах.
• Зафиксируйте режим до production-нагрузки.

Типовые коды: 401 — неверный ключ, 404 — опечатка в ID модели или api_base, 429 — превышение лимитов. Для 429 и 5xx допустимы повторы с задержкой, для 401 и 404 — нет. Если ответы обрываются по контексту, проверьте context_window и размер передаваемых фрагментов.

Помните, что возможности tools и структурированного вывода зависят от модели: OpenAILike передаёт стандартные параметры OpenAI-совместимого API, но не добавляет функций, которых нет у модели. Ориентируйтесь на карточку модели и документацию пакета, а не на ожидания от «любой OpenAI-совместимой» модели.

• 401 — ключ, 404 — модель и api_base, 429 — лимиты.
• Обрывы — проверьте context_window и размер фрагментов.
• tools доступны только при поддержке моделью.
• Сверяйте поведение с карточкой модели.

Перед запуском проверьте три вещи: размер контекста, качество поиска и обработку ошибок. Если ответы на реальных документах нерелевантны, дело чаще в разбиении или в embedding-модели, а не в LLM. Ошибки 429 и 5xx стоит обрабатывать повторами с задержкой и ограничением числа попыток.

Отдельно настройте наблюдаемость: логируйте модель, число найденных фрагментов и usage, но не полный текст приватных документов. Это помогает разбирать инциденты и считать стоимость на реальном трафике, не нарушая требования к данным.

• Проверьте context_window и размер фрагментов.
• Оцените релевантность поиска на реальных вопросах.
• Обрабатывайте 429 и 5xx повторами с задержкой.
• Логи без приватного текста, но с usage.