logo

多模态表格问答评测离线部署与复现指南

作者:十万个为什么2026.11.16 11:59浏览量:0

简介:本文面向开发、算法和运维人员,按环境测算、配置校验、推理解析、指标评估和验收排错五步,说明多模态表格问答评测的离线部署方法。文中提供依赖锁定命令、配置检查脚本、指标公式和排错对照表,有助于减少版本与配置差异,并让每次评测结果都能复核。

一、环境测算

本指南用于多模态表格问答评测基准的离线部署。评测系统由数据集、任务定义、推理程序、结果解析模块和评估脚本组成,通常不对外提供在线业务接口。部署前先确认两件事:待测模型通过远程接口调用还是部署在本地,以及评测是一次性运行还是周期性运行。

1.1 确定部署形态

远程接口方式下,主机只负责读取数据、调度请求和计算指标。主机对处理器和内存要求较低,但需要稳定的网络出口和足够的磁盘空间。

接口密钥不写入配置文件,而是通过环境变量传入。配置示例如下:

  1. endpoint: https://model-gateway.example.internal/v1/chat/completions
  2. api_key_env: EVAL_API_KEY
  3. concurrency: 8
  4. rate_limit_rps: 4
  5. timeout_s: 60
  6. max_retries: 3
  7. backoff_base_s: 2
  8. output_dir: /data/eval/runs

endpoint 为占位地址,需替换为实际地址。concurrency 是并发请求数,rate_limit_rps 是服务商允许的每秒请求数,二者分别依据主机性能和服务商配额确定。超时和重试会占用并发槽位,timeout_s 与 max_retries 的取值会直接影响总耗时。

设置密钥时,避免写入 shell 历史:

  1. read -rs EVAL_API_KEY && export EVAL_API_KEY

本地模型方式下,加速设备和显存配置必须通过实测确定,不能只依赖经验值。实测步骤如下:

  1. 选取 20 条样本,覆盖每个任务类别,使用目标上下文长度和目标并发数运行。
  2. 运行期间每 5 秒记录一次显存占用:
  1. nvidia-smi --query-gpu=index,memory.used,memory.total --format=csv,noheader,nounits -l 5 > /tmp/gpu_mem.log
  1. 运行结束后取 memory.used 的最大值作为峰值。

验收标准由团队在测试前确定。建议记录峰值显存与总显存的比值,并为运行时的临时缓存预留余量。若峰值接近上限,应降低并发数或上下文长度后重新测试。

周期性评测适合使用容器或弹性实例。数据卷与计算实例分开挂载,评测结束后释放计算实例,结果保存在独立存储中。

1.2 依赖锁定与离线安装

直接依赖写在 requirements.in 中,由 pip-tools 生成带哈希值的锁文件。锁文件的生成建议在独立的构建环境中完成,运行环境只从锁文件安装。

构建机上执行:

  1. python3 -m venv /opt/eval/build-venv
  2. source /opt/eval/build-venv/bin/activate
  3. pip install pip-tools
  4. pip-compile requirements.in -o requirements.lock --generate-hashes
  5. deactivate

运行机上执行:

  1. python3 -m venv /opt/eval/venv
  2. source /opt/eval/venv/bin/activate
  3. pip install --require-hashes -r requirements.lock
  4. pip check

pip check 应输出无冲突的结论。如果输出冲突,修改 requirements.in 后重新生成锁文件,不要手动编辑锁文件。锁文件中的依赖可能因操作系统、架构或 Python 版本而不同,因此生成锁文件的环境应与目标机一致。

部署后检查实际安装版本与锁文件是否一致:

  1. pip freeze --exclude-editable | sort > /tmp/installed.txt
  2. grep -E '^[A-Za-z0-9_.-]+==' requirements.lock | sed 's/ *\\$//' | sort > /tmp/locked.txt
  3. diff /tmp/locked.txt /tmp/installed.txt && echo "lock consistent"

diff 无输出时,锁文件与当前环境一致。若 diff 只显示大小写或下划线与连字符的差异,属于包名规范化差异,需人工确认后再判断。

