# Архитектура

OneAPA построена на многоуровневой архитектуре, обеспечивающей гибкость, масштабируемость и безопасность.

## Общая схема архитектуры

```
┌─────────────────────────────────────────────────────────────────────────┐
│                           КЛИЕНТСКИЙ УРОВЕНЬ                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐  │
│  │   Чат в 1С      │  │  Web UI         │  │   Внешние системы       │  │
│  │   (Толстый/     │  │  (Chainlit)     │  │   (API, Email,          │  │
│  │    Тонкий       │  │                 │  │    MCP клиенты)         │  │
│  │    клиент)      │  │                 │  │                         │  │
│  └────────┬────────┘  └────────┬────────┘  └────────────┬────────────┘  │
└───────────┼────────────────────┼────────────────────────┼───────────────┘
            │                    │                        │
            ▼                    ▼                        ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           УРОВЕНЬ 1С:ПРЕДПРИЯТИЕ                         │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                        Конфигурация OneAPA                        │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │   │
│  │  │ Справочники │  │ Обработки   │  │ Общие       │               │   │
│  │  │ - Агенты    │  │ - Чат       │  │ модули      │               │   │
│  │  │ - Инструм.  │  │ - Выгрузка  │  │ - MCP       │               │   │
│  │  │ - Модели    │  │   в RAG     │  │ - OneRPA    │               │   │
│  │  │ - Триггеры  │  │ - Экспорт/  │  │ - RAG       │               │   │
│  │  │ - MCP серв. │  │   Импорт    │  │ - Обмен с   │               │   │
│  │  │ - Форматы   │  │             │  │   Proxy     │               │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘               │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
│                                    │ HTTP (REST API)                     │
│                                    ▼                                     │
└─────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           УРОВЕНЬ PROXY                                  │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      Python Proxy Server                          │   │
│  │                                                                   │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐   │   │
│  │  │  FastAPI    │  │  LangGraph  │  │     Data Store          │   │   │
│  │  │  /health    │  │  Workflow   │  │  - Agents               │   │   │
│  │  │  /load      │  │  Engine     │  │  - Models               │   │   │
│  │  │  /chat      │  │             │  │  - Tools                │   │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────────────┘   │   │
│  │                                                                   │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐   │   │
│  │  │ Chainlit UI │  │ LLM Utils   │  │   Agent Logic           │   │   │
│  │  │ (Web Chat)  │  │ (providers) │  │   (Router, Tools)       │   │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────────────┘   │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
└────────────────────────────────────┼─────────────────────────────────────┘
                                     │
            ┌────────────────────────┼────────────────────────┐
            ▼                        ▼                        ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           УРОВЕНЬ LLM ПРОВАЙДЕРОВ                        │
│                                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │ Yandex GPT  │  │   OpenAI    │  │ OpenRouter  │  │   Ollama    │     │
│  │             │  │  GPT-4o     │  │  (любые     │  │  (локальные │     │
│  │  Cloud API  │  │  o1, o3     │  │   модели)   │  │   модели)   │     │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘     │
│                                                                          │
│  ┌─────────────┐                                                         │
│  │    Sber     │                                                         │
│  │  GigaChat   │                                                         │
│  └─────────────┘                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

## Компоненты архитектуры

### Клиентский уровень

#### Чат в 1С

Встроенный чат-интерфейс в конфигурации 1С:

* Доступен в толстом и тонком клиенте
* Поддержка прикрепления файлов
* История диалогов
* Выбор агента для общения

#### Web UI (Chainlit)

Веб-интерфейс чата:

* Доступ через браузер
* Не требует клиента 1С
* Современный интерфейс
* Поддержка изображений (для Vision моделей)

#### Внешние системы

Взаимодействие через:

* REST API (endpoint `/chat`)
* Email (триггер EMail)
* MCP протокол

### Уровень 1С:Предприятие

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

| Справочник        | Назначение                               |
| ----------------- | ---------------------------------------- |
| APA\_Агенты       | Основная сущность — настройки ИИ агентов |
| APA\_Инструменты  | Инструменты для агентов                  |
| APA\_Модели       | Конфигурация LLM провайдеров             |
| APA\_Триггеры     | События запуска агентов                  |
| APA\_MCPСерверы   | Внешние MCP серверы                      |
| APA\_Форматы      | Форматы выходных данных                  |
| APA\_Пользователи | Пользователи системы                     |

#### Обработки

| Обработка                    | Назначение              |
| ---------------------------- | ----------------------- |
| APA\_Chat                    | Чат-интерфейс           |
| APA\_ВыгрузкаВВекторнуюБД    | Выгрузка данных для RAG |
| APA\_ВыгрузкаЗагрузкаАгентов | Экспорт/импорт агентов  |

#### Общие модули

| Модуль                            | Назначение                      |
| --------------------------------- | ------------------------------- |
| APA\_MCP                          | Работа с Model Context Protocol |
| APA\_OneRPA                       | Интеграция с OneRPA             |
| APA\_RAG                          | Retrieval-Augmented Generation  |
| APA\_ОбменСПроксиКлиент           | Клиентский обмен с Proxy        |
| APA\_ОбменСПроксиСервер           | Серверный обмен с Proxy         |
| APA\_ВыполнениеИнструментовСервер | Выполнение инструментов         |
| APA\_ЗначенияКонстант             | Константы системы               |

### Уровень Proxy

#### FastAPI

REST API сервер с endpoints:

* `GET /health` — проверка работоспособности
* `POST /load` — загрузка агентов и инструментов
* `POST /chat` — обработка сообщений

#### LangGraph

Движок оркестрации workflow агентов:

```
Router → Agent → Tools → Agent → ... → END
```

* **Router Node** — выбор агента
* **Agent Node** — вызов LLM
* **Tools Node** — выполнение инструментов

#### Data Store

Хранилище данных в памяти:

* Загруженные агенты
* Инициализированные LLM
* Конфигурация инструментов

#### Chainlit UI

Веб-интерфейс на базе Chainlit:

* Монтируется на `/ui`
* Отдельная сессия для каждого пользователя
* Поддержка файлов и изображений

#### LLM Utils

Утилиты для работы с LLM провайдерами:

* Инициализация моделей
* Обработка ответов
* Поддержка Vision и Reasoning моделей

### Уровень LLM провайдеров

| Провайдер      | Особенности                                     |
| -------------- | ----------------------------------------------- |
| **Yandex GPT** | Российский провайдер, IAM авторизация           |
| **OpenAI**     | GPT-4o, Vision, Reasoning (o1, o3), web\_search |
| **OpenRouter** | Доступ к множеству моделей через единый API     |
| **Ollama**     | Локальные модели, On-Premise                    |
| **Sber**       | GigaChat, российский провайдер                  |

## Потоки данных

### Поток сообщения пользователя

```
1. Пользователь → [Чат 1С] → сообщение
                      │
