From d295adc300081cff33cc19b3a45d096e081ff943 Mon Sep 17 00:00:00 2001
From: SZCJW <792430652@qq.com>
Date: Sun, 29 Mar 2026 05:57:45 +0800
Subject: [PATCH] x

---
 README.md        | 11 +++++++++++
 requirements.txt |  1 +
 2 files changed, 12 insertions(+)

diff --git a/README.md b/README.md
index edfb933..2b39af2 100644
--- a/README.md
+++ b/README.md
@@ -143,3 +143,14 @@ curl -X POST "http://localhost:8001/v1/chat/completions" \
 - 首次部署建议设置 `GPU_MEMORY_UTILIZATION=0.90`，稳定后再调高
 - 若模型较大且吞吐压力高，可逐步调低 `MAX_MODEL_LEN` 或 `MAX_NUM_SEQS`
 - 确保宿主机已正确安装 ROCm 驱动并暴露 `/dev/kfd` 与 `/dev/dri`
+
+## 常见故障排查
+
+- 报错 `model type qwen3_5_moe ... Transformers does not recognize this architecture` 时，先重建镜像以更新依赖：
+
+```bash
+docker compose build --no-cache
+docker compose up -d --force-recreate
+```
+
+- 若仍报相同错误，说明当前 `vLLM/Transformers` 组合不支持该模型架构，建议在 `config.json` 切到其他本地模型，或升级基础镜像到更新的 vLLM 版本。
diff --git a/requirements.txt b/requirements.txt
index 3ae98d3..e96726b 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,3 +1,4 @@
 fastapi==0.116.1
 uvicorn==0.35.0
 pydantic==2.11.7
+transformers>=4.57.0