私有环境无法联网时,在能联网的机器上下载 wheel 包,再拷贝到目标机安装:

  1. pip download -r requirements.lock --require-hashes -d wheelhouse/
  2. pip install --no-index --find-links wheelhouse/ --require-hashes -r requirements.lock

若下载机与目标机的平台或 Python 版本不同,下载时需指定目标平台,例如:

  1. pip download -r requirements.lock --require-hashes -d wheelhouse/ \
  2. --only-binary=:all: --platform manylinux2014_x86_64 \
  3. --python-version 3.11 --implementation cp

参数值需按目标机填写。纯源码包无法加 --only-binary 下载,遇到此类包时需在目标机编译或换用可用的 wheel。

1.3 版本与平台检查

安装前,在目标机核对下表中的项目:

项目 要求 检查方式
Python 版本 与锁文件生成环境的主次版本一致 python3 --version
操作系统与架构 与 wheel 文件名中的平台标签一致 python3 -c "import platform; print(platform.system(), platform.machine())"
wheel 标签 每个 wheel 文件名至少匹配一个支持标签 pip debug --verbose 列出当前 pip 支持的标签
构建工具 pip-tools 只在构建环境使用,不进入运行环境 运行环境中执行 pip show pip-tools,应无输出

1.4 回滚与隔离

每次发布使用新的虚拟环境,例如 /opt/eval/venv-20261101。/opt/eval/venv 为指向当前版本的符号链接。新版本验收通过前,不删除旧版本目录。

  1. ln -sfn /opt/eval/venv-20261101 /opt/eval/venv

需要回滚时,将符号链接指回旧目录即可。该操作不删除任何文件。

1.5 资源估算

正式规划资源前,先用小样本实测。抽取 20 条样本,覆盖每个任务类别,在相同网络和相同模型端点下重复运行至少 3 次,记录以下四项:

记录项 含义 记录方式
样本数 N0 本次测试的样本数量 固定为抽样数量
单条平均耗时 t 总耗时除以尝试样本数,包含重试等待 从任务启动到结果落盘计时
单条峰值内存 m 单个推理进程的内存峰值 /usr/bin/time -v 输出中的 Maximum resident set size
单条输出大小 s 单条原始响应文件的平均大小 du -b 统计后取平均

t 计入全部尝试样本,包括最终失败的样本、重试次数和退避等待时间。失败样本同样占用并发槽位,不能排除在外。

估算公式中,N 为完整样本数:

  • 完整耗时 T ≈ max(N × t / C, N / R)。C 为有效并发数,R 为服务商允许的每秒请求数。没有限流时只取第一项。
  • 峰值内存 M ≈ M_base + C × m,M_base 为框架与数据加载的基线内存。
  • 输出磁盘 D ≈ N × s × k,k 为安全系数。k 初始取 1.5,之后根据日志和临时文件的实际增长调整。

有效并发数 C 超过 R 乘以单次请求平均耗时后,吞吐不再增加,多出的并发只会等待限流。

示意计算使用假设值,不代表任何实测结果。设 N = 1000,t = 3 秒,C = 8,R = 4。第一项为 1000 × 3 / 8 = 375 秒,第二项为 1000 / 4 = 250 秒,T 取较大值 375 秒。若 M_base = 2 GB,m = 1.5 GB,则 M = 2 + 8 × 1.5 = 14 GB。若 s = 20 KB,k = 1.5,则 D = 1000 × 20 × 1.5 = 30000 KB,约 30 MB。

监控命令如下。程序输出写入单独文件,避免与时间统计混在一起:

  1. /usr/bin/time -v python3 run_infer.py /opt/eval/configs/eval_config.yaml > /tmp/run.log 2> /tmp/time.log
  2. grep -E "Maximum resident|Elapsed" /tmp/time.log
  3. df -h /data/eval

统计单次运行的磁盘占用时,先设置运行目录名,再统计对应目录。该命令只读取文件大小,不修改任何内容:

  1. RUN_ID=run_20261116_0900
  2. du -sb "/data/eval/runs/${RUN_ID}" | tee -a "/data/eval/runs/${RUN_ID}/disk_usage.txt"

RUN_ID 需替换为本次运行的实际目录名。统计结果包含原始响应、日志和临时文件。

