Ваш браузер устарел. Рекомендуем обновить его до последней версии.

Итоговый проектный документ, который объединяет все технологические и архитектурные требования:
РЕД ОС 8, платформа виртуализации zVirt (кластер из двух серверов на базе 2×Xeon Silver 4314 / 384 ГБ ОЗУ), оркестрация через Deckhouse Kubernetes Platform, полная интеграция с 1С:Документооборот 2.0 и Битрикс24 Энтерпрайз, а также жёсткое требование физической изоляции от интернета (Air Gap).

Документ построен как пошаговая дорожная карта из семи фаз – от подготовки артефактов до ввода системы в постоянную эксплуатацию с возможностью горизонтального масштабирования.

Справочно:  рекомендуется также для ознакомления Сценарий: развёртывание собственными силами без внешних компетенций

 

Фаза 0: Подготовка Jump Station и сбор артефактов

Цель: В условиях полной изоляции сформировать проверенный набор файлов (артефактов), который будет перенесён в закрытый контур на отчуждaемом носителе.

Терминология:

  • Jump Station: Временная машина (РЕД ОС 8) с доступом в интернет для загрузки всех компонентов.

  • Air Gap: Физический барьер, исключающий любое сетевое взаимодействие с внешним миром.

  • Podman: Штатный инструмент управления контейнерами в РЕД ОС 8, эмулирующий Docker CLI.

Инструкция

  1. Разверните Jump Station на отдельном ПК с РЕД ОС 8 и временным доступом в интернет.

  2. Загрузите RPM-пакеты Podman и сопутствующих утилит для офлайн-установки:
    sudo dnf install --downloadonly --downloaddir=./offline_rpms podman podman-docker skopeo buildah

  3. Скачайте дистрибутивы и инструменты для будущей инфраструктуры:

    • zVirt – с официального сайта orion-soft.ru (необходима учётная запись).

    • Deckhouse CLI (d8) – GitHub Releases.

    • Дистрибутив Deckhouse для Air-Gap – согласно официальной документации Deckhouse (образ виртуальной машины и контейнеры).

  4. Загрузите языковые модели:

  5. Создайте офлайн-репозиторий Python‑пакетов:
    pip download -r requirements.txt -d ./offline_pkgs
    (файл requirements.txt должен содержать fastapi, uvicorn, langchain, langchain-community, qdrant-client, sentence-transformers, pypdf, python-docx, pytesseract, Pillow).

  6. Загрузите Tesseract OCR с языковыми пакетами (rus, eng).

  7. Сохраните необходимые контейнерные образы с помощью Podman:

    bash
    podman pull qdrant/qdrant
podman pull docker.io/ollama/ollama:latest
podman save qdrant/qdrant -o qdrant.tar
podman save docker.io/ollama/ollama:latest -o ollama.tar

  8. Проверьте все файлы антивирусом, запишите на внешний HDD/SSD и оформите ввод в закрытый контур согласно регламенту СБ.

✅ Контрольная точка: Все артефакты собраны и готовы к переносу.

Фаза 1: Отказоустойчивый фундамент – кластер zVirt и Deckhouse

Цель: Построить масштабируемую и отказоустойчивую платформу на базе двух физических серверов, которая станет основой для всех компонентов ИИ-агента.

Терминология:

  • zVirt Hypervisor (KVM): Платформа виртуализации, обеспечивающая запуск изолированных ВМ на каждом хосте.

  • Hosted Engine: Режим высокой доступности управления кластером – управляющая ВМ автоматически перезапускается на другом хосте при отказе.

  • Deckhouse Kubernetes Platform: Российская Enterprise-платформа для управления контейнерами, работающая на основе Kubernetes, с собственными операторами, автоматизирующими обновления и настройку.

  • Pod (под): Минимальная развёртываемая единица в Kubernetes, в которой запускается один или несколько контейнеров.

