语义角色标注（Semantic Role Labeling，SRL）负责回答一句话里谁对谁做了什么、发生在什么时间地点。它的输出结果通常是谓词和一组带角色标签的论元，比如施事、受事、时间、处所。在自然语言处理流水线中，SRL常被用来做事件抽取、信息补全和知识图谱构建。可是训练好的SRL模型迁移到线上时，很容易因为PyTorch版本、底层C++库或者模型文件加载方式不一致而启动失败。把模型和运行环境一起打成镜像，是解决这类交付问题的直接办法。
一、模型文件整理与依赖固化
容器化SRL服务的第一步，是把推理需要的模型文件、词表、配置和依赖列表整理清楚。假设你使用本地训练或微调后的SRL模型，目录可以统一放在 /app/models/srl 下，包含 config.json、pytorch_model.bin、tokenizer.json 等文件。不要在容器启动时再去远程下载模型，否则首次请求延迟会非常高，而且网络波动可能造成启动失败。更好的做法是在构建镜像阶段就把模型复制进去。但如果模型体积超过1GB，建议考虑挂载卷或使用模型仓库，避免镜像过于臃肿。
依赖方面，SRL推理通常离不开 torch 和 transformers，部分实现还会用到 allennlp、hanlp 或 ltp。requirements.txt 里最好固定主版本号，例如 torch==2.1.0、transformers==4.36.0。镜像基础推荐 python:3.10-slim，不要使用完整版镜像，体积能减少一半以上。需要注意，slim 镜像缺少 gcc、g++ 等编译工具，如果某个依赖没有预编译的 wheel，pip 会尝试源码编译并报错。遇到这种情况，可以在构建阶段先安装 build-essential，安装完依赖后不要在同一层删除工具，这样镜像仍会变大；更合理的做法是用多阶段构建，把最终运行镜像和构建镜像分开。
另外要留意模型加载路径。容器内的工作目录通常设为 /app，如果代码中使用相对路径，容易受启动命令影响。建议统一使用环境变量传递路径，例如 MODEL_PATH=/app/models/srl，并在代码里通过 os.environ.get 读取。这样以后更换模型版本，只需要更新环境变量而不必改代码。对于 HanLP 这类会写用户目录缓存模型的库，还要设置 HANLP_HOME，避免 root 用户目录下产生不可控缓存。
二、用FastAPI封装推理接口
SRL模型加载通常比较慢，尤其是基于BERT的模型，初始化可能需要几秒到几十秒。因此服务要把模型加载放到应用启动阶段，而不是每个请求里重新加载。FastAPI 提供了 lifespan 或 on_event 机制，可以方便地管理全局对象。下面是一个简单的本地模型加载示例，模型初始化后保存在全局变量中，请求到达时直接调用推理方法。
import os
import torch
from fastapi import FastAPI
from pydantic import BaseModel
from transformers import AutoTokenizer, AutoModelForTokenClassification
MODEL_PATH = os.environ.get("MODEL_PATH", "/app/models/srl")
class SRLRequest(BaseModel):
text: str
class SRLResponse(BaseModel):
words: list
roles: list
app = FastAPI(title="SRL Service")
model = None
tokenizer = None
@app.on_event("startup")
def load_model():
global model, tokenizer
tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH)
model = AutoModelForTokenClassification.from_pretrained(MODEL_PATH)
model.eval()
@app.post("/predict", response_model=SRLResponse)
def predict(request: SRLRequest):
inputs = tokenizer(request.text, return_tensors="pt", truncation=True, max_length=512)
with torch.no_grad():
outputs = model(**inputs).logits
predictions = torch.argmax(outputs, dim=2)
words = tokenizer.convert_ids_to_tokens(inputs["input_ids"][0])
roles = [model.config.id2label[p.item()] for p in predictions[0]]
return SRLResponse(words=words, roles=roles)
@app.get("/health")
def health():
return {"status": "ok"}
上面的接口只接收原始文本，返回分词结果和角色标签。实际业务中，SRL可能需要传入指定谓词，让模型只标注该谓词的论元。此时可以在请求体中增加 predicate_index 或 target_verb 字段。为了保持接口兼容，建议先做最小版本，后续再扩展。响应体使用 Pydantic 模型做校验，FastAPI 会自动生成 JSON Schema，前端或调用方可以直接查看接口文档。
并发方面，基于Python的推理服务默认是同步阻塞的。如果同时来多个请求，FastAPI 会分派到线程池，但底层模型推理涉及CPU或GPU计算，Python全局解释器锁会限制CPU密集型并发。对于小规模流量，设置单进程多线程足够；如果请求量大，需要将服务改为多 worker 模式运行，例如 uvicorn app:app --workers 2。不过要注意，多 worker 会重复加载模型，增加内存占用。更稳妥的方法是使用队列加批量推理，但实现复杂度更高。容器化部署时可以先通过资源限制和 worker 数量之间做平衡。
三、编写Dockerfile并构建镜像
把代码和模型文件固定后，就可以编写 Dockerfile。下面是一个基于 python:3.10-slim 的示例，假定项目根目录下有 app.py、requirements.txt 和 models 目录。
FROM python:3.10-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY app.py . COPY models ./models ENV MODEL_PATH=/app/models/srl ENV HANLP_HOME=/app/hanlp EXPOSE 8000 CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
构建命令很简单：docker build -t srl-service:0.1 .。如果依赖安装时间较长，可以把 requirements.txt 单独 COPY 并在 RUN pip 之前执行，这样只要依赖文件不变，Docker 就会复用缓存层。构建完成后，先不要急着推送到仓库，可以用 docker run --rm -it srl-service:0.1 python -c 'import torch; print(torch.__version__)' 检查关键依赖是否安装成功。也可以进入容器查看模型路径是否存在：docker run --rm -it srl-service:0.1 ls -lh /app/models/srl。
启动容器时建议限制资源并开启健康检查。docker run -d --name srl -p 8000:8000 --memory=4g --cpus=2 srl-service:0.1 可以避免单个容器耗尽宿主机内存。健康检查可以通过 curl 调用 /health 接口，Docker 会按照配置的间隔探测服务状态。如果模型加载失败导致 /health 无响应，容器会被标记为 unhealthy，编排工具可以及时重启。此外，把容器日志输出到 stdout，方便后续用 docker logs 或集中日志平台排查问题。
四、生产环境调优与常见问题
容器化SRL服务上线后，首先要关注内存。基于BERT的SRL模型加载后通常占用1GB到3GB内存，加上PyTorch运行时，单容器内存最好预留4GB以上。如果物理机内存有限，不要在同一台机器上启动过多 worker。可以使用 torch.set_num_threads 限制推理线程数，并设置环境变量 OMP_NUM_THREADS=1，避免线程争抢导致延迟抖动。GPU场景下，镜像中需要安装对应的CUDA版本，基础镜像可以换成 nvidia/cuda:12.1.0-base-ubuntu22.04，然后用 pip 安装带CUDA支持的 torch。
常见问题之一是冷启动慢。模型从磁盘载入到GPU显存需要时间，尤其在大体积模型上可能超过一分钟。可以将模型转换为 ONNX 或 TensorRT 格式来加速推理，但要注意算子兼容性。另一个问题是长文本导致超时，SRL模型对超过512个token的句子需要截断或分句，接口中最好加上 max_length 限制并返回明确错误信息。还有一类问题是容器重启后模型文件丢失，这通常是因为挂载卷配置错误。只要在 docker run 或 docker-compose 中把宿主机模型目录映射到 /app/models，重启后数据就不会丢。
如果需要横向扩展，可以使用 docker compose 或 Kubernetes 管理多个副本。在 compose 文件中定义服务、资源限制和健康检查，一条命令就能拉起多个容器。对于生产集群，建议把镜像推送到私有仓库，并通过 CI 流水线在代码提交后自动构建和测试。镜像标签不要使用 latest，应该用提交哈希或版本号，方便回滚。最终目标是把SRL服务变成无状态、可替换的推理节点，任何一台支持Docker的机器都能稳定运行同一套服务。
