LangChain + NeuroAPI: ChatOpenAI и embeddings

LangChain — фреймворк для приложений на LLM: цепочки, агенты, RAG и инструменты. Интеграция с NeuroAPI идёт через пакет langchain-openai, который использует официальный OpenAI SDK, поэтому достаточно заменить base_url и ключ. Сначала создайте ключ в кабинете NeuroAPI и выберите тариф, затем выпишите ID чат-модели и embedding-модели из /price.

Установите пакет langchain-openai (и langchain, если строите цепочки). Для RAG понадобится embedding-модель: в каталоге на 19.10.2026 доступны text-embedding-3-small и text-embedding-3-large — точный список и цены проверяйте в /price и /docs/embeddings.

• pip install langchain-openai langchain
• Ключ NeuroAPI — в переменной окружения.
• ID чат-модели и embedding-модели — из каталога.
• Для RAG документы и запросы кодируются одной embedding-моделью.

Базовый вызов выглядит так: ChatOpenAI(model=<ID>, base_url="https://neuroapi.host/v1", api_key=<ключ>), затем model.invoke(messages) или model.stream(...) для потокового ответа. Поля base_url и api_key относятся к клиенту OpenAI SDK, поэтому работают так же, как с официальным API, но с другим адресом.

Инструменты подключаются через bind_tools, но их реальная поддержка зависит от модели: если модель не умеет function calling, вызов инструментов не сработает. Структурированный вывод тоже зависит от модели. Проверяйте флаги в карточке модели и тестируйте на простом примере до того, как строить сложного агента.

• ChatOpenAI(model=..., base_url=..., api_key=...).
• model.invoke() — обычный вызов, model.stream() — стриминг.
• bind_tools работает только с моделями, поддерживающими tools.
• Структурированный вывод зависит от возможностей модели.

Для эмбеддингов используется OpenAIEmbeddings с параметрами base_url, api_key и model. Модель указывается та же, что и для индексации: документы и поисковые запросы должны кодироваться одной моделью и с одной размерностью, иначе близость векторов теряет смысл.

При смене embedding-модели индекс приходится перестраивать: старые векторы несопоставимы с новыми. Стоимость эмбеддингов зависит от объёма текста, поэтому большие корпуса стоит индексировать партиями и проверять размерность на небольшом наборе до полной загрузки.

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

В JavaScript и TypeScript используется пакет @langchain/openai. Класс ChatOpenAI принимает model и apiKey, а кастомный адрес задаётся через объект configuration с полем baseURL. Названия полей в разных версиях пакета могут отличаться, поэтому сверяйте их с документацией установленной версии.

Если приложение на JS использует стриминг, проверьте, что выбранная модель поддерживает потоковый режим, а обработчик корректно завершает поток. Для embeddings в JS используется OpenAIEmbeddings из того же пакета с теми же параметрами адреса и ключа.

• npm install @langchain/openai
• model: ID из каталога, apiKey: ключ NeuroAPI.
• configuration.baseURL — кастомный адрес API.
• Проверяйте стриминг и завершение потока отдельно.

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

Документация langchain-openai предупреждает: ChatOpenAI ориентирован на официальную спецификацию OpenAI, и нестандартные поля ответа могут быть недоступны. Это важно для провайдеров с расширениями: держитесь стандартных полей чата и не полагайтесь на недокументированные свойства. Баланс NeuroAPI предоплаченный, тариф выбирается на уровне ключа.

Для нескольких разработчиков разумно завести отдельные ключи NeuroAPI: расход по проектам будет виден отдельно, а инцидент с одним ключом не заблокирует остальных. base_url при этом остаётся общим, поэтому переключение окружений сводится к смене ключа.

Зафиксируйте в проекте список допустимых моделей и требования к совместимости: tools, стриминг и структурированный вывод зависят от модели. Это избавит от ситуации, когда код проверен на одной модели, а на другой не работает агентный сценарий или инструменты. Для CI полезно завести отдельный ключ с ограниченным бюджетом: тесты не должны упираться в общий баланс разработки. Держите базовый набор smoke-тестов на одной модели, чтобы быстрые проверки не зависели от доступности всего каталога. Отдельно фиксируйте, какие функции модели проверяет каждый тест: вызов инструментов, стриминг, структурированный вывод.

• 401 — ключ, 404 — ID модели, 429 — лимиты.
• Повторы — только для 429 и 5xx.
• Сохраняйте usage для сверки расходов.
• Опирайтесь на стандартные поля OpenAI-совместимого ответа.
• Отдельные ключи для окружений и проектов.
• Список допустимых моделей — в документации проекта.
• Проверяйте tools и стриминг на каждой модели.
• Логируйте usage, не сохраняя чувствительный текст.

Для RAG понадобятся загрузчик документов, сплиттер и векторное хранилище. Документы разбиваются на фрагменты, кодируются OpenAIEmbeddings и сохраняются в хранилище; при вопросе кодируется запрос, находятся ближайшие фрагменты и передаются в ChatOpenAI вместе с вопросом.

Начните с небольшого набора документов и проверьте релевантность поиска до того, как добавлять сложные цепочки и агентов. Размер фрагмента и их число влияют и на качество ответа, и на объём контекста, а значит, и на стоимость запроса к модели.

• Загрузчик → сплиттер → эмбеддинги → хранилище.
• Одна embedding-модель для документов и запросов.
• Сначала проверьте поиск, потом усложняйте цепочку.
• Контролируйте число фрагментов в контексте.