LingBot-Vision 在容器化环境中部署的资源限制配置

LingBot-Vision 这类视觉模型服务在容器化环境里部署时，资源限制的核心不是把容器包裹起来就算完，而是要让进程管理工具、容器运行时和推理框架三层的配置口径一致。单独限制容器内存而不处理推理框架的缓存池，或者只设置 GPU 数量却不限制显存占用，都会出现容器还活着但请求已经不可用的情况。下面按先观测、再限制、后验证的顺序给出可操作的配置思路。

判断方向：把容器资源限制拆成 CPU 配额、内存上限、GPU 设备与显存、共享内存四类，分别用 Docker 或 Kubernetes 的对应字段设置。设置前先跑一次无限制推理摸清基线，设置后通过日志和进程状态确认是正常终止还是被 OOM 杀死。LingBot-Vision 若使用 PyTorch 等框架，需要注意其缓存分配器可能预占显存，容器级显存限制不是强隔离，必须配合框架环境变量。

先摸基线，再写限制

在写配置之前，先用最简单的方式启动一个不带资源限制的容器，用一个固定 prompt 跑若干次推理，同时执行 docker stats 观察容器内存和 CPU 波动，宿主机上用 nvidia-smi 看显存占用。重点记录三个数：推理前常驻内存、推理峰值内存、单次推理显存峰值。没有这几个基线值，后续的 limits 设置就是拍脑袋。

# 观察容器资源占用
docker stats `--no-stream` `--format` "table {{.Name}}\t{{.MemUsage}}\t{{.CPUPerc}}"

# 宿主机观察显存占用
watch -n 1 nvidia-smi

对于视觉模型，基线测试还需要覆盖长短两种输入尺寸，因为不同分辨率对显存和内存的影响可能相差很大。如果连基线测试都出现 OOM，那么优先检查的是宿主机是否给了足够资源，而不是急着设置 limits。

Docker 运行时的资源限制配置

Docker 本身不区分通用内存和显存，GPU 是以设备方式透传的。内存限制用 `--memory`，CPU 用 `--cpus`，GPU 用 `--gpus`。共享内存 `--shm-size` 容易被忽略，但视觉模型的数据加载和并行处理常会用到，默认 64MB 往往不够。

docker run -d \
  `--name` lingbot-vision \
  `--memory` 8g \
  `--cpus` 4 \
  `--gpus` '"device=0"' \
  `--shm-size` 2g \
  -p 8000:8000 \
  your-registry/lingbot-vision:latest

这段命令的效果是：容器最多使用 8GB 内存和 4 个 CPU 核心，只能访问物理 GPU 0，共享内存最多 2GB。如果容器内进程尝试分配超过 8GB 内存，会被内核 OOM 杀掉，而不是继续拖垮宿主机。

如果使用 docker-compose，同样的配置写在 deploy 字段下：

services:
  lingbot-vision:
    image: your-registry/lingbot-vision:latest
    ports:
      - "8000:8000"
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8g
        reservations:
          cpus: '2'
          memory: 4g
    shm_size: '2g'
    gpus: 'device=0'

注意 deploy.resources.limits 在普通 docker-compose up 下不会生效，它只对 Swarm 模式生效。本地或单机 docker compose 场景需要直接使用顶层 mem_limit、cpus 字段，或者继续用命令行参数。

Kubernetes 中的等效配置

Kubernetes 里用 resources 字段声明请求和限制。内存限制建议给到基线值的 1.5 到 2 倍，CPU 限制根据并发需求调整。GPU 部分通过资源名 nvidia.com/gpu 声明，但要先安装 NVIDIA Device Plugin。

resources:
  requests:
    cpu: "2"
    memory: 4Gi
    nvidia.com/gpu: 1
  limits:
    cpu: "4"
    memory: 8Gi
    nvidia.com/gpu: 1

在 Kubernetes 中，memory limit 小于实际需要时，容器会因内存超限被 OOMKilled，且 PID 会被 kill，进程退出码 137。设置 limits 时务必保留余量，不要把限制压到和基线峰值一样紧。CPU limit 仅控制 CPU 调度份额，不会让进程失败，但 CPU 限太紧会导致推理延迟升高。

另外，共享内存在 Kubernetes 里默认不单独设置，需要把 emptyDir 的介质设为内存，或直接修改 Pod 的 shm-size 相关字段。更常见的做法是在 deployment 中挂载一个 emptyDir 到 /dev/shm：

volumes:
  - name: dshm
    emptyDir:
      medium: Memory
      sizeLimit: 2Gi

containers:
  - name: lingbot-vision
    volumeMounts:
      - name: dshm
        mountPath: /dev/shm

显存限制的边界说明

容器的资源限制字段并不直接限制 GPU 显存。Docker 的 `--gpus` 只控制可见 GPU，NVIDIA 驱动通常只对显存分配做“尽力而为”式的限制，也就是说即便容器声明了显存上限，实际超过上限时容器不一定会被杀死，而是可能分配失败。PyTorch 的缓存分配器会在进程启动后逐步占用显存，如果不设置限制，它可能占满整张卡。

建议在启动命令中增加 PyTorch 相关的环境变量，给显存预留一个安全裕量：

ENV PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128

这个参数的意义是控制缓存块的最大尺寸，不让碎片化导致显存无谓膨胀。更严格的显存限制需要在推理框架内部实现，例如通过模型加载前的空张量探测来预留显存，或者使用 NVIDIA 的 MPS 控制单进程显存占用。这些方式都比较复杂，建议先通过 nvidia-smi `--query-compute-apps`=used_memory 观察单个容器的实际显存占用。

验证资源限制是否生效

配置完成后，不要只看容器能启动就认为限制生效。常规验证分四步：

进入容器执行 cat /sys/fs/cgroup/memory.max（Cgroup v2）或 cat /sys/fs/cgroup/memory/memory.limit_in_bytes（Cgroup v1），确认内存限制已写入。
运行一个故意申请大内存的进程（如 python -c "x = bytearray(1024*1024*1024*10)"），观察容器是否被 OOMKilled。
在容器内执行 nvidia-smi 查看能看到的 GPU 设备编号是否与配置一致。
启动真实推理请求，同时用 docker stats 和宿主机 nvidia-smi 观察资源是否被控制在设定范围附近。

如果发现容器频繁重启，先 docker inspect 看退出状态和 OOMKilled 字段，再调整 limits。Kubernetes 用户用 kubectl describe pod 查看 Last State 里的终止原因。

常见问题

容器被 OOMKilled，但日志里没有明显错误，如何处理？

先看退出码：137 表示内存超过 limit 被内核杀掉，125 表示 Docker daemon 本身无法执行容器。如果确认是 OOM，提高 container 的 memory limit，或者检查推理框架是否有缓存不释放的问题。要注意，PyTorch 在进程结束前可能不会释放所有缓存，增加 limits 比强制重启更可靠。

设置了 GPU 限制但显存占用仍然超过预期？

这是因为容器级限制只控制设备可见性，不控制显存分配量。先用 nvidia-smi pmon 查看具体进程占用，再考虑在应用层设置 PYTORCH_CUDA_ALLOC_CONF 或限制 batch size。如果持续超出，建议将单个 GPU 上的并发容器数降为 1，而不是继续依赖容器配置。