# ai_agent

**Repository Path**: RaidenLumine/ai_agent

## Basic Information

- **Project Name**: ai_agent
- **Description**: 基于FastAPI构建的智能视觉AI Agent平台，集成了多种先进的计算机视觉算法，提供图像超分辨率增强、图像去噪、图像去雨、图像去模糊、暗光增强、人脸情绪识别等功能。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-18
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 算法服务层

这个仓库是小组项目里的 Python 算法层，主要负责加载模型，并把 4 个图像处理服务通过 HTTP 提供给上层 Java 端调用。

## 包含的内容

- 4 个彼此独立的 FastAPI 服务
- 固定端口 `6001` 到 `6004`
- 统一提供 `GET /health` 和 `POST /process`
- 使用 JSON + Base64 传输图片
- 提供单服务测试脚本，以及四个服务一起跑的黑盒测试脚本

组内对接时，Java 端调用的是四个服务入口，不是 `test_codes/` 里的测试脚本。

## 当前服务列表

| 服务 | 端口 | 作用 | 当前参数 |
|---|---:|---|---|
| Emotion | `6001` | 人脸检测与情绪标注 | 暂无业务参数 |
| ESRGAN | `6002` | 图像超分辨率增强 | `scale`，支持 `2` 或 `4`，默认 `4` |
| Restormer | `6003` | 图像去模糊、去雨、去噪等恢复任务 | `task`，支持 `Motion_Deblurring`、`Single_Image_Defocus_Deblurring`、`Deraining`、`Real_Denoising` |
| SCI | `6004` | 低光照图像增强 | 暂无业务参数 |

补充：

- Restormer 还兼容一些简写值，比如 `motion_deblurring`、`defocus_deblurring`、`deraining`、`denoising`
- 四个服务的端口和接口路径目前已经固定，改这里前要先考虑 Java 侧调用

## 运行环境

- Python 建议固定为 `3.8`
- 建议使用 Conda 或虚拟环境
- 部分依赖在更高 Python 版本下不一定稳定，所以不建议直接升版本
- 模型代码和默认权重路径都放在 `models/` 下

安装依赖后，建议先做一次环境检查：

```bash
pip install -r requirements.txt
python scripts/check_environment.py
```

`scripts/check_environment.py` 不参与服务运行，只是用来检查当前 Python 和关键依赖版本是否接近项目基线。

## 启动方式

### 方式一：使用脚本启动

如果是直接跑整套服务，这种方式更省事。

Linux / WSL：

```bash
bash scripts/setup_Linux.sh
bash scripts/shutdown_Linux.sh
```

Windows PowerShell：

```powershell
powershell -ExecutionPolicy Bypass -File scripts/setup_Windows.ps1
powershell -ExecutionPolicy Bypass -File scripts/shutdown_Windows.ps1
```

说明：

- `scripts/setup_Linux.sh` 会在 Linux 或 WSL 内启动 4 个服务，并做健康检查
- 如果当前环境是 WSL，脚本会尝试调用 Windows 侧的 PowerShell 辅助脚本，放行 TCP `6001-6004` 和 ping 相关规则，方便局域网联调
- 如果当前环境是原生 Linux，脚本只负责启动服务，不会处理 Windows 网络规则
- 日志和 PID 文件会写到 `scripts/logs/`

### 方式二：手动启动单个服务

如果只是本地调试某个服务，也可以直接单独启动：

```bash
uvicorn algorithm_services.app_emotion:app --host 127.0.0.1 --port 6001
uvicorn algorithm_services.app_esrgan:app --host 127.0.0.1 --port 6002
uvicorn algorithm_services.app_restormer:app --host 127.0.0.1 --port 6003
uvicorn algorithm_services.app_sci:app --host 127.0.0.1 --port 6004
```

如果需要让同组同学从局域网访问，把 `127.0.0.1` 改成 `0.0.0.0`。不过在 Windows / WSL 场景下，除了监听地址，还要看防火墙规则有没有放行。

## 接口概况

四个服务都提供同样的两个接口。

### `GET /health`

用于确认服务是否能访问，以及模型是否已经加载完成。

返回字段里主要会看到这些内容：

- `status`
- `service`
- `modelLoaded`
- `gpuAvailable`
- `startupError`，启动失败时可能有

