AI on-premises

Обновлено: 08.07.2026

Добавление AI-сервисов в существующее on-premises-развертываниеДобавление AI-сервисов в существующее on-premises-развертывание

Эта инструкция предназначена только для обновления уже работающего on-premises-развертывания Timetta, в котором AI-сервисы отсутствуют.

Для новой установки используйте штатные разделы документации:

• Поставка on-premises;
• Конфигурация приложений;
• Настройка проекта Docker Compose;
• Маршрутизация сервисов Timetta по FQDN.

AI является обычной частью поставки Timetta. Отдельные ai-backend, ai-consumer, Weaviate и отдельная база данных ai не требуются.

Перед обновлениемПеред обновлением

1. Проверьте совместимость версий backend, frontend и AI-клиента.
2. Создайте резервную копию баз данных и конфигурационных файлов .env, settings.json, client-settings.json, compose.yml и proxy/nginx.conf.
3. Установите расширение pgvector для используемой версии PostgreSQL и подключите его в основной базе Timetta, указанной в ConnectionStrings:TimettaDB. Это необходимо сделать до запуска миграции новой версии backend.
4. Подготовьте адрес, идентификатор модели и API-ключ LLM-провайдера с OpenAI-совместимым API.
5. Обеспечьте доступ к registry с образами Timetta.

Образ infinity:latest-cpu-2.0.0 содержит сервер Infinity и модель intfloat/multilingual-e5-large. Модель загружается из образа локально, поэтому доступ к Hugging Face и отдельный volume для кеша модели не требуются. Для загрузки, распаковки и хранения образа предусмотрите не менее 8 ГБ свободного дискового пространства на Docker-host.

1. Добавить версии образов1. Добавить версии образов

Добавьте в .env:

AI_CLIENT_IMAGE=<ai-client-tag>
EMBEDDINGS_IMAGE_TAG=latest-cpu-2.0.0

Для production используйте согласованные в поставке фиксированные версии образов.

2. Обновить конфигурацию приложений2. Обновить конфигурацию приложений

В примерах используется домен op.timetta-test.com. Замените его на домен обновляемого экземпляра.

settings.jsonsettings.json

В корневом объекте settings.json дополните CORS и OAuth-настройки:

"AllowedCorsOrigins": "https://op.timetta-test.com,https://op.timetta-test.com:5402",
"WepAppClient": {
  "RedirectUris": "https://op.timetta-test.com,https://op.timetta-test.com/auth-callback,https://op.timetta-test.com/assets/silent-refresh.html,https://op.timetta-test.com:5401/login-successful,https://op.timetta-test.com:5402/auth-callback,https://op.timetta-test.com:5402/auth-callback.html,https://op.timetta-test.com:5402/assets/silent-refresh.html",
  "PostLogoutRedirectUris": "https://op.timetta-test.com:5401/logout-successful,https://op.timetta-test.com:5402/logout-successful",
  "AllowedCorsOrigins": "https://op.timetta-test.com,https://op.timetta-test.com:5402"
}

Сохраните существующие URI и добавьте к ним значения для AI-клиента.

В тот же корневой объект settings.json добавьте HelpSearch и AI, например после LicenseKey:

"HelpSearch": {
  "Endpoint": "https://timetta.com/api/rag/search",
  "MaxContentCharacters": 12000
},
"AI": {
  "Embeddings": {
    "Endpoint": "http://embeddings:8080",
    "ApiKey": null,
    "Model": "e5-large",
    "Dimensions": 1024
  },
  "TextCommands": [],
  "Chat": {
    "Enabled": true,
    "DefaultModelKey": "system:deepseek-v4",
    "ChatApiDefaultModelKey": "system:deepseek-v4",
    "ServicesDefaultModelKey": "system:deepseek-v4",
    "SystemProviders": [
      {
        "ProviderName": "yandex",
        "BaseUrl": "https://ai.api.cloud.yandex.net/v1",
        "ApiKey": "<api-key>",
        "Models": [
          {
            "Key": "deepseek-v4",
            "ExternalModelId": "gpt://<folder-id>/deepseek-v4-flash",
            "DisplayName": "DeepSeek V4 Flash",
            "SupportsStreaming": true,
            "SupportsTools": true,
            "SupportsVision": false
          }
        ]
      }
    ]
  }
}

Заполните TextCommands стандартными командами из статьи «Конфигурация приложений» либо оставьте пустой массив, если команды обработки текста не требуются.

client-settings.jsonclient-settings.json

Добавьте aiBotLoader в существующий корневой объект, поставив запятую после предыдущего свойства:

{
  "api": {
    "url": "https://op.timetta-test.com:5400"
  },
  "passport": {
    "url": "https://op.timetta-test.com:5401"
  },
  "websocket": {
    "url": "https://op.timetta-test.com:5404"
  },
  "aiBotLoader": "https://op.timetta-test.com:5402/loader.js"
}

ai-client-settings.jsonai-client-settings.json

Создайте рядом с compose.yml новый файл ai-client-settings.json:

{
  "passportUrl": "https://op.timetta-test.com:5401",
  "apiUrl": "https://op.timetta-test.com:5400",
  "aiBotUrl": "https://op.timetta-test.com:5402",
  "webSocketUrl": "https://op.timetta-test.com:5404",
  "apiTimettaUrl": "https://op.timetta-test.com:5400",
  "baseAppUrl": "https://op.timetta-test.com"
}

При AI:Chat:Enabled = true backend не запустится без системного провайдера, API-ключа и корректной модели по умолчанию.

3. Обновить Docker Compose3. Обновить Docker Compose

В существующий раздел configs файла compose.yml добавьте:

