在Ubuntu上部署OpenMAIC

Created on May 22, 2026

2026   ·   AI   OpenMAIC   ·   AI

1. 安装WSL2

使用管理员启动PowerShell，执行启用WSL2：

# 启用WSL功能：/all -- 所有用户启用，/norestart -- 不重启系统
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
# WSL2 依赖 Windows 虚拟机功能，需要额外启用
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
# 将WSL2设为默认WSL
wsl --set-default-version 2

执行完成之后，重启win10/win11。

接下来在WSL2中安装Ubuntu系统。

# 查看可用的WSL发行版本
wsl --list --online

# 安装过程中，在用户目录下如果有.wslconfig引起的错误，可用直接上这个配置文件
# 安装过程中，会提示输入用户名和密码，输入完成之后就安装完成了
wsl --install -d Ubuntu-26.04 --location D:\WSL\Ubuntu-26.04

其他命令列表：

# 退出 WSL
wsl --shutdown

# 验证安装
wsl -l -v

# 启动
wsl -d Ubuntu-26.04

# 删除命令
wsl --unregister Ubuntu-26.04
Remove-Item -Recurse -Force "D:\WSL\Ubuntu-26.04"

如果Windows系统上安装了Nvidia CUDA套件，WSL2会自动安装Nvidia驱动程序，并且可以直接使用GPU进行计算。使用命令nvidia-smi可以验证GPU是否可用。

安装并启动之后，可以在Windows中访问WSL2中的Ubuntu系统，比如在文件管理器中输入路径\\wsl$\Ubuntu-26.04\home\<用户名>\。也可以从WSL/Ubuntu系统中访问Windows文件系统，比如输入路径/mnt/d/访问D盘。

1.1. WSL2/Ubuntu 26.04 系统配置

Ubuntu 26.04系统更换软件源。备份之后清空文件/etc/apt/sources.list.d/ubuntu.sources，并粘贴如下内容：

Types: deb
URIs: https://mirrors.aliyun.com/ubuntu
Suites: resolute resolute-updates resolute-backports
Components: main restricted universe multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

Types: deb
URIs: https://mirrors.aliyun.com/ubuntu
Suites: resolute-security
Components: main restricted universe multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

安装必要的软件：

sudo apt install -y git cmake build-essential wget unzip vim htop
sudo apt install python3 python3-pip -y

资料:

1.2. WSL清理及备份

首先查看Ubuntu占用空间分配情况：

usdo apt install -y ncdu
sudo ncdu --exclude="mnt*" --exclude="proc*" /

#####################
# docker 清理
docker volume prune # 清理 无用的volumes
docker system prune # 删除无用的镜像和容器及构建缓存

# 删除不必要的docker
docker images
docker rmi xxx

执行WSL压缩（在windows/powrshell环境下）：

wsl --shutdown
diskpart

DISKPART> select vdisk file="D:\WSL\Ubuntu-26.04\ext4.vhdx"
DISKPART> compact vdisk
DISKPART> detach vdisk
# 退回到Powershell环境

备份及恢复命令：

# 备份指定系统到指定位置
wsl --export Ubuntu-26.04 D:\Ubuntu-26.04.tar

# 还原指定系统
wsl --import Ubuntu-26.04 D:\Ubuntu-26.04.tar

2. 安装Nodejs以及pnpm

需要安装Node.js和pnpm，并更换源，命令如下：

# 可以使用nvm在本地安装Node.js以及npm，并选择Node.js/npm 的版本
# nvm是一个Node.js版本管理工具：https://github.com/nvm-sh/nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
nvm install 24 # 安装Node.js 24版本
nvm use 24 # 切换到Node.js 24版本
node -v # 验证Node.js版本

# 也可以管理员安装Node.js
sudo apt install nodejs npm
node -v # 验证Node.js版本
npm -v # 验证npm版本

# 安装pnpm
npm install -g pnpm

# 更换源为阿里云，阿里云速度快，同步及时
npm config set registry https://registry.npmmirror.com
pnpm config set registry https://registry.npmmirror.com

3. 安装 docker 以及 NVIDIA Container Toolkit

需要在带Nvidia GPU的服务器上部署MinerU。不带GPU的服务器，使用CPU运行MinerU，性能会非常差。

MinerU可以使用本地部署，或者使用docker部署。使用docker部署+Nvidia GPU，需要安装NVIDIA Container Toolkit。