Инструкция

  1. Установка zVirt на «голое железо»:
    На обоих серверах (2×Xeon 4314, 384 ГБ) установите гипервизор zVirt.

  2. Создание кластера высокой доступности:
    Через консоль администратора zVirt объедините оба хоста в кластер, настройте Hosted Engine для автоматического восстановления управления.

  3. Развёртывание управляющей ВМ Deckhouse:

    • Создайте в zVirt виртуальную машину с РЕД ОС 8. Выделите ей, например, 8 vCPU и 32 ГБ RAM.

    • Установите на неё Podman из ранее скачанных RPM, загрузите сохранённые контейнеры и дистрибутив Deckhouse.

    • С помощью утилиты d8 разверните Deckhouse в offline-режиме, следуя документации для Air-Gap.

  4. Подготовка рабочих узлов (worker nodes):

    • Создайте ещё 2–3 виртуальные машины с РЕД ОС 8 (рабочие узлы будущего Kubernetes-кластера). Распределите между ними оставшиеся ресурсы CPU и RAM, например:

      • worker-ai – 32 vCPU / 128 ГБ RAM (для запуска LLM и RAG-сервисов).

      • worker-data – 16 vCPU / 96 ГБ RAM (для Qdrant и ETL-воркеров).

    • Подключите эти ВМ к кластеру Deckhouse как узлы (с помощью команды d8 node add).

  5. Настройка базовых модулей Deckhouse:

    • Включите модули мониторинга (monitoring), логирования (logging), ingress-контроллера (nginx-ingress) для будущего UI.

✅ Контрольная точка: Кластер zVirt и работающий Kubernetes (через Deckhouse) готовы к приёму полезной нагрузки. Все рабочие узлы зарегистрированы.

Фаза 2: Базовая платформа ИИ (Inference Server) на Deckhouse

Цель: Развернуть Ollama как масштабируемый сервис в Kubernetes, обеспечив стабильный API для генерации ответов LLM.

Терминология:

  • Deployment: Ресурс Kubernetes, описывающий желаемое состояние реплик (экземпляров) приложения.

  • Horizontal Pod Autoscaler (HPA): Механизм автоматического увеличения/уменьшения количества реплик в зависимости от загрузки (CPU/память).

  • GGUF: Формат квантованных моделей, оптимизированный для CPU-инференса.

Инструкция

  1. Загрузка образа Ollama в локальный реестр:
    На управляющей ВМ Deckhouse командой podman load < ollama.tar загрузите образ, затем запушьте его во встроенный локальный реестр Deckhouse.

  2. Создание Persistent Volume для моделей:
    Опишите PersistentVolume и PersistentVolumeClaim, которые будут хранить скачанные модели на быстром хранилище (SSD), доступном всем узлам.

  3. Импорт модели:
    Временно запустите Pod с Ollama в интерактивном режиме, скопируйте GGUF-файл модели и Modelfile, создайте модель командой ollama create company-model -f /models/Modelfile. После этого модель окажется на Persistent Volume.

  4. Создание Deployment для Ollama:
    Опишите манифест, в котором Pod монтирует Persistent Volume с моделями и запускает ollama serve. Укажите replicas: 2 (по одному на каждом мощном узле).

  5. Настройка HPA:
    Для быстрого реагирования на всплеск запросов настройте автомасштабирование по загрузке CPU: минимальное число реплик – 2, максимальное – 4.

  6. Проверка работы:
    Через временный Pod отправьте тестовый запрос к сервису Ollama:

    bash
    curl http://ollama-service:11434/api/generate -d '{"model":"company-model","prompt":"Тест","stream":false}'

✅ Контрольная точка: Ollama работает как отказоустойчивый сервис Kubernetes, модель загружена и отвечает со скоростью 5–20 токенов/с.

Фаза 3: Интеграционный слой и векторное хранилище (Qdrant + RAG Backend)

Цель: Развернуть векторную базу данных Qdrant и микросервис на FastAPI, который будет преобразовывать запросы пользователей в векторное представление и выполнять семантический поиск.

Терминология:

  • Embedding: Векторная проекция смысла текста. Сравнение векторов (косинусное сходство) определяет релевантность документов.

  • Qdrant Operator: Специализированный оператор Kubernetes, автоматизирующий развёртывание, масштабирование и резервное копирование кластера Qdrant.

  • Payload: Метаданные, хранимые вместе с вектором в Qdrant (имя файла, дата, гриф доступа).

Инструкция

  1. Установка Qdrant через Operator:
    В Deckhouse добавьте репозиторий Helm-чартов Qdrant и настройте кастомный ресурс QdrantCluster. Укажите шардирование и репликацию для высокой доступности.

  2. Развёртывание RAG-микросервиса (FastAPI):

    • Соберите Docker-образ с FastAPI-приложением (из скачанного wheelhouse) и загрузите в локальный реестр Deckhouse.

    • Создайте Deployment для этого сервиса. В нём будут настроены переменные окружения: QDRANT_HOST, EMBEDDINGS_MODEL_PATH.

    • Модель для эмбеддингов (multilingual-e5-large) разместите на Persistent Volume и смонтируйте в Pod.

    • Настройте HPA для автоматического масштабирования RAG-сервиса при росте числа запросов.

  3. API-маршрутизация:
    Используйте Ingress Deckhouse, чтобы открыть точку доступа http://rag.internal/query для внутреннего использования.

  4. Тестовая проверка:
    Отправьте пробный запрос, чтобы убедиться, что микросервис корректно вычисляет эмбеддинг и возвращает контекст из Qdrant (пока с тестовыми данными).

