# LMeterX

**Repository Path**: tiny_dust/LMeterX

## Basic Information

- **Project Name**: LMeterX
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-12
- **Last Updated**: 2026-03-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <img src="docs/images/logo.png" alt="LMeterX Logo" width="300"/>
  <p>
    <a href="https://github.com/MigoXLab/LMeterX/blob/main/LICENSE"><img src="https://img.shields.io/github/license/MigoXLab/LMeterX" alt="License"></a>
    <a href="https://github.com/MigoXLab/LMeterX/stargazers"><img src="https://img.shields.io/github/stars/MigoXLab/LMeterX" alt="GitHub stars"></a>
  <a href="https://github.com/MigoXLab/LMeterX/network/members"><img src="https://img.shields.io/github/forks/MigoXLab/LMeterX" alt="GitHub forks"></a>
  <a href="https://github.com/MigoXLab/LMeterX/issues"><img src="https://img.shields.io/github/issues/MigoXLab/LMeterX" alt="GitHub issues"></a>
    <a href="https://deepwiki.com/MigoXLab/LMeterX"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
  </p>
  <p>
    <strong>简体中文</strong> |
    <a href="README.md">English</a>
  </p>
</div>

## 📋 项目简介

LMeterX 是一个专业的大语言模型性能测试平台，支持基于大模型推理框架（如 LiteLLM、vLLM、TensorRT-LLM、LMDeploy 等）的模型推理服务，同时也支持对 Azure OpenAI、AWS Bedrock、Google Vertex AI 等主流云服务进行性能测试。通过直观的 Web 界面，可以轻松创建和管理测试任务，实时监控测试过程，并获得详细的性能分析报告，为模型部署和性能优化提供可靠的数据支撑。


<div align="center">
  <img src="docs/images/images.gif" alt="LMeterX Demo" width="700"/>
</div>

## ✨ 核心特性