首先在WSL2/Ubuntu系统上安装docker，命令如下：

sudo apt-get update
sudo apt-get install -y ca-certificates curl util-linux-extra
sudo install -m 0755 -d /etc/apt/keyrings

# 从阿里云下载 GPG key
sudo curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 使用阿里云仓库，原始仓库国内连接不上
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://mirrors.aliyun.com/docker-ce/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 将当前用户添加到docker用户组中，以便不使用sudo运行docker命令
sudo usermod -aG docker $USER
newgrp docker

再执行安装NVIDIA Container Toolkit的命令：

# Install the prerequisites for NVIDIA Container Toolkit
sudo apt-get update && sudo apt-get install -y --no-install-recommends ca-certificates curl gnupg2

# Configure the production repository and the GPG key
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# Optional: use experimental packages
sudo sed -i -e '/experimental/ s/^#//g' /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt update

# Install the NVIDIA Container Toolkit packages
export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.19.1-1
sudo apt-get install -y \
      nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
      nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
      libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
      libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

安装完成之后，执行如下命令配置docker使用NVIDIA Container Toolkit：

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

验证 NVIDIA Container Toolkit 是否安装成功：

docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi

3.1. 配置 docker Hub 仓库镜像

sudo tee /etc/docker/daemon.json <<EOF
{
  "runtimes": {
    "nvidia": {
      "args": [],
      "path": "nvidia-container-runtime"
    }
  },
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://mirror.baidubce.com"
  ]
}
EOF

sudo systemctl restart docker

参考资料：

4. 安装/部署/运行 MinerU

下载仓库：

git clone https://github.com/opendatalab/MinerU.git

构建镜像：

cd MinerU/docker/china

mkdir -p ~/mineru/pdfs
mkdir -p ~/mineru/output
cp ../../demo/pdfs/demo1.pdf ~/mineru/pdfs/

docker run --rm --gpus=all -v ~/mineru/pdfs:/data/pdfs -v ~/mineru/output:/data/output mineru:latest mineru -p /data/pdfs/demo1.pdf -o /data/output

其中：

  • -v ~/mineru/pdfs:/data/pdfs 将本地的pdfs目录挂载到容器的/data/pdfs目录，-v ~/mineru/output:/data/output 将本地的output目录挂载到容器的/data/output目录。
  • mineru -p /data/pdfs/demo1.pdf -o /data/output 是在容器中运行MinerU命令，指定输入pdf文件和输出目录。
  • -p、-o两个参数，表示运行一次MinerU，处理一个pdf文件，输出结果到指定目录。随后就退出了，导致docker容器也随之退出。
  • --gpus=all去掉这个参数，则使用CPU进行计算，速度会非常慢。
  • 使用docker images命令可以查看本地的docker镜像列表，确认是否成功构建了mineru:latest镜像。

MinerU的另外一种方式：

docker run -it --name mineru --gpus=all mineru:latest /bin/bash

这种方式，会在容器中启动一个交互式的bash终端，用户可以在这个终端中执行MinerU命令，处理多个pdf文件，输出结果到指定目录。用户可以在这个交互式终端中执行多次MinerU命令，处理多个pdf文件，输出结果到指定目录。用户处理完成之后，可以输入exit命令退出交互式终端，随之docker容器也会退出。

MinerU还提供web方式访问，使用Gradio Web进行部署，见参考博客。

使用如上命令运行docker+MinerU，构建镜像的Dockerfile文件中，是使用pip安装的方式安装MinerU的依赖包，与本地代码没有关系，即不会部署本地代码。

4.1. Docker compose 服务

在生产环境下，使用docker compose部署服务会更方便，运行命令如下：

# CDN加速下载compose.yaml文件，避免下载失败
# compose.yml文件中，是使能了GPU的配置
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/compose.yaml

# 运行命令，启动服务。docker在后台运行，使用`-d`参数
docker compose -f compose.yaml --profile api up -d

# 验证服务是否就绪
curl http://localhost:8000/health

# 停止并移除容器（推荐）
docker compose -f compose.yaml --profile api down
# 只停止不删除容器
docker compose -f compose.yaml --profile api stop

其他关联命令用法：

# 查看容器状态
docker compose -f compose.yaml --profile api ps

