ATLAS故障排查清单：GPU OOM、模型加载失败、Lens降级等常见错误的逐一解决方法

ATLAS故障排查清单GPU OOM、模型加载失败、Lens降级等常见错误的逐一解决方法【免费下载链接】ATLASAdaptive Test-time Learning and Autonomous Specialization项目地址: https://gitcode.com/gh_mirrors/atlas112/ATLASATLASAdaptive Test-time Learning and Autonomous Specialization是一个完全运行在本地硬件上的 AI 编程代理它把推理、候选生成、质量评分和沙箱验证打包成一套 Docker 服务栈让小参数模型也能独立完成真实的编码任务。当你遇到GPU OOM、模型加载失败、Lens 降级等报错时本故障排查清单带你按顺序快速定位并逐一解决这些问题。官方完整版排障手册在 docs/TROUBLESHOOTING.md本文是最常用的错误子集与处理路径。 第一步用 atlas doctor 一键自检30 秒定位故障源遇到任何异常先跑atlas doctor——它是官方推荐的第一诊断工具会一次性检查约 20 项内容Docker 与 Compose、GPU 直通、5 个服务的容器状态、各健康端点、模型文件、Lens 权重、工作区挂载一致性最后还会发一条真实请求做端到端冒烟测试。常用参数atlas doctor --quick跳过冒烟测试节省约 10 秒atlas doctor --json输出机器可读结果便于脚本化atlas doctor -v展开每项检查的详细原因检查逻辑源码见 atlas/commands/doctor.py。如果某项失败输出的 detail 里会直接给出修复提示例如显存不够时会提示你运行atlas tier fit --write先照做再看下文对应章节。 快速分诊看 /health 端点哪个服务掉线proxy 的健康端点会汇报全部上游服务状态curl http://localhost:8090/health返回的 JSON 中inference、lens、lens_ready、sandbox任一为false时整体status会变成degraded——那个false的字段就是问题服务。特别留意lens与lens_ready的区分前者是 HTTP 不通后者是进程活着但/ready门槛失败通常是权重缺失或嵌入维度不匹配。 GPU OOM 与显存不足的 3 种常见表现及解决方法1. 启动即崩CUDA 分配错误现象llama-server 启动后打印 “fitting params to device memory” 随即报 CUDA 分配错误退出或nvidia-smi显示显存接近 100% 后被 OOMKilled。原因模型权重 KV 缓存 计算缓冲超过了显卡显存。解决按顺序尝试atlas tier fit --write—— 读取 GGUF 头和你的显存自动算出“完全上 GPU”的最大配置然后docker compose up -d llama-server --no-deps --force-recreate若提示 DOES NOT FIT换更小的量化如 Q4_K_M 替代 Q6_K、用atlas tier fit --slots 1 --write降低并行槽位或换更小模型用nvidia-smi检查并清理其他占用显存的进程经验法则默认 4 槽位GGUF 文件大小 ≤ 显存 − 4.5 GiB 才放得下。即 8 GB 显卡选约 3 GiB 以下文件16 GB 选 11 GiB 以下。2.no kernel image is available for execution on the device现象NVIDIA 老卡RTX 20xx/30xx/40xx 等 Blackwell 之前运行时报此错或本地编译报nvcc fatal: unsupported gpu architecture。原因预构建镜像只编译了 Blackwellsm_120/121内核你的显卡算力低于 12.0。这是镜像与显卡不匹配不是驱动问题。解决为你自己的架构重建一次推理镜像一次性约 30–75 分钟。把算力版本号去掉小数点8.6 → 86docker compose build --build-arg CUDA_ARCH86 llama-server docker compose up -d --no-deps llama-server3. AMD 卡/dev/kfd不存在或权限被拒/dev/kfd: no such file or directoryamdgpu 内核驱动没带计算支持安装 ROCm 内核模块后必须重启Permission denied把当前用户加入video和render组后重新登录RDNA4RX 9070 系列报gfx1201 is not supported需在.env设置ATLAS_ROCM_TAG7.2.3-complete且不要设置ATLAS_HSA_OVERRIDE_GFX_VERSION 模型加载失败的排查步骤从文件缺失到架构不匹配你看到的报错原因解决failed to load model模型文件缺失或路径不对确认.env中ATLAS_MODEL_FILE指向的文件确实存在于ATLAS_MODELS_DIR默认./models/unknown (model) architecture …锁定的 llama.cpp 版本不认识新架构属维护级操作升级LLAMA_CPP_REV并保留 hidden-states 补丁见 inference/patches/expose-hidden-states.patch容器里nvidia-smi有卡、推理却跑在 CPU~2 tok/s未安装 NVIDIA Container Toolkit安装 toolkit 并配置 docker runtime验证docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smilibnvidia-ml.so.1: cannot open shared object file用户态驱动库缺失或 ldconfig 缓存过期先sudo ldconfig sudo systemctl restart docker仍不行则安装与驱动版本匹配的libnvidia-compute-NNatlas doctor的model_file检查还会发现下载截断的文件小于 100 MB 会告警——重新下载即可。 Lens 降级评分全为 0.5、embedding 漂移怎么修LensGeometric Lens负责对候选代码打分。它降级时 ATLAS 仍能用只是候选选择退回纯沙箱验证。1.lens: false先查curl http://localhost:8099/health和docker compose logs geometric-lens。两个常见原因Lens 连不上 llama-server检查LLAMA_URL、模型权重文件缺失全新安装未训练 Lens 时属预期行为按设计优雅降级。2. 所有候选都是cx_energy: 0.0、gx_score: 0.5这是中性默认值说明权重没加载。全新安装需要构建/下载与当前模型匹配的 Lens 工件cost_field.pt、gx_xgboost.json、gx_thresholds.json等文件清单见 geometric-lens/geometric_lens/models/README.md。推荐路径跑一轮atlas bench后用atlas lens build --from-results per_task目录生成。3. 分数离谱 fingerprint_ok: false/drifted: true嵌入约定漂移嵌入服务的返回方式逐 token / 未归一化与 Lens 训练时不一致。确认.env中ATLAS_EMBED_POOLINGmean重建 llama-server 容器服务端返回的向量范数应约等于 1.0。4. retrain 接口返回 503 models directory is mounted read-onlyCompose 部署里 Lens 模型目录是只读挂载容器内重训被设计为拒绝。正确做法是在宿主机执行atlas lens retrain反馈语料或atlas lens buildbench 候选然后docker compose restart geometric-lens重新加载。 Proxy 与 Sandbox 报错速查权限、端口与截断每次写文件都报.atlas.tmp: permission deniedproxy 以内置 uid 1001 运行与宿主机挂载目录属主不符。在.env写入ATLAS_PROXY_UID$(id -u)和ATLAS_PROXY_GID$(id -g)然后重建 atlas-proxy 容器。Agent 坚称“文件不存在”但文件明明在proxy 与 sandbox 把不同的宿主机目录挂成了/workspace文件工具和 shell 命令操作的是两个世界。atlas doctor的workspace_mounts检查会直接报出两条路径。修复在.env固定ATLAS_PROJECT_DIR再docker compose up -d --force-recreate atlas-proxy sandbox。sandbox: falsesandbox 只挂在sandbox-net网络上隔离设计故意的。Compose 部署请查docker compose logs sandbox。address already in use端口冲突lsof -i :8080找出占用者或在.env改ATLAS_LLAMA_PORT等端口。全部端口可配见 docs/CONFIGURATION.md。反复出现 Your output was truncated模型想一次写整个大文件。改用“给登录函数加输入校验”这类定向修改的措辞而不是“重写 auth.py”。V3 验证报ModuleNotFoundError被编辑文件 import 的模块没被读入上下文——先让 Agentread_file该文件即可。更多条目V3 不触发、编辑未读文件被拒、探索预算警告等在 docs/TROUBLESHOOTING.md 的 “Find your error” 表格里按报错原文一键跳转。 性能问题生成慢、卡几十秒、内存占用高生成只有 ~2 tok/s几乎总是模型跑在 CPU 上。三连查nvidia-smi里有没有 llama-server 进程、是否设置了-ngl 99、容器 GPU 直通是否配好。参考基准RTX 5060 Ti 16 GB 上带语法约束约 51 tok/s。V3 管线要几分钟T2 文件属正常——Probe 约 10–15 秒Phase 1 生成 1–2 分钟修复阶段 2–5 分钟。想让快就减少逻辑复杂度或保持文件短小T1 直接写入。工具结果与下一步之间卡 ~30 秒模型在受约束语法下输出了空轮次proxy 会自动重试一次持续出现就docker compose restart atlas-proxy llama-server清理槽位缓存。系统整体卡顿、服务被 OOMKilled正常占用约为 8 GB VRAM 各服务合计 ~500 MB RAM。若宿主机内存低于 14 GB其他服务会抢内存atlas doctor的tier_constraints检查会提前警告这类“显存够但内存不够”的机器。✅ 排障收尾确认修复改完配置后重新跑一次atlas doctor不加--quick看到 “ATLAS install is healthy” 即完成。若还有未覆盖的问题按官方建议的顺序收集信息docker compose logs 服务名、curl http://localhost:8090/health、docs/CONFIGURATION.md 中的环境变量全集然后到项目 issue 区反馈。相关文档docs/SETUP.md安装与验证、docs/CLI.mdatlas tier fit等命令详解、docs/TROUBLESHOOTING.md完整错误索引【免费下载链接】ATLASAdaptive Test-time Learning and Autonomous Specialization项目地址: https://gitcode.com/gh_mirrors/atlas112/ATLAS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考