add beginner docker evaluation SOP

DOCKER_SOP_BEGINNER.md

@@ -0,0 +1,197 @@
+# EvalScope Docker 评测 SOP（新手版）
+
+本文档以 P800-02 为例，假设模型已经由 `/data1/yy/deploy_dsv4.sh` 部署为 OpenAI 兼容 API。
+
+## 0. 固定目录
+
+统一使用以下目录，避免宿主机和容器路径混淆：
+
+```bash
+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. 检查机器和目录
+
+```bash
+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'
+```
+
+若代码不存在：
+
+```bash
+git clone https://git.meta-stone.net/sora/evalstone.git "$EVAL_ROOT"
+```
+
+## 2. 下载数据集
+
+```bash
+mkdir -p "$EVAL_ROOT/datasets"
+modelscope download \
+  --repo-type dataset \
+  --local_dir "$EVAL_ROOT/datasets" \
+  SoraAmami/evalscope-datasets
+```
+
+验证数据没有多套 `datasets/` 嵌套：
+
+```bash
+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 源码。宿主机直接运行时：
+
+```bash
+cd "$EVAL_ROOT"
+python3 -m py_compile bash/run.py
+python3 bash/run.py --help
+```
+
+Docker 中运行时，使用 `/opt/evalscope`，不要使用不存在的 `/workspace/evalscope`。
+
+## 4. 启动并验证模型
+
+```bash
+bash /data1/yy/deploy_dsv4.sh int8 30000
+```
+
+验证 OpenAI API：
+
+```bash
+curl -sS "$API_URL/models"
+```
+
+必须能看到模型列表。若 `/health` 返回空响应但 `/v1/models` 正常，以 `/v1/models` 为准。
+
+## 5. 准备代码执行 sandbox
+
+humaneval 和 bigcodebench 需要 Docker sandbox：
+
+```bash
+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 运行评测容器
+
+```bash
+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
+
+```bash
+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 选择
+
+```text
+full             28 个：完整标准评测
+lite              6 个：快速检查
+mid              13 个：中等规模
+k3                 9 个：gpqa_diamond、hle、terminal_bench_v2、browsecomp、
+                       mcp_atlas、officeqa、deepsearchqa、jobbench、automation_bench
+tencent_hunyuan    当前为空，等清单确认后再启用
+```
+
+正式运行示例：
+
+```bash
+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：
+
+```bash
+python3 bash/run.py --datasets gsm8k,arc --limit none
+```
+
+## 9. 查看结果
+
+```bash
+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. 清理
+
+只删除本次输出，不删除数据和模型：
+
+```bash
+rm -rf "$EVAL_ROOT/output_smoke"
+```
+
+删除 Docker benchmark 镜像前，必须确认没有其他评测任务使用它们。