Туннели Ollama — документация Entity Enricher

Туннели Ollama

Подключите локальный Ollama на вашем ноутбуке к Entity Enricher одной командой. Используйте уже установленные модели, оставляйте определённые данные на своём компьютере и мгновенно отзывайте доступ — всё через одно исходящее HTTPS-соединение.

            Production (Hetzner)          Your Laptop / your server
        ┌─────────────────────────┐         ┌────────────────────┐
        │  Org enrichment         │         │  ee-tunnel CLI     │
        │     │                   │         │     │              │
        │     ▼                   │         │     ▼              │
        │  Ollama provider URL:   │         │  Ollama :11434     │
        │  http://ollama.<org>    │         │  ┌──────────────┐  │
        │       .tunnel/v1/chat   │         │  │ qwen3:36b    │  │
        │     │                   │         │  │ llama3:70b   │  │
        │     ▼                   │         │  │ ...          │  │
        │  WebSocket bridge       │◀───────▶│  └──────────────┘  │
        └─────────────────────────┘         └────────────────────┘
                                  one outbound :443/wss connection

Синтетическое имя хоста ollama.<org-slug>.tunnel никогда не разрешается через DNS. Специальный транспорт в процессе Entity Enricher перехватывает запросы к *.tunnel и направляет их через соответствующий активный WebSocket.

Зачем использовать туннель?

Используйте модели, которые у вас уже есть

Запускайте обогащения на моделях с открытыми весами, уже загруженных на вашем ноутбуке (Llama 3, Qwen, DeepSeek, Mistral, …), без их повторной загрузки на сервере.

Храните некоторые входные данные на своём компьютере

Для конфиденциальных промптов направляйте конкретные обогащения через собственный GPU. Платформа по-прежнему фиксирует стоимость, токены и метаданные — локальным остаётся только сам вывод модели.

Попробуйте новую модель за 30 секунд

Загрузите модель командой `ollama pull` на своём ноутбуке, нажмите «Найти модели», и она появится в селекторе Entity Enricher с реальной длиной контекста и возможностями.

Разгрузка пиковых нагрузок

Когда размещённый провайдер ограничивает частоту ваших запросов, переключитесь на локальную модель через туннель до конца пакета.

Быстрый старт

Две команды на вашем ноутбуке, один клик в браузере. Весь процесс занимает около минуты.

1
Создать туннель в интерфейсе
Откройте API Keys → Ollama Tunnels и нажмите New Ollama Tunnel. Введите метку, чтобы позже узнать это устройство (например, «MacBook Энтони»).
[Заглушка скриншота — вкладка Tunnels с выделенной кнопкой «New Ollama Tunnel»]
2
Установите CLI на ваш ноутбук
Вставьте это в терминал. Скрипт проверяет подпись cosign перед установкой.
```
curl -fsSL https://entityenricher.ai/install.sh | sh
```
Установщик выводит, что он собирается сделать (URL загрузки, подпись, путь установки), и делает паузу в 5 секунд, чтобы у вас было окно для нажатия Ctrl+C. Исходный код находится по адресу TOT-Concept/ee-tunnel (MIT). Пользователи Windows используют install.ps1 вместо этого.
3
Свяжите через браузер
Запустите ee-tunnel pair. В браузере откроется вкладка /tunnel/connect с кодом из 6 символов. Подтвердите название устройства и нажмите Connect.
```
ee-tunnel pair --server https://entityenricher.ai

Open this URL in your browser to confirm pairing:
   https://entityenricher.ai/tunnel/connect?code=9KV-DU6

  Code: 9KV-DU6

Waiting for confirmation...
```
[Заглушка скриншота — страница подтверждения /tunnel/connect с кодом устройства]
Вы никогда не копируете токен вручную. Браузер видит только метаданные tunnel; CLI получает свои учётные данные по собственному каналу опроса.
4
Подключение и обнаружение моделей
Запустите ee-tunnel. Индикатор статуса на вкладке Tunnels за секунды переключится на Connected. Затем нажмите Discover Models у провайдера Ollama в разделе Models & Pricing, чтобы автоматически импортировать все локально установленные чат-модели.
[Заглушка видео — Discover Models загружает 4 локальные модели Ollama в платформу]

Как работает связывание

