用 FlagEval 自动评测接口完成模型多芯片评测与结果对比

FlagEval 天秤平台提供两类评测方式：在线评测由用户提供模型推理接口，平台用自带测试数据发起推理；离线评测则由用户上传模型与推理代码，平台提供算力。在这之上还有一层自动化封装——自动评测工具（Auto-Evaluation），它把「开启评测、查进度、看结果、停止、重启、多芯片结果差异分析」做成一组 HTTP 接口，覆盖 LLM、VLM 与具身 VLM 三个领域，并绑定了各领域的经典数据集。本文讲的是如何用这组接口把一次模型评测从提交跑到出结果，适合已经把模型部署成公网可访问服务、希望用脚本而不是网页表单来驱动评测的个人、团队或企业。平台侧的操作入口与排行榜可以在 FlagEval 上找到。

需要先说明一点：自动评测目前只支持在线评测模式，也就是你的模型必须已经以服务形式跑起来，并且能从公网访问。它不负责替你部署模型，也不负责分配推理算力。接口返回的评测结果目前只覆盖 mmlu 与 gsm8k 两个数据集，这一点在规划评测范围时要提前考虑。

准备工作

账号与平台权限

未注册用户只能查看首页、新闻、排行榜和用户手册，可以体验大模型角斗场与 Debate 辩论赛，但不能提交评测任务。要使用评测功能，需要先完成注册并通过管理员审核。

注册时线上填写邮箱、手机号与验证码。表单中有几项需要特别注意：

• 用户名：作为平台唯一标识，填写后不允许修改。长度 3 到 32 个字符，只支持小写字母和数字，且必须以小写字母开头。建议用姓名全拼加数字。
• 真实姓名：填写个人真实姓名，管理员审核时会优先通过。
• 组织机构：建议写成「机构 + 部门」的形式，并且需要中英文双语填写。真实、完整的组织机构信息同样有助于审核优先通过。
• 评测方式：在在线评测与离线评测之间选择。走自动评测接口的读者应选择在线评测。
• 是否评测自研模型：是 / 否单选。
• 协议声明：必须阅读并同意协议后才能使用评测功能。

邮箱和手机号务必填写有效，审核状态会通过邮件和短信通知，后续评测任务的状态也会通过邮件推送。每个用户每个月有 1 次修改邮箱的机会，注册时不要填错。

平台也支持通过 Hugging Face 第三方账号登录：点击 Hugging Face 登录入口后跳转到其登录界面，输入用户名或邮箱地址与密码即可；没有账号的先注册，也可以通过授权方式登录。

模型服务与网络条件

自动评测的前提是模型已经部署为服务，并且该服务支持公网可访问。接口中的 eval_url 字段就是用来填这个服务地址的。在算力资源上把服务开起来、确认外部能访问到，是调用评测接口之前必须完成的一步。

需要提前确定的参数

提交评测前，建议先把下面这些值想清楚，它们都会作为请求体字段传入：

• 评测领域 domain：NLP 或 MM。
• 评测任务名称 eval_model：必须唯一。如果这次评测的是 Nvidia 基线模型，命名要用 xxx-nvidia-origin 的形式，以便区分。
• 模型标识 model：模型部署为服务时使用的模型名。同名模型多次开启评测会复用同一份缓存。
• tokenizer 信息 tokenizer：填写厂商及模型信息，例如 Qwen/Qwen3-8B。
• 芯片名称 chip：格式为「厂商-芯片名称」，默认 Nvidia-H100。
• 生成参数 gen_kwargs：以逗号分隔，例如 temperature=0.6,top_k=20,top_p=0.95,min_p=0。

操作步骤

第一步：在平台上创建评测任务

登录后进入【评测管理】页面，这里包含模型评测、创新算法评测和镜像管理三块。按需求选择模型评测或创新算法评测，点击【创建评测】，在弹出的对话框中按所选评测领域填写表单，提交后即生成一条评测任务。

提交后页面会自动跳转到详情页。详情页里可以查看【上传模型&代码】规范，按规范用 flageval-serving 上传模型与代码。上传完成后先点【推理验证】快速确认推理评测代码能否跑通，验证通过再点【启动推理评测】进入正式评测。评测过程中如果中断失败，可以通过日志查看错误信息。

如果评测需要自定义运行环境，可以在【镜像管理 / 自定义镜像 / 导入镜像】中填写表单提交，等待平台管理员审核，审核通过后镜像会自动导入，导入成功之后才能在评测任务中使用。需要注意，平台目前只支持导入已有镜像，不支持用 dockerfile 在平台上构建镜像；用户填写的 dockerfile 仅供平台审核人员审查镜像之用。

