Microservice: ИИ-сервис локальная модель шлюз генерации стохастического события

ai-stochastic-gateway

Репозиторий сервиса

Published

October 20, 2026

Ограничение публичной документации

В открытом доступе представлена демонстрационная версия архитектуры, конфигурации развертывания и контрактов сервиса. Полные контекстные векторы резидентов, спецификации сетевых политик и приватные сценарии генерации доступны только во внутреннем контуре разработки умного дома (Confluence / Swagger Enterprise).

1 Общее назначение сервиса

Микросервис представляет собой специализированный ИИ-шлюз (LLM Gateway), предназначенный для стохастического моделирования действий пользователя в экосистеме холодильника (food_tracker). На основе входящих параметров (тип действия, данные продуктов, контекст пользователей), передаваемых из внешнего симулятора, сервис выполняет инференс на маленькой локальной языковой модели Qwen 2.5 (3B) через движок Ollama API.

Сервис спроектирован как легковесный конвейер обработки данных, оптимизированный для работы на CPU (без использования дискретных GPU). Основная задача сервиса — преобразовывать сценарии поведения в строго форматированные плоские строковые векторы, выступая как Single Source of Truth для генерации событий внутри симулятора бизнес-процессов.

1.1 Основные бизнес-функции:

Интерпретация пользовательских действий: Прием и валидация входящих запросов на симуляцию одного из четырех паттернов поведения (shopping, cooking, consumption, waste).
Оркестрация LLM-инференса: Динамическая сборка системных/пользовательских промптов и контроль параметров генерации данных.
Детерминированное обеспечение схемы: Применение параметров RESPONSE_SCHEMA и stop-последовательностей для исключения дрейфа разметки нейросети и минимизации задержек до ~1.2 – 3.5 секунд.
Нормализация и выдача векторов: Парсинг сгенерированного LLM-ответа и отгрузка очищенного плоского текстового вектора (vector_output) для обработки на стороне клиента.

1.2 Схема архитектуры компонента (Конвейер генерации векторов поведения)

graph LR
    %% HIGH-CONTRAST PASTEURIZED UI NODES (Text forced to absolute black)
    classDef client fill:#CBD5E0,stroke:#718096,stroke-width:1.5px,color:#000000,font-weight:bold;
    classDef core fill:#B2F5EA,stroke:#319795,stroke-width:1.5px,color:#000000,font-weight:bold;
    classDef ai fill:#BEE3F8,stroke:#3182CE,stroke-width:1.5px,color:#000000,font-weight:bold;

    %% ULTRA-LIGHT CUSTOM PASTEL SUBGRAPH DOMAIN FRAMES
    style Слой_1 fill:#F7FAFC,stroke:#A0AEC0,stroke-width:1px,color:#4A5568,font-weight:bold
    style Слой_2 fill:#E6FFFA,stroke:#4FD1C5,stroke-width:1px,color:#234E52,font-weight:bold
    style Слой_3 fill:#EBF8FF,stroke:#63B3ED,stroke-width:1px,color:#2B6CB0,font-weight:bold

    subgraph Слой_1 ["1. Потребитель симуляции"]
        Sim["Внешний симулятор (Go)<br>HTTP REST (InferenceRequest)"]:::client
    end

    subgraph Слой_2 ["2. Шлюз ИИ (ai-stochastic-gateway)"]
        FastAPI_Srv["FastAPI Router (Port 8000)<br>Валидация DTO и сборка промпта"]:::core
    end

    subgraph Слой_3 ["3. Локальный движок ИИ"]
        Ollama["Ollama Engine (Port 11434)<br>Модель: qwen2.5:3b (CPU)"]:::ai
    end

    %% ПОТОКИ ВЗАИМОДЕЙСТВИЯ (СТРОГО СЛЕВА НАПРАВО)
    Sim -->|POST /generate| FastAPI_Srv
    FastAPI_Srv -->|POST /api/chat 4 потока CPU| Ollama
    Ollama -->|Строгий JSON по Response Schema| FastAPI_Srv
    FastAPI_Srv -->|Извлеченный flat vector_output| Sim