configs:
  ai_client_settings:
    file: ./ai-client-settings.json

В существующий раздел services добавьте сервис embeddings:

services:
  embeddings:
    container_name: embeddings
    image: cr.yandex/crpr8bvek949tq2fuqkf/infinity:${EMBEDDINGS_IMAGE_TAG}
    restart: always
    environment:
      OMP_NUM_THREADS: "4"
      MKL_NUM_THREADS: "4"
      OPENBLAS_NUM_THREADS: "4"
      NUMEXPR_NUM_THREADS: "4"
      OMP_WAIT_POLICY: ACTIVE
      KMP_BLOCKTIME: "0"
    expose:
      - "8080"
    command:
      - v2
      - --engine
      - torch
      - --model-id
      - /opt/models/multilingual-e5-large
      - --served-model-name
      - e5-large
      - --port
      - "8080"
      - --batch-size
      - "4"
      - --pooling-method
      - mean
      - --dtype
      - float32
    deploy:
      resources:
        limits:
          cpus: "4"
          memory: 8G
        reservations:
          cpus: "4"
          memory: 8G
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8080/models > /dev/null"]
      interval: 30s
      timeout: 10s
      retries: 20
      start_period: 5m

Для CPU-конфигурации embeddings требуется не менее 4 vCPU и 8 ГБ RAM. В примере эти значения установлены одновременно как reservation и limit.

В тот же раздел services добавьте AI-клиент:

services:
  ai-bot:
    container_name: ai-bot
    image: cr.yandex/crpr8bvek949tq2fuqkf/ai-client-host:${AI_CLIENT_IMAGE}
    restart: always
    configs:
      - source: ai_client_settings
        target: /usr/share/nginx/html/config.json
      - source: ai_client_settings
        target: /usr/share/nginx/html/assets/config.json

В существующем сервисе nginx-proxy добавьте порт и зависимость:

services:
  nginx-proxy:
    ports:
      - "5402:5402"
    depends_on:
      - ai-bot

Не заменяйте приведенными фрагментами целиком существующие разделы configs, services, ports и depends_on: добавьте в них только новые элементы.

Порт embeddings 8080 не публикуется на хосте. Backend обращается к сервису по адресу http://embeddings:8080 внутри Docker-сети.

4. Обновить маршрутизацию4. Обновить маршрутизацию

Выберите используемую в инсталляции схему.

Один домен и разные портыОдин домен и разные порты

Добавьте в proxy/nginx.conf:

server {
    listen 5402 ssl;
    server_name _;

    add_header Access-Control-Allow-Origin "https://op.timetta-test.com" always;
    add_header Vary "Origin" always;

    location / {
        proxy_pass http://ai-bot;
    }
}

Порт 5402 уже добавлен в пример nginx-proxy выше. Используйте адрес https://op.timetta-test.com:5402 в клиентских настройках, CORS и OAuth URI.

Отдельные FQDN через порт 443Отдельные FQDN через порт 443

В соответствии со статьей «Маршрутизация сервисов Timetta по FQDN»:

• создайте DNS-запись, например ai-timetta.domain.com;
• добавьте AI-домен в SSL-сертификат, CORS и OAuth URI;
• добавьте в proxy/nginx.conf виртуальный хост:

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name ai-timetta.domain.com;

    add_header Access-Control-Allow-Origin "https://timetta.domain.com" always;
    add_header Vary "Origin" always;

    location / {
        proxy_pass http://ai-bot:80;
    }
}

Для FQDN-схемы укажите адреса без нестандартных портов в client-settings.json и ai-client-settings.json, как описано в статье «Маршрутизация сервисов Timetta по FQDN».

При маршрутизации по FQDN отдельный внешний порт 5402 не требуется.

5. Запустить сервисы и применить обновление БД5. Запустить сервисы и применить обновление БД

Проверьте итоговую конфигурацию и загрузите новые образы:

docker compose config
docker compose pull
docker compose up -d --build --force-recreate

Проверьте состояние контейнеров:

docker compose ps
docker compose logs --tail=200 api ai-bot embeddings

Дождитесь состояния healthy у сервиса embeddings. Сервер Infinity и модель E5 уже находятся в образе и запускаются без обращения к внешнему хранилищу моделей.

После обновления backend выполните штатные миграции обновления Timetta. Они применят к существующей базе только недостающие изменения схемы. Если ваш процесс развертывания выполняет миграции автоматически, отдельно запускать их не требуется.

Для схемы с одним доменом и разными портами ручной запуск миграций доступен по адресу:

https://<domain>:5400/migrate

Миграции backend создают необходимые таблицы, поля vector(1024) и индексы в основной базе Timetta. Создавать таблицы вручную не требуется.

6. Проверить результат6. Проверить результат

Проверьте доступность AI-клиента. Для схемы с одним доменом:

https://<domain>:5402/loader.js
https://<domain>:5402/assets/config.json

Проверьте embeddings внутри контейнера:

docker compose exec -T embeddings curl -fsS http://127.0.0.1:8080/models

После входа в Timetta проверьте:

• открытие AI-ассистента;
• отправку сообщения и получение потокового ответа;
• выполнение одной из команд обработки текста;
• семантический поиск по внутренним данным и Wiki.

Фоновая задача BackfillSemanticSearchIndex заполняет семантический индекс для ранее созданных данных. По умолчанию она запускается ежедневно в 04:00 UTC; при необходимости ее можно запустить вручную через интерфейс планировщика.

Внешние подключенияВнешние подключения

• Для генерации ответов backend должен иметь доступ к настроенному LLM-провайдеру.
• Для поиска по официальной справке требуется исходящий HTTPS-доступ к https://timetta.com/api/rag/search.