模型部署

本文介绍如何部署私有化本地模型。

一、模型下载

推荐从魔搭社区模型库下载所需模型。平台要求模型文件必须存放在容器内的 /home/models/ 目录下（或您通过卷挂载映射的宿主机对应路径），以便后续启动命令正确加载。

魔搭社区模型库

下载方式可参阅魔搭社区 文档 → 模型的下载：

模型下载文档入口

注意：

为正常使用灵州AI平台全套功能需要至少接入对话(LLM)、重排序(rerank)、向量化(embedding)三种模型各一个( 私有化部署或使用云服务API )

模型文件夹推荐下载至 /home/models/ 目录下。

模型文件夹命名和位置影响到模型启动命令和平台模型配置

1. 进入容器

启动容器：

docker start <容器名或ID>

或：

cd <项目路径>
docker compose up -d

进入容器：
```
docker exec -it <容器名或ID> bash
```

容器ID可以通过
docker ps -a
显示所有容器ID来寻找

2.安装依赖

依照期望的下载方式有两种选择：

安装 ModelScope 包（选用 ModelScope SDK 或 CLI 下载）
```
pip install modelscope
```

安装 Git 和 Git LFS（选用 Git 方式下载）

apt-get update && apt-get install -y git git-lfs
git lfs install

在下载模型前，请确保容器内已安装必要的工具依赖，若容器内未预装上述依赖，建议在构建镜像时将其写入 Dockerfile。

3.创建模型存放目录

在容器内部创建一个固定目录存放所有模型，本文均使用 /home/models 为例供参考：

mkdir -p /home/models

启动模型时会用到模型的存放路径

4.模型下载方式

方式一：ModelScope 命令行工具（推荐）

适用于高带宽环境，支持断点续传和模型高速下载。以下以 Qwen/Qwen2.5-7B-Instruct 为例：

modelscope download --model="Qwen/Qwen2.5-0.5B-Instruct" --local_dir ./model-dir

说明：

--model ：模型 ID，可以在魔搭社区模型页面找到。

--local_dir ：下载到容器内部的路径。

方式二：ModelScope Python SDK （推荐）

适用于需要脚本化或集成到现有流程的场景，同样支持断点续传和模型高速下载：

在容器命令行中直接执行下列代码即可（此处以 Qwen/Qwen2.5-7B-Instruct 为例，执行时须手动替换为实际名称）

python3 -c "from modelscope import snapshot_download; snapshot_download('Qwen/Qwen2.5-7B-Instruct', local_dir='/home/models/Qwen2.5-7B-Instruct')"

在容器内创建python文件然后执行该文件：
1. 进入存放脚本的目录
```
mkdir -p <文件路径>
cd <文件路径>
```
2. 使用 nano 或 vi 创建 Python 文件：
```
nano download_model.py
```
  如果没有 nano ，可以使用 vi ：
```
vi download_model.py
```
3. 在文件中输入下载代码（ model_id 指定模型， file_path 指定下载路径）
```
from modelscope.hub.file_download import model_file_download

model_dir = model_file_download(model_id='Qwen/QwQ-32B-GGUF',file_path='qwq-32b-q4_k_m.gguf')
```
4. 保存并退出：
  - nano ：按 Ctrl+O 保存，Enter 确认，Ctrl+X 退出
  - vi ：按 Esc 输入 :wq 保存并退出，再按 Enter 确认

方式三：Git + Git LFS

此方法方便使用git命令管理，也方便与市面平台集成，但是默认不支持断点续传，下载速度也主要由您的网络环境决定，不一定比推荐的工具快。

cd /home/models # 进入目标下载路径
git lfs install # 初始化Git LFS
git clone https://www.modelscope.cn/<owner_name>/<model-name>.git

在模型详情页面可以直接点击复制按钮替换 <owner_name>/<model-name> ：

如果希望跳过LFS大文件的下载，可以在git clone命令前添加 GIT_LFS_SKIP_SMUDGE=1 ，来只获取LFS指针，而不下载实际的大文件：

GIT_LFS_SKIP_SMUDGE=1 https://www.modelscope.cn/<namespace>/<model-name>.git

注意：

如果下载中断，需要手动进入目录执行 git lfs pull 重试。

为保证下载的模型文件完整可用，务必在安装 git-lfs 后执行 git lfs install 进行完整的初始化。

