大模型Agent实验环境部署与验收指南

作者:有好多问题2026.11.18 11:27浏览量:0

简介:本文面向开发者与运维人员,给出大模型Agent实验环境的部署步骤、端口与资源清单、验收用例和回滚判定标准。按文中命令操作,读者可在一台8核16G的服务器上完成推理、编排、结构对比与可视化四项服务的上线,并能根据日志关键字定位常见故障。

一、适用范围与前置条件

本环境用于教学培训、原型验证和小规模内部实验,不适用于高并发生产系统。操作人员需要具备以下基础能力。

项目 要求
操作系统 Ubuntu 22.04 LTS 或同等发行版
容器与运行时 Docker 24.x,Python 3.10.12
网络 能区分内网与外网地址,会查看端口监听状态
技能 Linux 基础命令、systemd 服务管理、基础 HTTP 调试

版本号为示例值。实际部署以团队锁定的依赖清单为准,不要混用不同版本的模型文件与推理代码。

二、使用场景与验收目标

场景 典型用户 最小验收标准
入门演示 初学者、培训讲师 演示页面返回 200,推理接口可返回文本
可行性验证 算法或应用团队 Agent 链路完成一次工具调用,日志可查询
内部分享 技术负责人 可视化任务生成结果文件,页面可打开

三、组件与端口清单

组件 职责 监听地址与端口 依赖 健康检查 日志路径
推理服务 infer-svc 加载模型,提供生成接口 127.0.0.1:8000 模型文件 GET /health /var/log/agent-lab/infer.log
编排服务 orchestrator 按步骤调用模型与工具 127.0.0.1:8100 infer-svc GET /health /var/log/agent-lab/orch.log
结构对比页面 静态展示 Transformer、CNN、RNN 对比 127.0.0.1:8080 Nginx GET /index.html /var/log/nginx/access.log
可视化任务 viz-job 投影高维优化空间到二维 无常驻端口 样本数据 结果文件存在 /var/log/agent-lab/viz.log
网关 统一入口与 TLS 0.0.0.0:443 证书 GET / /var/log/nginx/error.log

只有网关的 443 端口对外开放。推理、编排和静态页面只绑定本机地址,避免被直接访问。

四、资源规划与版本矩阵

组件 CPU 内存 磁盘 说明
推理服务 4 核 8 GB 10 GB 按 7B 参数、4-bit 量化模型规划
编排服务 1 核 2 GB 1 GB 主要消耗在网络等待
可视化任务 2 核 2 GB 5 GB 通过限制内存防止影响推理
日志与监控 1 核 1 GB 20 GB 按 14 天保留期规划

以上为规划值。上线后用 docker stats 或 systemctl status 复核实际占用,再调整规格。

模型文件和样本数据需要记录 SHA256 校验值,保存在 /opt/agent-lab/models/SHA256SUMS 中。配置文件中不写入明文密钥。

五、部署步骤

第一步,创建运行账号与目录。 使用无登录权限的专用账号运行服务。

  1. sudo useradd -r -m -s /usr/sbin/nologin agentlab
  2. sudo mkdir -p /opt/agent-lab/{models,data,releases,logs}
  3. sudo chown -R agentlab:agentlab /opt/agent-lab

第二步,校验模型文件。 复制模型后先核对哈希值,校验失败时停止部署。

  1. sha256sum -c /opt/agent-lab/models/SHA256SUMS

输出中每一行都应为 OK。出现 FAILED 时重新下载模型,不要继续启动服务。

第三步,写入推理服务环境变量。 密钥和路径放在权限为 600 的环境文件中。

  1. sudo tee /etc/agent-lab/infer.env >/dev/null <<'EOF'
  2. MODEL_PATH=/opt/agent-lab/models/chat-7b-q4.gguf
  3. MAX_CONCURRENCY=4
  4. REQUEST_TIMEOUT=30
  5. LOG_LEVEL=INFO
  6. EOF
  7. sudo chmod 600 /etc/agent-lab/infer.env
  8. sudo chown agentlab:agentlab /etc/agent-lab/infer.env

MAX_CONCURRENCY=4 和 REQUEST_TIMEOUT=30 是按 4 核 8 GB 规格取的初始值。第六步的压测结果出来后再调整。

第四步,启动推理服务。 使用 systemd 管理进程,异常退出后自动拉起。

  1. # /etc/systemd/system/agent-infer.service
  2. [Unit]
  3. Description=Agent lab inference service
  4. After=network.target
  5. [Service]
  6. User=agentlab
  7. EnvironmentFile=/etc/agent-lab/infer.env
  8. ExecStart=/opt/agent-lab/venv/bin/uvicorn app.infer:app --host 127.0.0.1 --port 8000 --workers 1
  9. Restart=on-failure
  10. RestartSec=5
  11. [Install]
  12. WantedBy=multi-user.target
  1. sudo systemctl daemon-reload
  2. sudo systemctl enable --now agent-infer
  3. curl -fsS http://127.0.0.1:8000/health

健康检查返回 {"status":"ok"} 视为通过。

第五步,配置编排服务。 工具调用只允许白名单中的工具。

  1. TOOL_ALLOWLIST=search_docs,calc
  2. INFER_URL=http://127.0.0.1:8000
  3. RETRY_COUNT=1
  4. TRACE_LOG=on

白名单之外的工具调用会被拒绝,并在日志中记录 tool not in allowlist。

第六步,部署可视化任务。 可视化任务按需运行,并限制资源,避免影响推理主链路。

  1. sudo systemd-run --unit=viz-projection --property=MemoryMax=2G --property=CPUQuota=200% \
  2. nice -n 19 timeout 600 /opt/agent-lab/venv/bin/python jobs/project_viz.py \
  3. --input /opt/agent-lab/data/samples.npy --out /opt/agent-lab/data/results/

运行结束后检查 results/projection.png 是否存在且大小大于 0。

第七步,配置网关并灰度上线。 网关将 /api/ 转发到编排服务,其余路径指向静态页面。先只放行单个实例,验收通过后再开放域名。

  1. server {
  2. listen 443 ssl;
  3. server_name lab.example.internal;
  4. location /api/ { proxy_pass http://127.0.0.1:8100/; proxy_read_timeout 60s; }
  5. location / { proxy_pass http://127.0.0.1:8080/; }
  6. }

修改后执行 sudo nginx -t 检查语法,通过后再执行 sudo systemctl reload nginx。

六、上线验收用例

编号 输入 预期结果 失败判定 日志关键字
T01 GET https://lab.example.internal/ 状态码 200,页面包含结构对比标题 状态码非 200 502、no such file
T02 GET 127.0.0.1:8000/health {"status":"ok"},3 秒内返回 超时或非 ok model load failed
T03 向推理接口发送一条生成请求 状态码 200,响应含 text 字段,耗时小于 30 秒 状态码 504 或超时 ReadTimeout
T04 编排服务执行一次包含 calc 的任务 追踪日志出现 tool_call 与 final 两个步骤 出现未授权工具 tool not in allowlist
T05 运行可视化任务 退出码为 0,结果图片存在且大于 0 字节 退出码非 0 或被系统终止 MemoryError、Killed
T06 查看最近 10 分钟的服务日志 无持续出现的 ERROR 记录 ERROR 连续出现 ERROR
T07 查看 10 分钟内的资源指标 CPU 低于 80%,内存低于 85% 指标持续超过阈值 无

推理接口的验收命令如下。

  1. curl -sS -X POST http://127.0.0.1:8000/v1/generate \
  2. -H "Content-Type: application/json" \
  3. -d '{"prompt":"用一句话解释残差连接","max_tokens":128}' \
  4. -w "\nHTTP %{http_code} %{time_total}s\n"

Agent 链路的验收命令如下。

  1. curl -sS -X POST http://127.0.0.1:8100/v1/run \
  2. -H "Content-Type: application/json" \
  3. -d '{"task":"计算 12 乘以 7,并给出结果"}'

返回结果中应包含一次 calc 调用和最终答案 84。

七、常见故障与排查顺序

现象 常见原因 关键字 处理方法
模型加载失败 路径错误、校验失败、内存不足 model load failed、out of memory 核对路径与 SHA256,降低并发后重启
端口不通 进程未启动或端口被占用 address already in use 执行 `ss -lntp \ grep 8000` 查看占用进程
依赖版本不一致 未按锁定清单安装 ImportError 使用 pip install -r requirements.lock 重装
请求超时 并发超过上限 ReadTimeout 先检查并发数,再考虑调高超时时间
可视化占用过多资源 样本规模过大 MemoryError、Killed 对样本降采样,并保持内存限制
证书异常 证书过期或域名不匹配 certificate has expired 更新证书并重新加载网关

排查时按以下顺序进行:先看健康检查,再看日志关键字,然后核对配置、网络策略和存储路径,最后才考虑回滚。

回滚判定。 满足以下任一条件时执行回滚:连续两次 T02 或 T03 失败;5 分钟内错误率超过 5%;可视化任务影响推理服务的响应。回滚前先确认目标版本号,再执行切换。

  1. ln -sfn /opt/agent-lab/releases/v1.2.0 /opt/agent-lab/current
  2. sudo systemctl restart agent-infer

操作风险提示。 删除模型或样本前,先确认已有备份,并列出待删文件清单交人工核对,不要直接对目录执行递归删除。轮换密钥时,先备份旧密钥,再让新密钥在推理和编排两个服务中都生效,最后才废止旧密钥。两个服务中任一服务未更新时,立即恢复旧密钥。

八、运维优先级与检查频率

优先级 事项 检查频率 负责人
P0 健康检查与错误率告警 实时 运维
P0 模型与配置备份 每