第二步：调用开启评测接口

自动评测工具的服务地址为 120.92.17.239:5050。开启评测使用 /evaluation 接口，方法为 POST，采用同步方式调用上传的服务 URL 开始模型推理。请求头需要设置：

"Content-Type": "application/json"

请求体顶层字段如下：

参数	类型	含义	是否必须
eval_infos	EvalInfo[]	模型评测服务信息列表	是
domain	string	评测领域：NLP、MM	是
mode	string	评测项目标识，有默认值	否
region	string	评测工具集群：bj（默认）、sz	否
special_event	string	是否为芯片评测，默认是	否
user_id	int	FlagEval 平台的用户 id	否

eval_infos 数组里每个元素的字段如下：

参数	类型	含义	是否必须
eval_model	string	评测任务名称，需唯一；Nvidia 基线模型用 xxx-nvidia-origin 命名	是
model	string	模型部署为服务时使用的模型，同名模型多次评测共用缓存	是
eval_url	string	各模型部署服务的评测接口地址	是
tokenizer	string	厂商及模型信息，如 Qwen/Qwen3-8B	是
api_key	string	模型调用 API_KEY，默认 "EMPTY"	否
batch_size	int	模型可开启的 batch_size，默认 1	否
num_concurrent	int	并发数，默认 1	否
num_retry	int	重试次数，默认 10	否
gen_kwargs	string	温度、top_k 等生成参数，逗号分隔	否
thinking	bool	是否开启 thinking 模型，暂只对 EmbodiedVerse 的 RoboBrain 适用，默认 False	否
retry_time	int	超时时间，暂支持 MM、具身领域，目前默认 3600s	否
chip	string	评测使用芯片名称，格式「厂商-芯片名称」，默认 Nvidia-H100	否
base_model_name	string	评测使用的基础模型，如 Qwen3-8B	否

关于 gen_kwargs 有一个容易踩的细节：NLP 领域使用 max_gen_toks 控制生成长度，如果模型的 max_model_len 是 16384，应设置 max_gen_toks=16000；MM 与 EV 领域同样用 max_gen_toks 字段指定。

由于模型评测耗时较长，该接口不会同步等到结果，而是先返回评测 id 与 batch id，后续用这些信息查询结果。返回字段包括：

• err_code：0 表示请求处理成功，1 表示失败；为 1 时返回数据中不包含 request_id。
• err_msg：请求处理消息。
• request_id：唯一标识，后续所有查询、停止、重启操作都要用到。
• eval_tasks：各个服务开启的评测详细信息。

第三步：查询评测进度

用 /evaluation_progress 接口（POST）查看进度，请求体需要两个字段：request_id（必须）与 domain（必须，NLP 或 MM）。返回内容包括：

• err_code、err_message：处理结果与消息。
• finished：评测是否完成。
• status：评测状态。
• datasets_progress：数据集进度。
• running_dataset：正在运行的数据集。
• running_progress：当前数据集内的评测进度。

第四步：查询评测结果

用 /evaldiffs 接口（GET）查询评测结果，请求体传 request_id。返回的 eval_results 是一个映射结构，键为开启评测时对应的 eval_model，值为该模型的评测结果数组。每个结果包含：

• status：评测状态，取值含义为 S 成功、F 失败、C 取消、OOR 超过重试次数。
• details：该评测服务在各数据集上的结果，目前只支持 mmlu 与 gsm8k。
• release：该模型是否可发布，判断依据是 diff 是否在可接受范围内。

details 中每一项包含 dataset（数据集名称）、status（S 成功、F 失败、C 取消）、accuracy（数据集评测结果）与 diff（与 Nvidia 基线的差异）。

第五步：停止或重启评测

如果服务出现问题需要暂停，调用 /stop_evaluation（POST），请求体只传 request_id，返回 err_code 与 err_message。

需要继续时调用 /resume_evaluation（POST），同样只传 request_id。重启支持断点续评，不必从头再跑一遍。

第六步：对比多个模型的评测差异

多芯片评测结果差异分析使用 /evaluation_diffs 接口（POST），请求体传 request_ids，类型为字符串数组。返回的 eval_diffs 是评测结果差异对比列表，每一项包含：

• request_id：被评估的评测记录 uuid。
• details：各数据集的详细对比数据。
• release：是否满足发布条件。

其中 details 的每一项包含 dataset（数据集名称）、base_acc（基线得分）、accuracy（被评估评测的数据集得分）与 diff（被评估数据集与基线的差值）。把同一模型在不同芯片上的评测记录 id 一起传进去，就能直接看出芯片之间的分数差异。

一个完整示例