✅ Контрольная точка: Qdrant и RAG-сервис функционируют в Kubernetes, готовы к приёму реальных документов.

Фаза 4: Загрузка и обработка документов (ETL Pipeline)

Цель: Настроить регулярное извлечение документов из 1С:Документооборот и Битрикс24, их парсинг, OCR, интеллектуальную нарезку и индексацию в Qdrant.

Терминология:

  • ETL: Extract (извлечение) – Transform (преобразование) – Load (загрузка).

  • Chunking (чанкование): Разбиение документа на фрагменты по 500-1000 символов с перекрытием для сохранения контекста.

  • OCR (Tesseract): Оптическое распознавание символов для извлечения текста из сканов.

Инструкция

  1. Создание ETL-воркера как CronJob/Deployment:
    Разработайте Python-приложение, выполняющее по расписанию опрос источников. Упакуйте его в образ и разверните в кластере.

  2. Интеграция с 1С:

    • Настройте HTTP-сервис 1С (REST API) с учётными данными.

    • В воркере реализуйте вызовы для получения списка договоров, приказов и их файлов (включая вложения).

  3. Интеграция с Битрикс24:

    • Используйте REST API коробочной версии. Для работы в изолированной среде настройте локального провайдера авторизации, чтобы приложения не обращались к внешним серверам Битрикс.

    • Получайте файлы писем и загруженные документы через disk.file.get.

  4. Парсинг и OCR:

    • Для PDF с текстовым слоем – PyPDFLoader, для сканов – pdf2image + pytesseract.

    • Для DOCX – python-docx, для писем – mailparser.

    • Для корректной работы OCR убедитесь, что Tesseract и русский языковой пакет установлены в контейнере.

  5. Интеллектуальный чанкинг с метаданными:

    • RecursiveCharacterTextSplitter с параметрами chunk_size=1000, chunk_overlap=200.

    • Каждый чанк обогащается полным payload: source, date, type, access_roles (список ролей, которым разрешён доступ).

  6. Загрузка в Qdrant:

    • Чанк преобразуется в вектор эмбеддинга и сохраняется вместе с payload. За это отвечает отдельная функция, вызываемая воркером.

✅ Контрольная точка: Документы из обоих источников регулярно и корректно индексируются в Qdrant.

Фаза 5: Логика агента и безопасность (RAG Security)

Цель: Реализовать точный и безопасный ответ ассистента с учётом прав доступа пользователя.

Терминология:

  • RBAC (Role-Based Access Control): Разграничение доступа на основе ролей из Active Directory / LDAP.

  • System Prompt: Набор жёстких инструкций, управляющих поведением LLM.

  • Guardrails: Программные фильтры, предотвращающие нежелательное поведение.

Инструкция

  1. Системный промпт:
    В Modelfile или в запросе к Ollama зафиксируйте инструкцию:

    text
    Ты — ИИ-ассистент по корпоративным документам. Отвечай ТОЛЬКО на основе переданного контекста. Если информации недостаточно, пиши: «В предоставленных документах ответ не найден». Не выдумывай факты.

  2. Интеграция с LDAP:
    В RAG-микросервис добавьте функцию получения ролей текущего пользователя (через библиотеку ldap3).

  3. RBAC-фильтрация в Qdrant:
    При каждом поисковом запросе применяйте фильтр:

    python
    Filter(must=[FieldCondition(key="access_roles", match=MatchAny(any=user_roles))])

    Это гарантирует, что пользователь не получит содержимое документов, на которые у него нет прав.

  4. Полный RAG-пайплайн:

    • Получение вопроса → определение ролей → эмбеддинг запроса → поиск с фильтром в Qdrant (топ 5 чанков) → сбор контекста → отправка в Ollama с системным промптом.

    • Ответ возвращается пользователю со ссылками на исходные документы.

  5. Защита от Prompt Injection:
    Предусмотрите простые проверки (например, отклонять запросы, содержащие фразы вроде «игнорируй предыдущие инструкции»).

✅ Контрольная точка: Ассистент даёт ответы только на основе разрешённых документов, не раскрывает секретную информацию и не галлюцинирует.

Фаза 6: Пользовательский интерфейс и сбор обратной связи

