# 大模型私有化简易测试部署教程（Docker+Docker-Compose 本地部署）

## 一、部署概述

本文提供一套**纯本地、轻量化、仅用于测试和Demo**的大模型私有化部署方案，基于 Docker 与 Docker-Compose 实现，无需复杂环境配置。整体方案分为两大模块：

1. **Ollama 基础服务**：快速运行、管理本地大模型，提供统一调用接口，作为模型运行载体；

2. **HuggingFace 镜像环境**：搭建国内加速的模型下载环境，解决境外模型下载慢、超时、失败问题，支持自定义模型下载后导入 Ollama 使用。

本方案**非生产环境**，仅适用于功能测试、效果演示、本地开发调试，全程适配国内网络，配置清华PyPI源、PyTorch官方CPU源、HF国内镜像源，规避网络访问问题。

## 二、整体目录结构

统一规划项目目录，结构清晰、脚本解耦，方便后续维护和批量管理模型，完整目录如下：

```Plain Text
├── huggingface
│   ├── Dockerfile          # HuggingFace 自定义镜像构建文件
│   ├── download_models.sh  # 国内加速下载HF模型脚本
│   ├── load_model_2_ollama.sh  # 本地模型导入Ollama脚本
│   ├── models              # 本地模型存储目录（自动生成）
│   └── requirements.txt    # Python依赖配置
├── ollama
│   ├── docker-compose.yaml # Ollama服务编排配置
│   ├── ollama_data         # Ollama数据持久化目录（自动生成）
│   ├── ollama.sh           # Ollama快捷操作脚本
│   ├── start_ollama.sh     # Ollama启动脚本
│   └── stop_ollama.sh      # Ollama停止脚本
    
```

## 三、Ollama 服务部署（模型运行核心）

Ollama 负责大模型的本地加载、运行、推理调用，通过Docker容器化部署，实现数据持久化、端口本地映射，支持一键拉取、运行、管理各类开源大模型。

### 3.1 编写 docker-compose 配置文件

在 `ollama` 目录下创建 `docker-compose.yaml`，配置镜像、端口、数据挂载、DNS解析，保障国内网络稳定性：

```Plain Text
services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ./ollama_data/:/root/.ollama  # 数据持久化，重启容器不丢失模型
    dns:
      - 8.8.8.8  # 优化域名解析，规避国内DNS解析异常

```

### 3.2 Ollama 基础部署与常用命令

进入 ollama 目录，执行以下命令启动服务：

```Plain Text
# 后台启动Ollama服务
docker-compose up -d

# 查看服务运行状态
docker-compose ps

```

Ollama 容器启动后，可通过以下核心命令管理本地模型（测试常用）：

```Plain Text
# 1. 拉取开源大模型（示例：deepseek-r1:7b 轻量测试模型）
docker exec -it ollama ollama pull deepseek-r1:7b

# 2. 运行模型，进入交互式对话测试
docker exec -it ollama ollama run deepseek-r1:7b

# 3. 查看本地已下载的所有模型
docker exec -it ollama ollama list

# 4. 停止指定模型运行
docker exec -it ollama ollama stop deepseek-r1:7b

# 5. 删除本地模型
docker exec -it ollama ollama rm deepseek-r1:7b

```

## 四、HuggingFace 国内加速环境部署（模型下载）

原生 HuggingFace 官方源国内访问极慢、易超时，本方案基于 Python 官方镜像，自定义构建容器环境，搭配**清华PyPI源、PyTorch CPU专用源、HF国内镜像源**，实现模型高速稳定下载，支持任意HF开源模型本地化保存。

### 4.1 配置 Python 依赖 requirements.txt

在 `huggingface` 目录创建 `requirements.txt`，包含模型下载、推理核心依赖，适配CPU测试环境：

```Plain Text
# 模型推理核心依赖
torch
transformers==4.48.3
huggingface-hub==0.28.1
tokenizers==0.21.0
safetensors

# 工具辅助依赖
numpy
tqdm
requests

```

### 4.2 编写 Dockerfile 构建自定义镜像

基于轻量化 `python:3.14.5-slim` 镜像构建专属环境，区分依赖下载源：PyTorch 从官方CPU源安装，其余依赖从清华源加速安装，规避安装失败问题：

