diff --git a/README.md b/README.md
index 63fd27e..5b0a62e 100644
--- a/README.md
+++ b/README.md
@@ -173,6 +173,16 @@ npm run dev         # Vite 开发服务器（5173），API 代理见 vite.config
 
 ## 模型配置
 
+### 首次部署 / 迁移到新电脑
+
+Python 虚拟环境（`.venv/`）**不可跨机器复制**：其中 `pyvenv.cfg`、`bin/` 下脚本的 shebang 及 `bin/python` 符号链接都写死了本机绝对路径，复制后无法运行，这是 Python 的设计，不能靠改文件修复。复制/迁移项目目录时排除 `.venv/`（`.gitignore` 已排除；整体拷贝时连同复制则先删除），到新机器上重建：
+
+```bash
+./scripts/start_models.sh  # 自动检测 .venv：未就绪（缺失/损坏/依赖未装全）时依 scripts/requirements.txt 重建，就绪则直接启动
+```
+
+> `.venv` 重建需按 `scripts/requirements.txt` 安装 115 个依赖（含 omlx，需可访问 GitHub），仅首次或 venv 失效时执行一次。
+
 任意 OpenAI 兼容接口均可使用：
 
 - **对话模型**（`/v1/chat/completions`，支持 SSE 流式）：用于问答与知识图谱实体抽取
diff --git a/scripts/requirements.txt b/scripts/requirements.txt
new file mode 100644
index 0000000..663a08a
--- /dev/null
+++ b/scripts/requirements.txt
@@ -0,0 +1,115 @@
+aiohappyeyeballs==2.7.1
+aiohttp==3.14.3
+aiosignal==1.4.0
+annotated-doc==0.0.5
+annotated-types==0.8.0
+anyio==4.14.2
+attrs==26.1.0
+beautifulsoup4==4.15.0
+certifi==2026.7.22
+cffi==2.1.1
+charset-normalizer==3.4.9
+click==8.4.2
+cobble==0.1.4
+cohere_melody==0.13.0
+cryptography==50.0.0
+datasets==5.0.1
+defusedxml==0.7.1
+dflash-mlx @ git+https://github.com/bstnxbt/dflash-mlx@5d70faebe3d0af0a3dae76fcc15cc731f7ba46da
+dill==0.4.1
+fastapi==0.141.1
+filelock==3.32.2
+flatbuffers==25.12.19
+frozenlist==1.8.0
+fsspec==2026.6.0
+h11==0.16.0
+hf-xet==1.6.0
+httpcore==1.0.9
+httpx==0.28.1
+huggingface_hub==1.27.0
+idna==3.18
+itsdangerous==2.2.0
+Jinja2==3.1.6
+jsonschema==4.26.0
+jsonschema-specifications==2025.9.1
+llguidance==1.8.0
+lxml==6.1.1
+magika==0.6.3
+mammoth==1.11.0
+markdown-it-py==4.2.0
+markdownify==1.2.3
+markitdown==0.1.6
+MarkupSafe==3.0.3
+mdurl==0.1.2
+miniaudio==1.71
+mistral_common==1.11.7
+mlx==0.32.0
+mlx-audio==0.4.8
+mlx-embeddings @ git+https://github.com/Blaizzy/mlx-embeddings@32981fa4e8064ed664b52071789dd18271fe4206
+mlx-lm==0.31.3
+mlx-metal==0.32.0
+mlx-vlm @ git+https://github.com/Blaizzy/mlx-vlm@5a4222a15c70cb3725179d591442b1fbe1044b60
+modelscope==1.39.1
+modelscope-hub==0.2.0
+mpmath==1.3.0
+multidict==6.7.1
+multiprocess==0.70.19
+networkx==3.6.1
+numpy==2.3.5
+omlx @ git+https://github.com/jundot/omlx@e4354435bbe8c0b9d5d60d3d3fa3cc02e97e0aa8
+onnxruntime==1.28.0
+openai-harmony==0.0.8
+opencv-python==5.0.0.93
+packaging==26.3
+pandas==3.0.5
+pdfminer.six==20260107
+pdfplumber==0.11.10
+pillow==12.3.0
+propcache==0.5.2
+protobuf==7.35.1
+psutil==7.2.2
+py-spy==0.4.2
+pyarrow==25.0.1
+pycountry==26.2.16
+pycparser==3.0
+pydantic==2.13.4
+pydantic-extra-types==2.11.1
+pydantic_core==2.46.4
+Pygments==2.20.0
+pypdfium2==5.12.1
+python-dateutil==2.9.0.post0
+python-dotenv==1.2.2
+python-multipart==0.0.32
+python-pptx==1.0.2
+PyYAML==6.0.3
+referencing==0.37.0
+regex==2026.7.19
+requests==2.34.2
+rich==15.0.0
+rpds-py==2026.6.3
+safetensors==0.8.0
+scipy==1.18.0
+sentencepiece==0.2.2
+setproctitle==1.3.7
+setuptools==84.0.0
+shellingham==1.5.4
+six==1.17.0
+socksio==1.0.0
+sounddevice==0.5.5
+soupsieve==2.9.2
+starlette==1.6.0
+sympy==1.14.0
+tabulate==0.10.0
+tiktoken==0.13.0
+tokenizers==0.22.2
+torch==2.13.0
+tqdm==4.70.0
+transformers==5.15.0
+typer==0.27.1
+typing-inspection==0.4.3
+typing_extensions==4.16.0
+urllib3==2.7.0
+uvicorn==0.52.1
+xlsxwriter==3.2.9
+xxhash==3.8.1
+yarl==1.24.5
diff --git a/scripts/start_models.sh b/scripts/start_models.sh
index b501c3f..f3b4f68 100755
--- a/scripts/start_models.sh
+++ b/scripts/start_models.sh
@@ -1,8 +1,9 @@
 #!/bin/bash
 # 启动本地 MLX 模型服务：chat + embedding 均由 oMLX(18080) 提供
 # chat=Qwen3.5-9B-MLX-4bit（4-bit），embedding=BGE-M3（oMLX 原生 BERT 系支持）
