dosnav/n8n-nodes-teamorouter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
n8n-nodes-teamorouter/README.md

12 KiB
Raw Blame History

n8n-nodes-teamorouter

Кастомные узлы n8n для шлюза TeamoRouter (https://api.teamorouter.com/v1) — OpenAI-совместимого роутера к GPT, Claude, Gemini, DeepSeek, GLM, Grok, Kimi и другим моделям.

Пакет содержит два узла и один тип учётных данных:

Узел Тип Назначение
TeamoRouter Chat Model (lmChatTeamRouter) sub-node, ai_languageModel Подключается к AI Agent, Basic LLM Chain, Question and Answer Chain и любым другим узлам, которые принимают Language Model
TeamoRouter (teamorouter) обычный узел Три операции: Chat → Message a Model, Image → Generate an Image, Model → List Models
TeamoRouter API (teamorouterApi) credentials API-ключ + Base URL

1. Установка

Вариант А. Через интерфейс n8n (рекомендуется)

Community nodes в n8n ставятся из npm, поэтому пакет должен быть опубликован:

  1. Выгрузите папку в свой git-репозиторий.

  2. Опубликуйте в npm:

    npm install
npm run build
npm publish --access public

  3. В n8n: Settings → Community nodes → Install a community node, введите n8n-nodes-teamorouter, подтвердите предупреждение.

  4. Перезапускать n8n не нужно — узлы появляются сразу.

Нужна роль Owner/Admin и включённые community nodes. Community nodes ставятся на весь инстанс.

Вариант Б. Копированием папки (если есть доступ к серверу n8n)

  1. npm install && npm run build — на выходе нужна папка dist/.

  2. Положите всю папку пакета (в ней обязателен package.json) в каталог пользовательских расширений, например:

    • в Docker: /home/node/.n8n/custom/n8n-nodes-teamorouter/
    • через переменную окружения: N8N_CUSTOM_EXTENSIONS=/path/to/custom-nodes, а внутри уже папка пакета

  3. Внутри папки пакета один раз выполните npm install --omit=dev, чтобы n8n-workflow (peer-зависимость) был доступен из вашей папки.

  4. Перезапустите n8n.

Вариант В. Локальная разработка

npm install
npm run build:watch     # tsc в режиме наблюдения
export N8N_CUSTOM_EXTENSIONS="$(pwd)"
npx n8n start

2. Учётные данные

Settings → Credentials → New → TeamoRouter API

Поле Значение
API Key ключ из панели TeamoRouter, начинается с sk-teamo-
Base URL https://api.teamorouter.com/v1 (по умолчанию; меняйте только для зеркала .cn или своего роутера)

Кнопка проверки делает GET /v1/models с заголовком Authorization: Bearer <ключ>.

3. TeamoRouter Chat Model (для AI Agent)

  1. Добавьте AI Agent (или Basic LLM Chain).
  2. В слот Chat Model добавьте TeamoRouter Chat Model.
  3. Выберите модель из списка — он читается вживую из GET /v1/models. В подписи к модели видны провайдер и цена за 1M токенов (если роутер их отдаёт).

Опции

Опция Что делает
Sampling Temperature случайность ответа, 0…2
Maximum Number of Tokens лимит генерации; -1 = решает модель
Top P nucleus sampling; меняйте либо temperature, либо topP
Force JSON Response просит модель отвечать объектом JSON (в промпте должно быть слово JSON)
Service Tier → Fast режим Fast у TeamoRouter: до 2,5× быстрее, тарифицируется ×2
Extra Body произвольные JSON-поля в тело запроса, например {"top_k": 40}; перекрывает всё выше
Timeout по умолчанию 600000 мс (роутер допускает ответы до 600 с)
Max Retries повторы при ошибке, по умолчанию 2

Модель, которой нет в списке

Поле Model можно переключить в режим выражения (переключатель Expression в правом верхнем углу поля) и вписать ID руками:

{{ 'some-new-model-id' }}

Это пригодится, если модель появилась у роутера, а список в UI ещё не перечитан.

4. Узел TeamoRouter (обычные операции)

Chat → Message a Model

Отправляет POST /v1/chat/completions и возвращает JSON-ответ как есть.

Поле Описание
Model список читается из GET /v1/models (только текстовые модели; картинные скрыты)
Prompt сообщение пользователя
Options → System Prompt системная инструкция
Options → остальное temperature, topP, max tokens, JSON-ответ, Service Tier Fast, Extra Body, Timeout

Текст ответа доступен как {{ $json.choices[0].message.content }}, расход токенов — {{ $json.usage }}.

Image → Generate an Image

Отправляет POST /v1/images/generations и кладёт результат в бинарное поле (по умолчанию data, PNG).

Поле Описание
Model по умолчанию gpt-image-2, список — только картинные модели; можно вписать ID выражением
Prompt описание картинки
Put Output File in Field имя бинарного свойства

Дальше файл уходит в Write Binary File, в Telegram, в S3 и т. д. Долгие генерации узел ждёт до 5 минут.

Model → List Models

Возвращает модели роутера: по одному элементу на модель (id, object, owned_by, pricing и др.). Удобно, чтобы построить собственный справочник или посчитать цены.

5. Известные особенности и ограничения

  • Ответы идут на /v1/chat/completions. Исключение — модель из семейства gpt-5.6* и всё, что содержит codex: LangChain внутри n8n сам переключает такие ID на /v1/responses (это поведение зашито в @langchain/openai и не отключается настройками). TeamoRouter поддерживает /v1/responses, но только для GPT-моделей, поэтому схема рабочая. Для Claude/Gemini запросы идут обычным Chat Completions.
  • Claude через OpenAI-формат не отдаёт prompt caching. Это ограничение формата роутера, а не узла: кэширование промпта доступно только через нативный протокол Anthropic (в README TeamoRouter это указано отдельно).
  • max_tokens, а не max_completion_tokens. Узел отправляет именно max_tokens — как в примере из документации TeamoRouter. Если конкретная модель требует max_completion_tokens, добавьте его через Extra Body.
  • Формат ответа JSON передаётся через response_format — это параметр Chat Completions. Для моделей, которые уходят на /v1/responses, он может игнорироваться.
  • Список картинных моделей определяется по имени: *-image, gpt-image*, nano-banana*, dall-e*, imagen*. Если роутер назовёт модель иначе, она попадёт в список чата (или наоборот); при этом поле всегда можно заполнить вручную выражением.
  • Цены в списке моделей — подсказка. Роутер может отдавать цену за токен или уже за 1M токенов; узел считает значения меньше 0.005 как «за токен». Это только отображение, на запросы не влияет.
  • У полей Model список загружается при открытии, кэша нет: если модель только что появилась, нажмите перезагрузить список или используйте выражение.

6. Разработка и проверки

npm install
npm run build          # tsc + копирование иконок в dist/
npm test               # проверка структуры пакета + тесты узлов на мок-сервере
npm run typecheck
npm run mock           # мок TeamoRouter на http://127.0.0.1:4123/v1 (ключ test-key)

npm test запускает два набора:

  1. test/validate-nodes.mjs — имитирует загрузку пакета n8n: проверяет описание узлов, наличие иконок, реализацию loadOptionsMethod, ссылки на credential, тип соединения ai_languageModel у саб-узла.
  2. test/run-node-tests.mjs — поднимает мок роутера (test/mock-server.mjs, без зависимостей) и прогоняет скомпилированные узлы с настоящим HTTP и настоящим @langchain/openai: список моделей и фильтрация картинных, supplyData + реальный вызов модели, проброс опций (service_tier, extra_body, лимиты), обе операции у обычного узла, генерация изображения в бинарном виде, разбор ошибок 401/402/404, Continue On Fail и таймаут.

Тесты не требуют ключа TeamoRouter. Модели fail-401, fail-402, fail-404, fail-500 в моке принудительно отдают ошибку, slow-model отвечает через 2,5 с.

7. Первый запуск и диагностика

  • Пакет собран и проверен автотестами (см. npm test), но в живом n8n ещё не запускался — первый запуск делайте на тестовом воркфлоу.
  • При установке через Settings → Community nodes интерфейс может показать предупреждение о сообщественном узле — это нормально.
  • Если n8n пишет, что узел не загрузился, проверьте Help → About (версия n8n) и логи контейнера: чаще всего причина — недоступная peer-зависимость n8n-workflow (Вариант Б, шаг 3).

Лицензия

MIT