目前 `status=healthy` 主要表示接口在线；模型是否真的能处理请求，最好结合 `modelLoaded` 一起看。

### `POST /process`

请求体格式：

```json
{
  "image": "base64 encoded image",
  "params": {}
}
```

说明：

- `image` 必填
- `params` 可以省略
- `params` 就算传 `null`，当前代码也会按空对象处理

响应里常用字段如下：

- `success`
- `image`
- `message`
- `processingTime`
- `error`
- `code`

补充：

- 输入图片支持普通 Base64 字符串，也兼容带 `data:` 前缀的内容
- 输出图片会统一编码成 PNG 后再转成 Base64
- 如果仓库里的旧文档和当前代码不一致，现阶段先以服务代码和测试脚本为准

## 测试方式

仓库里现在有两类测试：

- `test_codes/test_*.py`：分别测试单个服务
- `test_codes/blackbox_test.py`：四个服务一起做基础联通测试
- `test_codes/blackbox_edge_test.py`：测异常和边界输入，比如缺字段、非法 Base64、`params=null`

示例：

```bash
python test_codes/test_emotion.py
python test_codes/test_esrgan.py
python test_codes/test_restormer.py
python test_codes/test_sci.py
python test_codes/blackbox_test.py
python test_codes/blackbox_edge_test.py
```

补充：

- 单服务测试脚本默认超时是 `30` 秒
- 黑盒脚本默认超时更短，第一次加载模型或纯 CPU 环境下，必要时可以调大 `BLACKBOX_HEALTH_TIMEOUT` 或 `BLACKBOX_PROCESS_TIMEOUT`
- 所有测试脚本都支持 `SERVICE_HOST`
- 单服务测试脚本还支持 `SERVICE_REQUEST_TIMEOUT`
- `test_codes/test_restormer.py` 还支持 `RESTORMER_TEST_MODE`
- 测试输出图片会写到 `test_output_images/`

## 目录结构

```text
ai_agent/
├── algorithm_services/               # 四个服务入口和少量公共代码
│   ├── app_emotion.py                # Emotion 服务，端口 6001
│   ├── app_esrgan.py                 # ESRGAN 服务，端口 6002
│   ├── app_restormer.py              # Restormer 服务，端口 6003
│   ├── app_sci.py                    # SCI 服务，端口 6004
│   ├── service_common.py             # 公共请求模型、响应模型、Base64 编解码
│   └── service_config.py             # 服务名、端口、描述等集中配置
├── models/                           # 各算法对应的模型代码、权重和原始说明
│   ├── Emotion-detection/
│   ├── Real-ESRGAN/
│   ├── Restormer/
│   └── SCI/
├── scripts/                          # 启停、网络配置、环境检查脚本
│   ├── setup_Linux.sh
│   ├── shutdown_Linux.sh
│   ├── setup_Windows.ps1
│   ├── shutdown_Windows.ps1
│   ├── configure_Windows_network.ps1
│   ├── cleanup_Windows_network.ps1
│   └── check_environment.py
├── test_codes/                       # 测试脚本
│   ├── test_emotion.py               # Emotion 单服务测试
│   ├── test_esrgan.py                # ESRGAN 单服务测试
│   ├── test_restormer.py             # Restormer 单服务测试
│   ├── test_sci.py                   # SCI 单服务测试
│   ├── blackbox_test.py              # 四个服务的基础联通测试
│   └── blackbox_edge_test.py         # 异常和边界输入测试
├── docs/                             # 项目内保留的说明文档
│   └── API 接口文档.md               # 旧版接口文档，当前仅作讨论参考
├── test_input_images/                # 测试输入图片
├── test_output_images/               # 测试输出目录，按需生成
├── requirements.txt                  # Python 依赖
├── README.md                         # 中文说明
└── README.en.md                      # 英文说明
```

## 其他说明

- 这个仓库目前更适合当“算法服务层”的代码仓库来看，不是一个完整业务系统
- 组内联调时，优先保证端口、接口路径、请求字段稳定，别随便改
- 如果只是验证服务是否能跑，先看 `/health`，再跑测试脚本，比直接翻日志高效
- 如果在 WSL 里启动后需要给别人访问，除了服务本身启动成功，还要确认 Windows 侧网络规则确实已经加上