[qiulang]

DOC: add Docker Swarm deployment guide

This PR adds a guide for deploying Xinference across multiple machines with Docker Swarm

The guide covers:

• why Docker Swarm is a better choice than Kubernetes for a cluster of a dozen or so machines GPU machines, and where it falls short (mainly GPU support)
• how Swarm's manager/node relates to Xinference's supervisor/worker
• the changes needed to run the distributed compose file on Swarm: starting the supervisor and workers with their overlay IP (--host $(hostname -i)), adding an nginx proxy so the Web UI is reachable from outside, and declaring GPUs with generic resources

Note: how Swarm's manager/node relates to Xinference's supervisor/worker is my own understanding (so it may need further check)and I write this section to help other better understand swarm.

Attached the Chinese version for localization why-swarm.pdf

[gemini-code-assist]

Code Review

This pull request introduces a new documentation guide, using_docker_swarm.rst, detailing distributed deployment of Xinference using Docker Swarm. The guide covers Swarm's advantages over Kubernetes for small clusters, GPU support limitations, and adaptation steps for the official compose file. The review feedback highlights a syntax error in a section header underline and points out several broken references to missing files (docker-compose-swarm.yml and setup-gpu-swarm.sh) and non-existent sections within the deployment guide.

[qinxuye]

Two additional correctness issues are noted inline. The existing threads already cover the missing Compose file, setup script, and deployment-guide sections; please address those together and include the referenced nginx configuration so the documented deployment is reproducible.

For documentation integration, please also add this page to the getting-started toctree and provide the corresponding gettext updates for the maintained locales, as required by the repository guidance.

[qiulang]

@qinxuye 我再说下我写这个初衷：微信群里我在3月3号就发了这份文档的第一稿，不过当时给我感觉大家兴趣不大，也可能对swarm了解不多，所以我也就没再提。接着因为自己工作也忙，这件事就搁置下来了。直到这次1 0.1 假期长我有些闲工夫，我就把它当成一个还债的任务做个了解 。过了7个月，一直觉得有件事没了。而且我碰到太多次 只有10台也去就要上马k8s 情况，这种情况下使用k8s完全是自找麻烦，得不偿失。但现在可能很多人对swarm了解确实不多， docker-compose-distributed.yml 也是一个单机版部署，虽然名字叫 distributed。

但我这个文档更多写的 why， 写了 how Swarm's manager/node relates to Xinference's supervisor/worker 也是为了解释swam 这个技术，但 getting_started 目录下的文档我看了，基本都只讲 how, 不讲 why， 所以我这个文档放在这可能有点突兀。 另外 how Swarm's manager/node relates to Xinference's supervisor/worker 是我个人的理解，写得对不对你也要校对一下。

还有，我实在3月份做的一次，最好现在3.5 版本再验证一下，不过我现在没有集群环境没法验证了 。

[qiulang]

如果要实际、直接能用docker swam 会需要下面这些文件

文件	说明
doc/source/getting_started/using_docker_swarm.rst	修正两个问题，补上被引用的部署章节
doc/source/getting_started/index.rst	toctree 加一行
doc/source/locale/zh_CN/.../using_docker_swarm.po	中文翻译，随正文重新生成
xinference/deploy/docker/docker-compose-swarm.yml	和官方的 docker-compose-distributed.yml 放在同一目录
xinference/deploy/docker/nginx-swarm.conf	改个带 swarm 的名字，避免和别的配置混淆
xinference/deploy/docker/setup-gpu-swarm.sh	修正环境变量名

[qinxuye]

明白，你主要想分享为什么选 Swarm，以及它和 Xinference 的部署关系，不一定要在这个 PR 里补齐一套完整部署方案。这个内容可以保留，文档位置也可以调整，不必限定在 getting_started。

我之前是按可直接照着操作的部署教程审的，所以提了补齐配置和脚本的要求。如果这次定位为选型与架构说明，可以先去掉依赖缺失文件的操作步骤和引用，保留你实际验证过的经验，并明确验证版本、3.x 尚未验证。

GPU 环境变量和 supervisor 持久化这两处事实问题还是需要修正。完整部署示例和新版集群验证可以后续单独补，不要求你现在没有环境的情况下完成。目录和翻译这些集成工作也可以分开处理，不需要你一个人包办。

[qinxuye]

我直接补了一轮收尾，已推到当前分支（cc7af6826）。

这次按前面说的范围整理成选型与架构说明：保留选择 Swarm 的背景、两层调度的分工和 GPU 管理的取舍；去掉依赖缺失文件的部署步骤、脚本引用及未验证的 3.x 操作建议。明确保留原测试环境及 3.x 未验证的边界，不再把它作为可直接执行的部署教程。

GPU 环境变量已统一为 DOCKER_RESOURCE_NVIDIA-GPU；补充了关闭认证后 supervisor 仍需持久化，以及主机存储和重新调度的关系。补上文档入口及现有 9 个维护语言的翻译，标题也调整为部署考量。

验证：所有新增 PO 通过 msgfmt --check --check-format，doc/build_i18n.py --all 完成；英文与 9 种译文的 HTML 已构建，并核验翻译正文及目录链接。本次页面没有告警；全站严格构建仍有未改动页面的既有告警（如 release_notes 的重复锚点），没有顺带修改。未进行实际 Swarm/GPU 集群验证，完整配置和当前版本的集群验证留给后续工作。

[qinxuye]

补充目录调整（3c23aaa7d）：在 User Guide 下新增 Deployment 分组，将本文及 9 种译文移入其中。Getting Started 保留官方 Docker、Compose 和 Kubernetes 部署入口。已同步修复迁移后的相对链接，并验证英文和 9 种译文的页面、导航和迁移指南链接。

[qinxuye]

LGTM. Scoped as community deployment considerations under User Guide / Deployment, with the GPU resource variable and supervisor persistence guidance corrected. English and nine translated pages, navigation, catalogs and migration links verified locally. All six review threads are resolved. Actual Swarm validation for Xinference 3.x remains explicitly out of scope. CI is still pending.

[qiulang]

setup-gpu-swarm.sh

@qinxuye 这是我写过的 setup-gpu-swarm.sh 这次又改了一下，我现在没有环境了，所以没试验，但我加了一些注释，而且脚本本身也好懂，你看下

[qiulang]

docker-compose-swarm.yml
还有 swarm 文件示例，事实上，三月份时候 它和 setup_gpu_swarm.sh 我都试验过，这次你再找人试验一下。

supervisor 持久化 ，固定在 manager 就是下面这句

        # The data above is in a host directory, so the supervisor must stay on the same machine.
        constraints:
          - node.role == manager
      restart_policy: