简介:本文提供一份可复现的部署指南,依次说明资源规划、推理服务的启动与鉴权、医疗智能体评测环境接入、上线验证、故障排查和日常运维。读者按步骤操作后,可以得到受控访问的模型接口,并获得带哈希记录、可追溯的评测结果。
本文面向开发者、运维人员和架构负责人。按本文操作,可以在一台服务器上完成两件事:启动一个十亿参数级(1B)轻量语言模型的推理服务,并在同一套基础设施上搭建医疗智能体评测环境。
交付目标如下:
评测基准模拟了一个医疗业务环境。它包含 20 个通过标准接口开放的业务系统,附带 1,279 份运营文档,覆盖预授权管理、医保利用率管理和人群护理管理三类业务。文中的数量以基准包的发布说明为准,部署前请用文件清单核对。
下表是本文使用的示例版本。实际环境请按驱动和 CUDA 版本选择兼容组合,并先在测试环境验证。
| 组件 | 示例版本 | 说明 |
|---|---|---|
| 操作系统 | Ubuntu 22.04 LTS | 其他发行版需自行验证 |
| Python | 3.10 | 推理服务和评测程序共用 |
| NVIDIA 驱动 | 535 及以上 | 仅 GPU 模式需要 |
| CUDA | 12.1 | 需与推理框架版本匹配 |
| 推理框架 | vLLM 0.6.3 | 提供 OpenAI 兼容接口 |
| 评测程序 | 基准包自带版本 | 记录版本号或 commit |
资源建议如下。1B 参数以 FP16 存储时,权重约 2 GB,其余显存用于 KV 缓存和运行开销。
| 模式 | 最低配置 | 推荐配置 | 适用场景 |
|---|---|---|---|
| GPU | 1 张 8 GB 显存加速卡,32 GB 内存 | 1 张 16 GB 显存加速卡,64 GB 内存 | 正式评测、并发调用 |
| CPU | 16 核,32 GB 内存 | 32 核,64 GB 内存 | 功能验证,吞吐量明显偏低 |
磁盘方面,模型权重和分词器约需 10 GB。知识库、索引、日志和结果文件建议预留 100 GB。
部署前请逐项确认:
sudo useradd --system --home /opt/medagent --shell /usr/sbin/nologin svc-llmsudo mkdir -p /opt/medagent/{models/llm-1b,kb,eval,logs,results,secrets}sudo chown -R svc-llm:svc-llm /opt/medagentsudo chmod 750 /opt/medagentsudo chmod 700 /opt/medagent/secrets
各目录用途如下:models 存放权重和分词器,kb 存放知识库文档,eval 存放题集和接入配置,logs 和 results 分别存放日志与结果,secrets 存放令牌文件。
模型提供方通常会给出哈希清单。把清单放入模型目录后执行校验:
cd /opt/medagent/models/llm-1bsha256sum -c model.sha256
所有文件显示 OK 才能继续。出现 FAILED 时,重新下载对应文件。
创建虚拟环境并安装推理框架:
sudo -u svc-llm python3.10 -m venv /opt/medagent/venvsudo -u svc-llm /opt/medagent/venv/bin/pip install --upgrade pipsudo -u svc-llm /opt/medagent/venv/bin/pip install vllm==0.6.3
生成令牌并写入环境文件。令牌不写入命令行参数,避免出现在进程列表中:
sudo sh -c 'printf "VLLM_API_KEY=%s\n" "$(openssl rand -hex 32)" > /opt/medagent/secrets/inference.env'sudo chown svc-llm:svc-llm /opt/medagent/secrets/inference.envsudo chmod 600 /opt/medagent/secrets/inference.env
创建服务单元文件 /etc/systemd/system/llm-infer.service:
[Unit]Description=LLM inference serviceAfter=network-online.targetWants=network-online.target[Service]User=svc-llmGroup=svc-llmWorkingDirectory=/opt/medagentEnvironmentFile=/opt/medagent/secrets/inference.envExecStart=/opt/medagent/venv/bin/python -m vllm.entrypoints.openai.api_server \--model /opt/medagent/models/llm-1b \--served-model-name llm-1b \--host 10.0.0.10 \--port 8000 \--dtype float16 \--max-model-len 4096 \--gpu-memory-utilization 0.85Restart=on-failureRestartSec=5NoNewPrivileges=true[Install]WantedBy=multi-user.target
启动并设置开机自启:
sudo systemctl daemon-reloadsudo systemctl enable --now llm-infer.service
配置防火墙,只允许评测主机 10.0.0.20 访问端口 8000。规则按顺序匹配,因此先放行,再拒绝其他来源:
sudo ufw allow from 10.0.0.20 to any port 8000 proto tcpsudo ufw deny 8000/tcp
若使用 CPU 模式,需安装支持 CPU 的推理框架构建。将 --dtype 改为 float32 或 bfloat16,并把 --max-model-len 降到 2048 以控制内存。具体参数以所用构建的文档为准。
在 /opt/medagent/eval/config/systems.yaml 中登记 20 个业务系统。每条记录包含名称、业务场景、地址、鉴权方式和超时时间。令牌只写环境变量名,不写明文:
systems:- name: preauth_01scenario: 预授权管理base_url: https://10.0.1.11:8443/api/v1auth:type: bearertoken_env: PREAUTH_01_TOKENtimeout_s: 10verify_tls: true# 其余 19 个系统按同样格式登记,scenario 取值为# 预授权管理、医保利用率管理、人群护理管理之一
真实令牌写入 /opt/medagent/secrets/eval.env,权限设为 600,由评测程序在启动时读取。
导入知识库前,先核对文档数量:
find /opt/medagent/kb -type f | wc -l
输出应为 1279。随后记录文件哈希:
find /opt/medagent/kb -type f -print0 | sort -z | xargs -0 sha256sum > /opt/medagent/kb.sha256
使用基准包提供的导入工具,把知识库写入检索索引。导入完成后,记录索引文件的哈希,并确认文档数仍为 1279。
题集放在 eval/questions/ 下,同样生成 SHA-256 清单。
启动批量评测。入口和参数以基准包为准,以下为通用示例。首次运行并发数建议设为 1 到 4,因为单张卡的并发能力有限:
sudo -u svc-llm /opt/medagent/venv/bin/python eval/run_eval.py \--config eval/config/systems.yaml \--env-file /opt/medagent/secrets/eval.env \--model-endpoint http://10.0.0.10:8000/v1 \--model-name llm-1b \--questions eval/questions/ \--concurrency 2 \--output results/run-$(date +%Y%m%d-%H%M)
每次运行都应在结果目录生成 manifest.json,记录本次运行的依据。示例如下:
{"run_id": "run-20261118-0330","model": "llm-1b","model_sha256": "<来自 model.sha256>","config_sha256": "<systems.yaml 的哈希>","questions_sha256": "<题集清单的哈希>","kb_sha256": "<kb.sha256 的哈希>","started_at": "2026-11-18T03:30:00Z"}
有了这份清单,任何人都能判断两次结果是否来自同一配置。
按下列顺序检查,全部通过后再开放给评测任务。
服务状态应为 active:
systemctl is-active llm-infer.service
读取令牌并查询模型列表,应返回 llm-1b:
source /opt/medagent/secrets/inference.envcurl -sS http://10.0.0.10:8000/v1/models -H "Authorization: Bearer ${VLLM_API_KEY}"
发送一条短请求,并记录状态码和耗时:
curl -sS -o /dev/null -w "HTTP %{http_code}, 耗时 %{time_total} 秒\n" \http://10.0.0.10:8000/v1/chat/completions \-H "Authorization: Bearer ${VLLM_API_KEY}" \-H "Content-Type: application/json" \-d '{"model":"llm-1b","messages":[{"role":"user","content":"请用一句话说明什么是预授权。"}],"max_tokens":64,"temperature":0}'
不带令牌的请求必须被拒绝:
curl -sS -o /dev/null -w "HTTP %{http_code}\n" http://10.0.0.10:8000/v1/models
应返回 401。
评测程序的 --check-only 模式只检查连通性,不发起评测任务。它会对 20 个系统各输出一行结果。
最后试跑 5 道题,检查日志和结果目录。验收标准如下:
| 检查项 | 通过标准 |
|---|---|
| 服务可用性 | systemctl 显示 active,重启主机后自动恢复 |
| 鉴权 | 无令牌返回 401,有令牌返回 200 |
| 延迟 | 团队在测试前设定目标值,记录 p50 与 p95 |
| 业务接口 | 20 个系统全部返回成功状态 |
| 知识库 | 文档数为 1279,哈希与清单一致 |
| 日志 | 不含令牌、Authorization 头和患者标识 |
| 结果追溯 | manifest.json 字段完整 |
日志过滤可用下面的命令检查,输出应为空:
grep -Eil "bearer |password|token=" /opt/medagent/logs/*.log
| 现象 | 可能原因 | 检查方法 | 处理方式 | |
|---|---|---|---|---|
| 启动失败,日志出现 out of memory | 显存不足 | nvidia-smi 查看占用 |
把 --gpu-memory-utilization 降到 0.80,或把 --max-model-len 降到 2048 |
|
| 返回 401 | 令牌不一致或环境文件未更新 | 对比 env 文件与请求头 | 更新 env 文件后执行 systemctl restart llm-infer.service |
|
| 连接超时 | 防火墙拒绝或监听地址错误 | `ss -lntp \ | grep 8000,sudo ufw status numbered` |
修正 --host 或调整 ufw 规则 |
| 业务接口返回 403 | 凭证过期或权限不足 | 用 --check-only 定位系统 |
向系统管理员申请新凭证,替换环境文件中的值 | |
| 输出被截断 | max_tokens 过小,或总长度超过上下文上限 |
检查请求参数 | 增大 max_tokens,并保证输入加输出不超过 --max-model-len |
|
| 同一题集结果不一致 | 温度参数非 0,或配置哈希不同 | 对比两份 manifest.json |
固定 temperature 为 0,使用相同配置重跑 |
查看服务日志:
journalctl -u llm-infer.service -n 200 --no-pager
1B 模型在多步骤、长上下文任务上能力有限。它适合步骤清楚、上下文较短的单次判断。
建议按下列方式使用:
部署之前应先用评测环境确认模型是否满足业务要求。结论以自己的评测结果为准,本文不引用任何第三方指标。
| 频率 | 检查项 | 命令 |
|---|---|---|
| 每日 | 服务状态 | systemctl is-active llm-infer.service |
| 每日 | 磁盘空间,可用率应高于 20% | df -h /opt/medagent |