下面用一次 NLP 领域的评测走完整流程。假设模型服务已经部署好并可从公网访问，服务地址为 http://example-host:8000/v1/completions，平台用户 id 为 12345。

1. 开启评测

curl -X POST http://120.92.17.239:5050/evaluation \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "NLP",
    "region": "bj",
    "user_id": 12345,
    "eval_infos": [
      {
        "eval_model": "qwen3-8b-h100-run1",
        "model": "Qwen3-8B",
        "eval_url": "http://example-host:8000/v1/completions",
        "tokenizer": "Qwen/Qwen3-8B",
        "api_key": "EMPTY",
        "batch_size": 1,
        "num_concurrent": 4,
        "num_retry": 10,
        "gen_kwargs": "temperature=0.6,top_k=20,top_p=0.95,min_p=0,max_gen_toks=16000",
        "chip": "Nvidia-H100",
        "base_model_name": "Qwen3-8B"
      }
    ]
  }'

返回中 err_code 为 0 时，记下 request_id，后续每一步都用它。如果 err_code 为 1，返回里不会有 request_id，需要根据 err_msg 排查请求体。

2. 轮询进度

curl -X POST http://120.92.17.239:5050/evaluation_progress \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "<上一步返回的 request_id>",
    "domain": "NLP"
  }'

反复调用直到 finished 为 true。期间可以通过 running_dataset 与 running_progress 判断当前卡在哪个数据集、跑到什么位置。

3. 取结果

curl -X GET http://120.92.17.239:5050/evaldiffs \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "<上一步返回的 request_id>"
  }'

在返回的 eval_results 里按 eval_model 找到本次任务，检查 status 是否为 S，再看 details 中 mmlu 与 gsm8k 的 accuracy 和 diff。release 为 true 表示该模型可以发布。

4. 换芯片再跑一次并对比

把同样的请求再提交一次，只改 eval_model（例如改成 qwen3-8b-ascend-run1）与 chip（改成对应的「厂商-芯片名称」），拿到第二个 request_id。然后调用差异接口：

curl -X POST http://120.92.17.239:5050/evaluation_diffs \
  -H "Content-Type: application/json" \
  -d '{
    "request_ids": ["<H100 的 request_id>", "<另一芯片的 request_id>"]
  }'

返回的 eval_diffs 中，每个 request_id 对应一组 details，逐数据集给出 base_acc、accuracy 与 diff，据此判断不同芯片上的分数偏差是否在可接受范围内。

5. 中途出问题时的处理

如果推理服务异常，先停止：

curl -X POST http://120.92.17.239:5050/stop_evaluation \
  -H "Content-Type: application/json" \
  -d '{"request_id": "<request_id>"}'

服务恢复后重启，断点续评：

curl -X POST http://120.92.17.239:5050/resume_evaluation \
  -H "Content-Type: application/json" \
  -d '{"request_id": "<request_id>"}'

注意事项

• 只支持在线评测：自动评测工具目前仅支持开启在线评测，模型必须先部署成公网可访问的服务。
• 结果数据集有限：评测结果目前只覆盖 mmlu 与 gsm8k，不要期待在这组接口里拿到其他数据集的分数。
• 用户名不可改：注册时填写的用户名是平台唯一标识，提交后无法修改，长度 3 到 32 位、小写字母开头、只含小写字母与数字。
• 邮箱修改有次数限制：每个用户每月只能修改 1 次邮箱，注册时务必核对。
• eval_model 必须唯一：重复的名称会让评测记录难以区分；评测 Nvidia 基线模型时按 xxx-nvidia-origin 命名。
• 同名模型共用缓存：model 字段相同的多次评测会使用同一份缓存，换模型或换配置时注意这一点。
• max_gen_toks 要留余量：NLP 领域若模型 max_model_len 为 16384，应设 max_gen_toks=16000，不要顶满。
• 超时时间适用范围：retry_time 目前只支持 MM 与具身领域，默认 3600s。
• thinking 参数适用范围：thinking 暂只对 EmbodiedVerse 的 RoboBrain 生效。
• 镜像只能导入不能构建：平台不支持用 dockerfile 构建镜像，填写的 dockerfile 仅用于审核人员审查；镜像需经管理员审核通过并自动导入后才能在评测任务中使用。
• 状态码要会读：S 成功、F 失败、C 取消、OOR 超过重试次数；err_code 为 1 时返回中不含 request_id。
• 审核与通知走邮件短信：注册审核结果、后续评测任务状态都通过邮件（及短信）通知，请保持联系方式有效。

接口地址、默认值、支持的数据集与领域范围都可能随平台迭代调整，实际使用前请以官网当前信息为准。