+# 首次运行自动检测 .venv：缺失/损坏（如来自其他机器）时按 requirements.txt 重建，就绪则跳过安装
 # 用法: ./scripts/start_models.sh
-set -u
+set -eu
 cd "$(dirname "$0")/.."
 ROOT=$(pwd)
 VENV="$ROOT/.venv"
@@ -10,6 +11,30 @@ LOG_DIR="$HOME/.omlx/logs"
 CACHE_DIR="$HOME/.omlx/cache"
 mkdir -p "$LOG_DIR" "$CACHE_DIR"
 
+# .venv 不可跨机复制（pyvenv.cfg / bin 脚本 shebang 写死本机路径），须在本机重建
+if [ ! -x "$VENV/bin/python" ]; then
+    if [ -d "$VENV" ]; then
+        echo "[warn] $VENV 存在但 python 不可用（可能来自其他机器），删除重建"
+        rm -rf "$VENV"
+    fi
+    if ! command -v python3 >/dev/null 2>&1; then
+        echo "[error] 未找到 python3，请先安装 Python >= 3.11" >&2
+        exit 1
+    fi
+    if ! python3 -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)' 2>/dev/null; then
+        echo "[error] 需要 Python >= 3.11（当前 $(python3 --version 2>&1)），omlx 依赖无法安装" >&2
+        exit 1
+    fi
+    echo "[setup] 创建 venv 并安装依赖（首次/新机器运行，见 scripts/requirements.txt）..."
+    python3 -m venv "$VENV"
+    "$VENV/bin/pip" install -r "$ROOT/scripts/requirements.txt"
+elif [ ! -x "$VENV/bin/omlx" ]; then
+    echo "[setup] venv 存在但依赖未装全，补装 scripts/requirements.txt ..."
+    "$VENV/bin/pip" install -r "$ROOT/scripts/requirements.txt"
+else
+    echo "[ok] .venv 已就绪，跳过安装"
+fi
+
 # oMLX 模型目录：chat（Qwen3.5-9B-MLX-4bit）+ embedding（bge-m3）均为实体目录，oMLX 按目录扫描注册模型
 OMLX_MODEL_DIR="$ROOT/models/mlx/omlx"