PDFTranslator API性能压测：Locust模拟高并发翻译请求

最新推荐文章于 2026-08-19 17:55:17 发布

原创最新推荐文章于 2026-08-19 17:55:17 发布 · 226 阅读

3 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

在接入任何第三方API之前，了解其性能边界都是必要的。本文介绍如何用Locust对PDF翻译API做压力测试，获取吞吐量、响应延迟、错误率等关键指标。

背景

假设你正在开发一个内部文档翻译系统，需要调用PDFTranslator API处理上传的PDF文件。在上线前，你需要回答几个问题：

单个并发用户下的平均响应时间是多少？
系统能支持多少并发用户而不明显降速？
在什么并发量下开始出现失败请求？
大文件和小文件的性能差异有多大？

Locust是一个Python编写的负载测试工具，适合模拟真实用户行为，可以很好地回答这些问题。

环境准备

pip install locust requests python-dotenv

需要准备：

测试用的PDF文件（建议准备小、中、大三个样本）
API endpoint和认证信息
一个Locust测试脚本

测试目标API说明

本文以通用的PDF翻译API为例，接口形式通常为：

POST /api/translate
Content-Type: multipart/form-data

file: <PDF文件>
target_lang: <目标语言，如 zh>

响应示例：

{
  "task_id": "abc123",
  "status": "processing"
}

实际测试时，请替换为你使用的真实API地址和参数。

Locust测试脚本

import os
import time
from pathlib import Path
from locust import HttpUser, task, between
from dotenv import load_dotenv

load_dotenv()

# 测试文件路径
TEST_FILES = {
    "small": "samples/5pages.pdf",
    "medium": "samples/30pages.pdf",
    "large": "samples/100pages.pdf",
}

class PDFTranslateUser(HttpUser):
    """模拟调用PDF翻译API的用户"""
    
    wait_time = between(1, 3)  # 每个任务之间等待1-3秒
    
    def on_start(self):
        """每个用户启动时执行"""
        self.api_key = os.getenv("PDFTRANSLATOR_API_KEY", "")
        self.headers = {}
        if self.api_key:
            self.headers["Authorization"] = f"Bearer {self.api_key}"
    
    def upload_pdf(self, file_key: str):
        """上传PDF并请求翻译"""
        file_path = TEST_FILES[file_key]
        if not Path(file_path).exists():
            print(f"File not found: {file_path}")
            return
        
        with open(file_path, "rb") as f:
            files = {"file": (Path(file_path).name, f, "application/pdf")}
            data = {"target_lang": "zh"}
            
            start_time = time.time()
            with self.client.post(
                "/api/translate",
                files=files,
                data=data,
                headers=self.headers,
                catch_response=True,
                name=f"translate_{file_key}",
            ) as response:
                elapsed = time.time() - start_time
                
                if response.status_code == 200:
                    response.success()
                    print(f"[{file_key}] Success in {elapsed:.2f}s")
                else:
                    response.failure(f"Status {response.status_code}: {response.text[:200]}")
    
    @task(5)
    def translate_small(self):
        self.upload_pdf("small")
    
    @task(3)
    def translate_medium(self):
        self.upload_pdf("medium")
    
    @task(1)
    def translate_large(self):
        self.upload_pdf("large")

运行压测

启动Locust：

locust -f locust_pdf_translate.py

然后打开浏览器访问 http://localhost:8089，设置并发用户数和 ramp-up 速率。

建议分阶段测试：

阶段	并发用户	持续时间	目的
基准测试	1	5分钟	获取单用户基线
轻负载	5	10分钟	观察正常并发表现
中负载	20	10分钟	寻找性能拐点
高负载	50+	10分钟	观察错误率和延迟

关键指标解读

Locust Web界面会展示以下核心指标：

指标	含义	关注重点
Requests/s	每秒请求数	吞吐量
50%/95%/99% percentile	响应时间分位值	长尾延迟
Failures	失败请求数/率	稳定性
RPS/User	每用户平均请求率	用户行为真实性

实际压测中，你可能会观察到这样的曲线：

低并发时，响应时间稳定，错误率接近0。
达到一定并发后，响应时间开始明显上升。
继续加压，错误率开始增加，出现排队或超时。

这个拐点就是你需要关注的"性能边界"。

结果记录模板

建议每次压测后记录：

## 压测配置
- 并发用户：20
- Ramp-up：2用户/秒
- 持续时间：10分钟
- 测试文件：small(5页) / medium(30页) / large(100页)

## 关键结果
| 文件大小 | RPS | 平均响应时间 | 95%响应时间 | 错误率 |
|----------|-----|--------------|-------------|--------|
| small    | 2.1 | 1.2s         | 2.5s        | 0%     |
| medium   | 0.8 | 4.5s         | 8.1s        | 0%     |
| large    | 0.2 | 15.3s        | 28.7s       | 2%     |

## 结论
- 小文件性能良好，20并发无压力
- 大文件建议限制并发数或增加队列机制

优化建议

根据压测结果，可以考虑以下优化：

文件预处理：大文件先拆分再翻译，避免单任务耗时过长。
异步队列：用Celery + Redis接收翻译任务，避免客户端长时间等待。
限流保护：在客户端或服务端设置并发上限，防止拖垮服务。
缓存机制：相同文件的翻译结果可以缓存，减少重复计算。
重试策略：对偶发失败的任务做指数退避重试。

完整代码结构

pdf_translate_load_test/
├── locust_pdf_translate.py
├── samples/
│   ├── 5pages.pdf
│   ├── 30pages.pdf
│   └── 100pages.pdf
├── .env
└── requirements.txt

.env 示例：

PDFTRANSLATOR_API_KEY=your_api_key_here

requirements.txt：

locust>=2.24.0
requests>=2.31.0
python-dotenv>=1.0.0

总结

Locust是评估PDF翻译API性能的有效工具。通过模拟真实并发场景，你可以获得清晰的性能边界数据，为系统设计和容量规划提供依据。

需要强调的是，压测结果取决于测试环境、网络状况、文件大小和API实现。建议在自己的真实环境中复测，并根据业务需求设定合理的SLA。

标签：PDF翻译、Python自动化、Locust、性能测试、API测试

标签

#git #java #github #python #pdf