2 Реестр инфраструктурных компонентов и файлов

Примечание: Микросервис является вычислительным шлюзом без сохранения состояния (Stateless). Хранение весов моделей LLM изолировано на постоянном диске хоста с помощью Docker Volumes.

2.1 Топология и сетевая маршрутизация (Topology)

Инфраструктура развернута в изолированном сетевом периметре Docker (Сеть bridge) на удаленном сервере Ubuntu.

Название компонента	Строка подключения / Эндпоинт	Сетевой драйвер	Назначение и операционная зона
fridge-ai-gateway	`http://gateway:8000`	`bridge`	Принимает входящие JSON-структуры от внешнего Go-симулятора.
fridge-ollama	`http://ollama:11434`	`bridge`	Выполняет низкоуровневые матричные вычисления, ограниченные 4 потоками.
fridge-model-puller	Внутренний Curl-контейнер	`bridge`	Асинхронный автоматический бутстрап-загрузчик весов модели `qwen2.5:3b`.

3 Спецификация REST-интерфейса (Контракт)

Протокол: HTTP/1.1
Метод: POST
Эндпоинт: /generate
Content-Type: application/json

3.1 Входящий запрос (Request)

Спецификация полей (Environment Specifications):

action (VARCHAR, NOT NULL) — Флаг маршрутизации симуляции (shopping, cooking, consumption, waste).
items (VARCHAR, NOT NULL) — Матрица продуктов: лимиты или индексированный массив из оперативной памяти Redis (например, 1:EGG(67),2:MILK(289)).
context (VARCHAR, NOT NULL) — Плоский вектор поведенческих, финансовых и контекстных тегов жильцов.

{
  "action": "shopping",
  "items": "3",
  "context": "1:2:3:0:1:4:2:1:0:0:5:2:1:9:0:1:1:3:2:4"
}

3.2 Исходящий ответ (Response)

Корневой элемент:

JSON Object * vector_output (VARCHAR) — Выходной плоский реестр токенов, разделенный двоеточиями и запятыми.

{
  "vector_output": "SHOPPING,1:CHICKEN FILLET:3100:2:2434.5,2:TOMATOES:924:1:415.2"
}

4 Диаграмма последовательности (Sequence Diagram)

Полный жизненный цикл обработки HTTP-запроса, оркестрация локального инференса на CPU-ядрах и нормализация ответа нейросети.

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'actorBkg': '#EBF8FF',
    'actorBorder': '#A3BFFA',
    'actorTextColor': '#000000',
    'rectBkg': '#FAF7F0',
    'rectBorder': '#E3DDCF',
    'noteBkgColor': '#E6F4EA',
    'noteBorderColor': '#34D399',
    'noteTextColor': '#064E3B',
    'signalColor': '#2D3748',
    'signalLineColor': '#4A5568'
  }
}}%%

sequenceDiagram
    autonumber
    actor Client as Симулятор (Go)
    participant App as FastAPI (fridge-ai-gateway)
    participant AI as Движок LLM (fridge-ollama)

    Client->>App: HTTP POST /generate (InferenceRequest JSON)
    activate App
    
    note over App: Шаг 2: Валидация DTO через Pydantic. Защита LLM от сырого текста.
    note over App: Шаг 3: Генерация user_instruction на основе входных параметров.
    
    App->>AI: HTTP POST /api/chat (Контекст, RESPONSE_SCHEMA, num_thread: 4)
    activate AI
    
    note over AI: Шаг 5: Инференс Qwen2.5 (3B) на P-ядрах.<br/>Мгновенный останов по маркеру stop=["\n"]
    
    AI-->>App: HTTP 200 OK (Детерминированный JSON с ключом "vector" в content)
    deactivate AI

    note over App: Шаг 7: Десериализация строки контента LLM и вызов метода .strip()
    
    App-->>Client: HTTP 200 OK (JSON c результирующим vector_output)
    deactivate App