Связывание использует поток device-code в стиле OAuth (по образцу RFC 8628). Пользователь вводит короткий код в браузере вместо копирования токена. Браузер видит только метаданные туннеля; CLI получает свой refresh-токен напрямую по собственному каналу опроса — одноразовое использование.

 laptop                  entity-enricher                  browser
   │                          │                              │
   │── ee-tunnel pair ──────▶ │                              │
   │   --server URL           │                              │
   │                          │                              │
   │  POST /api/tunnel/       │                              │
   │       device-code        │                              │
   │ ───────────────────────▶ │                              │
   │ ◀── { device_code,       │                              │
   │     user_code='9KV-DU6', │                              │
   │     verification_uri }   │                              │
   │                          │                              │
   │  prints URL, opens       │                              │
   │  browser at /tunnel/     │                              │
   │  connect?code=… ──────────────────────────────────────▶│
   │                          │                              │
   │                          │  POST /api/tunnel/confirm/   │
   │                          │       {user_code}            │
   │                          │  body: { label }             │
   │                          │  Authorization: Bearer       │
   │                          │   <user JWT, role=owner>     │
   │                          │ ◀──────────────────────────── │
   │                          │  • create tunnel_credentials │
   │                          │  • mark device_code complete │
   │                          │    with refresh_token        │
   │                          │ ────────────────────────────▶│
   │                          │  200 { tunnel metadata }     │
   │                          │                              │
   │  POST /api/tunnel/poll   │                              │
   │ ───────────────────────▶ │                              │
   │ ◀── { status:'ok',       │                              │
   │     refresh_token,       │                              │
   │     server_url,          │                              │
   │     tunnel_id }          │                              │
   │                          │                              │
   │  persist token mode 0600 │                              │
   │  ✓ Paired                │                              │

Как запрос проходит через туннель

После подключения ваш туннелированный Ollama становится для остальной части платформы обычным LLM-провайдером. Мультиэкспертиза, слияние, пакеты — всё работает без изменений.

  enrichment job
       │
       ▼
  agent_factory  →  Ollama provider, base_url=http://ollama.acme.tunnel
       │
       ▼
  custom httpx transport  ← intercepts *.tunnel hosts
       │
       ▼
  TunnelSession (one per laptop)
       │ frames request: { id, method, path, headers, body_b64 }
       ▼
  WebSocket  ──────────────────────▶  ee-tunnel CLI
                                          │
                                          ▼
                                     localhost:11434
                                     (your local Ollama)
                                          │
                          response_start, response_chunk, ...
       ◀──────────────────────────────────┘
       │
       ▼
  pydantic_ai consumes streaming body  →  enrichment record

Мультиплексирование

Несколько выполняющихся обогащений используют один WebSocket туннеля. Каждый запрос получает UUID; кадры демультиплексируются по id на обеих сторонах, поэтому параллельные вызовы (например, из нескольких областей экспертизы) работают естественно.

Потоковые ответы (stream=true в Ollama) передаются как последовательность кадров response_chunk, поэтому обновления интерфейса по токенам остаются инкрементальными даже через туннель.

Жизненный цикл

Создать

Владелец организации нажимает «Новый туннель Ollama», вводит название и подтверждает. Платформа выделяет учётные данные.

Связать

На вашем ноутбуке запустите установщик в одну строку и `ee-tunnel pair`. Откроется вкладка браузера — подтвердите тем же аккаунтом Entity Enricher.

Подключить

Запустите `ee-tunnel`. CLI открывает один исходящий HTTPS WebSocket. Новый провайдер появляется в вашем списке моделей за считанные секунды.

Использовать

Нажмите «Найти модели» — каждая модель в вашем локальном Ollama автоматически импортируется с реальной длиной контекста и возможностями. Обогащайте как обычно.

Отозвать

Один клик в интерфейсе разрывает WebSocket и немедленно аннулирует учётные данные.

Безопасность

Туннель был разработан так, чтобы добавлять как можно меньшую поверхность атаки. В более ранней версии этой функции использовался публичный SSH-сервер на новом порту; мы заменили его внутрипроцессным мультиплексором WebSocket, чтобы полностью устранить поверхность атаки SSH.

Нет новых публичных портов

Всё проходит через существующий ingress :443 — тот же TLS-эндпоинт, что и у веб-приложения. Никакого SSH-сервера, никакого открытого порта Ollama.

Только исходящий

CLI инициирует WebSocket. Ваш ноутбук никогда не принимает входящие подключения — настройки брандмауэра вашей домашней сети менять не нужно.

Ограничено организацией