3. Docker 环境注意事项

事项	说明
网络配置	确保容器能够访问外网（魔搭社区 / ModelScope CDN）。如处于内网或代理环境，需配置相应的 HTTP/HTTPS 代理。
存储空间	大语言模型通常占用数十 GB 磁盘空间，请确保宿主机及容器卷有足够剩余空间。
权限设置	下载完成后，请确认模型目录及其文件对容器内运行用户可读，避免因权限问题导致启动失败。

4. 目录规范与验证

模型的下载位置必须在 /home/models/ 目录下，且建议以模型名称作为子目录名，以保持与后续启动命令中的 --model 参数路径一致。例如：

/home/models/
├── qwen3-vl-32b/
├── Qwen3-Embedding-0.6B/
└── bge-reranker-v2-m3/

下载完成后，可通过以下命令快速验证模型文件完整性：

ls -lh /home/models/<模型目录名>/
# 正常应包含 config.json、模型权重文件（.bin / .safetensors）等

若模型和 ModelScope SDK 做了原生集成，下载后仅需几行代码即可加载；对于暂未原生集成的模型，下载后可通过 vLLM、Transformers、Diffusers 等主流框架进行推理。

二、模型启动

以下指令均在容器内执行

请依照真实文件所在位置替换启动命令中的文件地址以及端口等参数

参数解释：

--model ：模型路径，必须对应下载的模型目录
--served-model-name ：启动服务时的唯一标识，用于接入平台
--port ：服务端口，可以自行修改，保证容器内外不冲突
--gpu-memory-utilization ：GPU占用比例，如果显存不足可调低
nohup ... & ：后台运行，日志写入 llm.log

模型启动验证失败常见情况：

情况	可能原因	处理方法
连接失败	模型未启动 / 端口被占用	检查容器内模型服务进程，确认端口配置
JSON 结构异常	模型启动异常	查看模型启动日志（`llm.log` 或 `embed.log`）
超时	容器资源不足	增加 GPU 显存 / 降低批量大小 / 检查并行配置

如果提示没有安装 curl 则执行 apt-get install -y curl 下载

1.大语言模型

以启动 qwen3.6-27b 作为示例：

模型文件下载位置： /data/models/Qwen/Qwen3.6-27B/
于端口 8080 开放

VLLM_USE_V1=0 \
TORCH_COMPILE_DISABLE=1 \
VLLM_SOURCE_BROADCAST_TIMEOUT=600 \
CUDA_VISIBLE_DEVICES=0,1,2,3 \
nohup python3 -m vllm.entrypoints.openai.api_server \
  --model /data/models/Qwen/Qwen3.6-27B/ \
  --served-model-name qwen3.6-27b-chat \
  --tensor-parallel-size 4 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.65 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --reasoning-parser qwen3 \
  --max-num-seqs 24 \
  --max-num-batched-tokens 32768 \
  --port 8080 \
  --host 0.0.0.0 \
> qwen27b_4card_32k.log 2>&1 &

其中这三个参数必须

  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --reasoning-parser qwen3 \

验证启动：

curl -X POST http://10.212.90.100:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model":"qwen3.6-27b-chat",
"tool_choice":"auto",
"tools":[{"type":"function","function":{"name":"get_weather","description":"查询城市天气","parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}}],
"messages":[{"role":"user","content":"查询北京今天天气"}]
}'

如果返回如下JSON 格式的回答，说明模型已成功启动，特别注意tool_calls这部分需要保持一致。

{
    "id": "chatcmpl-a50527387ff11a91",
    "object": "chat.completion",
    "created": 1780627846,
    "model": "qwen3.6-27b-chat",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": null,
                "refusal": null,
                "annotations": null,
                "audio": null,
                "function_call": null,
                "tool_calls": [
                    {
                        "id": "chatcmpl-tool-a66fdc9088519145",
                        "type": "function",
                        "function": {
                            "name": "get_weather",
                            "arguments": "{\"city\": \"北京\"}"
                        }
                    }
                ],
                "reasoning": "用户需要查询北京的天气，我可以使用get_weather工具，参数city设置为\"北京\"。"
            },
            "logprobs": null,
            "finish_reason": "tool_calls",
            "stop_reason": null,
            "token_ids": null
        }
    ],
    "service_tier": null,
    "system_fingerprint": null,
    "usage": {
        "prompt_tokens": 269,
        "total_tokens": 317,
        "completion_tokens": 48,
        "prompt_tokens_details": null
    },
    "prompt_logprobs": null,
    "prompt_token_ids": null,
    "kv_transfer_params": null
}