```Plain Text
FROM python:3.14.5-slim

# 关闭Python缓冲区，日志实时输出
ENV PYTHONUNBUFFERED=1

# 设定工作目录
WORKDIR /workspace

# 复制依赖配置文件
COPY requirements.txt .

# 升级基础包，使用清华源加速
RUN pip install --upgrade pip setuptools wheel -i https://pypi.tuna.tsinghua.edu.cn/simple --root-user-action=ignore

# 安装核心依赖：
# 1. PyTorch 强制使用官方CPU源
# 2. 其余包使用清华镜像源
RUN pip install --no-cache-dir \
    --index-url https://download.pytorch.org/whl/cpu \
    --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple \
    -r requirements.txt \
    --root-user-action=ignore

```

### 4.3 构建自定义镜像

进入 `huggingface` 目录，执行构建命令，生成名为 `my-transformers-cpu` 的本地镜像：

```Plain Text
# 构建镜像，当前目录为构建上下文
docker build -t my-transformers-cpu .

```

### 4.4 编写模型批量下载脚本 download_models.sh

通过 HF 国内镜像站 `https://hf-mirror.com` 加速下载，支持自定义模型ID，自动创建本地存储目录，适配断点续传、超时优化：

```Plain Text
#!/bin/bash
# 大模型国内加速下载脚本
# 用法: ./download_models.sh [HF模型ID]
# 示例:
#   ./download_models.sh                     # 默认下载 bert-base-uncased 测试模型
#   ./download_models.sh prajjwal1/bert-tiny # 下载轻量化 tiny 测试模型

set -e

# 默认测试模型（约400MB，适合快速测试）
DEFAULT_MODEL="bert-base-uncased"

# 接收自定义模型参数
MODEL_ID="${1:-$DEFAULT_MODEL}"

# 解析模型名称，作为本地存储目录名
MODEL_NAME="${MODEL_ID##*/}"
LOCAL_DIR="./models/${MODEL_NAME}"

# 创建本地模型存储目录
mkdir -p "$LOCAL_DIR"

echo ">>> 准备下载模型: $MODEL_ID"
echo ">>> 本地保存路径: $LOCAL_DIR"
echo ">>> 下载加速源: https://hf-mirror.com (国内公益镜像)"
echo ""

# 启动容器执行模型下载，配置国内镜像与超时时间
docker run -it --rm \
  -v "$(pwd)/$LOCAL_DIR:/models" \
  -e HF_ENDPOINT="https://hf-mirror.com" \
  -e HF_HUB_DOWNLOAD_TIMEOUT=120 \
  my-transformers-cpu \
  huggingface-cli download "$MODEL_ID" --local-dir /models

echo ""
echo "✅ 模型下载完成！本地路径: $LOCAL_DIR"

```

### 4.5 赋予脚本执行权限并使用

```Plain Text
# 赋予执行权限
chmod +x download_models.sh

# 下载默认测试模型
./download_models.sh

# 下载指定HF模型
./download_models.sh 模型ID

```

## 五、本地HF模型导入Ollama服务

对于下载到本地的HF模型，可通过脚本一键导入Ollama，实现本地模型私有化运行，无需重复下载。

### 5.1 编写模型导入脚本 load_model_2_ollama.sh

