简介:本文面向开发者与运维人员,给出大模型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 中。配置文件中不写入明文密钥。
第一步,创建运行账号与目录。 使用无登录权限的专用账号运行服务。
sudo useradd -r -m -s /usr/sbin/nologin agentlabsudo mkdir -p /opt/agent-lab/{models,data,releases,logs}sudo chown -R agentlab:agentlab /opt/agent-lab
第二步,校验模型文件。 复制模型后先核对哈希值,校验失败时停止部署。
sha256sum -c /opt/agent-lab/models/SHA256SUMS
输出中每一行都应为 OK。出现 FAILED 时重新下载模型,不要继续启动服务。
第三步,写入推理服务环境变量。 密钥和路径放在权限为 600 的环境文件中。
sudo tee /etc/agent-lab/infer.env >/dev/null <<'EOF'MODEL_PATH=/opt/agent-lab/models/chat-7b-q4.ggufMAX_CONCURRENCY=4REQUEST_TIMEOUT=30LOG_LEVEL=INFOEOFsudo chmod 600 /etc/agent-lab/infer.envsudo chown agentlab:agentlab /etc/agent-lab/infer.env
MAX_CONCURRENCY=4 和 REQUEST_TIMEOUT=30 是按 4 核 8 GB 规格取的初始值。第六步的压测结果出来后再调整。
第四步,启动推理服务。 使用 systemd 管理进程,异常退出后自动拉起。
# /etc/systemd/system/agent-infer.service[Unit]Description=Agent lab inference serviceAfter=network.target[Service]User=agentlabEnvironmentFile=/etc/agent-lab/infer.envExecStart=/opt/agent-lab/venv/bin/uvicorn app.infer:app --host 127.0.0.1 --port 8000 --workers 1Restart=on-failureRestartSec=5[Install]WantedBy=multi-user.target
sudo systemctl daemon-reloadsudo systemctl enable --now agent-infercurl -fsS http://127.0.0.1:8000/health
健康检查返回 {"status":"ok"} 视为通过。
第五步,配置编排服务。 工具调用只允许白名单中的工具。
TOOL_ALLOWLIST=search_docs,calcINFER_URL=http://127.0.0.1:8000RETRY_COUNT=1TRACE_LOG=on
白名单之外的工具调用会被拒绝,并在日志中记录 tool not in allowlist。
第六步,部署可视化任务。 可视化任务按需运行,并限制资源,避免影响推理主链路。
sudo systemd-run --unit=viz-projection --property=MemoryMax=2G --property=CPUQuota=200% \nice -n 19 timeout 600 /opt/agent-lab/venv/bin/python jobs/project_viz.py \--input /opt/agent-lab/data/samples.npy --out /opt/agent-lab/data/results/
运行结束后检查 results/projection.png 是否存在且大小大于 0。
第七步,配置网关并灰度上线。 网关将 /api/ 转发到编排服务,其余路径指向静态页面。先只放行单个实例,验收通过后再开放域名。
server {listen 443 ssl;server_name lab.example.internal;location /api/ { proxy_pass http://127.0.0.1:8100/; proxy_read_timeout 60s; }location / { proxy_pass http://127.0.0.1:8080/; }}
修改后执行 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% | 指标持续超过阈值 | 无 |
推理接口的验收命令如下。
curl -sS -X POST http://127.0.0.1:8000/v1/generate \-H "Content-Type: application/json" \-d '{"prompt":"用一句话解释残差连接","max_tokens":128}' \-w "\nHTTP %{http_code} %{time_total}s\n"
Agent 链路的验收命令如下。
curl -sS -X POST http://127.0.0.1:8100/v1/run \-H "Content-Type: application/json" \-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%;可视化任务影响推理服务的响应。回滚前先确认目标版本号,再执行切换。
ln -sfn /opt/agent-lab/releases/v1.2.0 /opt/agent-lab/currentsudo systemctl restart agent-infer
操作风险提示。 删除模型或样本前,先确认已有备份,并列出待删文件清单交人工核对,不要直接对目录执行递归删除。轮换密钥时,先备份旧密钥,再让新密钥在推理和编排两个服务中都生效,最后才废止旧密钥。两个服务中任一服务未更新时,立即恢复旧密钥。
| 优先级 | 事项 | 检查频率 | 负责人 |
|---|---|---|---|
| P0 | 健康检查与错误率告警 | 实时 | 运维 |
| P0 | 模型与配置备份 | 每 |