在arm服务器使用Dokcer离线部署Markitdown

MarkItDown 是微软 开源的一个轻量级 Python 工具。可以将各种类型的文件和办公文档转换为 Markdown 格式，主要目的是为了方便大型语言模型（LLM）阅读以及用于文本分析流水线（Pipeline）。

官网地址

https://github.com/microsoft/markitdown

外网环境构建

为了构建速度快，提前拉取 ARM64 Python 镜像

docker pull --platform linux/arm64 python:3.12-slim

也可以临时绕过 BuildKit（由于BuildKit的本地构建缓存异常或损坏，一直卡在load界面）：

DOCKER_BUILDKIT=0 docker build -t markitdown:arm64 .

默认只对当前 Shell 会话及其子进程生效，不是永久设置。

Dockerfile文件内容

# Python official images publish linux/arm64 variants, so this works natively
# on 64-bit ARM hosts and can also be cross-built with Docker Buildx.
FROM python:3.12-slim

LABEL org.opencontainers.image.title="markitdown"
LABEL org.opencontainers.image.description="Convert files and office documents to Markdown"

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

WORKDIR /work

ARG MARKITDOWN_PIP_INDEX_URL=https://pypi.org/simple

# Install the core package plus the PDF, DOCX, and PPTX converters. These are
# the common office/document formats used by this deployment.
# Do not use markitdown[all] by default: optional AI/audio integrations can
# have incomplete ARM64 wheel support and are not needed for local conversion.
RUN python -m pip install --no-cache-dir \
        --index-url "${MARKITDOWN_PIP_INDEX_URL}" \
        'markitdown[pdf,docx,pptx,xlsx]' \
    && rm -rf /root/.cache

# Run as an unprivileged user. Input and output files should be mounted at /work.
RUN useradd --create-home --uid 10001 appuser \
    && chown appuser:appuser /work

USER appuser

ENTRYPOINT ["markitdown"]
CMD ["--help"]

同目录下新建.dockerignore文件，内容如下

# The image does not COPY files from the build context. Exclude everything so
# a large source directory or .git checkout is never sent to the Docker daemon.
**

构建命令

DOCKER_BUILDKIT=0 docker build \
  --pull=false \
  --build-arg MARKITDOWN_PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
  -t markitdown:arm64 .

构建成功后查看

# docker images | grep markitdown

markitdown       arm64          3f20576229be   About a minute ago   274MB

导出

docker save markitdown:arm64 | gzip > markitdown-arm64.tar.gz

外网环境执行

导入

gunzip -c markitdown-arm64.tar.gz | docker load

使用命令

docker run --rm \
  --user "$(id -u):$(id -g)" \
  --mount type=bind,source=/data/markitdown,target=/work \
  markitdown:arm64 \
  /work/input.pdf -o /work/output.md

这条命令的作用是：启动一个临时容器，把宿主机的 files 目录挂载到容器的 /work，将 /work/input.pdf 转换为 /work/output.md。

docker run --rm \
  --user "$(id -u):$(id -g)" \
  --mount type=bind,source="$PWD/files",target=/work \
  markitdown:arm64 \
  /work/input.pdf -o /work/output.md

各参数含义：

• docker run：运行容器
• --rm：命令执行结束后自动删除容器，不删除镜像和文件
• --user "$(id -u):$(id -g)"：使用当前宿主机用户身份运行，避免输出文件属于 root
• --mount ...：把宿主机目录挂载到容器目录
• source="$PWD/files"：宿主机当前目录下的 files
• target=/work：容器内的 /work
• markitdown:arm64：要运行的镜像
• /work/input.pdf：输入文件
• -o /work/output.md：输出文件

如果原始文件和目标文件都放在宿主机 /data/markitdown，执行：

mkdir -p /data/markitdown

把源文件放进去：

cp /path/to/input.pdf /data/markitdown/

然后运行：

docker run --rm \
  --user "$(id -u):$(id -g)" \
  --mount type=bind,source=/data/markitdown,target=/work \
  markitdown:arm64 \
  /work/input.pdf -o /work/output.md

执行完成后，文件会位于：

/data/markitdown/output.md

如果当前用户没有写入权限，先调整目录权限：

chown -R "$(id -u):$(id -g)" /data/markitdown

你也可以直接指定其他文件名，例如：

docker run --rm \
  --user "$(id -u):$(id -g)" \
  --mount type=bind,source=/data/markitdown,target=/work \
  markitdown:arm64 \
  /work/report.docx -o /work/report.md

图片无法在md文件中展示

解决办法：将文件中的图片转为base64存到md中

先确认当前版本支持显式保留图片数据

docker run --rm markitdown:arm64 --help | grep -i data

执行命令

docker run --rm \
  --user "$(id -u):$(id -g)" \
  --mount type=bind,source=/data/markitdown,target=/work \
  markitdown:arm64 \
  --keep-data-uris \
  /work/input.pptx -o /work/output.md

执行完成后，文件会位于：

/data/markitdown/output.md

转换中报错：缺失依赖

markitdown[...] 中填写的是需要安装的可选依赖（extras）。例如：

'markitdown[pdf,docx,pptx,xlsx]'

表示安装：

• pdf：PDF
• docx：Word .docx
• pptx：PowerPoint .pptx
• xlsx：Excel .xlsx

完整写法：

RUN python -m pip install --no-cache-dir \
        --index-url "${MARKITDOWN_PIP_INDEX_URL}" \
        'markitdown[pdf,docx,pptx,xlsx]' \
    && rm -rf /root/.cache

解决办法：需要修改 Dockerfile 后，重新构建镜像：

docker build -t markitdown:arm64 .

不是所有格式都需要额外依赖。遇到缺少依赖时，MarkItDown 的报错通常会直接提示，例如：

include the optional dependency [docx]

也可以安装全部可选依赖：

'markitdown[all]'

但这会安装音频、AI、云服务等额外组件，镜像更大，ARM64 兼容性也更复杂。对一般场景，建议只安装：

pdf,docx,pptx,xlsx

.dockerignore 作用

.dockerignore 用于控制执行 docker build . 时哪些文件不会被发送到 Docker daemon。

当前文件内容是：

**

表示忽略构建目录中的所有文件。

因为当前 Dockerfile 没有使用 COPY 或 ADD，构建时不需要任何宿主机文件，所以这样可以：

• 避免发送大量无关文件
• 避免把 .git、日志、测试文件或敏感配置发送给 Docker
• 减少构建上下文大小
• 加快构建速度

Docker 即使匹配了 **，仍会自动读取 Dockerfile 和 .dockerignore 本身。

如果以后 Dockerfile 需要复制文件，例如：

COPY app.py /app/app.py

则需要在 .dockerignore 中放行：

**
!app.py

.dockerignore 只影响构建上下文，不会影响运行时通过 -v 或 --mount 挂载的 /data/markitdown 文件。

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/qq_45083975/article/details/163568437