企业官网建设流程全解析

• 模型评测
• 人工智能
• 大模型
• AI 评测

导读

本文讲解如何在 OpenCompass 评测平台中使用 LightLLM，自 2023.11.20 起在 新闻页 正式对外宣布支持）。读完本文，你将掌握：如何用 LightLLM 将模型以 API 服务形式在本机拉起、如何验证服务可用、如何编写 OpenCompass 评测配置并通过python run.py一键完成从推理到指标计算的全流程，以及该链路在源码层面的工作原理与调优要点。

一、整体架构：OpenCompass 如何与 LightLLM 协作

OpenCompass 的评测分为"推理（infer）+ 指标计算（eval）"两个阶段，模型端既支持直接加载 Hugging Face 权重进行本地推理，也支持通过 API 访问外部推理服务。当选用 LightLLM 作为后端时，评测链路如下：

1. 用户先用 LightLLM 将模型权重加载到显存，并以 HTTP 服务的形式暴露在本地端口（默认http://localhost:8080/generate）；
2. 评测时 OpenCompass 通过requests以 JSON 格式将批量 prompt 喂给 LightLLM 的/generate接口；
3. LightLLM 完成推理后将generated_text返回；
4. OpenCompass 收集生成结果，交由数据集自带的评价器完成指标计算，最终产出评测报告。

这一适配在源码中体现为 LightllmAPI 模型类，它在 models/__init__.py 中被导出并注册进MODELS注册表，配置中通过type=LightllmAPI即可引用。同时，该文件还提供了面向对话/API 风格服务的LightllmChatAPI封装（见 lightllm_api.py），用于多轮对话格式（messages结构）的推理服务。

二、环境配置

2.1 安装 OpenCompass 并准备数据集

请参照 OpenCompass 官方安装指南完成算法库安装与评测数据集准备。数据集下载后，评测脚本会从本地数据集目录读取数据。

2.2 安装 LightLLM

按照 LightLLM 主页 的指引安装 LightLLM。文档特别提醒：注意对齐相关依赖库的版本，尤其是transformers的版本，因为 LightLLM 内部依赖 transformers 完成分词与模型加载，版本不匹配可能导致服务启动失败或生成行为异常。

三、评测实战：以 llama2-7B 评测 Humaneval 为例

以下以 llama2-7B 在 Humaneval 代码生成基准上的评测为例，演示完整流程。

3.1 第一步：用 LightLLM 将模型以服务形式拉起

在终端执行：

python -m lightllm.server.api_server --model_dir /path/llama2-7B \ --host 0.0.0.0 \ --port 1030 \ --nccl_port 2066 \ --max_req_input_len 4096 \ --max_req_total_len 6144 \ --tp 1 \ --trust_remote_code \ --max_total_token_num 120000

各启动参数含义如下：

关键注意事项（原文档明确给出，务必遵守）：

• --tp与多卡并行：tp可设置为大于 1 的整数，启用多张 GPU 上的 TensorParallel 推理，适用于较大的模型。例如--tp 2即在 2 张卡上做张量并行。
• --max_total_token_num影响吞吐：该参数直接影响测试过程中的吞吐性能，应按 LightLLM 主页 文档进行设置。它的本质是 KV cache 的容量上限，只要不爆显存，往往设置越大越好，因为更大的缓存意味着更高的并发吞吐和更少的显存不足触发。
• 同机多服务需换端口：如果要在同一台机器上启动多个 LightLLM 服务，必须重新设定--port和--nccl_port，避免端口冲突。

3.2 验证服务是否已启动成功

服务启动后，可以用下面这段 Python 脚本快速验证：

import time import requests import json url = 'http://localhost:8080/generate' headers = {'Content-Type': 'application/json'} data = { 'inputs': 'What is AI?', "parameters": { 'do_sample': False, 'ignore_eos': False, 'max_new_tokens': 1024, } } response = requests.post(url, headers=headers, data=json.dumps(data)) if response.status_code == 200: print(response.json()) else: print('Error:', response.status_code, response.text)

若返回 200 且响应中包含generated_text字段，说明服务可用。注意此处的url端口（8080）仅为演示，实际使用时必须与你启动服务时的--port保持一致。若后续要启用 PPL（困惑度）类评测任务，服务还需额外开启--return_all_prompt_logprobs参数并返回prompt_token_ids、prompt_logprobs字段（详见下文源码解析）。

3.3 第二步：编写评测配置并运行

仓库中已提供可直接运行的示例配置 examples/eval_lightllm.py，在 OpenCompass 项目根目录执行：

python run.py examples/eval_lightllm.py

当模型完成推理和指标计算后，即可在终端/输出目录获得评测结果。

重要提示：eval_lightllm.py中配置的url必须与上一步 LightLLM 服务的地址对齐（端口、host 完全一致），否则 OpenCompass 将无法请求到服务。

3.4 深入解读示例配置

examples/eval_lightllm.py 的核心配置结构如下（为便于阅读做了整理）：

