evalstone/DOCKER_SOP_BEGINNER.md

EvalScope Docker 评测 SOP（新手版）

本文档以 P800-02 为例，假设模型已经由 /data1/yy/deploy_dsv4.sh 部署为 OpenAI 兼容 API。

0. 固定目录

统一使用以下目录，避免宿主机和容器路径混淆：

export EVAL_ROOT=/data1/sora/temp/evalstone
export IMAGE=evalscope-complete-py312:latest
export MODEL=DeepSeek-V4-Flash-INT8
export API_URL=http://127.0.0.1:30000/v1

重要：EvalScope 会自动在 --dataset-dir 后查找 datasets/，所以数据位于 $EVAL_ROOT/datasets/ 时，必须传 $EVAL_ROOT，不能传 $EVAL_ROOT/datasets。

1. 检查机器和目录

test -d "$EVAL_ROOT" && echo '代码目录 OK'
test -d /data1/models/DeepSeek-V4-Flash-INT8 && echo '模型目录 OK'
docker version
docker image inspect "$IMAGE" >/dev/null && echo '评测镜像 OK'

若代码不存在：

git clone https://git.meta-stone.net/sora/evalstone.git "$EVAL_ROOT"

2. 下载数据集

mkdir -p "$EVAL_ROOT/datasets"
modelscope download \
  --repo-type dataset \
  --local_dir "$EVAL_ROOT/datasets" \
  SoraAmami/evalscope-datasets

验证数据没有多套 datasets/ 嵌套：

test -d "$EVAL_ROOT/datasets"
find "$EVAL_ROOT/datasets" -mindepth 1 -maxdepth 1 -type d | head
test ! -d "$EVAL_ROOT/datasets/datasets" && echo '数据目录结构 OK'

3. 安装/验证 Python 入口

评测代码内置 EvalScope 源码。宿主机直接运行时：

cd "$EVAL_ROOT"
python3 -m py_compile bash/run.py
python3 bash/run.py --help

Docker 中运行时，使用 /opt/evalscope，不要使用不存在的 /workspace/evalscope。

4. 启动并验证模型

bash /data1/yy/deploy_dsv4.sh int8 30000

验证 OpenAI API：

curl -sS "$API_URL/models"

必须能看到模型列表。若 /health 返回空响应但 /v1/models 正常，以 /v1/models 为准。

5. 准备代码执行 sandbox

humaneval 和 bigcodebench 需要 Docker sandbox：

docker pull python:3.11-slim
docker pull bigcodebench/bigcodebench-evaluate:latest
cd "$EVAL_ROOT"
docker build -t bigcodebench-sandbox:latest -f - . <<'EOF'
FROM bigcodebench/bigcodebench-evaluate:latest
ENTRYPOINT []
CMD ["tail", "-f", "/dev/null"]
EOF

6. Docker 运行评测容器

mkdir -p "$EVAL_ROOT/output"
docker run --rm --network host \
  -v "$EVAL_ROOT:/opt/evalscope" \
  -v /data1/models:/opt/models:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  "$IMAGE" bash -lc '
    cd /opt/evalscope
    python3 bash/run.py --help
  '

关键路径规则：

• 宿主机 $EVAL_ROOT 对应容器 /opt/evalscope
• 容器内数据目录是 /opt/evalscope/datasets
• --dataset-dir 填 /opt/evalscope
• --tokenizer-path 填 /opt/models/DeepSeek-V4-Flash-INT8

7. 先做一条样本 smoke test

docker run --rm --network host \
  -v "$EVAL_ROOT:/opt/evalscope" \
  -v /data1/models:/opt/models:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  "$IMAGE" bash -lc '
    cd /opt/evalscope
    python3 bash/run.py \
      --model DeepSeek-V4-Flash-INT8 \
      --api-url http://127.0.0.1:30000/v1 \
      --dataset-dir /opt/evalscope \
      --output-dir /opt/evalscope/output_smoke \
      --tokenizer-path /opt/models/DeepSeek-V4-Flash-INT8 \
      --datasets gsm8k \
      --limit 1 \
      --batch-size 1
  '

smoke test 成功标准：生成 output_smoke/，并出现 reports/gsm8k.json。

8. Suite 选择

full             28 个：完整标准评测
lite              6 个：快速检查
mid              13 个：中等规模
k3                 9 个：gpqa_diamond、hle、terminal_bench_v2、browsecomp、
                       mcp_atlas、officeqa、deepsearchqa、jobbench、automation_bench
tencent_hunyuan    当前为空，等清单确认后再启用

正式运行示例：