二、配置校验

正式运行前,先核对配置文件中的每一项。下表列出各项的含义与约束:

配置项 含义 约束
dataset_path 数据集目录 必须存在且可读
endpoint 模型接口地址 必须以 https:// 开头
api_key_env 保存密钥的环境变量名 对应变量必须已设置
concurrency 并发请求数 正整数,依据 1.5 节实测结果确定
rate_limit_rps 每秒请求上限 正数,不超过服务商配额
timeout_s 单次请求超时秒数 正数,需大于实测的单次请求耗时
max_retries 最大重试次数 非负整数
backoff_base_s 退避基准秒数 正数
output_dir 结果输出目录 必须存在且可写

运行下面的脚本进行自动校验。脚本依赖 PyYAML,该包应已写入锁文件:

  1. python3 - <<'EOF'
  2. import os
  3. import sys
  4. import yaml
  5. path = "/opt/eval/configs/eval_config.yaml"
  6. with open(path, encoding="utf-8") as f:
  7. cfg = yaml.safe_load(f)
  8. required = [
  9. "dataset_path", "endpoint", "api_key_env", "concurrency",
  10. "rate_limit_rps", "timeout_s", "max_retries", "backoff_base_s", "output_dir",
  11. ]
  12. errors = []
  13. for key in required:
  14. if key not in cfg:
  15. errors.append(f"缺少配置项: {key}")
  16. if "dataset_path" in cfg and not os.path.isdir(cfg["dataset_path"]):
  17. errors.append("dataset_path 不存在或不是目录")
  18. if "endpoint" in cfg and not str(cfg["endpoint"]).startswith("https://"):
  19. errors.append("endpoint 必须以 https:// 开头")
  20. if "api_key_env" in cfg and not os.environ.get(str(cfg["api_key_env"])):
  21. errors.append(f"环境变量 {cfg['api_key_env']} 未设置")
  22. if "concurrency" in cfg and (not isinstance(cfg["concurrency"], int) or cfg["concurrency"] < 1):
  23. errors.append("concurrency 必须为正整数")
  24. if "output_dir" in cfg and not os.path.isdir(str(cfg["output_dir"])):
  25. errors.append("output_dir 不存在")
  26. elif "output_dir" in cfg and not os.access(str(cfg["output_dir"]), os.W_OK):
  27. errors.append("output_dir 不可写")
  28. if errors:
  29. print("校验失败:")
  30. for e in errors:
  31. print(" -", e)
  32. sys.exit(1)
  33. print("配置校验通过")
  34. EOF

脚本只检查环境变量是否存在,不打印其取值。配置文件中不应出现明文密钥。以下命令用于排查:

  1. grep -inE "api[_-]?key|token|secret|password" /opt/eval/configs/eval_config.yaml

该命令的输出应只包含 api_key_env 这一行。若出现其他行,应删除明文值,改由环境变量或团队的密钥管理服务提供。已经写入过的密钥应视为泄露,需按团队流程轮换。

磁盘余量需与 1.5 节的 D 估算对比。df -h /data/eval 显示的可用空间应明显大于 D。

三、推理解析

3.1 输出文件结构

推理程序为每条样本保存一份原始响应,路径为 output_dir/<run_id>/raw/<sample_id>.json。解析模块从原始响应中提取答案,并写入 output_dir/<run_id>/parsed.jsonl。原始响应保留不变,便于后续复核。

3.2 答案规范化

解析前,对答案做统一处理:

  1. 去除首尾空白字符。
  2. 使用 Unicode NFKC 规范化,把全角字符转为半角。
  3. 英文答案统一转为小写。
  4. 按任务定义中的格式解析,例如表格单元格坐标或数值。

规范化规则属于评测口径的一部分。修改规则时,必须更新版本号,并在运行清单中记录,否则结果之间无法比较。

3.3 失败分类

解析过程中遇到的失败需要分类记录。失败样本计入分母 N,不得从统计中删除。

类型 判定条件 处理方式
timeout 单次请求超过 timeout_s,且重试次数用尽 计为错误,记录最后一次异常
http_error 返回 4xx 或

发表评论

活动