Туннель привязан к одной организации. Другие арендаторы платформы не могут видеть, выбирать или вызывать его. Системные администраторы по замыслу имеют видимость между организациями.

Мгновенный отзыв

Отзыв удаляет учётные данные из базы данных. Следующий запрос завершается ошибкой 401. Активный WebSocket отключается в течение ~1 секунды.

Никаких скопированных секретов

Процесс OAuth в браузере обрабатывает учётные данные от начала до конца. Браузер никогда не видит ваш токен обновления; CLI получает его напрямую через свой канал опроса.

Квоты и лимиты кадров

5 активных туннелей на организацию по умолчанию; ограничение входящего WebSocket-фрейма 16 МБ; структурированные ошибки 402 при превышении квоты.

Защита от SSRF. Функция туннеля также закрывает существовавшую ранее уязвимость: поле specific_endpoint у провайдеров Ollama теперь проверяется по регулярному выражению из списка разрешённых, поэтому приватные IP-адреса, loopback и имена сервисов Docker compose больше не могут использоваться как URL провайдера.

Справочник по CLI

Команда	Что это делает
ee-tunnel pair --server URL	Связка через браузер и OAuth. Автоматически открывает URL для проверки.
ee-tunnel pair --server URL <token>	Ручное сопряжение с токеном обновления, скопированным из интерфейса (запасной вариант для сред без графического интерфейса).
ee-tunnel	Подключайтесь и работайте. Переподключение с экспоненциальной задержкой (1 с → 30 с) при временных обрывах.
ee-tunnel status	Показать состояние сопряжения, URL сервера, настроенный URL Ollama, метку.
ee-tunnel disconnect	Забыть локальные учётные данные. Не отзывает их на стороне сервера; для этого используйте интерфейс.
ee-tunnel version	Версия для печати.

Пользовательский URL для Ollama

Если ваш Ollama слушает другой порт, задайте EE_TUNNEL_OLLAMA_URL или передайте --ollama URL при сопряжении.

Где хранятся файлы

macOS · ~/Library/Application Support/ee-tunnel/
Linux · ~/.config/ee-tunnel/
Windows · %APPDATA%\ee-tunnel\

Лимиты и тайминг

Активные tunnel на организацию	5 (по умолчанию)
TTL токена обновления	365 дней
TTL токена доступа	15 минут
TTL связывания	10 минут
Макс. размер входящего WebSocket-кадра	16 МБ
Размер исходящего фрагмента (CLI)	16 КБ
Интервал heartbeat	30 секунд

Частые вопросы

Доступен ли мой Ollama из интернета?

Нет. CLI инициирует исходящее WebSocket-соединение. Ваш ноутбук никогда не принимает входящие подключения, а порт Ollama остаётся привязанным к localhost.

Что происходит, когда мой ноутбук переходит в спящий режим?

CLI корректно завершает работу при отключении. Возобновление работы ноутбука и повторный запуск ee-tunnel восстанавливает подключение с существующими учётными данными. Обогащения, выполняемые при отключённом туннеле, завершаются с чистой ошибкой ConnectError.

Могут ли другие организации использовать мой туннель?

Нет. Каждый туннель привязан к одной организации. Другие арендаторы платформы не могут его видеть, выбирать или вызывать. Системные администраторы видят все туннели по замыслу (как и глобальные ключи API).

Работает ли это за корпоративным брандмауэром?

Почти всегда — нужен только исходящий :443. Тот же путь, что использует веб-приложение.

Как обновить учётные данные?

Нажмите «Сменить токен» на вкладке «Туннели». Старый токен аннулируется немедленно; в окне отобразится новая команда сопряжения для вашего ноутбука.

Можно ли использовать это без Ollama?

Да — CLI пересылает произвольный HTTP. Укажите в EE_TUNNEL_OLLAMA_URL любую локальную конечную точку, совместимую с OpenAI. Подойдёт всё, что поддерживает /v1/chat/completions или /api/tags от Ollama.

Открытый исходный код

CLI и установщик распространяются по лицензии MIT и находятся в публичном репозитории, чтобы каждый мог проверить, что запускается на его машине.

Источник: github.com/TOT-Concept/ee-tunnel

Релизы: github.com/TOT-Concept/ee-tunnel/releases — каждый бинарный файл подписывается с помощью cosign перед публикацией.

Проверьте установщик: curl -fsSL https://entityenricher.ai/install.sh | less