python3 bash/run.py \
  --model DeepSeek-V4-Flash-INT8 \
  --api-url http://127.0.0.1:30000/v1 \
  --dataset-dir /data1/sora/temp/evalstone \
  --output-dir /data1/sora/temp/evalstone/output \
  --tokenizer-path /data1/models/DeepSeek-V4-Flash-INT8 \
  --suite lite \
  --limit none \
  --batch-size 4

也可以覆盖 suite：

python3 bash/run.py --datasets gsm8k,arc --limit none

9. 查看结果

find "$EVAL_ROOT/output" -name '*.json' | sort
python3 - <<'PY'
import glob, json
for f in sorted(glob.glob('/data1/sora/temp/evalstone/output/*/seed_*/reports/*/*.json')):
    d=json.load(open(f))
    print(f, d.get('score', d.get('mean_acc', 'N/A')))
PY

10. 常见问题

• ModuleNotFoundError: evalscope：使用仓库最新版 bash/run.py，或在容器内从 /opt/evalscope 执行。
• 找不到数据：确认 --dataset-dir 指向父目录，而不是 datasets/。
• API 连接失败：先执行 curl http://127.0.0.1:30000/v1/models。
• XCCL shmget errno=17：检查其他 XPU 任务和残留共享内存，不要未经确认执行全局 ipcrm。
• Docker sandbox 失败：确认已加载 python:3.11-slim 和 bigcodebench-sandbox:latest。
• Excel 汇总失败：镜像和宿主机应包含 openpyxl；可验证 python3 -c 'import openpyxl'。

11. 清理

只删除本次输出，不删除数据和模型：

rm -rf "$EVAL_ROOT/output_smoke"

删除 Docker benchmark 镜像前，必须确认没有其他评测任务使用它们。

12. Benchmark 与环境矩阵

当前 full 套件共 28 项：

类型	数量	Benchmark	环境要求
Multi-run	8	humaneval、live_code_bench、aime24、aime25、aime26、hmmt26、imo_answerbench、gpqa_diamond	普通 API；humaneval 另需代码 sandbox
Single-run	18	bigcodebench、bfcl_v3、competition_math、gsm8k、hle、super_gpqa、arc、bbh、cmmlu、drop、hellaswag、mmlu、mmlu_pro、simple_qa、trivia_qa、winogrande、openai_mrcr、longbench_v2	普通 API；bigcodebench 另需代码 sandbox；长文本项目需要 tokenizer
Agent	2	tau2_bench、general_fc	API、judge API 和工具/Agent 配置

套件数量：full=28、lite=6、mid=13、k3=9。tencent_hunyuan 已预留入口，具体清单确认后再启用。

13. 环境构建代码索引

仓库中已有以下环境脚本和说明：

环境	构建/加载代码
EvalScope 主镜像	DOCKER_BUILD.md、DOCKER_README.md
BigCodeBench sandbox	本文第 5 节的 Dockerfile；Dockerfile.withcode
Humaneval	bash/run.py 的 SANDBOX_CONFIGS，使用 python:3.11-slim
SWE-bench 镜像	bash/load_swe_images.sh、bash/save_swe_images.sh
Terminal Bench	bash/images_load/preload_terminal_bench_images.sh
Docker 镜像清理	bash/cleanup_docker_images.sh
SWE 镜像诊断	bash/diagnose_swe_images.py

构建代码 sandbox：

cd "$EVAL_ROOT"
docker pull bigcodebench/bigcodebench-evaluate:latest
docker build -t bigcodebench-sandbox:latest -f - . <<'EOF'
FROM bigcodebench/bigcodebench-evaluate:latest
ENTRYPOINT []
CMD ["tail", "-f", "/dev/null"]
EOF

加载 SWE-bench 镜像：

bash bash/load_swe_images.sh "$EVAL_ROOT/docker/swe_images"

加载 Terminal Bench 镜像：

bash bash/images_load/preload_terminal_bench_images.sh

14. 全量启动与状态检查

全量任务会运行 Multi-run 重复次数，预计需要很长时间。建议后台启动：

nohup docker run --rm --name evalscope_full \
  --network host \
  -v "$EVAL_ROOT:/opt/evalscope" \
  -v /data1/models:/opt/models:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  "$IMAGE" bash -lc '
    cd /opt/evalscope && python3 bash/run.py \
      --model DeepSeek-V4-Flash-INT8 \
      --api-url http://127.0.0.1:30000/v1 \
      --dataset-dir /opt/evalscope \
      --output-dir /opt/evalscope/output_full \
      --tokenizer-path /opt/models/DeepSeek-V4-Flash-INT8 \
      --suite full --limit none --batch-size 4
  ' >/tmp/evalscope_full.log 2>&1 &

状态检查：

docker ps --filter name=evalscope_full
tail -f /tmp/evalscope_full.log
find "$EVAL_ROOT/output_full" -name '*.json' | sort