```Plain Text
#!/bin/bash
# 本地HF模型导入Ollama脚本
# 用法: ./load_model_2_ollama.sh <本地模型目录名>
# 示例: ./load_model_2_ollama.sh distil-qwen3-0.6b-SHELLper

set -e

# 校验输入参数
if [ $# -eq 0 ]; then
    echo "错误：请指定模型目录名称"
    echo "用法: $0 <模型目录名>"
    exit 1
fi

MODEL_DIR_NAME="$1"
BASE_MODELS_PATH="$HOME/huggingface/models"
MODEL_PATH="$BASE_MODELS_PATH/$MODEL_DIR_NAME"

# 校验模型目录是否存在
if [ ! -d "$MODEL_PATH" ]; then
    echo "错误：模型目录不存在: $MODEL_PATH"
    exit 1
fi

# 校验模型配置文件 Modelfile
if [ ! -f "$MODEL_PATH/Modelfile" ]; then
    echo "错误：在 $MODEL_PATH 中未找到 Modelfile 配置文件"
    exit 1
fi

# 校验Modelfile中指定的GGUF模型文件
GGUF_FILE=$(grep -E '^FROM\s+' "$MODEL_PATH/Modelfile" | head -n1 | sed -E 's/^FROM\s+//' | tr -d ' ')
if [ -n "$GGUF_FILE" ] && [ ! -f "$MODEL_PATH/$GGUF_FILE" ]; then
    echo "错误：Modelfile 绑定的模型文件 $GGUF_FILE 不存在"
    exit 1
fi

# 校验Ollama容器运行状态
CONTAINER_NAME="ollama"
if ! docker ps --format "table {{.Names}}" | grep -q "^$CONTAINER_NAME$"; then
    echo "错误：Ollama容器未启动，请先启动ollama服务"
    exit 1
fi

# 容器内临时目录存储模型文件
CONTAINER_TMP="/tmp/ollama_import_$MODEL_DIR_NAME"
echo ">>> 创建容器临时目录: $CONTAINER_TMP"
docker exec "$CONTAINER_NAME" mkdir -p "$CONTAINER_TMP"

# 复制本地模型文件到Ollama容器
echo ">>> 正在导入模型文件至容器（大模型请耐心等待）..."
docker cp "$MODEL_PATH/." "$CONTAINER_NAME:$CONTAINER_TMP/"

# 在Ollama中创建本地模型
MODEL_NAME="$MODEL_DIR_NAME"
echo ">>> 正在Ollama中注册模型: $MODEL_NAME"
docker exec "$CONTAINER_NAME" ollama create "$MODEL_NAME" -f "$CONTAINER_TMP/Modelfile"

# 清理临时文件
echo ">>> 清理容器临时资源"
docker exec "$CONTAINER_NAME" rm -rf "$CONTAINER_TMP"

echo ""
echo "✅ 模型导入Ollama成功！"
echo "👉 运行模型命令: docker exec -it ollama ollama run $MODEL_NAME"

```

### 5.2 脚本使用方式

```Plain Text
# 赋予执行权限
chmod +x load_model_2_ollama.sh

# 导入本地模型（参数为 models 下的模型文件夹名）
./load_model_2_ollama.sh 模型目录名

```

## 六、部署核心优化说明（国内网络适配）

本方案全程解决国内部署大模型的核心痛点，所有源均做本土化适配：

1. **PyPI依赖安装**：使用清华开源镜像站 `https://pypi.tuna.tsinghua.edu.cn/simple`，加速Python依赖安装；

2. **PyTorch安装**：单独指定官方CPU源 `https://download.pytorch.org/whl/cpu`，避免清华源PyTorch版本缺失、安装失败问题；

3. **模型下载**：基于HF国内公益镜像 `https://hf-mirror.com`，替代官方境外地址，解决模型下载超时、断连、403问题；

4. **超时优化**：配置 `HF_HUB_DOWNLOAD_TIMEOUT=120`，延长下载超时时间，适配大体积模型。

## 七、整体部署流程总结

1. 搭建目录结构，创建所有配置文件与脚本；

2. 启动 Ollama Docker 服务，搭建模型运行环境；

3. 构建 HuggingFace 自定义CPU镜像；

4. 使用加速脚本下载任意HF开源大模型到本地；

5. 将本地模型导入Ollama，实现私有化本地测试运行。

## 八、注意事项

- 本方案**仅用于测试、Demo、本地开发**，不支持生产环境高并发、高可用、负载均衡场景；

- Gated权限模型（需授权模型），需先在HuggingFace官网申请权限、获取Token，再通过脚本带Token下载；

- 所有模型均本地化存储，无需联网即可推理运行，实现离线私有化测试；

- 首次构建镜像、下载模型耗时较长，后续可重复使用镜像和本地模型文件。

AI整理文字

本文提供一套纯本地、轻量化、仅用于测试和Demo的大模型私有化部署方案，基于 Docker 与 Docker-Compose 实现，无需复杂环境配置。整体方案分为两大模块：

大模型私有化简易测试部署教程

本文提供一套**纯本地、轻量化、仅用于测试和Demo**的大模型私有化部署方案，基于 Docker 与 Docker-Compose 实现，无需复杂环境配置。

编程语言

本教程提供基于Docker+Docker-Compose的大模型本地私有化部署方案，包含Ollama模型运行服务和HuggingFace国内加速下载环境。方案采用清华PyPI源、PyTorch CPU源和HF国内镜像，解决国内网络访问问题，支持模型快速下载、本地导入和私有化运行，适合开发测试和Demo演示。

负载均衡

容器

Docker

Python

2026上云采购 | AI焕新·智启新局

tione

DNS解析新购特惠59元起，续费优惠低至5.3折！

热销域名限时优惠，新客首年免费！


domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

大模型私有化简易测试部署教程-腾讯云开发者社区-腾讯云

大模型私有化简易测试部署教程

大模型私有化简易测试部署教程

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