关闭模型

进入docker 容器

docker exec -it 容器id bash

pkill -f "vllm.entrypoints.openai.api_server" 

2.向量化模型

以启动 千问3-Embedding-0.6B-向量化模型 作为示例：

模型文件下载位置： /home/models/Qwen3-Embedding-0.6B/
于端口 8011 开放

VLLM_USE_V1=0 TORCH_COMPILE_DISABLE=1  CUDA_VISIBLE_DEVICES=2 nohup python3 -m vllm.entrypoints.openai.api_server \
    --model /home/models/Qwen3-Embedding-0.6B/ \
    --served-model-name qwen-embedding \
    --tensor-parallel-size 1 \
    --max-model-len 4096 \
    --gpu-memory-utilization 0.1 \
    --enforce-eager \
    --max-num-seqs 32 \
    --port 8080 --host 0.0.0.0 > embed.log 2>&1 &

**查看启动日志 **

tail embed.log -f

当显示Application startup complete. 说明模型启动成功

验证启动：

 curl http://127.0.0.1:8080/v1/models

如果返回 JSON 格式的回答，说明模型已成功启动。

3.重排序模型启动

以启动 BAAI/bge-reranker-v2-m3 作为示例：

模型文件下载位置： /home/models/bge-reranker-v2-m3
于端口 8013 开放

 CUDA_VISIBLE_DEVICES=3 nohup python3 -m vllm.entrypoints.openai.api_server   --model /home/models/bge-reranker-v2-m3   --served-model-name bge-rerank   --runner pooling   --tensor-parallel-size 1   --max-model-len 4096   --gpu-memory-utilization 0.1   --max-num-seqs 10   --enforce-eager   --port 8013 --host 0.0.0.0 > bge-rerank.log 2>&1 &

验证启动：

curl http://localhost:8013/v1/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-rerank",
    "query": "What is machine learning?",
    "documents": ["Machine learning is a branch of AI.", "The sky is blue today."]
  }'

如果返回 JSON 格式的回答，说明模型已成功启动。

模型关闭

pkill -f vllm.entrypoints.openai.api_server

三、接入平台

模型的接入需要获取下列参数：

模型服务启动时的标识 (参数 --served-model-name )
模型所擅长的能力类型
模型启动时使用的端口
模型服务相对应的API Key

四、常见问题排查

问题现象	可能原因	解决方案
模型启动报错 `FileNotFoundError`	模型路径错误或模型文件未下载完整	检查 `--model` 路径是否为 `/home/models/<模型名>/`，确认文件存在且完整
启动时显存不足	GPU 显存不足	调整 `--gpu-memory-utilization` 或降低 `--tensor-parallel-size`
容器内无法下载模型	网络不通或 DNS 解析失败	检查容器网络模式（建议使用 `bridge` 或 `host` 模式），配置 HTTP/HTTPS 代理
Git 克隆后模型无法加载	未安装 Git LFS，大文件未实际下载或下载中断	重新执行 `git lfs install && git lfs pull` 补全大文件
端口冲突	目标端口已被占用	修改启动命令中的 `--port` 参数，或释放占用端口的进程

更多模型下载与部署细节，请参阅 魔搭社区官方文档 。

一、模型下载​

1. 进入容器​

2.安装依赖​

3.创建模型存放目录​

4.模型下载方式​

方式一：ModelScope 命令行工具（推荐）​

方式二：ModelScope Python SDK （推荐）​

方式三：Git + Git LFS​

3. Docker 环境注意事项​

4. 目录规范与验证​

二、模型启动​

1.大语言模型​

2.向量化模型​

3.重排序模型启动​

模型关闭​

三、接入平台​

四、常见问题排查​

一、模型下载

1. 进入容器

2.安装依赖

3.创建模型存放目录

4.模型下载方式

方式一：ModelScope 命令行工具（推荐）

方式二：ModelScope Python SDK （推荐）

方式三：Git + Git LFS

3. Docker 环境注意事项

4. 目录规范与验证

二、模型启动

1.大语言模型

2.向量化模型

3.重排序模型启动

模型关闭

三、接入平台

四、常见问题排查