> For the complete documentation index, see [llms.txt](https://docs.onerpa.ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onerpa.ru/ai-platforma-oneapa/obzor-sistemy/arkhitektura.md).

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

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) — функциональность системы