- **主流框架兼容**：适配 vLLM、LiteLLM、TRT-LLM 等主流推理框架及云平台，实现环境无缝迁移。
- **全模态全场景**：支持 GPT、Claude、Llama 及 [MinerU](https://github.com/opendatalab/MinerU)、[dots.ocr](https://github.com/rednote-hilab/dots.ocr) 等文档解析模型，涵盖文本、多模态与流式交互。
- **混合协议压测**：支持标准 Chat API 与业务 HTTP&nbsp;<img src="docs/images/badge-new.svg" alt="NEW" height="16" />接口，实现从底层模型到上层业务的全链路压测。
- **多模式高并发压测**：支持固定/阶梯式并发&nbsp;<img src="docs/images/badge-new.svg" alt="NEW" height="16" />策略，支持模拟超高并发，精准定位性能拐点与系统容量上限。
- **内置双模数据集**：预置高质量自建集与 ShareGPT 标准集，支持一键调用，大幅降低测试准备门槛。
- **智能自动化预热**&nbsp;<img src="docs/images/badge-new.svg" alt="NEW" height="16" />：支持模型自动预热，消除冷启动干扰，确保测试数据精准可靠。
- **多维指标可视化**：集成 TTFT、RPS、TPS 及吞吐分布等核心指标，支持性能数据实时追踪与可视化&nbsp;<img src="docs/images/badge-new.svg" alt="NEW" height="16" />。
- **系统资源监控**&nbsp;<img src="docs/images/badge-new.svg" alt="NEW" height="16" />：支持压测机 CPU、内存与网络带宽的实时监控，精准排除本地资源瓶颈
- **AI 驱动数据洞察**：AI 辅助分析报告&nbsp;<img src="docs/images/badge-new.svg" alt="NEW" height="16" />，支持多模型多维度结果对比，直观呈现性能优化方向。
- **一站式 Web 控制台**：直观管理任务调度、监控与实时日志，显著降低上手门槛与运维成本。
- **企业级架构安全**：支持分布式弹性部署与 LDAP/AD&nbsp;<img src="docs/images/badge-new.svg" alt="NEW" height="16" />集成，满足企业级高可用与安全认证需求。

### 工具对比

| 维度 | LMeterX | EvalScope | llmperf |
|------|---------|---------|-----------|
| 使用 | 提供 Web UI：任务创建、监控、停止全生命周期管理（压测） | CLI 命令行，面向 ModelScope 生态（效果评测和压测）| CLI 命令行，依赖 Ray 框架（压测） |
| 并发与压测 | 支持多进程、多任务、固定和阶梯式并发模式，企业级规模化压测 | 支持命令参数并发 | 支持命令参数并发 |
| 测试报告 | 支持多模型/多版本对比，AI 分析，提供可视化页面 | 基础报告 + 可视化图表（需额外安装 gradio, plotly等） | 简易报告 |
| 模型与数据支持 | 支持 OpenAI 格式，支持自定义数据和模型接口 | 默认支持 OpenAI 格式，扩展新 API 需自行实现代码 | 支持 OpenAI 格式 |
| 性能与资源监控| 支持实时监控性能指标和压测机资源情况 | - | - |
| 部署与扩展 | 提供 Docker / K8s 部署方案，易于弹性伸缩 | `pip` 或源码 | 源码 |

## 🏗️ 系统架构

LMeterX 采用微服务架构，由四个核心组件构成：

- **后端API服务** - FastAPI REST API，负责任务管理和数据存储
- **压测引擎** - Locust负载测试引擎，执行性能测试任务
- **前端界面** - React + TypeScript + Ant Design 现代化Web界面
- **MySQL数据库** - 存储测试任务、结果数据和配置信息

<div align="center">
  <img src="docs/images/tech-arch.png" alt="LMeterX tech arch" width="800"/>
</div>

## 🚀 快速开始

### 环境检查清单
- Docker 20.10.0+（确保 Docker 守护进程已启动）
- Docker Compose 2.0.0+（支持 `docker compose` 或 `docker-compose`）
- 至少 4GB 可用内存、5GB 磁盘空间

> **需要更多部署方式？** 请查阅 [完整部署指南](docs/DEPLOYMENT_GUIDE_CN.md)，获取 Kubernetes、离线环境等高级方案。

### 一键部署（推荐）

```bash
# 默认使用预构建镜像启动全套服务
curl -fsSL https://raw.githubusercontent.com/MigoXLab/LMeterX/main/quick-start.sh | bash
```

启动完成后可执行：
- `docker compose ps` 查看容器状态
- `docker compose logs -f` 追踪实时日志
- `docker compose up -d --scale backend=2 --scale engine=2` 服务扩容(如需)
- 在浏览器打开 http://localhost:8080（详见下方「使用指南」）

### 数据目录与挂载说明
- `./data` → 挂载到 `engine` 容器的 `/app/data`（大规模数据集不会打包进镜像，便于更新）
- `./logs` → 后端与压测引擎的统一日志输出目录
- `./upload_files` → 用户上传的自定义文件及导出的报表

如需准备自定义数据，请参考 [数据集使用指南](docs/DATASET_GUIDE.md)。

### 使用指南

1. **访问界面**: 打开 http://localhost:8080
2. **创建任务**: 导航至 测试任务 → 创建任务，配置 API 请求信息、测试数据以及请求响应字段映射
   - 2.1 基础信息: 对于 OpenAI-like 和 Claude-like API 只需填写 API 路径、模型与响应模式，也可在请求参数中补充完整 payload
   - 2.2 数据&负载: 根据需要选择数据集类型、并发数、压测时间等
   - 2.3 字段映射: 针对自定义 API 需要配置 payload 中 prompt 对应字段路径，以及响应数据中 content、reasoning_content、usage 等字段路径；该映射对于使用压测数据集和解析流式响应尤为关键
   > 💡 **提示**: 若需自定义图文数据集压测，请参考 [数据集使用指南](docs/DATASET_GUIDE.md) 了解数据准备、挂载与常见问题排查。
3. **API 测试**: 在 测试任务 → 创建任务，点击基础信息面板的「测试」按钮，快速验证接口连通性（建议使用简短 prompt）
4. **实时监控**: 访问 测试任务 → 日志/监控中心，查看全链路测试日志，快速定位异常
5. **结果分析**: 进入 测试任务 → 结果，查看详细性能指标并导出报告
6. **结果对比**: 在 模型擂台 模块选择多个模型/版本，进行多维度性能对比
7. **AI 分析**: 在 测试任务 → 结果/模型擂台 中配置 AI 分析服务后，可对单个或多任务进行智能评估

## 🔧 配置说明

### 数据库配置
```bash
=== 数据库配置 ===
DB_HOST=mysql
DB_PORT=3306
DB_USER=lmeterx
DB_PASSWORD=lmeterx_password
DB_NAME=lmeterx
```

### LDAP/AD 认证配置

```bash
=== LDAP 认证配置 ===
# 启用或禁用 LDAP 认证 (on/off)，默认关闭
LDAP_ENABLED=on

# LDAP 服务器连接配置
LDAP_SERVER=ldap://ldap.example.com    # LDAP 服务器地址
LDAP_PORT=389                          # LDAP 服务器端口 (389为LDAP，636为LDAPS)
LDAP_USE_SSL=false                     # 是否使用 SSL/TLS 连接 (LDAPS使用true)
LDAP_TIMEOUT=5                         # 连接超时时间(秒)

# LDAP 搜索配置
LDAP_SEARCH_BASE=dc=example,dc=com     # 用户搜索基准 DN
LDAP_SEARCH_FILTER=(sAMAccountName={username})  # LDAP 搜索过滤器

# 认证方式 1: 使用 DN 模板直接绑定(适用于简单 LDAP 场景)
LDAP_USER_DN_TEMPLATE=cn={username},ou=users,dc=example,dc=com

# 认证方式 2: 使用服务账号绑定(适用于 Active Directory)
LDAP_BIND_DN=cn=service,ou=users,dc=example,dc=com    # 服务账号 DN
LDAP_BIND_PASSWORD=service_password                   # 服务账号密码

# JWT 配置(可选)
JWT_SECRET_KEY=your-secret-key-here    # JWT 签名密钥(生产环境请修改)
JWT_EXPIRE_MINUTES=10080                 # Token 过期时间(分钟，默认7天)
```

**配置说明:**
- **简单 LDAP 部署**: 使用 `LDAP_USER_DN_TEMPLATE` 进行用户直接绑定
- **Active Directory**: 使用 `LDAP_BIND_DN` + `LDAP_BIND_PASSWORD` 进行服务账号绑定
- **安全性**: 生产环境务必设置 `LDAP_USE_SSL=true`
- **前端配置**: 设置 `VITE_LDAP_ENABLED=on` 以启用登录界面

### 资源配置
```bash
=== 高并发压测 部署要求 ===
# 当并发用户数超过此阈值，系统将自动启用多进程模式（需多核 CPU 支持）
MULTIPROCESS_THRESHOLD: 1000
# 每个子进程至少承载的并发用户数（避免进程过多导致资源浪费）
MIN_USERS_PER_PROCESS: 500
# ⚠️ 重要提示：
#   - 当并发量 ≥ 1000 时，强烈建议启用多进程以提升性能。
#   - 多进程模式依赖多核 CPU 资源，请确保部署环境满足资源要求
deploy:
  resources:
    limits:
      cpus: '2.0'    # 建议至少分配 2 核 CPU（高并发场景建议 4 核或以上）
      memory: 2G     # 内存限制，可根据实际负载调整（推荐 ≥ 2G）
```

### VictoriaMetrics 配置

LMeterX 使用 [VictoriaMetrics](https://victoriametrics.com/) 作为轻量级高性能时序数据库，用于存储实时性能指标及压测引擎的资源监控数据（CPU、内存、网络带宽）。

```bash
# ================= VictoriaMetrics 配置 =================
# VictoriaMetrics 服务地址（后端与引擎均需配置）
VICTORIA_METRICS_URL=http://victoria-metrics:8428

# 引擎资源采集间隔，单位秒（默认 2s）
RESOURCE_COLLECT_INTERVAL=2
```

`docker-compose.yml` 中的核心参数说明：

```yaml
victoria-metrics:
  image: victoriametrics/victoria-metrics:v1.106.1
  ports:
    - "8428:8428"             # HTTP API 及 UI 端口
  command:
    - "-retentionPeriod=7d"               # 数据保留周期（默认 7 天）
    - "-search.maxUniqueTimeseries=50000" # 查询允许的最大唯一时间序列数
    - "-memory.allowedPercent=60"         # 允许使用的内存占比（%）
  deploy:
    resources:
      limits:
        cpus: '1'
        memory: 2G
```

> **说明**：资源采集模块支持 cgroup v1 与 cgroup v2，可实现容器感知的精准监控。多引擎部署场景下，每个引擎实例通过唯一的 `engine_id` 标签加以区分（自动从容器 hostname 派生，或通过 `ENGINE_ID` / `ENGINE_POD_NAME` 环境变量显式指定）。

## 🤝 开发指南

> 💡 **欢迎贡献**！查看 [贡献指南](docs/CONTRIBUTING.md) 了解详情

### 技术栈

- **后端** - Python + FastAPI + SQLAlchemy + MySQL
- **压测引擎** - Python + Locust + 自定义扩展
- **前端** - React + TypeScript + Ant Design + Vite
- **部署** - Docker + Docker Compose + Nginx

### 开发环境搭建

1. **Fork项目** → 克隆到本地
2. **创建分支** → 进行功能开发
3. **代码检查** → 运行 `make all` 确保质量
4. **提交PR** → 遵循约定式提交规范
5. **文档更新** → 为新功能撰写文档

## 🗺️ 发展路线图

### 规划中
- [ ] CLI 命令行工具
- [ ] 多接口场景压测

## 📚 相关文档

- [部署指南](docs/DEPLOYMENT_GUIDE_CN.md) - 详细部署说明
- [贡献指南](docs/CONTRIBUTING.md) - 参与开发指南
- [数据集使用指南](docs/DATASET_GUIDE.md) - 自定义图文数据集准备与使用说明

## 👥 贡献者

感谢所有为 LMeterX 做出贡献的开发者：

- [@LuckyYC](https://github.com/LuckyYC) - 项目维护者 & 核心开发者
- [@del-zhenwu](https://github.com/del-zhenwu) - 核心开发者

## 🗂️ 数据集引用说明

> LMeterX 基于开源 ShareGPT 数据集构建测试样本，严格遵循原始许可要求。

- **数据来源**：使用 [ShareGPT 数据集](https://huggingface.co/datasets/learnanything/sharegpt_v3_unfiltered_cleaned_split) 作为原始对话语料
- **调整范围**：
  - 筛选高质量对话样本，剔除低质量或与压测场景无关的数据
  - 进行随机抽样，减轻数据规模的同时保留多样化对话

## 📄 开源许可

本项目采用 [Apache 2.0 许可证](LICENSE)。

<div align="center">

**⭐ 如果这个项目对您有帮助，请给我们一个 Star！您的支持是我们持续改进的动力。**

</div>