znlgis 博客

GIS开发与技术分享 — GDAL · GeoServer · PostGIS · QGIS · OpenLayers · Cesium · FreeCAD · NPOI

第二章：安装、部署与快速上手

本章介绍 DocuTranslate 的多种安装 / 部署方式，并带你跑通第一个翻译任务。你可以根据自己的情况选择其中一种：

前提：DocuTranslate 需要 Python 3.11 或更高版本（整合包与 Docker 已内置运行环境，无需自行安装 Python）。

2.1 整合包（懒人包，最省心）

对于希望快速上手、不想折腾环境的用户，官方在 GitHub Releases 提供 Windows 和 Mac 整合包，体积不到 40MB。

使用步骤：

  1. 打开 Releases 页面，下载对应操作系统的压缩包。
  2. 解压到任意目录。
  3. 运行其中的可执行程序，它会自动启动本地服务并打开浏览器界面。
  4. 在界面中填入你的 AI 平台 API-Key（如何获取见第四章），即可开始翻译。

整合包本质上就是把 Python 运行环境和 DocuTranslate 打包在一起的「绿色版」，功能与用 pip 安装完全一致。

2.2 使用 pip 安装

如果你的机器已经装好了 Python 3.11+，最直接的方式就是 pip：

# 基础安装
pip install docutranslate

# 如果需要 MCP 拓展（供 AI 助手调用，详见第十章）
pip install docutranslate[mcp]

# 启动图形界面（Web UI）
docutranslate -i

# 启动图形界面并同时启用 MCP SSE 端点
# docutranslate -i --with-mcp

安装完成后，docutranslate 就成为一个可用的命令行工具。运行 docutranslate -i 会在本机 8010 端口启动 Web 服务。

2.3 使用 uv 安装（推荐）

uv 是一个高性能的 Python 包与环境管理器，能自动创建隔离环境，避免污染全局 Python，官方推荐使用。

# 初始化一个项目环境（会生成 pyproject.toml 等）
uv init

# 基础安装
uv add docutranslate

# 安装 MCP 扩展
uv add docutranslate[mcp]

# 运行（--no-dev 表示不安装开发依赖）
uv run --no-dev docutranslate -i

# 同时启用 MCP
# uv run --no-dev docutranslate -i --with-mcp

uv 的好处是依赖被锁定在当前项目目录内，切换项目、卸载都很干净，也便于后续做成脚本。

2.4 使用 git 克隆源码

如果你想阅读 / 修改源码，或使用尚未发布到 PyPI 的最新特性，可以直接克隆仓库：

# 克隆仓库
git clone https://github.com/xunbu/docutranslate.git

cd docutranslate

# 用 uv 同步依赖（--no-dev 不装开发依赖）
uv sync --no-dev

# 仅额外安装 mcp 扩展
# uv sync --no-dev --extra mcp

# 安装全部可选扩展
# uv sync --no-dev --all-extras

同步完成后，即可用 uv run docutranslate -i 启动，或直接以模块方式运行源码。这种方式最适合参与开发或调试。

2.5 使用 Docker 部署

在服务器上部署、或希望环境完全隔离时，Docker 是最省事的方式：

# 后台运行，映射 8010 端口
docker run -d -p 8010:8010 xunbu/docutranslate:latest

# 交互式运行（可看到日志）
# docker run -it -p 8010:8010 xunbu/docutranslate:latest

# 指定某个版本（例如 v1.5.4）
# docker run -it -p 8010:8010 xunbu/docutranslate:v1.5.4

容器启动后，通过宿主机的 http://<服务器IP>:8010 访问 Web 界面。若要在容器内使用环境变量预置默认配置（如 API-Key），可用 -e 传入，例如 -e DOCUTRANSLATE_API_KEY=sk-xxx（环境变量清单见第十一章）。

生产环境建议：为容器挂载持久化目录保存输出、通过反向代理（Nginx / Caddy）加上 HTTPS 与访问认证。详见第九、十一章。

2.6 启动 Web UI 与 API 服务

无论用哪种方式安装，启动 Web 服务的核心命令都是 docutranslate -i。常用启动方式：

docutranslate -i                       # 启动图形界面，默认仅本地访问(127.0.0.1)
docutranslate -i --host 0.0.0.0        # 允许局域网内其他设备访问
docutranslate -i -p 8081               # 指定端口号
docutranslate -i --cors                # 启用默认的跨域(CORS)设置
docutranslate -i --with-mcp            # 启动界面的同时启用 MCP SSE 端点（共用队列、共用端口）
docutranslate --mcp                    # 仅启动 MCP 服务器（stdio 模式）
docutranslate --mcp --transport sse    # 启动 MCP 服务器（SSE 模式）
docutranslate --version                # 查看版本号
docutranslate --help                   # 查看全部可用参数

启动后：

  • 交互式界面：浏览器访问 http://127.0.0.1:8010（或你指定的端口）。
  • API 文档：完整的 Swagger UI 位于 http://127.0.0.1:8010/docs。
  • MCP SSE 端点：--with-mcp 方式启动时位于 http://127.0.0.1:8010/mcp/sse；--mcp 独立方式默认位于 http://127.0.0.1:8000/mcp/sse。

第九章会详细讲各命令行参数与 API 端点，第十章讲 MCP。

2.7 第一个翻译任务（三步走）

以最常见的「用 Web 界面翻译一个 txt / md 文件」为例，快速跑通：

  1. 启动服务：终端运行 docutranslate -i，浏览器自动打开或手动访问 http://127.0.0.1:8010。
  2. 填写模型配置：在界面中填入 base_url、api_key、model_id（例如智谱 glm-4-flash、DeepSeek deepseek-chat，如何获取见第四章），并选择目标语言（如「中文」）。
  3. 上传文件并翻译：选择要翻译的文件，点击开始翻译，等待进度完成后下载译文。

对于纯文本 / Markdown / Word / Excel / 字幕等文件，只需要一个大模型 API-Key 即可。只有翻译 PDF 才需要额外配置 PDF 解析引擎（MinerU Token 或本地部署），这部分见第四章。

如果你更喜欢写代码，可以直接用 Client SDK 跑第一个任务（详见第六章）：

from docutranslate.sdk import Client

client = Client(
    api_key="YOUR_API_KEY",
    base_url="https://api.deepseek.com/v1",
    model_id="deepseek-chat",
    to_lang="中文",
)

result = client.translate("path/to/your/document.txt")
print(f"翻译完成！保存位置: {result.save()}")

2.8 小结

  • 非技术用户用整合包；开发者用 pip / uv；改源码用 git；上服务器用 Docker。
  • 启动 Web 服务统一用 docutranslate -i，可加 --host、-p、--cors、--with-mcp 等参数。
  • 翻译纯文本类文件只需一个大模型 API-Key；翻译 PDF 才需要额外的 MinerU 解析引擎。
  • 下一章我们详细讲解 Web 界面的每一项操作。
↑