# llm-deploy

**Repository Path**: ceagle/llm-deploy

## Basic Information

- **Project Name**: llm-deploy
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM 推理服务部署

生产级 LLM 推理服务部署方案，支持 AMD GPU 加速和多模型部署。

## 特性

- 🚀 **GPU 加速** - AMD ROCm 支持，推理速度提升 9 倍
- ⚖️ **负载均衡** - Nginx 反向代理，智能路由
- 🔐 **安全认证** - Bearer Token API Key 验证
- 🔌 **OpenAI 兼容** - 无缝对接现有应用
- 📦 **多模型支持** - 单机部署多个大模型，按需启动
- 📊 **队列管理** - 高并发请求入队、超时落地、空闲自动重试
- 🤖 **智能告警** - AI 驱动的告警分析与日报生成
- 📈 **监控告警** - Prometheus 指标、Grafana Dashboard、Alertmanager 告警

## 架构概览

```mermaid
graph TB
    subgraph Client["客户端"]
        User["用户"]
    end

    subgraph Gateway["网关层"]
        Nginx["Nginx Gateway<br/>:80, :443"]
    end

    subgraph Services["服务层"]
        AccessControl["Access Control<br/>src/access-control/"]
        AIReport["AI Reporter<br/>src/ai-report/"]
        GPUModel["GPU Model<br/>DeepSeek-32B / Qwen3-30B"]
    end

    subgraph Storage["存储层"]
        Redis["Redis<br/>队列存储"]
    end

    subgraph Monitoring["监控层"]
        Prometheus["Prometheus"]
        Grafana["Grafana"]
        Alertmanager["Alertmanager"]
    end

    subgraph Notification["通知层"]
        DingTalk["钉钉机器人"]
    end

    User -->|HTTPS| Nginx
    Nginx --> AccessControl
    Nginx --> GPUModel
    Nginx --> Prometheus
    Nginx --> Grafana
    AccessControl --> Redis
    AccessControl --> GPUModel
    Prometheus --> GPUModel
    Prometheus --> AccessControl
    Prometheus --> AIReport
    Alertmanager --> AIReport
    AIReport --> GPUModel
    AIReport --> DingTalk
```

**部署解耦**: Nginx 网关独立部署，可灵活调度模型、队列、监控服务。

## 快速开始

### 环境要求

| 依赖 | 版本 |
|------|------|
| Docker | 24.0+ |
| Docker Compose | V2 |
| AMD ROCm | 可选 (GPU 加速) |

### 使用 Makefile（推荐）

```bash
# 查看所有可用命令
make help

# 初始化环境（创建网络、配置文件、生成 API Key）
make init

# 启动服务（根据需求选择一种）
make up-gpu        # GPU 单模型模式
make up-cpu        # CPU 模式
make up-multi      # 多模型模式
make up-monitoring # 仅监控系统
make up-queue      # 仅队列管理
make up-full       # 全部服务

# 查看服务状态
make ps

# 查看日志
make logs

# 健康检查
make health
```

### 使用 Docker Compose

```bash
# 初始化配置
cp deploy/.env.example deploy/.env
docker network create docker_llm-network

# 生成 API Key
mkdir -p llm
python3 scripts/generate-api-key.py --save

# 启动服务（使用 profile）
docker compose -f deploy/docker-compose.yml --profile gpu up -d
```

### 验证部署

```bash
# 健康检查
curl http://localhost/health

# 测试推理 (通过 Nginx 端口 80)
curl http://localhost/v1/chat/completions \
  -H "Authorization: Bearer $(cat llm/api-keys.txt)" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.5-35b","messages":[{"role":"user","content":"你好"}]}'

# 测试推理 (通过模型专用端口 8081)
curl http://localhost:8081/v1/chat/completions \
  -H "Authorization: Bearer $(cat llm/api-keys.txt)" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.5-35b","messages":[{"role":"user","content":"你好"}]}'
```

## 部署模式

通过 Profile 选择部署模式：

| Profile | 模式 | 启动命令 | 说明 |
|---------|------|----------|------|
| `cpu` | CPU 单模型 | `make up-cpu` | 测试/开发环境 |
| `gpu` | GPU 单模型 | `make up-gpu` | 生产环境 |
| `gpu-ha` | GPU 单模型双实例 | `make up PROFILE=gpu-ha` | 负载均衡 |
| `multi` | GPU 多模型 | `make up-multi` | DeepSeek-32B + Qwen3-30B |
| `all-models` | GPU 全部模型 | `make up PROFILE=all-models` | 所有模型同时运行 |
| `monitoring` | 监控系统 | `make up-monitoring` | Prometheus + Grafana |
| `queue` | 队列管理 | `make up-queue` | 高并发场景 |
| `full` | 全部服务 | `make up-full` | 完整部署 |

## 访问端口

| 端口 | 用途 | 说明 |
|------|------|------|
| 80 | 主网关 | 自动路由到队列/模型服务 |
| 443 | HTTPS | 加密访问 |
| 8080 | Queue Manager | 队列管理服务直连 |
| 8081 | Model 1 | DeepSeek-32B 专用直连 |
| 8082 | Model 2 | Qwen3-30B 专用直连 |
| 3000 | Grafana | 监控面板 |
| 9090 | Prometheus | 指标服务 |
| 9093 | Alertmanager | 告警服务 |

