LangChain через TokenTool: базовый вызов, границы и приёмочные тесты
Публичная инструкция TokenTool показывает базовое подключение Python и JavaScript клиентов LangChain через ChatOpenAI. Совместимый transport — только первый слой: модель, ключ, лимит и логи полезно привязать к проекту, а retrieval вести либо во встроенной базе знаний TokenTool, либо во внешнем индексе с отдельным тестом. Публичный embeddings endpoint эта страница не предполагает.
Инфраструктурный слой
После подключения API начинается управление
Базовый вызов
Сначала отдельно принимаются авторизация, маршрут и текстовый ответ клиента.
Проверить поверхностьПроектный контроль
Ключи, модельные настройки, лимиты и статистика учитываются по проектам.
Проверить поверхностьДва RAG-режима
Встроенная база знаний и внешний retrieval — разные контуры; публичный embeddings endpoint не подразумевается.
Проверить поверхностьРабочий инструмент
Матрица приёмки режимов LangChain
Каждый режим включается после собственного воспроизводимого теста.
| Режим | Что измерить | Блокирующий сбой |
|---|---|---|
| invoke | Текст, статус, usage | Нет ответа или usage не разбирается |
| stream | Порядок, конец, cancel | Поток зависает или дублирует фрагменты |
| structured output | Схема, лишние поля, отказ | Невалидные данные проходят дальше |
| tools | Имя, аргументы, allowlist | Исполняется неизвестная операция |
| fallback | Причина и выбранная модель | Переключение происходит незаметно |
Сначала транспорт, потом цепочка
Создайте минимальный клиент только с base URL, ключом из переменной окружения и одним актуальным model ID. Выполните короткий текстовый запрос без memory, tools и парсеров. Так вы отдельно подтверждаете авторизацию, маршрут и базовую форму ответа.
После этого добавляйте компоненты по одному. PromptTemplate, parser, retriever и agent создают собственные точки отказа. Если собрать их одновременно, ошибка модели, транспорта или преобразования будет выглядеть одинаково. Версии `langchain`, `langchain-openai` или `@langchain/openai` фиксируйте в lock-файле приложения.
Матрица режимов
Для обычного invoke проверьте текст и метаданные. Для streaming — порядок чанков, завершение и отмену клиентом. Для structured output — валидность схемы на ответах с пустыми и лишними полями. Для tools — имя, аргументы, allowlist и отказ от неизвестной команды. Наличие режима в LangChain не подтверждает его поддержку каждой моделью.
Если режим не описан в текущей документации TokenTool, держите его выключенным до отдельного controlled test. Fallback на свободный текст не должен молча заменять строгий JSON, а fallback-модель не должна менять права на выполнение инструмента.
Наблюдаемость без утечки данных
Логируйте версию цепочки, идентификатор модели, код результата, задержку, число токенов и тип ошибки. API-ключ, системный промпт, найденные документы и полный ответ не нужны для маркетинговой аналитики. Если содержание требуется для отладки, используйте отдельное защищённое хранилище с ограниченным сроком.
Добавьте correlation ID от входного запроса до последнего узла. Он помогает отличить повтор LangChain от повтора вашего приложения. Ограничьте общий deadline всей цепочки, иначе последовательность умеренных таймаутов превратится в очень долгий пользовательский запрос.
Выбор модели и откат
Model ID берите из публичного каталога в день выпуска. Сравнивайте модели на закрытом наборе задач и одинаковой конфигурации. Контекст и тариф — измеряемые поля; способность корректно вызвать ваш tool или заполнить вашу схему подтверждается только тестом.
Абстракция провайдера полезна, если конфигурация действительно отделена от бизнес-логики. Подготовьте предыдущий model ID и base URL как управляемый rollback, но не переключайте автоматически после смысловой ошибки: другой ответ может пройти техническую схему и изменить бизнес-результат.
Порядок внедрения
- 01Зафиксировать версии LangChain-пакетов.
- 02Проверить минимальный текстовый invoke.
- 03Добавлять streaming, parser и tools по одному.
- 04Настроить технические метрики и общий deadline.
- 05Проверить rollback на закрытом наборе.
Перед запуском
- Ключ приходит из окружения
- Model ID взят из живого каталога
- Каждый режим имеет отдельный тест
- Tool-операции ограничены allowlist
- Логи не содержат документов и секретов
- Rollback не скрывает смысловую ошибку
Границы решения
- Поведение зависит от зафиксированной версии LangChain и клиента.
- Поддержка tools и structured output не выводится из названия модели.
Начните с небольшого измеримого теста
Проверьте один сценарий, зафиксируйте результат и расходы, затем расширяйте нагрузку.