Figure 1: Пошаговая последовательность выполнения ИИ-генерации в изолированном контуре

5 Таблица расшифровки шагов сценария

Шаг	Действие	Параметры / Запросы / DTO	Код ошибки (`canonical_code`)	HTTP статус
1 (`Client -> App`)	Внешний симулятор отправляет структурированные параметры контекста среды для предсказания поведения резидента.	InferenceRequest JSON: `{ "action": "waste", "items": "1:EGG(67)", "context": "1:2:3..." }`	INFERENCE_BAD_REQUEST	422
2 (`App -> App`)	Внутренняя логика: Проверка контракта данных. Защищает контекстное окно модели от неструктурированного шума.	Валидация встроенных строковых полей Pydantic v2.	INFERENCE_BAD_REQUEST	422
3 (`App -> App`)	Внутренняя логика: Интерполяция переменных и подготовка инструкции для передачи в Ollama API.	Сборка строки формата: `"ACTION TYPE: {action}\nINPUT ITEMS DATA: ..."`	Нет	200
4 (`App -> AI`)	Запуск синхронного HTTP-запроса к нейросетевому движку. Ограничение инференса 4 физическими потоками хоста.	JSON Payload: `{"model": "qwen2.5:3b", "options": {"temperature": 0.6, "num_thread": 4}, "stream": false}`	INFERENCE_ENGINE_DOWN	500
5 (`AI -> AI`)	Внутренняя логика: Математический расчет токенов локальной LLM с аппаратным ограничением контекста (`2048`).	Фиксация вывода через JSON Schema. Принудительный брейк генерации при обнаружении переноса строки `\n`.	Нет	200
6 (`AI -> App`)	Эндпоинт Ollama возвращает строковый JSON-контейнер, гарантированно содержащий целевой плоский вектор.	Ollama Response: `{"message": {"role": "assistant", "content": "{\"vector\": \"WASTE,1:1.0:412.0:1\"}"}}`	INFERENCE_ENGINE_FAILURE	500
7 (`App -> App`)	Внутренняя логика: Извлечение и финализация строки. Предотвращает падение парсеров на стороне Go-потребителя.	Вызовы методов стандартной библиотеки: `json.loads(ollama_json)` и `.strip()`	INFERENCE_PARSE_FAILURE	500
8 (`App -> Client`)	Шлюз отгружает очищенный вектор симуляции в выходной канал транзакций.	Response JSON: `{ "vector_output": "WASTE,1:1.0:412.0:1" }`	Нет	200

6 Справочник ошибок для Observability

Код (`canonical_code`)	Уровень (`log_level`)	Статусы (`transport_statuses`)	Получатель (`error_target`)	JSON для Фронтенда (`ui_payload`)	Метрики для ClickHouse (`observability_json`)
`INFERENCE_BAD_REQUEST`	WARN	`{"grpc": 3, "http": 422}`	EXTERNAL_SYSTEM	`{"error": "Invalid input dto format"}`	`{"metric": "bad_request", "labels": {"service": "ai_gateway", "reason": "pydantic_validation_failed"}}`
`INFERENCE_ENGINE_DOWN`	CRITICAL	`{"grpc": 14, "http": 500}`	INTERNAL_SYSTEM	null	`{"code": "INFERENCE_ENGINE_DOWN", "metric": "ollama_lost", "labels": {"target": "fridge-ollama:11434"}}`
`INFERENCE_ENGINE_FAILURE`	ERROR	`{"grpc": 13, "http": 500}`	INTERNAL_SYSTEM	null	`{"metric": "llm_exception", "labels": {"service": "ai_gateway", "reason": "runtime_exception"}}`
`INFERENCE_PARSE_FAILURE`	ERROR	`{"grpc": 2, "http": 500}`	INTERNAL_SYSTEM	null	`{"metric": "json_parse_fail", "labels": {"validator": "llm_output_mismatch"}}`