from mmengine.config import read_base from opencompass.models import LightllmAPI from opencompass.partitioners import NaivePartitioner from opencompass.runners import LocalRunner from opencompass.tasks import OpenICLInferTask with read_base(): from opencompass.configs.datasets.humaneval.deprecated_humaneval_gen_a82cae import \ humaneval_datasets from opencompass.configs.summarizers.leaderboard import summarizer datasets = [*humaneval_datasets] _meta_template = None # 如需 Chat 模型可替换为对应的 meta_template models = [ dict( abbr='LightllmAPI', type=LightllmAPI, url='http://localhost:1030/generate', meta_template=_meta_template, batch_size=32, max_workers_per_task=128, rate_per_worker=1024, retry=4, generation_kwargs=dict(do_sample=False, ignore_eos=False, max_new_tokens=1024), ), ] infer = dict( partitioner=dict(type=NaivePartitioner), runner=dict( type=LocalRunner, max_num_workers=32, task=dict(type=OpenICLInferTask), ), )

各字段在源码中的语义（对照 lightllm_api.py 的构造函数）：

其余配置遵循 OpenCompass 标准约定：NaivePartitioner将数据集按样本朴素切分，LocalRunner在本地以max_num_workers=32并发执行OpenICLInferTask。若使用其他数据集，只需替换read_base中导入的*_datasets即可。

四、源码级原理：LightllmAPI 的请求链路

4.1 生成（generate）链路

LightllmAPI.generate()（lightllm_api.py）使用ThreadPoolExecutor按max_workers_per_task并发地对每个输入调用内部方法_generate。每个请求的核心逻辑（lightllm_api.py）：

1. 调用self.wait()从令牌桶获取令牌，实现rate_per_worker限流；
2. 构造data = dict(inputs=input, parameters=self.generation_kwargs)，即把 prompt 与生成参数一并打包；
3. 以 JSON 形式POST到self.url；
4. 解析响应中的generated_text（若为列表则取第一个元素）并返回；
5. 若遇requests.ConnectionError（服务未启动、网络中断）则记录日志并重试；若 JSON 解析失败或缺少generated_text键也进入重试；重试耗尽后抛出RuntimeError。

可以看到，generation_kwargs是透传给服务端的关键通道，max_new_tokens等参数最终决定服务端生成的长度。self.max_out_len也从generation_kwargs.get('max_new_tokens', 1024)读取（lightllm_api.py）。

4.2 PPL（困惑度）链路与 LightLLM 服务的额外要求

LightllmAPI同样实现了get_ppl()/_get_ppl()（lightllm_api.py），用于困惑度类（PPL）评测任务。它对响应有严格校验：

• 响应中必须包含prompt_token_ids和prompt_logprobs字段，否则会断言失败，并提示在启动 LightLLM 服务时添加--return_all_prompt_logprobs参数；
• 随后取出每个 token 对应的 logprob，计算平均交叉熵损失ce_loss = -sum(logprobs) / len(logprobs)作为 PPL 得分。

因此，如果你的评测集属于 PPL 型（如部分选择题、语言建模类基准），启动 LightLLM 服务时必须追加--return_all_prompt_logprobs，否则 PPL 评测会因响应字段缺失而失败。生成（gen）型评测则无此要求。

4.3 流控机制：TokenBucket 与 rate_per_worker

LightllmAPI使用 base_api.py 中定义的TokenBucket实现限流：后台线程按rate_per_worker的速率向信号量补充令牌，wait()则阻塞获取一个令牌，从而保证对服务端的请求频率可控，避免压垮本地推理服务。这与BaseAPIModel体系的query_per_second思路一致（参见 base_api.py）。

4.4 配套的 Chat 服务封装：LightllmChatAPI

如果 LightLLM 服务暴露的是 OpenAI 风格的messages对话接口（/chat类），可使用 LightllmChatAPI（继承自BaseAPIModel）。它会将 OpenCompass 的PromptList（含HUMAN/BOT角色）转换为{'role': 'user'/'assistant', 'content': ...}的消息列表（lightllm_api.py），并通过query_per_second控制请求速率、按retry处理 401/400/429 等状态码（lightllm_api.py），适用于对话评测场景。

五、常见问题与调优建议

调优的核心思路是以"不爆显存"为前提最大化max_total_token_num以提升吞吐，同时结合数据集类型选择合适的评测范式（gen 型无需额外参数，PPL 型需开启--return_all_prompt_logprobs）。

六、相关资源

• 官方教程：本文中文原版见 docs/zh_cn/advanced_guides/evaluation_lightllm.md，英文版见 docs/en/advanced_guides/evaluation_lightllm.md
• 核心实现：opencompass/models/lightllm_api.py（LightllmAPI、LightllmChatAPI）
• 示例配置：examples/eval_lightllm.py
• 基类与限流：opencompass/models/base_api.py
• 模型注册入口：opencompass/models/__init__.py
• 适配历史：见 docs/zh_cn/notes/news.md（2023.11.20 由社区贡献支持 LightLLM 后端评测）

• 模型评测
• 人工智能
• 大模型
• AI 评测