RomiconEZ/agentiq-platform
GitHub: RomiconEZ/agentiq-platform
一个基于Docker Compose的LLM编排平台，提供多代理路由、负载均衡与全链路可观测的安全可控网关。
Stars: 3 | Forks: 0
# 🤖 A2A Agent Platform
**Агентная платформа с балансировкой LLM-нагрузки, мониторингом, защитными механизмами и авторизацией.**
A2A Agent Platform — платформа для оркестрации LLM-запросов с поддержкой нескольких провайдеров, интеллектуальной балансировкой, реестром агентов, системой guardrails и полным стеком observability.
## 📑 Содержание
- [Возможности](#-возможности)
- [Архитектура](#-архитектура)
- [Docker-контейнеры](#-docker-контейнеры)
- [Быстрый старт](#-быстрый-старт)
- [Веб-интерфейсы](#-веб-интерфейсы)
- [Конфигурация](#%EF%B8%8F-конфигурация)
- [Примеры использования](#-примеры-использования)
- [Стратегии балансировки](#-стратегии-балансировки)
- [Тестирование](#-тестирование)
- [Документация](#-документация)
- [Структура проекта](#-структура-проекта)
- [Лицензия](#-лицензия)
## 🚀 Возможности
### LLM-оркестрация
- **Chat Completions** — единый API для взаимодействия с LLM через эндпоинт `/api/v1/llm/chat/completions`
- **4 mock-провайдера**: OpenAI GPT-4, Anthropic Claude, Google Gemini, OpenAI GPT-4 Replica — все маршрутизируются через LiteLLM к локальной LLM
- **Streaming (SSE)** — потоковая передача ответов LLM через Server-Sent Events
- **4 стратегии балансировки**: Round Robin, Weighted Round Robin, Latency-Based, Health-Aware (по умолчанию)
### Реестры
- **A2A Agent Registry** — регистрация, вызов, обновление и удаление агентов
- **2 встроенных агента**: Summarizer (порт 8001) и Code Reviewer (порт 8002)
- **Dynamic LLM Provider Registry** — CRUD для провайдеров с ценами, лимитами и приоритетами
### Безопасность
- **Token-based аутентификация** — HMAC-SHA256, client_id/client_secret, scopes, TTL
- **Guardrails**: обнаружение prompt injection (12 паттернов), обнаружение утечки секретов (9 паттернов), контроль длины ввода
### Observability
- **Prometheus** — сбор метрик
- **Grafana** — 3 преднастроенных дашборда (LLM Monitoring, Traffic Distribution, System Overview)
- **OpenTelemetry** — распределённая трассировка
- **Langfuse** — трассировка LLM-вызовов
- **MLFlow** — трекинг экспериментов
- **Loki + Promtail** — агрегация логов с автоматическим обнаружением Docker-контейнеров
### Инфраструктура
- **Redis** — кэширование ответов
- **Nginx** — reverse proxy с оптимизацией для SSE
- **Health-check эндпоинты** — мониторинг состояния компонентов
- **Полностью контейнеризировано** — Docker Compose для всех компонентов
## 🏗 Архитектура
```
flowchart TB
Client([Клиент])
subgraph internal["Docker Network: internal"]
Nginx["Nginx
Reverse Proxy
:80"] subgraph backend["FastAPI Backend :8000"] MW["Middleware
Metrics → Auth → Cache"] API["API Layer
/health /metrics
/api/v1/llm /auth
/providers /agents"] GR["Guardrails
Filter"] BM["Balancer Manager
RR / WRR / Latency / Health-Aware"] PR["Provider Registry"] P1["openai-gpt4
weight=3"] P2["anthropic-claude
weight=2"] P3["google-gemini
weight=1"] P4["openai-gpt4-replica
weight=1"] end Redis["Redis Cache"] subgraph agents["A2A Агенты"] SA["Summarizer
:8001"] CR["Code Reviewer
:8002"] end subgraph monitoring["Мониторинг"] Prom["Prometheus :9090"] Graf["Grafana :3001"] MLF["MLFlow :5001"] LF["Langfuse :3000"] Loki["Loki :3100"] PT["Promtail"] end LFDB["Langfuse DB
PostgreSQL"] end subgraph llmshared["Docker Network: llm-shared"] LiteLLM["LiteLLM Gateway
:4000"] LLMDB["LiteLLM DB
PostgreSQL"] end LLM["Локальная / Облачная LLM"] Client --> Nginx Nginx --> MW MW --> API API --> GR GR --> BM BM --> PR PR --> P1 & P2 & P3 & P4 P1 & P2 & P3 & P4 --> LiteLLM LiteLLM --> LLM LiteLLM --> LLMDB API --> Redis SA & CR --> API backend --> Prom Prom --> Graf Loki --> Graf PT --> Loki LF --> LFDB backend --> MLF backend --> LF ``` ### Ключевые принципы - **Единая точка входа** — все запросы проходят через Nginx (порт 80) - **Изоляция сетей** — внутренняя сеть `internal` и общая сеть `llm-shared` для связи с LiteLLM - **Плагинная архитектура** — провайдеры и агенты добавляются через реестры - **Прозрачный мониторинг** — каждый запрос отслеживается на всех уровнях ## 🐳 Docker-контейнеры ### Основная платформа (`docker-compose.yml`) | Контейнер | Описание | Порт | Образ / Технология | |---|---|---|---| | `backend` | Основная платформа (FastAPI) | 8000 (внутренний, через nginx на 80) | Python / FastAPI | | `nginx` | Reverse proxy, оптимизирован для SSE | **80** (внешний) | Nginx | | `redis_cache` | Кэширование ответов | 6379 (внутренний) | Redis Alpine | | `summarizer-agent` | Встроенный A2A-агент: суммаризация текста | 8001 (внутренний) | Python / FastAPI | | `code-reviewer-agent` | Встроенный A2A-агент: ревью кода | 8002 (внутренний) | Python / FastAPI | | `prometheus` | Сбор метрик | **9090** | Prometheus | | `grafana` | Дашборды и визуализация | **3001** (admin/admin) | Grafana | | `langfuse` | Трассировка LLM-вызовов | **3000** | Langfuse | | `langfuse-db` | БД для Langfuse | 5432 (внутренний) | PostgreSQL 15 | | `mlflow` | Трекинг экспериментов | **5001** | MLFlow | | `loki` | Агрегация логов | **3100** | Grafana Loki | | `promtail` | Сборщик логов (Docker discovery) | — | Grafana Promtail | ### LiteLLM Gateway (`llm-gateway-litellm/docker-compose.yml`) — отдельный деплой | Контейнер | Описание | Порт | |---|---|---| | `litellm` | LLM Gateway — проксирование к LLM | **4000** | | `litellm-db` | БД для LiteLLM | 5432 (внутренний) | ### Docker-сети | Сеть | Тип | Назначение | |---|---|---| | `internal` | bridge | Внутренняя коммуникация контейнеров платформы | | `llm-shared` | external | Связь между платформой и LiteLLM Gateway | ## ⚡ Быстрый старт ### Предварительные требования - [Docker](https://docs.docker.com/get-docker/) ≥ 20.10 - [Docker Compose](https://docs.docker.com/compose/install/) ≥ 2.0 - (Для тестов) [Poetry](https://python-poetry.org/docs/#installation) ### Шаг 1. Клонирование и настройка окружения ``` git clone
cd HW_agent_platform
cp .env.example .env
```
### Шаг 2. Создание общей Docker-сети
```
docker network create llm-shared
```
### Шаг 3. Настройка `.env`
Откройте файл `.env` и укажите необходимые параметры:
```
# LiteLLM Gateway
LITELLM_BASE_URL=http://litellm:4000
LITELLM_API_KEY=sk-your-litellm-key
LITELLM_MODEL=gpt-4 # значение по умолчанию в коде — local-llm; здесь можно переопределить
# Langfuse (опционально)
LANGFUSE_ENABLED=true
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=http://langfuse:3000
```
### Шаг 4. Запуск LiteLLM Gateway
```
cd llm-gateway-litellm
cp .env.example .env
docker compose up -d
cd ..
```
### Шаг 5. Запуск платформы
```
docker compose up -d --build
```
### Шаг 6. Проверка работоспособи
```
curl http://localhost:80/health
```
Ожидаемый ответ:
```
{
"status": "healthy",
"version": "1.0.0"
}
```
### Шаг 7. Остановка
```
# Остановка основной платформы
docker compose down
# Остановка LiteLLM Gateway
cd llm-gateway-litellm && docker compose down
```
## 🌐 Веб-интерфейсы
После запуска платформы доступны следующие интерфейсы:
| Интерфейс | URL | Описание |
|---|---|---|
| **Swagger UI** | [http://localhost:80/docs](http://localhost:80/docs) | Интерактивная документация API |
| **ReDoc** | [http://localhost:80/redoc](http://localhost:80/redoc) | Альтернативная документация API |
| **Grafana** | [http://localhost:3001](http://localhost:3001) | Дашборды и визуализация метрик (логин: `admin` / пароль: `admin`) |
| **Prometheus** | [http://localhost:9090](http://localhost:9090) | Запросы к метрикам (PromQL) |
| **MLFlow** | [http://localhost:5001](http://localhost:5001) | Трекинг экспериментов и моделей |
| **Langfuse** | [http://localhost:3000](http://localhost:3000) | Трассировка LLM-вызовов, анализ промптов |
| **Loki** | [http://localhost:3100](http://localhost:3100) | API агрегации логов (используется через Grafana) |
### Grafana-дашборды
В Grafana предустановлены 3 дашборда:
| Дашборд | Что отображает |
|---|---|
| **LLM Monitoring** | Латентность p50/p95, распределение трафика по провайдерам, Time To First Token (TTFT) |
| **Traffic Distribution** | Распределение запросов по провайдерам (donut-диаграммы), RPS (запросов в секунду) |
| **System Overview** | CPU, память, HTTP-запросы, Time Per Output Token (TPOT) |
### Полезные PromQL-запросы
```
# Средняя латентность LLM за 5 минут
rate(llm_request_latency_seconds_sum[5m]) / rate(llm_request_latency_seconds_count[5m])
# 95-й перцентиль латентности по провайдерам
histogram_quantile(0.95, sum(rate(llm_request_latency_seconds_bucket[5m])) by (le, provider))
# Количество запросов по провайдерам (RPS)
sum(rate(llm_requests_total[1m])) by (provider)
# Частота ошибок (доля ошибок от общего числа запросов)
sum(rate(llm_requests_total{status="error"}[5m])) / sum(rate(llm_requests_total[5m]))
```
## ⚙️ Конфигурация
Все параметры задаются через переменные окружения в файле `.env`.
### Приложение
| Переменная | Описание | Значение по умолчанию |
|---|---|---|
| `APP_NAME` | Название приложения | `Agent Platform` |
| `APP_VERSION` | Версия приложения | `1.0.0` |
| `BACKEND_PORT` | Внутренний порт backend | `8000` |
| `ENVIRONMENT` | Окружение (`local` / `staging` / `production`) | `local` |
### LiteLLM Gateway
| Переменная | Описание | Значение по умолчанию |
|---|---|---|
| `LITELLM_BASE_URL` | URL LiteLLM-шлюза | `http://localhost:4000` |
| `LITELLM_API_KEY` | API-ключ для LiteLLM | — |
| `LITELLM_MODEL` | Модель LLM по умолчанию | `local-llm` |
| `LITELLM_TIMEOUT` | Таймаут запроса (секунды) | `120` |
| `LITELLM_MAX_RETRIES` | Максимальное количество повторов | `3` |
### Redis
| Переменная | Описание | Значение по умолчанию |
|---|---|---|
| `REDIS_CACHE_HOST` | Хост Redis | `localhost` |
| `REDIS_CACHE_PORT` | Порт Redis | `6379` |
### Langfuse
| Переменная | Описание | Значение по умолчанию |
|---|---|---|
| `LANGFUSE_ENABLED` | Включить Langfuse-трассировку | `true` |
| `LANGFUSE_PUBLIC_KEY` | Публичный ключ Langfuse | — |
| `LANGFUSE_SECRET_KEY` | Секретный ключ Langfuse | — |
| `LANGFUSE_HOST` | URL Langfuse | `http://localhost:3000` |
### MLFlow
| Переменная | Описание | Значение по умолчанию |
|---|---|---|
| `MLFLOW_ENABLED` | Включить MLFlow-трекинг | `true` |
| `MLFLOW_TRACKING_URI` | URI MLFlow-сервера | `http://localhost:5000` |
| `MLFLOW_EXPERIMENT_NAME` | Название эксперимента | `agent-platform` |
### Авторизация
| Переменная | Описание | Значение по умолчанию |
|---|---|---|
| `AUTH_ENABLED` | Включить аутентификацию | `false` |
| `AUTH_SECRET_KEY` | Секретный ключ для HMAC-SHA256 | — |
| `AUTH_TOKEN_EXPIRE_SECONDS` | Время жизни токена (секунды) | `3600` |
| `AUTH_ADMIN_CLIENT_ID` | Client ID администратора | `admin` |
| `AUTH_ADMIN_CLIENT_SECRET` | Client Secret администратора | — |
### Guardrails
| Переменная | Описание | Значение по умолчанию |
|---|---|---|
| `GUARDRAILS_ENABLED` | Включить защитные фильтры | `true` |
| `GUARDRAILS_MAX_INPUT_LENGTH` | Максимальная длина ввода (символы) | `50000` |
### Мониторинг
| Переменная | Описание | Значение по умолчанию |
|---|---|---|
| `PROMETHEUS_PORT_EXTERNAL` | Внешний порт Prometheus | `9090` |
| `GRAFANA_PORT_EXTERNAL` | Внешний порт Grafana | `3001` |
| `GRAFANA_ADMIN_USER` | Логин администратора Grafana | `admin` |
| `GRAFANA_ADMIN_PASSWORD` | Пароль администратора Grafana | `admin` |
## 📖 Примеры использования
### Health Check
```
curl http://localhost:80/health
```
### Получение списка провайдеров
```
curl http://localhost:80/api/v1/providers/
```
### Получение токена авторизации
```
curl -X POST http://localhost:80/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{
"client_id": "admin",
"client_secret": "your-secret"
}'
```
Ответ:
```
{
"access_token": "eyJ...",
"token_type": "bearer",
"expires_in": 3600
}
```
### Chat Completion (обычный запрос)
```
curl -X POST http://localhost:80/api/v1/llm/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"messages": [
{"role": "system", "content": "Ты полезный ассистент."},
{"role": "user", "content": "Объясни, что такое Docker."}
],
"model": "gpt-4",
"temperature": 0.7,
"max_tokens": 500,
"stream": false
}'
```
Ответ:
```
{
"content": "Docker — это платформа контейнеризации...",
"model": "gpt-4",
"provider": "openai-gpt4",
"usage": {
"prompt_tokens": 25,
"completion_tokens": 150,
"total_tokens": 175
},
"latency_ms": 1234.5,
"ttft_ms": 89.2
}
```
### Chat Completion (стриминг через SSE)
```
curl -X POST "http://localhost:80/api/v1/llm/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"messages": [
{"role": "user", "content": "Напиши стихотворение о программировании."}
],
"model": "gpt-4",
"stream": true
}'
```
Ответ — поток SSE-событий:
```
data: {"content": "В ", "done": false}
data: {"content": "мире ", "done": false}
data: {"content": "кода ", "done": false}
...
data: {"content": "", "done": true}
```
### Выбор стратегии балансировки
```
# Round Robin
curl -X POST "http://localhost:80/api/v1/llm/chat/completions?strategy=round_robin" \
-H "Content-Type: application/json" \
-d '{"messages": [{"role": "user", "content": "Привет!"}]}'
# Weighted Round Robin
curl -X POST "http://localhost:80/api/v1/llm/chat/completions?strategy=weighted_round_robin" \
-H "Content-Type: application/json" \
-d '{"messages": [{"role": "user", "content": "Привет!"}]}'
# Latency-Based
curl -X POST "http://localhost:80/api/v1/llm/chat/completions?strategy=latency_based" \
-H "Content-Type: application/json" \
-d '{"messages": [{"role": "user", "content": "Привет!"}]}'
# Health-Aware (по умолчанию)
curl -X POST "http://localhost:80/api/v1/llm/chat/completions?strategy=health_aware" \
-H "Content-Type: application/json" \
-d '{"messages": [{"role": "user", "content": "Привет!"}]}'
```
### Регистрация провайдера
```
curl -X POST http://localhost:80/api/v1/providers/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"name": "custom-provider",
"display_name": "Custom LLM Provider",
"model_name": "custom-model",
"url": "http://custom-llm:8080",
"price_per_input_token": 0.00003,
"price_per_output_token": 0.00006,
"max_rpm": 100,
"max_tokens_limit": 4096,
"priority": 1,
"weight": 10,
"enabled": true
}'
```
### Регистрация агента
```
curl -X POST http://localhost:80/api/v1/agents/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"name": "my-agent",
"description": "Мой пользовательский агент",
"methods": ["summarize", "analyze"],
"url": "http://my-agent:9000",
"version": "1.0.0",
"tags": ["custom", "nlp"]
}'
```
### Вызов агента
```
# Вызов встроенного агента Summarizer
curl -X POST http://localhost:80/api/v1/agents/summarizer/invoke \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"input_text": "Длинный текст для суммаризации...",
"parameters": {}
}'
# Вызов встроенного агента Code Reviewer
curl -X POST http://localhost:80/api/v1/agents/code-reviewer/invoke \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"input_text": "def hello():\n print(\"world\")",
"parameters": {
"language": "python"
}
}'
```
Ответ Code Reviewer:
```
docker network create llm-shared
```
### Обновление агента
```
curl -X PUT http://localhost:80/api/v1/agents/my-agent \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"description": "Обновлённое описание",
"methods": ["summarize", "analyze", "translate"],
"version": "1.1.0",
"tags": ["custom", "nlp", "translation"]
}'
```
### Удаление агента
```
curl -X DELETE http://localhost:80/api/v1/agents/my-agent \
-H "Authorization: Bearer "
```
### Получение списка стратегий балансировки
```
curl http://localhost:80/api/v1/llm/strategies
```
Ответ:
```
{
"strategies": ["round_robin", "weighted_round_robin", "latency_based", "health_aware"],
"default": "health_aware"
}
```
## ⚖️ Стратегии балансировки
Платформа поддерживает 4 стратегии распределения запросов между LLM-провайдерами.
### Сравнительная таблица
| Стратегия | Распределение | Учёт латентности | Учёт здоровья | Сложность | Лучше всего подходит для |
|---|---|---|---|---|---|
| **Round Robin** | Равномерное | ❌ | ❌ | O(1) | Разработка/тестирование, идентичные провайдеры |
| **Weighted Round Robin** | По весам | ❌ | ❌ | O(W) | Провайдеры разной мощности |
| **Latency-Based** | По латентности | ✅ | ❌ | O(N) | Оптимизация скорости |
| **Health-Aware** | Латентность + здоровье | ✅ | ✅ | O(N) | Продакшен, отказоустойчивость |
### Round Robin
Простейшая стратегия — запросы распределяются равномерно по всем доступным провайдерам по кругу. Каждый провайдер получает одинаковое количество запросов.
```
Запрос 1 → Provider A
Запрос 2 → Provider B
Запрос 3 → Provider C
Запрос 4 → Provider A (начинаем сначала)
```
### Weighted Round Robin
Каждому провайдеру назначается вес (weight). Чем больше вес, тем больше запросов направляется на этот провайдер. Полезна, когда провайдеры имеют разную пропускную способность.
```
Provider A (weight=5): ■■■■■
Provider B (weight=3): ■■■
Provider C (weight=2): ■■
```
### Latency-Based
Запросы направляются к провайдеру с наименьшей средней латентностью. Система постоянно обновляет статистику и адаптируется к текущей производительности.
```
Provider A (avg 120ms) ← выбран
Provider B (avg 250ms)
Provider C (avg 180ms)
```
### Health-Aware (по умолчанию)
Комбинирует учёт латентности и состояния здоровья провайдеров. Автоматически исключает нездоровые провайдеры и направляет трафик к самым быстрым и стабильным. **Рекомендуется для продакшена.**
```
Provider A (healthy, avg 120ms) ← выбран
Provider B (unhealthy) ← исключён
Provider C (healthy, avg 180ms)
```
### Рекомендации
- **Разработка и тестирование** → Round Robin (простота, предсказуемость)
- **Провайдеры разной мощности** → Weighted Round Robin (гибкое распределение)
- **Оптимизация скорости** → Latency-Based (минимальная задержка)
- **Продакшен** → Health-Aware (отказоустойчивость + скорость)
## 🧪 Тестирование
### Юнит-тесты
Запуск всех юнит-тестов:
```
poetry run pytest tests/ -v
```
| Файл | Кол-во тестов | Что тестирует |
|---|---|---|
| `test_balancer.py` | 8 | Все 4 стратегии балансировки, выбор провайдера, fallback |
| `test_guardrails.py` | 9 | Обнаружение prompt injection (12 паттернов), утечки секретов (9 паттернов), контроль длины |
| `test_auth.py` | 7 | Генерация и валидация токенов, HMAC-SHA256, TTL, scopes, дублирование клиентов |
| `test_agents_registry.py` | 40 | Полное CRUD-тестирование реестра агентов: регистрация, удаление, обновление, поиск по тегам/методам, фильтрация, жизненный цикл |
| `test_providers_registry.py` | 32 | Полное CRUD-тестирование реестра провайдеров: регистрация, удаление, обновление, фильтрация по моделям, отслеживание здоровья, скользящее окно латентности |
### Интеграционные тесты
Запуск интеграционных тестов (требуется запущенная платформа):
```
poetry run pytest tests/integration/ -v
```
| Файл | Что тестирует |
|---|---|
| `test_health_api.py` | Health-check эндпоинты |
| `test_auth_api.py` | Аутентификация через API |
| `test_providers_api.py` | CRUD провайдеров через API |
| `test_agents_api.py` | CRUD и вызов агентов через API |
| `test_llm_api.py` | Chat Completions (обычный и стриминг) |
| `test_metrics_api.py` | Prometheus-метрики |
| `test_full_flow.py` | Полный сценарий: авторизация → запрос → мониторинг |
### Нагрузочные тесты
#### Locust (интерактивный UI)
```
locust -f tests/locustfile.py --host=http://localhost:80
```
После запуска откройте [http://localhost:8089](http://localhost:8089) для доступа к веб-интерфейсу Locust.
#### Программный нагрузочный тест
```
poetry run pytest tests/test_load.py -v
```
### Покрытие кода
```
poetry run pytest tests/ -v --cov=src --cov-report=html
```
Отчёт будет доступен в директории `htmlcov/`. Откройте `htmlcov/index.html` в браузере.
## 📚 Документация
В проекте подготовлена подробная документация, разделённая по уровням сложности:
| Документ | Описание |
|---|---|
| [`README.md`](README.md) | Обзор проекта, возможности, быстрый старт, примеры использования, конфигурация |
| [`README.dev.md`](README.dev.md) | Руководство разработчика: быстрый старт для локальной разработки, запуск тестов, настройка окружения |
| [`DOC.md`](DOC.md) | Техническая документация: все API-эндпоинты (с JSON-примерами), модули платформы, интеграции (LiteLLM, Langfuse, MLFlow, Prometheus, Grafana, Loki, Redis), доступы, справочник метрик, описание тестов |
| [`docs/level1.md`](docs/level1.md) | **Уровень 1** — Минимальный прототип (10 баллов): архитектурные диаграммы, API провайдеров и балансировщика, инструкции по запуску, отчёт о тестировании, сравнение Round Robin и Weighted Round Robin |
| [`docs/level2.md`](docs/level2.md) | **Уровень 2** — Реестры и умная маршрутизация (20 баллов): реестр агентов, динамическая регистрация провайдеров, Latency-Based и Health-Aware стратегии, MLFlow/Langfuse, расширенные метрики (TTFT, TPOT, токены, стоимость) |
| [`docs/level3.md`](docs/level3.md) | **Уровень 3** — Продвинутая платформа (25 баллов): Guardrails (prompt injection, утечка секретов), токенная авторизация, нагрузочное тестирован (Locust), отчёты об устойчивости балансировщика |
| [`docs/TASK.md`](docs/TASK.md) | Исходное техническое задание |
| [`docs/screenshots.md`](docs/screenshots.md) | Демонстрация работы платформы: скриншоты UI всех компонентов (Swagger, Grafana, Prometheus, MLFlow, Langfuse, Loki, Locust) |
## 📁 Структура проекта
```
HW_agent_platform/
├── docker-compose.yml # Docker Compose основной платформы
├── Dockerfile # Образ backend-сервиса
├── default.conf # Конфигурация Nginx (оптимизирована для SSE)
├── pyproject.toml # Зависимости Python (Poetry)
├── .env.example # Пример переменных окружения
├── README.md # Документация (этот файл)
├── README.dev.md # Руководство разработчика
│
├── assets/ # Скриншоты UI компонентов платформы
│
├── src/app/ # Исходный код backend
│ ├── main.py # Точка входа FastAPI-приложения
│ ├── api/ # API-эндпоинты
│ │ ├── health.py # Health-check
│ │ ├── metrics.py # Prometheus-метрики
│ │ ├── auth.py # Аутентификация
│ │ ├── llm.py # Chat Completions
│ │ ├── providers.py # Реестр провайдеров
│ │ └── agents.py # Реестр агентов
│ ├── core/ # Ядро приложения
│ │ ├── config.py # Конфигурация (Pydantic Settings)
│ │ ├── setup.py # Инициализация приложения
│ │ ├── logger_setup.py # Настройка логирования
│ │ └── exceptions/ # Кастомные исключения
│ │ ├── base_exceptions.py # Базовые исключения платформы
│ │ └── cache_exceptions.py # Исключения кэширования
│ ├── providers/ # LLM-провайдеры
│ │ ├── base.py # Базовый класс провайдера
│ │ └── registry.py # Реестр провайдеров
│ ├── balancer/ # Балансировщик нагрузки
│ │ ├── strategies.py # 4 стратегии балансировки
│ │ └── manager.py # Менеджер балансировки
│ ├── agents/ # A2A-агенты
│ │ └── registry.py # Реестр агентов
│ ├── auth/ # Авторизация
│ │ └── service.py # HMAC-SHA256 token service
│ ├── guardrails/ # Защитные механизмы
│ │ └── filter.py # Prompt injection, secret leak detection
│ ├── observability/ # Стек наблюдаемости
│ │ ├── langfuse_client.py # Клиент Langfuse
│ │ ├── mlflow_client.py # Клиент MLFlow
│ │ ├── otel_setup.py # Настройка OpenTelemetry
│ │ └── metrics.py # Prometheus-метрики
│ ├── middleware/ # Middleware
│ │ ├── auth_middleware.py # Проверка авторизации
│ │ ├── metrics_middleware.py # Сбор HTTP-метрик
│ │ └── client_cache_middleware.py # Кэширование (Cache-Control)
│ ├── schemas/ # Pydantic-схемы
│ │ ├── llm.py # Схемы LLM-запросов/ответов
│ │ ├── agent.py # Схемы агентов
│ │ ├── auth.py # Схемы авторизации
│ │ ├── guardrails.py # Схемы guardrails
│ │ ├── health.py # Схемы health-check
│ │ └── environment.py # Схемы окружения
│ └── utils/ # Утилиты
│ ├── cache.py # Работа с Redis-кэшем
│ └── async_helpers.py # Асинхронные хелперы
│
├── agents/ # Встроенные A2A-агенты
│ ├── common/ # Общий код агентов
│ │ ├── config.py # Конфигурация
│ │ ├── schemas.py # Общие схемы
│ │ ├── llm_client.py # Клиент для обращения к LLM
│ │ ├── registration.py # Авторегистрация в реестре
│ │ └── exceptions.py # Исключения
│ ├── summarizer/ # Агент суммаризации
│ │ ├── main.py # FastAPI-приложение (порт 8001)
│ │ └── service.py # Логика суммаризации
│ └── code_reviewer/ # Агент код-ревью
│ ├── main.py # FastAPI-приложение (порт 8002)
│ └── service.py # Логика ревью кода
│
├── monitoring/ # Конфигурация мониторинга
│ ├── prometheus/
│ │ └── prometheus.yml # Конфигурация Prometheus
│ ├── grafana/
│ │ ├── dashboards/ # 3 JSON-дашборда
│ │ └── provisioning/ # Автопровижининг источников и дашбордов
│ ├── loki/
│ │ └── loki-config.yml # Конфигурация Loki
│ └── promtail/
│ └── promtail-config.yml # Конфигурация Promtail (Docker discovery)
│
├── tests/ # Тесты
│ ├── test_balancer.py # Юнит-тесты балансировщика
│ ├── test_guardrails.py # Юнит-тесты guardrails
│ ├── test_auth.py # Юнит-тесты авторизации
│ ├── test_agents_registry.py # Юнит-тесты реестра агентов
│ ├── test_providers_registry.py # Юнит-тесты реестра провайдеров
│ ├── test_load.py # Программный нагрузочный тест
│ ├── locustfile.py # Сценарий нагрузочного тестирования (Locust)
│ └── integration/ # Интеграционные тесты
│ ├── test_health_api.py
│ ├── test_auth_api.py
│ ├── test_providers_api.py
│ ├── test_agents_api.py
│ ├── test_llm_api.py
│ ├── test_metrics_api.py
│ └── test_full_flow.py
│
└── llm-gateway-litellm/ # LiteLLM Gateway (отдельный деплой)
├── docker-compose.yml
├── config.yaml
└── .env.example
```
## 📄 Лицензия
Этот проект распространяется под лицензией [Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)](LICENSE.md).
Reverse Proxy
:80"] subgraph backend["FastAPI Backend :8000"] MW["Middleware
Metrics → Auth → Cache"] API["API Layer
/health /metrics
/api/v1/llm /auth
/providers /agents"] GR["Guardrails
Filter"] BM["Balancer Manager
RR / WRR / Latency / Health-Aware"] PR["Provider Registry"] P1["openai-gpt4
weight=3"] P2["anthropic-claude
weight=2"] P3["google-gemini
weight=1"] P4["openai-gpt4-replica
weight=1"] end Redis["Redis Cache"] subgraph agents["A2A Агенты"] SA["Summarizer
:8001"] CR["Code Reviewer
:8002"] end subgraph monitoring["Мониторинг"] Prom["Prometheus :9090"] Graf["Grafana :3001"] MLF["MLFlow :5001"] LF["Langfuse :3000"] Loki["Loki :3100"] PT["Promtail"] end LFDB["Langfuse DB
PostgreSQL"] end subgraph llmshared["Docker Network: llm-shared"] LiteLLM["LiteLLM Gateway
:4000"] LLMDB["LiteLLM DB
PostgreSQL"] end LLM["Локальная / Облачная LLM"] Client --> Nginx Nginx --> MW MW --> API API --> GR GR --> BM BM --> PR PR --> P1 & P2 & P3 & P4 P1 & P2 & P3 & P4 --> LiteLLM LiteLLM --> LLM LiteLLM --> LLMDB API --> Redis SA & CR --> API backend --> Prom Prom --> Graf Loki --> Graf PT --> Loki LF --> LFDB backend --> MLF backend --> LF ``` ### Ключевые принципы - **Единая точка входа** — все запросы проходят через Nginx (порт 80) - **Изоляция сетей** — внутренняя сеть `internal` и общая сеть `llm-shared` для связи с LiteLLM - **Плагинная архитектура** — провайдеры и агенты добавляются через реестры - **Прозрачный мониторинг** — каждый запрос отслеживается на всех уровнях ## 🐳 Docker-контейнеры ### Основная платформа (`docker-compose.yml`) | Контейнер | Описание | Порт | Образ / Технология | |---|---|---|---| | `backend` | Основная платформа (FastAPI) | 8000 (внутренний, через nginx на 80) | Python / FastAPI | | `nginx` | Reverse proxy, оптимизирован для SSE | **80** (внешний) | Nginx | | `redis_cache` | Кэширование ответов | 6379 (внутренний) | Redis Alpine | | `summarizer-agent` | Встроенный A2A-агент: суммаризация текста | 8001 (внутренний) | Python / FastAPI | | `code-reviewer-agent` | Встроенный A2A-агент: ревью кода | 8002 (внутренний) | Python / FastAPI | | `prometheus` | Сбор метрик | **9090** | Prometheus | | `grafana` | Дашборды и визуализация | **3001** (admin/admin) | Grafana | | `langfuse` | Трассировка LLM-вызовов | **3000** | Langfuse | | `langfuse-db` | БД для Langfuse | 5432 (внутренний) | PostgreSQL 15 | | `mlflow` | Трекинг экспериментов | **5001** | MLFlow | | `loki` | Агрегация логов | **3100** | Grafana Loki | | `promtail` | Сборщик логов (Docker discovery) | — | Grafana Promtail | ### LiteLLM Gateway (`llm-gateway-litellm/docker-compose.yml`) — отдельный деплой | Контейнер | Описание | Порт | |---|---|---| | `litellm` | LLM Gateway — проксирование к LLM | **4000** | | `litellm-db` | БД для LiteLLM | 5432 (внутренний) | ### Docker-сети | Сеть | Тип | Назначение | |---|---|---| | `internal` | bridge | Внутренняя коммуникация контейнеров платформы | | `llm-shared` | external | Связь между платформой и LiteLLM Gateway | ## ⚡ Быстрый старт ### Предварительные требования - [Docker](https://docs.docker.com/get-docker/) ≥ 20.10 - [Docker Compose](https://docs.docker.com/compose/install/) ≥ 2.0 - (Для тестов) [Poetry](https://python-poetry.org/docs/#installation) ### Шаг 1. Клонирование и настройка окружения ``` git clone
标签：A2A, Agent 编排, API 网关, API集成, Docker Compose, GET参数, Grafana, JWT 认证, LLM 编排, MLFlow 追踪, OpenTelemetry, SSE, 代理注册, 健康感知, 分布式追踪, 可观测性, 多提供商 LLM, 容器化部署, 延迟感知, 提示注入防护, 搜索引擎查询, 服务端流, 注册中心, 流式响应, 版权保护, 用户代理, 监控, 自定义请求头, 负载均衡, 路由策略, 轮询, 逆向工具, 防护墙