Цель: Предоставить сотрудникам единое окно вопросов, интегрированное в портал, и наладить сбор данных для улучшения системы.

Терминология:

  • Streamlit (self‑hosted): Python‑фреймворк для быстрой разработки веб‑интерфейсов.

  • iFrame‑интеграция: Встраивание Streamlit-приложения прямо в страницу Битрикс24.

Инструкция

  1. Развёртывание Streamlit в Deckhouse:

    • Создайте Docker-образ с вашим Streamlit‑приложением и задеплойте его как Deployment.

    • Настройте сервис и Ingress (например, http://ai-assistant.internal).

  2. Разработка интерфейса:

    • Простое окно чата, поле ввода вопроса, отображение истории диалога.

    • При получении ответа показывать список источников с датами и именами файлов.

    • Кнопки «???? Полезно» и «???? Бесполезно» для каждого ответа.

  3. Интеграция в Битрикс24:

    • В административной панели Битрикс24 создайте страницу, содержащую iFrame с URL вашего Streamlit-сервиса.

    • Через HTTP-заголовок X-Username пробрасывайте имя пользователя для идентификации.

  4. Сохранение фидбека:

    • Обратная связь (оценка и комментарий) сохраняется в простую базу данных (CSV или локальный PostgreSQL) для последующего анализа.

✅ Контрольная точка: Пользователи общаются с ассистентом через портал, каждая оценка фиксируется.

Фаза 7: Тестирование, метрики, итерации и масштабирование

Цель: Обеспечить непрерывное улучшение качества ответов и подготовить систему к росту нагрузки без перепроектирования.

Терминология:

  • Hallucination Rate: Процент ответов с вымышленными фактами.

  • Latency (P50/P95): Время ответа, которое видит пользователь.

  • Horizontal Pod Autoscaling (HPA): Автоматическое изменение числа экземпляров сервиса в зависимости от нагрузки.

Инструкция

  1. Определение ключевых метрик:

     
    МетрикаЦелевое значениеСпособ измерения
    Hallucination Rate ≤ 5% Ручная проверка ответов
    Context Precision ≥ 90% Сравнение ответа с найденными чанками
    Latency P95 ≤ 15 секунд Логирование в Prometheus
    Пользовательская оценка ≥ 4 из 5 Фидбек-кнопки

  2. Мониторинг и оповещения:
    Используйте встроенный в Deckhouse стек (Prometheus + Grafana) для визуализации метрик. Настройте алерты на превышение порогов Latency или рост числа ошибок.

  3. Разбор ошибок и итеративное улучшение:

    • Еженедельный анализ ответов с низкой оценкой. Корректировка:

      • чанкинга – если релевантная информация теряется;

      • эмбеддингов – при низкой точности семантического поиска;

      • системного промпта – если LLM галлюцинирует.

  4. Горизонтальное масштабирование в Kubernetes:

    • RAG‑сервис: HPA по CPU автоматически увеличивает количество подов при росте запросов.

    • Ollama: добавив второй Pod на другом узле, вы удваиваете пропускную способность. Для промышленных нагрузок рассмотрите миграцию на vLLM с поддержкой параллельных запросов.

    • Qdrant: шардирование распределяет векторы по нескольким узлам, а увеличение реплик повышает доступность чтения.
      Все изменения выполняются правкой нескольких строк в манифестах и не требуют остановки системы.

  5. Дообучение модели (опционально):
    При накоплении ≥500 качественных пар «вопрос – правильный ответ» возможно файнтюнинг LLM с использованием LoRA прямо на имеющемся оборудовании (CPU‑режим через llama.cpp).

✅ Контрольная точка: Система работает стабильно, ключевые метрики достигнуты, путь масштабирования понятен и протестирован.

Итоговая архитектура (краткая визуализация)

text
[Сотрудник] → (iFrame) → [Streamlit UI] (K8s Pod)
                ↓
[Ingress Deckhouse]
       ↓
(RAG Service Pod)───→ [Embedding Model]
       │                    ↓
       │              (Qdrant Cluster)
       │                    ↑
       │             (ETL CronJob) ← (1C:Документооборот REST API)
       │                           ← (Битрикс24 REST API)
       ↓
(Ollama Pod(s))  ─── Persistent Volume (GGUF Models)
       ↓
[Ответ агента]

Все компоненты работают внутри кластера Deckhouse, развёрнутого поверх кластера zVirt на двух физических серверах. Система изначально спроектирована для горизонтального масштабирования и полностью отвечает требованиям изолированной среды.