## 模型切换

```bash
# 查看服务状态
make ps

# 从 CPU 模式切换到 GPU 模式
make down
make up-gpu

# 从单模型切换到多模型
make down
make up-multi
```

## 配置文件

主配置文件位于 `deploy/.env`：

```bash
# 复制并编辑配置
cp deploy/.env.example deploy/.env
vim deploy/.env

# 主要配置项
MODELS_PATH=/data/models        # 模型文件目录
GFX_VERSION=11.0.0              # GPU 架构版本
GPU_MODEL_PATH=...              # 单模型路径
MODEL1_PATH=...                 # 多模型路径
```

## 性能基准

| 模型 | 参数量 | 量化 | 生成速度 | 首 Token 延迟 | 显存 |
|------|--------|------|----------|---------------|------|
| Qwen3.5-35B | 35B | Q4_K_M | ~59 tokens/s | ~15ms | ~22GB |
| DeepSeek-32B | 32B | Q4_K_M | ~19 tokens/s | ~130ms | ~20GB |
| Qwen3-30B | 30B | Q4_K_M | ~91 tokens/s | ~15ms | ~18GB |
| DeepSeek-1.5B | 1.5B | Q4_K_M | ~180 tokens/s | ~70ms | ~1GB |

*测试环境: AMD Radeon Pro W7800 (30GB)*

## API 端点

| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/health` | GET | 健康检查 | 否 |
| `/v1/models` | GET | 模型列表 | 否 |
| `/v1/chat/completions` | POST | 对话补全 | 是 |
| `/v1/completions` | POST | 文本补全 | 是 |
| `/` | GET | Web UI | 否 |

## GPU 配置

### AMD GPU 支持

| GPU 型号 | 架构 | GFX_VERSION |
|----------|------|-------------|
| Radeon Pro W7800 | gfx1100 | 11.0.0 |
| Radeon RX 7800 XT | gfx1100 | 11.0.0 |
| Radeon RX 7900 XTX | gfx1100 | 11.0.0 |
| Radeon RX 6800 XT | gfx1030 | 10.3.0 |

### GPU 设备检查

```bash
ls -la /dev/kfd /dev/dri/renderD*
rocminfo
```

## 目录结构

```
llm-deploy/
├── src/                          # 服务代码（统一入口）
│   ├── access-control/           # 队列管理与访问控制
│   │   ├── app/                  # FastAPI 应用
│   │   ├── tests/                # 测试代码
│   │   ├── Dockerfile            # 容器构建
│   │   ├── requirements.txt      # Python 依赖
│   │   └── README.md             # 服务文档
│   ├── ai-report/                # AI 告警报告服务
│   │   ├── app/
│   │   ├── tests/
│   │   ├── Dockerfile
│   │   ├── requirements.txt
│   │   └── README.md
│   └── inference/                # LLM 推理服务（预留）
│       └── README.md
├── deploy/                       # 部署配置
│   ├── docker-compose.yml        # 统一编排文件
│   ├── .env.example              # 环境变量模板
│   └── nginx/                    # 网关配置
│       ├── nginx-gateway.conf
│       ├── nginx.conf
│       ├── nginx-multi-model.conf
│       ├── nginx-queue.conf
│       └── ssl/                  # TLS 证书
├── monitoring/                   # 监控系统
│   ├── prometheus/               # Prometheus 配置
│   │   ├── prometheus.yml
│   │   ├── alert.rules.yml
│   │   └── gpu-exporter.sh
│   ├── grafana/                  # Grafana Dashboard
│   │   ├── provisioning/         # 自动配置
│   │   │   ├── datasources/
│   │   │   └── dashboards/
│   │   └── dashboards/
│   ├── alertmanager/             # Alertmanager 配置
│   │   └── alertmanager.yml
│   └── dingtalk/                 # 钉钉 Webhook
│       └── config.yml
├── scripts/                      # 部署脚本
├── docs/                         # 项目文档
├── tests/                        # 集成测试
├── llm/                          # API 密钥（gitignore）
├── data/                         # 数据目录（gitignore）
├── Makefile                      # 构建命令
└── README.md                     # 项目概述
```

## 文档

详细文档请参阅 [docs/](docs/) 目录。

### 快速入门

| 文档 | 说明 |
|------|------|
| [快速开始](docs/getting-started.md) | 5 分钟快速部署 |
| [安装部署](docs/installation.md) | 详细部署步骤 |
| [API 参考](docs/api-reference.md) | OpenAI 兼容 API |

### 运维与配置

| 文档 | 说明 |
|------|------|
| [配置说明](docs/configuration.md) | 环境变量与模型配置 |
| [运维手册](docs/OPERATIONS.md) | 服务管理与监控 |
| [故障排查](docs/troubleshooting.md) | 常见问题解决 |

### 架构与设计

| 文档 | 说明 |
|------|------|
| [系统架构](docs/ARCHITECTURE.md) | 整体架构设计 |
| [验证环境](docs/VALIDATION.md) | 本地验证流程 |

### 模块文档

| 模块 | 说明 |
|------|------|
| [监控模块](docs/modules/monitoring/) | Prometheus、Grafana、Alertmanager |
| [访问控制](docs/modules/access-control/) | 队列管理、请求限流 |
| [AI 报告](docs/modules/ai-report/) | 智能告警、日报服务 |

## 许可证

MIT License