Итоговый проектный документ, который объединяет все технологические и архитектурные требования:
РЕД ОС 8, платформа виртуализации zVirt (кластер из двух серверов на базе 2×Xeon Silver 4314 / 384 ГБ ОЗУ), оркестрация через Deckhouse Kubernetes Platform, полная интеграция с 1С:Документооборот 2.0 и Битрикс24 Энтерпрайз, а также жёсткое требование физической изоляции от интернета (Air Gap).
Документ построен как пошаговая дорожная карта из семи фаз – от подготовки артефактов до ввода системы в постоянную эксплуатацию с возможностью горизонтального масштабирования.
Справочно: рекомендуется также для ознакомления Сценарий: развёртывание собственными силами без внешних компетенций
Цель: В условиях полной изоляции сформировать проверенный набор файлов (артефактов), который будет перенесён в закрытый контур на отчуждaемом носителе.
Терминология:
Jump Station: Временная машина (РЕД ОС 8) с доступом в интернет для загрузки всех компонентов.
Air Gap: Физический барьер, исключающий любое сетевое взаимодействие с внешним миром.
Podman: Штатный инструмент управления контейнерами в РЕД ОС 8, эмулирующий Docker CLI.
Разверните Jump Station на отдельном ПК с РЕД ОС 8 и временным доступом в интернет.
Загрузите RPM-пакеты Podman и сопутствующих утилит для офлайн-установки:sudo dnf install --downloadonly --downloaddir=./offline_rpms podman podman-docker skopeo buildah
Скачайте дистрибутивы и инструменты для будущей инфраструктуры:
zVirt – с официального сайта orion-soft.ru (необходима учётная запись).
Deckhouse CLI (d8) – GitHub Releases.
Дистрибутив Deckhouse для Air-Gap – согласно официальной документации Deckhouse (образ виртуальной машины и контейнеры).
Загрузите языковые модели:
LLM (CPU‑оптимизированная, GGUF):IlyaGusev/saiga_mistral_7b_gguf (квантование Q5_K_M или Q6_K)
https://huggingface.co/IlyaGusev/saiga_mistral_7b_gguf
Модель для эмбеддингов:intfloat/multilingual-e5-large
https://huggingface.co/intfloat/multilingual-e5-large
Создайте офлайн-репозиторий 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).
Загрузите Tesseract OCR с языковыми пакетами (rus, eng).
Сохраните необходимые контейнерные образы с помощью Podman:
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
Проверьте все файлы антивирусом, запишите на внешний HDD/SSD и оформите ввод в закрытый контур согласно регламенту СБ.
✅ Контрольная точка: Все артефакты собраны и готовы к переносу.
Цель: Построить масштабируемую и отказоустойчивую платформу на базе двух физических серверов, которая станет основой для всех компонентов ИИ-агента.
Терминология:
zVirt Hypervisor (KVM): Платформа виртуализации, обеспечивающая запуск изолированных ВМ на каждом хосте.
Hosted Engine: Режим высокой доступности управления кластером – управляющая ВМ автоматически перезапускается на другом хосте при отказе.
Deckhouse Kubernetes Platform: Российская Enterprise-платформа для управления контейнерами, работающая на основе Kubernetes, с собственными операторами, автоматизирующими обновления и настройку.
Pod (под): Минимальная развёртываемая единица в Kubernetes, в которой запускается один или несколько контейнеров.
Установка zVirt на «голое железо»:
На обоих серверах (2×Xeon 4314, 384 ГБ) установите гипервизор zVirt.
Создание кластера высокой доступности:
Через консоль администратора zVirt объедините оба хоста в кластер, настройте Hosted Engine для автоматического восстановления управления.
Развёртывание управляющей ВМ Deckhouse:
Создайте в zVirt виртуальную машину с РЕД ОС 8. Выделите ей, например, 8 vCPU и 32 ГБ RAM.
Установите на неё Podman из ранее скачанных RPM, загрузите сохранённые контейнеры и дистрибутив Deckhouse.
С помощью утилиты d8 разверните Deckhouse в offline-режиме, следуя документации для Air-Gap.
Подготовка рабочих узлов (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).
Настройка базовых модулей Deckhouse:
Включите модули мониторинга (monitoring), логирования (logging), ingress-контроллера (nginx-ingress) для будущего UI.
✅ Контрольная точка: Кластер zVirt и работающий Kubernetes (через Deckhouse) готовы к приёму полезной нагрузки. Все рабочие узлы зарегистрированы.
Цель: Развернуть Ollama как масштабируемый сервис в Kubernetes, обеспечив стабильный API для генерации ответов LLM.
Терминология:
Deployment: Ресурс Kubernetes, описывающий желаемое состояние реплик (экземпляров) приложения.
Horizontal Pod Autoscaler (HPA): Механизм автоматического увеличения/уменьшения количества реплик в зависимости от загрузки (CPU/память).
GGUF: Формат квантованных моделей, оптимизированный для CPU-инференса.
Загрузка образа Ollama в локальный реестр:
На управляющей ВМ Deckhouse командой podman load < ollama.tar загрузите образ, затем запушьте его во встроенный локальный реестр Deckhouse.
Создание Persistent Volume для моделей:
Опишите PersistentVolume и PersistentVolumeClaim, которые будут хранить скачанные модели на быстром хранилище (SSD), доступном всем узлам.
Импорт модели:
Временно запустите Pod с Ollama в интерактивном режиме, скопируйте GGUF-файл модели и Modelfile, создайте модель командой ollama create company-model -f /models/Modelfile. После этого модель окажется на Persistent Volume.
Создание Deployment для Ollama:
Опишите манифест, в котором Pod монтирует Persistent Volume с моделями и запускает ollama serve. Укажите replicas: 2 (по одному на каждом мощном узле).
Настройка HPA:
Для быстрого реагирования на всплеск запросов настройте автомасштабирование по загрузке CPU: минимальное число реплик – 2, максимальное – 4.
Проверка работы:
Через временный Pod отправьте тестовый запрос к сервису Ollama:
curl http://ollama-service:11434/api/generate -d '{"model":"company-model","prompt":"Тест","stream":false}'
✅ Контрольная точка: Ollama работает как отказоустойчивый сервис Kubernetes, модель загружена и отвечает со скоростью 5–20 токенов/с.
Цель: Развернуть векторную базу данных Qdrant и микросервис на FastAPI, который будет преобразовывать запросы пользователей в векторное представление и выполнять семантический поиск.
Терминология:
Embedding: Векторная проекция смысла текста. Сравнение векторов (косинусное сходство) определяет релевантность документов.
Qdrant Operator: Специализированный оператор Kubernetes, автоматизирующий развёртывание, масштабирование и резервное копирование кластера Qdrant.
Payload: Метаданные, хранимые вместе с вектором в Qdrant (имя файла, дата, гриф доступа).
Установка Qdrant через Operator:
В Deckhouse добавьте репозиторий Helm-чартов Qdrant и настройте кастомный ресурс QdrantCluster. Укажите шардирование и репликацию для высокой доступности.
Развёртывание RAG-микросервиса (FastAPI):
Соберите Docker-образ с FastAPI-приложением (из скачанного wheelhouse) и загрузите в локальный реестр Deckhouse.
Создайте Deployment для этого сервиса. В нём будут настроены переменные окружения: QDRANT_HOST, EMBEDDINGS_MODEL_PATH.
Модель для эмбеддингов (multilingual-e5-large) разместите на Persistent Volume и смонтируйте в Pod.
Настройте HPA для автоматического масштабирования RAG-сервиса при росте числа запросов.
API-маршрутизация:
Используйте Ingress Deckhouse, чтобы открыть точку доступа http://rag.internal/query для внутреннего использования.
Тестовая проверка:
Отправьте пробный запрос, чтобы убедиться, что микросервис корректно вычисляет эмбеддинг и возвращает контекст из Qdrant (пока с тестовыми данными).
✅ Контрольная точка: Qdrant и RAG-сервис функционируют в Kubernetes, готовы к приёму реальных документов.
Цель: Настроить регулярное извлечение документов из 1С:Документооборот и Битрикс24, их парсинг, OCR, интеллектуальную нарезку и индексацию в Qdrant.
Терминология:
ETL: Extract (извлечение) – Transform (преобразование) – Load (загрузка).
Chunking (чанкование): Разбиение документа на фрагменты по 500-1000 символов с перекрытием для сохранения контекста.
OCR (Tesseract): Оптическое распознавание символов для извлечения текста из сканов.
Создание ETL-воркера как CronJob/Deployment:
Разработайте Python-приложение, выполняющее по расписанию опрос источников. Упакуйте его в образ и разверните в кластере.
Интеграция с 1С:
Настройте HTTP-сервис 1С (REST API) с учётными данными.
В воркере реализуйте вызовы для получения списка договоров, приказов и их файлов (включая вложения).
Интеграция с Битрикс24:
Используйте REST API коробочной версии. Для работы в изолированной среде настройте локального провайдера авторизации, чтобы приложения не обращались к внешним серверам Битрикс.
Получайте файлы писем и загруженные документы через disk.file.get.
Парсинг и OCR:
Для PDF с текстовым слоем – PyPDFLoader, для сканов – pdf2image + pytesseract.
Для DOCX – python-docx, для писем – mailparser.
Для корректной работы OCR убедитесь, что Tesseract и русский языковой пакет установлены в контейнере.
Интеллектуальный чанкинг с метаданными:
RecursiveCharacterTextSplitter с параметрами chunk_size=1000, chunk_overlap=200.
Каждый чанк обогащается полным payload: source, date, type, access_roles (список ролей, которым разрешён доступ).
Загрузка в Qdrant:
Чанк преобразуется в вектор эмбеддинга и сохраняется вместе с payload. За это отвечает отдельная функция, вызываемая воркером.
✅ Контрольная точка: Документы из обоих источников регулярно и корректно индексируются в Qdrant.
Цель: Реализовать точный и безопасный ответ ассистента с учётом прав доступа пользователя.
Терминология:
RBAC (Role-Based Access Control): Разграничение доступа на основе ролей из Active Directory / LDAP.
System Prompt: Набор жёстких инструкций, управляющих поведением LLM.
Guardrails: Программные фильтры, предотвращающие нежелательное поведение.
Системный промпт:
В Modelfile или в запросе к Ollama зафиксируйте инструкцию:
Ты — ИИ-ассистент по корпоративным документам. Отвечай ТОЛЬКО на основе переданного контекста. Если информации недостаточно, пиши: «В предоставленных документах ответ не найден». Не выдумывай факты.
Интеграция с LDAP:
В RAG-микросервис добавьте функцию получения ролей текущего пользователя (через библиотеку ldap3).
RBAC-фильтрация в Qdrant:
При каждом поисковом запросе применяйте фильтр:
Filter(must=[FieldCondition(key="access_roles", match=MatchAny(any=user_roles))])
Это гарантирует, что пользователь не получит содержимое документов, на которые у него нет прав.
Полный RAG-пайплайн:
Получение вопроса → определение ролей → эмбеддинг запроса → поиск с фильтром в Qdrant (топ 5 чанков) → сбор контекста → отправка в Ollama с системным промптом.
Ответ возвращается пользователю со ссылками на исходные документы.
Защита от Prompt Injection:
Предусмотрите простые проверки (например, отклонять запросы, содержащие фразы вроде «игнорируй предыдущие инструкции»).
✅ Контрольная точка: Ассистент даёт ответы только на основе разрешённых документов, не раскрывает секретную информацию и не галлюцинирует.
Цель: Предоставить сотрудникам единое окно вопросов, интегрированное в портал, и наладить сбор данных для улучшения системы.
Терминология:
Streamlit (self‑hosted): Python‑фреймворк для быстрой разработки веб‑интерфейсов.
iFrame‑интеграция: Встраивание Streamlit-приложения прямо в страницу Битрикс24.
Развёртывание Streamlit в Deckhouse:
Создайте Docker-образ с вашим Streamlit‑приложением и задеплойте его как Deployment.
Настройте сервис и Ingress (например, http://ai-assistant.internal).
Разработка интерфейса:
Простое окно чата, поле ввода вопроса, отображение истории диалога.
При получении ответа показывать список источников с датами и именами файлов.
Кнопки «???? Полезно» и «???? Бесполезно» для каждого ответа.
Интеграция в Битрикс24:
В административной панели Битрикс24 создайте страницу, содержащую iFrame с URL вашего Streamlit-сервиса.
Через HTTP-заголовок X-Username пробрасывайте имя пользователя для идентификации.
Сохранение фидбека:
Обратная связь (оценка и комментарий) сохраняется в простую базу данных (CSV или локальный PostgreSQL) для последующего анализа.
✅ Контрольная точка: Пользователи общаются с ассистентом через портал, каждая оценка фиксируется.
Цель: Обеспечить непрерывное улучшение качества ответов и подготовить систему к росту нагрузки без перепроектирования.
Терминология:
Hallucination Rate: Процент ответов с вымышленными фактами.
Latency (P50/P95): Время ответа, которое видит пользователь.
Horizontal Pod Autoscaling (HPA): Автоматическое изменение числа экземпляров сервиса в зависимости от нагрузки.
Определение ключевых метрик:
| Метрика | Целевое значение | Способ измерения |
|---|---|---|
| Hallucination Rate | ≤ 5% | Ручная проверка ответов |
| Context Precision | ≥ 90% | Сравнение ответа с найденными чанками |
| Latency P95 | ≤ 15 секунд | Логирование в Prometheus |
| Пользовательская оценка | ≥ 4 из 5 | Фидбек-кнопки |
Мониторинг и оповещения:
Используйте встроенный в Deckhouse стек (Prometheus + Grafana) для визуализации метрик. Настройте алерты на превышение порогов Latency или рост числа ошибок.
Разбор ошибок и итеративное улучшение:
Еженедельный анализ ответов с низкой оценкой. Корректировка:
чанкинга – если релевантная информация теряется;
эмбеддингов – при низкой точности семантического поиска;
системного промпта – если LLM галлюцинирует.
Горизонтальное масштабирование в Kubernetes:
RAG‑сервис: HPA по CPU автоматически увеличивает количество подов при росте запросов.
Ollama: добавив второй Pod на другом узле, вы удваиваете пропускную способность. Для промышленных нагрузок рассмотрите миграцию на vLLM с поддержкой параллельных запросов.
Qdrant: шардирование распределяет векторы по нескольким узлам, а увеличение реплик повышает доступность чтения.
Все изменения выполняются правкой нескольких строк в манифестах и не требуют остановки системы.
Дообучение модели (опционально):
При накоплении ≥500 качественных пар «вопрос – правильный ответ» возможно файнтюнинг LLM с использованием LoRA прямо на имеющемся оборудовании (CPU‑режим через llama.cpp).
✅ Контрольная точка: Система работает стабильно, ключевые метрики достигнуты, путь масштабирования понятен и протестирован.
[Сотрудник] → (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 на двух физических серверах. Система изначально спроектирована для горизонтального масштабирования и полностью отвечает требованиям изолированной среды.