Skip to content

README_CN.md

Latest commit

 

History

History
258 lines (197 loc) · 12.9 KB

README_CN.md

File metadata and controls

258 lines (197 loc) · 12.9 KB
LMeterX Logo

License GitHub stars GitHub forks GitHub issues Ask DeepWiki

简体中文 | English

📋 项目简介

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

LMeterX Demo

✨ 核心特性

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

工具对比

维度 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数据库 - 存储测试任务、结果数据和配置信息
LMeterX tech arch

🚀 快速开始

环境检查清单

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

需要更多部署方式？ 请查阅 完整部署指南，获取 Kubernetes、离线环境等高级方案。

一键部署（推荐）

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

启动完成后可执行：

数据目录与挂载说明

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

如需准备自定义数据，请参考 数据集使用指南。

使用指南

  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 等字段路径；该映射对于使用压测数据集和解析流式响应尤为关键

    💡 提示: 若需自定义图文数据集压测，请参考 数据集使用指南 了解数据准备、挂载与常见问题排查。

  3. API 测试: 在 测试任务 → 创建任务，点击基础信息面板的「测试」按钮，快速验证接口连通性（建议使用简短 prompt）
  4. 实时监控: 访问 测试任务 → 日志/监控中心，查看全链路测试日志，快速定位异常
  5. 结果分析: 进入 测试任务 → 结果，查看详细性能指标并导出报告
  6. 结果对比: 在 模型擂台 模块选择多个模型/版本，进行多维度性能对比
  7. AI 分析: 在 测试任务 → 结果/模型擂台 中配置 AI 分析服务后，可对单个或多任务进行智能评估

🔧 配置说明

数据库配置

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

LDAP/AD 认证配置

=== 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 以启用登录界面

资源配置

=== 高并发压测 部署要求 ===
# 当并发用户数超过此阈值，系统将自动启用多进程模式（需多核 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 作为轻量级高性能时序数据库，用于存储实时性能指标及压测引擎的资源监控数据（CPU、内存、网络带宽）。

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

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

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

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 环境变量显式指定）。

🤝 开发指南

💡 欢迎贡献！查看 贡献指南 了解详情

技术栈

  • 后端 - 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 命令行工具
  • 多接口场景压测

📚 相关文档

👥 贡献者

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

🗂️ 数据集引用说明

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

  • 数据来源：使用 ShareGPT 数据集 作为原始对话语料
  • 调整范围：
    • 筛选高质量对话样本，剔除低质量或与压测场景无关的数据
    • 进行随机抽样，减轻数据规模的同时保留多样化对话

📄 开源许可

本项目采用 Apache 2.0 许可证。

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