2.                    ▼
   1С: APA_ОбменСПроксиКлиент → HTTP POST /chat
                      │
3.                    ▼
   Proxy: api.py → chat() → LangGraph workflow
                      │
4.                    ▼
   LangGraph: router_node → выбор агента
                      │
5.                    ▼
   LangGraph: agent_node → вызов LLM
                      │
6.                    ▼
   LLM: анализ запроса → tool_call (если нужен инструмент)
                      │
7.                    ▼
   LangGraph: tools_node → HTTP POST к 1С (toolsendpoint)
                      │
8.                    ▼
   1С: APA_ВыполнениеИнструментовСервер → выполнение
                      │
9.                    ▼
   Proxy: получение результата → agent_node (LLM формирует ответ)
                      │
10.                   ▼
   Пользователь ← [Чат 1С] ← ответ агента
```

### Поток загрузки агентов

```
1. 1С: APA_ОбменСПроксиСервер → сбор данных агентов
                      │
2.                    ▼
   HTTP POST /load → LoadRequest {agents, toolsendpoint}
                      │
3.                    ▼
   Proxy: api.py → load()
        │
        ├── Сохранение агентов в DataStore
        ├── Инициализация LLM для каждого агента
        └── Сохранение toolsendpoint
                      │
4.                    ▼
   Ответ: статус загрузки
```

## Сетевое взаимодействие

### Порты и протоколы

| Компонент       | Порт по умолчанию    | Протокол   |
| --------------- | -------------------- | ---------- |
| Proxy Server    | 9000                 | HTTP/HTTPS |
| Chainlit UI     | 9000/ui              | HTTP/HTTPS |
| 1С HTTP Service | зависит от настройки | HTTP/HTTPS |
| Ollama          | 11434                | HTTP       |

### Требования к сети

```
┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   1С:       │ ◄─────► │   Proxy     │ ◄─────► │    LLM      │
│ Предприятие │  HTTP   │   Server    │  HTTPS  │  Provider   │
└─────────────┘         └─────────────┘         └─────────────┘
     Порт: *                Порт: 9000          Порт: 443 (или
                                                локальный 11434
                                                для Ollama)
```

{% hint style="info" %}
При использовании Ollama весь трафик остаётся внутри локальной сети — доступ к интернету не требуется.
{% endhint %}

## Масштабирование

### Горизонтальное масштабирование

```
                    ┌─────────────────┐
                    │  Load Balancer  │
                    └────────┬────────┘
                             │
           ┌─────────────────┼─────────────────┐
           ▼                 ▼                 ▼
    ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
    │   Proxy 1   │   │   Proxy 2   │   │   Proxy 3   │
    └─────────────┘   └─────────────┘   └─────────────┘
```

### Вертикальное масштабирование

* Увеличение ресурсов сервера Proxy
* Использование GPU для локальных моделей Ollama
* Оптимизация базы данных 1С

## Отказоустойчивость

### Защита от ошибок

| Уровень     | Механизм                                     |
| ----------- | -------------------------------------------- |
| LangGraph   | Лимит итераций (MAX\_AGENT\_ITERATIONS = 15) |
| LLM вызовы  | Таймаут 900 секунд                           |
| Инструменты | Таймаут 900 секунд                           |
| Router      | Таймаут 600 секунд                           |
| Fallback    | Обработка ошибок с fallback-ответом          |

### Логирование

* Все действия агентов логируются
* Регистр APA\_ЛогИнструментов в 1С
* Файловые логи Proxy сервера

## Далее

* [Компоненты](/ai-platforma-oneapa/obzor-sistemy/komponenty.md) — детальное описание каждого компонента
* [Ключевые возможности](/ai-platforma-oneapa/obzor-sistemy/klyuchevye-vozmozhnosti.md) — функциональность системы


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.onerpa.ru/ai-platforma-oneapa/obzor-sistemy/arkhitektura.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.