RomiconEZ/agentiq-platform
GitHub: RomiconEZ/agentiq-platform
一个基于Docker Compose的LLM编排平台，提供多代理路由、负载均衡与全链路可观测的安全可控网关。
Stars: 4 | Forks: 0
# 🤖 A2A Agent 平台
**具备 LLM 负载均衡、监控、防护机制和授权的 Agent 平台。**
A2A Agent Platform 是一个用于编排 LLM 请求的平台，支持多家提供商、智能负载均衡、Agent 注册表、guardrails 系统以及完整的 observability 技术栈。
## 📑 目录
- [功能](#-возможности)
- [架构](#-архитектура)
- [Docker 容器](#-docker-контейнеры)
- [快速开始](#-быстрый-старт)
- [Web 界面](#-веб-интерфейсы)
- [配置](#%EF%B8%8F-конфигурация)
- [使用示例](#-примеры-использования)
- [负载均衡策略](#-стратегии-балансировки)
- [测试](#-тестирование)
- [文档](#-документация)
- [项目结构](#-структура-проекта)
- [许可证](#-лицензия)
## 🚀 功能
### LLM 编排
- **Chat Completions** — 通过 `/api/v1/llm/chat/completions` 端点与 LLM 交互的统一 API
- **4 个 mock 提供商**：OpenAI GPT-4、Anthropic Claude、Google Gemini、OpenAI GPT-4 Replica — 全部通过 LiteLLM 路由到本地 LLM
- **Streaming (SSE)** — 通过 Server-Sent Events 进行 LLM 响应的流式传输
- **4 种负载均衡策略**：Round Robin、Weighted Round Robin、Latency-Based、Health-Aware（默认）
### 注册表
- **A2A Agent Registry** — Agent 的注册、调用、更新和删除
- **2 个内置 Agent**：Summarizer (端口 8001) 和 Code Reviewer (端口 8002)
- **Dynamic LLM Provider Registry** — 针对提供商的 CRUD 操作，包含价格、限制和优先级
### 安全
- **基于 Token 的身份验证** — HMAC-SHA256、client_id/client_secret、scopes、TTL
- **Guardrails**：检测 prompt injection（12 种模式）、检测机密泄露（9 种模式）、输入长度控制
### Observability
- **Prometheus** — 收集指标
- **Grafana** — 3 个预配置的 dashboard（LLM Monitoring、Traffic Distribution、System Overview）
- **OpenTelemetry** — 分布式 tracing
- **Langfuse** — LLM 调用 tracing
- **MLFlow** — 实验追踪
- **Loki + Promtail** — 日志聚合，支持自动发现 Docker 容器
### 基础设施
- **Redis** — 响应缓存
- **Nginx** — 针对流式传输优化的 reverse proxy
- **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` 和用于与 LiteLLM 通信的共享网络 `llm-shared` - **插件化架构** — 通过注册表添加提供商和 Agent - **透明监控** — 每个请求在所有层级均被追踪 ## 🐳 Docker 容器 ### 主平台 (`docker-compose.yml`) | 容器 | 描述 | 端口 | 镜像 / 技术 | |---|---|---|---| | `backend` | 主平台 (FastAPI) | 8000 (内部，通过 nginx 暴露于 80) | Python / FastAPI | | `nginx` | Reverse proxy，针对流式传输优化 | **80** (外部) | Nginx | | `redis_cache` | 响应缓存 | 6379 (内部) | Redis Alpine | | `summarizer-agent` | 内置 A2A Agent：文本摘要 | 8001 (内部) | Python / FastAPI | | `code-reviewer-agent` | 内置 A2A Agent：代码审查 | 8002 (内部) | Python / FastAPI | | `prometheus` | 收集指标 | **9090** | Prometheus | | `grafana` | Dashboard 和可视化 | **3001** (admin/admin) | Grafana | | `langfuse` | LLM 调用 tracing | **3000** | Langfuse | | `langfuse-db` | Langfuse 的数据库 | 5432 (内部) | PostgreSQL 15 | | `mlflow` | 实验追踪 | **5001** | MLFlow | | `loki` | 日志聚合 | **3100** | Grafana Loki | | `promtail` | 日志收集器 (Docker 自动发现) | — | 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
```
## 🌐 Web 界面
平台启动后，可访问以下界面：
| 界面 | 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) | 指标的 dashboard 和可视化 (用户名: `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 调用 tracing，prompt 分析 |
| **Loki** | [http://localhost:3100](http://localhost:3100) | 日志聚合 API (通过 Grafana 使用) |
### Grafana Dashboard
Grafana 中预装了 3 个 dashboard：
| Dashboard | 显示内容 |
|---|---|
| **LLM Monitoring** | p50/p95 延迟、各提供商的流量分布、Time To First Token (TTFT) |
| **Traffic Distribution** | 各提供商的请求分布 (环形图)、RPS (每秒请求数) |
| **System Overview** | CPU、内存、HTTP 请求、Time Per Output Token (TPOT) |
### 实用 PromQL 查询
```
# 5分钟内 LLM 平均 Latency
rate(llm_request_latency_seconds_sum[5m]) / rate(llm_request_latency_seconds_count[5m])
# 各 Provider 的 Latency 第95百分位
histogram_quantile(0.95, sum(rate(llm_request_latency_seconds_bucket[5m])) by (le, provider))
# 各 Provider 的 Request 数量 (RPS)
sum(rate(llm_requests_total[1m])) by (provider)
# Error 率（错误占总 Request 数的比例）
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` | LiteLLM 网关 URL | `http://localhost:4000` |
| `LITELLM_API_KEY` | LiteLLM 的 API 密钥 | — |
| `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 tracing | `true` |
| `LANGFUSE_PUBLIC_KEY` | Langfuse 公钥 | — |
| `LANGFUSE_SECRET_KEY` | Langfuse 密钥 | — |
| `LANGFUSE_HOST` | Langfuse URL | `http://localhost:3000` |
### MLFlow
| 变量 | 描述 | 默认值 |
|---|---|---|
| `MLFLOW_ENABLED` | 启用 MLFlow 追踪 | `true` |
| `MLFLOW_TRACKING_URI` | MLFlow 服务器 URI | `http://localhost:5000` |
| `MLFLOW_EXPERIMENT_NAME` | 实验名称 | `agent-platform` |
### 授权
| 变量 | 描述 | 默认值 |
|---|---|---|
| `AUTH_ENABLED` | 启用身份验证 | `false` |
| `AUTH_SECRET_KEY` | 用于 HMAC-SHA256 的密钥 | — |
| `AUTH_TOKEN_EXPIRE_SECONDS` | Token 有效期 (秒) | `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/
```
### 获取授权 Token
```
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
}'
```
### 注册 Agent
```
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"]
}'
```
### 调用 Agent
```
# 调用内置的 Summarizer Agent
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 Agent
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 响应：
```
{
"agent_name": "code-reviewer",
"result": "Код выглядит корректно. Рекомендации: ...",
"model_used": "gpt-4",
"provider_used": "openai-gpt4",
"metadata": {
"code_length": 32,
"language": "python"
}
}
```
### 更新 Agent
```
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"]
}'
```
### 删除 Agent
```
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 | Token 生成和验证、HMAC-SHA256、TTL、scopes、客户端重复 |
| `test_agents_registry.py` | 40 | Agent 注册表的全面 CRUD 测试：注册、删除、更新、按 tag/method 搜索、过滤、生命周期 |
| `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` | 通过 API 进行提供商的 CRUD |
| `test_agents_api.py` | 通过 API 进行 Agent 的 CRUD 和调用 |
| `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 Web 界面。
#### 编程式压力测试
```
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 分)：Agent 注册表、动态提供商注册、Latency-Based 与 Health-Aware 策略、MLFlow/Langfuse、高级指标 (TTFT、TPOT、token、成本) |
| [`docs/level3.md`](docs/level3.md) | **级别 3** — 高级平台 (25 分)：Guardrails (prompt injection、机密泄露)、token 授权、压力测试 (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` 和用于与 LiteLLM 通信的共享网络 `llm-shared` - **插件化架构** — 通过注册表添加提供商和 Agent - **透明监控** — 每个请求在所有层级均被追踪 ## 🐳 Docker 容器 ### 主平台 (`docker-compose.yml`) | 容器 | 描述 | 端口 | 镜像 / 技术 | |---|---|---|---| | `backend` | 主平台 (FastAPI) | 8000 (内部，通过 nginx 暴露于 80) | Python / FastAPI | | `nginx` | Reverse proxy，针对流式传输优化 | **80** (外部) | Nginx | | `redis_cache` | 响应缓存 | 6379 (内部) | Redis Alpine | | `summarizer-agent` | 内置 A2A Agent：文本摘要 | 8001 (内部) | Python / FastAPI | | `code-reviewer-agent` | 内置 A2A Agent：代码审查 | 8002 (内部) | Python / FastAPI | | `prometheus` | 收集指标 | **9090** | Prometheus | | `grafana` | Dashboard 和可视化 | **3001** (admin/admin) | Grafana | | `langfuse` | LLM 调用 tracing | **3000** | Langfuse | | `langfuse-db` | Langfuse 的数据库 | 5432 (内部) | PostgreSQL 15 | | `mlflow` | 实验追踪 | **5001** | MLFlow | | `loki` | 日志聚合 | **3100** | Grafana Loki | | `promtail` | 日志收集器 (Docker 自动发现) | — | 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协议, AI智能体, API集成, LLM网关, 可观测性, 平台架构, 负载均衡