# 查看日志
docker logs -f mineru-api
docker logs -f -t mineru-api # 带时间戳的日志

# 查看日志，另外一种方式
docker compose -f compose.yaml --profile api logs -f # 实时日志
docker compose -f compose.yaml --profile api logs --tail=100 # 查看最近100行日志

MinerU服务的所有配置，都在compose.yaml文件中，如端口、镜像名称等等。

MinerU启动之后，在OpenMAIC的配置文件.env.local中，将MINERU_API_URL=http://localhost:8000，即可使用本地部署的MinerU服务。

有关MinerU后端参数，见MinerU仓库的issue：使用docker compose启动mineru-api，如何选择hybrid-auto-engine和vlm-auto-engine。

MinerU不能很好的识别pdf中的目录结构，转换得到的markdown文件，目录似乎会都识别成二级目录##。需要借助LLM进行辅助识别，可以使用本地部署Ollama，或者第三方LLM（付费，需要API Key）。见MinerU代码仓库的Discussions：5003、4413。

4.2. MinerU 环境变量

部分实用可配置的 MinerU 环境变量：

# 限制单卡GPU显存
export MINERU_VIRTUAL_VRAM_SIZE=8

# 使用modelscope源加速国内下载，默认HuggingFace
# 官方文档：https://opendatalab.github.io/MinerU/zh/usage/model_source/
export MINERU_MODEL_SOURCE=modelscope

# 指定使用pipeline后端
#export MINERU_BACKEND=pipeline

4.3. MinerU　测试

如下测试命令，将 MinerU 返回的json结果保存到mineru_response.json文件中，并将响应头保存到mineru_headers.txt文件中：

curl.exe -F "files=@E:\义务教育教科书·物理八年级全一册.pdf" -F "parse_method=auto" -F "backend=hybrid-auto-engine" -F "return_content_list=true" -F "return_images=true" http://172.22.191.184:8000/file_parse -o mineru_response.json --max-time 1800 -D mineru_headers.txt -sS

4.4. 部分资料

5. 本地部署 QWen TTS

TODO

5.1. 资料

  • MOSS-TTS：MOSS-TTS主打高保真，相对QWen TTS，Voice Clone时间比较长（QWen TTS似乎限制3秒），但QWen TTS时延小（<96ms）。另外，MOSS-TTS nano版本占用资源很小，可以在CPU上运行。

6. 部署及使用 OpenMAIC

docker部署、运行命令，以及清理命令如下：

# 在OpenMAIC代码目录中
docker build --no-cache -t openmaic .
# docker build --no-cache --build-arg APK_MIRROR=mirrors.aliyun.com --build-arg NPM_REGISTRY=https://registry.npmmirror.com -t openmaic .
docker run --rm -p 3000:3000 --env-file .env.local openmaic

docker stop $(docker ps -q --filter "ancestor=openmaic") 2>/dev/null
docker rm $(docker ps -aq --filter "ancestor=openmaic") 2>/dev/null

# 清理所有项目的 BuildKit 缓存
docker builder prune -f

.env.local配置文件基于.env.example修改如下：

# 本地部署的MinerU服务地址，远程则还需要远程地址及API Key
PDF_MINERU_BASE_URL=http://172.22.191.184:8000
# PR提交的新增的参数，设置OpenMAIC等待MinerU的时间，单位秒，默认5分钟
MINERU_TIMEOUT_MS=1800000

# 使用DeepSeek模型，配置API Key
DEEPSEEK_API_KEY=<....>
DEEPSEEK_BASE_URL=
# Example: deepseek-v4-pro,deepseek-v4-flash
DEEPSEEK_MODELS=deepseek-v4-pro

# web search引擎的API Key
TAVILY_API_KEY=<....>

# 配置Porxy
HTTP_PROXY=http://192.168.11.139:7890
HTTPS_PROXY=http://192.168.11.139:7890

# 允许局域网访问，如localhost，192.168.x.x等
ALLOW_LOCAL_NETWORKS=true

6.1. 平台链接



    Enjoy Reading This Article?

    Here are some more articles you might like to read next:

  • AI工具大全
  • Fast DDS入门（On-Going）
  • NVIDIA GPU 架构：SP、SM 与 LSU 工作原理详解
  • al-folio 模板定制修改总结
  • al-folio 部署记录（Ubuntu 24.04）