xpu-server — 部署指南
【免费下载链接】ops-test-kitTTK（Ops Test Tool Kit）是CANN算子库提供的全链路、自动化、批量化算子测试框架，帮助开发者快速完成算子批量功能验证、性能评估以及Golden值比对，提升算子开发质量和效率。项目地址: https://gitcode.com/cann/ops-test-kit
TTK 远端 XPU 执行服务器。接收 TTK worker 端的算子执行请求，在多种硬件加速器上跑 PyTorch/TensorFlow 算子，回传结果。
本文档出现的硬件厂商名、设备路径、镜像名仅作示例；TTK 通过配置驱动支持任意符合接口的硬件加速器。
快速开始
# 1. 拷贝 server 包到 XPU 机器（只需要这个目录） scp -r ttk/remote/server/ user@xpu-box:/opt/xpu_server/ # 2. 在 XPU 机器上启动 # xpu-server 是 ttk-free 独立包，按 xpu_server 跑；包的**父目录**需在 PYTHONPATH 上或作为 cwd # （部署在 /opt/xpu_server/ → cd 到 /opt，或 PYTHONPATH=/opt） ssh user@xpu-box cd /opt python -m xpu_server.xpu_server --port 9090TTK worker 端通过ttk.conf.yaml（或--config）配置remote.endpoints连过来。到此就通了。
两个概念
- provider：用什么框架/库执行算子。用户通过
--provider=torch指定，server 通过/v1/heartbeat声明自己能提供哪些。常见值：torch、tf、flash_attn、vllm - hardware：底层硬件类型，决定设备字符串格式（如 torch 的
mlu:0、tf 的/device:MLU:0）。启动时 /dev 自动探测，也可手动覆盖
两个正交维度
部署场景 =传输×执行隔离，两两组合：
| per-Process 执行 | per-Container 执行 | |
|---|---|---|
| HTTP 明文 | 场景 1（本机）/ 场景 2（内部） | 场景 2b（可选的容器隔离） |
| mTLS 加密 | 场景 3（内部跨机） | 场景 4（CI 对外） |
- 传输：HTTP 用于同信任域，mTLS 用于跨机/不可信网络
- 执行隔离：per-Process（fork 子进程）用于可信代码，per-Container（Docker）用于不可信代码
部署配置
所有配置在一个 YAML 文件里（默认ttk/remote/server/xpu_server.yaml）：
server: bind: "127.0.0.1" # 监听地址 port: 9090 max_concurrent: 16 # 并发上限 run_deadline_s: 300 # 单请求超时(秒) execution: sandbox: none # none（per-Process）| docker（per-Container） # providers 可选，不配则框架探测到什么就暴露什么 providers: - torch # - tf # 注释掉 = 不暴露（即使 tf 已安装） # - flash_attn # 只暴露 flash_attn，不暴露 raw torch # # 注:providers 列表只表达「能力集合」,顺序不代表优先级。客户端优先级由 specs 顺序决定(应用层), # 不依赖 detect 返回顺序。endpoint providers 默认由 /v1/heartbeat 动态发现,也可在 yaml 显式配置(override)。 # hardware 可选，不配则启动时 /dev 自动探测（实体段配置见 xpu_server.yaml）优先级：命令行参数 > YAML > 内置默认
场景 1：本机测试 — HTTP + per-Process
TTK 和 xpu-server 在同一台机器，零配置，最快。
python -m xpu_server.xpu_server --port 9090 # TTK worker 端 ttk kernel -i case.csv --config ttk.conf.yaml- 绑定
127.0.0.1，无网络暴露 - 每请求一个子进程（
multiprocessing.Process），跑完即毁 - 无 TLS、无 Docker
场景 2：内部测试 — HTTP + 灵活部署
同信任域内，代码可信。Server 可按需选择部署位置和执行方式：
2a：Server 在 provider 容器中（per-Process）
利用用户已有的官方框架镜像，xpu-server 部署在容器内，端口映射对外：
# 加速器机器：用户已有官方镜像 # 用 -dit（不是 -d）：厂商镜像默认 CMD=bash，纯 -d 无 tty 会立即 EOF 退出 → 容器 Exited docker run -dit --device /dev/cambricon0 --name tf-server -p 9090:9090 \ cambricon/tensorflow:latest # 拷贝 xpu-server 包到容器（目录名用合法 Python 包名 xpu_server——带连字符的 xpu-server 无法被 python -m） scp -r ttk/remote/server/ user@xpu-box:/tmp/xpu_server/ docker cp /tmp/xpu_server/ tf-server:/opt/ # 容器内 /opt/xpu_server/（ttk-free 独立包） # 容器内安装依赖 docker exec tf-server pip install numpy pyyaml # 写 server 配置（只暴露 tf），拷进容器 # （不能 docker exec ... --config <(echo ...)：进程替换的 /dev/fd/N 在宿主机，容器读不到） echo 'providers: [tf]' > /tmp/xpu_server.yaml docker cp /tmp/xpu_server.yaml tf-server:/opt/xpu_server.yaml # 容器内启动：xpu-server 是 ttk-free（无 ttk.* 依赖），按独立包名跑，不是 ttk.remote.server.xpu_server docker exec -d -e PYTHONPATH=/opt tf-server \ python -m xpu_server.xpu_server --port 9090 --bind 0.0.0.0 --config /opt/xpu_server.yaml同理，torch 容器用cambricon/pytorch:latest镜像，配providers: [torch]。镜像天然隔开了框架环境——tf 镜像里没有 torch，反之亦然。
2b：Server 在 Host 上（per-Process 或 per-Container）
Server 直接跑在 Host，有完整的 framework 探测能力：
# per-Process（默认，最快） python -m xpu_server.xpu_server --port 9090 # 或 per-Container（需要 Docker，~300ms 额外开销） python -m xpu_server.xpu_server --port 9090 \ --config <(sed 's/sandbox: none/sandbox: docker/' xpu_server.yaml)注意：per-Container 模式下 server 必须在 Host 上运行，不能在容器内再起子容器（Docker-in-Docker 需要--privileged，安全上不推荐）。
场景 3：内部跨机 — mTLS + per-Process
TTK 和 XPU 在不同机器，团队内部代码可信，传输加密但执行从简。
# 1. 生成证书 bash scripts/gen_tls_certs.sh /opt/ttk-certs # 2. 分发 scp /opt/ttk-certs/ca.crt /opt/ttk-certs/server.* user@xpu-box:/opt/ttk-certs/ # client.{crt,key} 留在 TTK worker 机器 # 3. XPU 机器配置 + 启动 cat > /opt/xpu_server/xpu_server.yaml << 'EOF' server: bind: "0.0.0.0" port: 9090 execution: sandbox: none # per-Process（代码可信） tls: enabled: true ca_cert: "/opt/ttk-certs/ca.crt" server_cert: "/opt/ttk-certs/server.crt" server_key: "/opt/ttk-certs/server.key" EOF python -m xpu_server.xpu_server --port 9090 --config /opt/xpu_server/xpu_server.yaml # 4. TTK worker 端：default.yaml 配 TLS 证书路径场景 4：CI 对外 — mTLS + per-Container
不可信的用户代码。Server 部署在 Host 上，每个请求一个隔离容器。
# 1. 构建 executor 镜像 docker build -f Dockerfile.torch -t xpu-executor-torch:latest . docker build -f Dockerfile.tf -t xpu-executor-tf:latest . # 2. 配置 cat > /opt/xpu_server/xpu_server.yaml << 'EOF' server: bind: "0.0.0.0" port: 9090 execution: sandbox: docker # per-Container（不可信代码隔离） tls: enabled: true ca_cert: "/opt/ttk-certs/ca.crt" server_cert: "/opt/ttk-certs/server.crt" server_key: "/opt/ttk-certs/server.key" docker: images: torch: "xpu-executor-torch:latest" tf: "xpu-executor-tf:latest" memory: "8g" network: "none" # 用户代码无网络 EOF # 3. 启动（必须在 Host 上，不能在容器内） python -m xpu_server.xpu_server --port 9090 --config /opt/xpu_server/xpu_server.yaml容器防护矩阵：
| 恶意行为 | 容器阻断方式 |
|---|---|
| 删文件 | --read-only根文件系统 |
| 连外网 | --network none |
| 提权 | --cap-drop ALL |
| 持久化 | --rm（跑完即毁） |
| 资源耗尽 | --memory+ deadline timeout |
部署模式对照
| per-Process | per-Container | |
|---|---|---|
| 配置 | sandbox: none | sandbox: docker |
| Server 部署位置 | Host 或容器内均可 | 必须 Host（不能 DinD） |
| 隔离级别 | 进程级（sys.modules隔离） | 完整 OS 级 |
| 启动开销 | ~10ms（fork） | ~300-600ms（容器） |
| 需要 Docker | 否 | 是 |
| 适用 | 可信代码、内部团队 | 不可信代码、CI |
| 传输加密 | 可选 mTLS | mTLS 必须 |
硬件自动探测
启动时不配hardware且不传--devices则 /dev 自动探测：
/dev 设备文件 → /dev/cambricon0 → mlu, /dev/davinci0 → npu, ...（毫秒级,不依赖框架） Fallback: "cpu"/dev检测提取实际 device id（regex^prefix(\d+)$），不假设从 0 连续。例如/dev/cambricon2,cambricon5→device_ids=[2,5]。控制设备（无数字尾）自动排除。
手动指定（覆盖探测，直接给 device id 列表）：
python -m xpu_server.xpu_server --devices 0,1命令行参考
python -m xpu_server.xpu_server \ --port 9090 # 监听端口（默认：配置或 9090） --bind 127.0.0.1 # 绑定地址（默认：127.0.0.1） --config ./xpu_server.yaml # 配置文件路径 --devices 0,1 # 设备 ID 列表（不传则 /dev 自动探测） --dry-run # 空跑模式（返回随机数据）健康检查 / 服务发现
# /v1/heartbeat 合并了探活 + 服务发现 + tenant 注册（旧 /health、/v1/detect、/heartbeat 已并入此端点） curl http://127.0.0.1:9090/v1/heartbeat # → {"status":"ok","hardware":"gpu","device_count":2,"providers":["torch","tf"]} # device_count = 实际检测到的 device 数（多卡时 >1）多卡并发
多卡 server 自动启用 per-device 并发执行：
- 不同 device 上的请求并发跑（吞吐 × 卡数）
- 同一 device 上的请求串行（保护 PERF 测量精度：
reset_peak_memory_stats+ Event timing 不被其他请求干扰） - 分配策略：RR 起点 + try-lock 遍历（找空闲 device）+ fallback 阻塞起点（全占时等）
max_concurrent（yaml 配置）建议 ≥ device 数以用满并发；小于则 data_gate 限制总并发，部分 device 空闲（启动 warning 提示，不阻止启动）
注意：单卡 server 下，所有请求（含 DATA 模式）都串行——这是为了保证 PERF 测量精度。多卡场景下 DATA 仍跨卡并发。
X-API 响应头
/v1/run成功和错误的响应都带X-APIheader，回传 server 实际执行的 API 标识：
X-API: torch.add # 推导模式（client 没配 api，server 从 op_name 推导） X-API: torch.add # ACLNN 算子（aclnnAdd → strip → add → torch.add，回传实际执行的 API） X-API: AddSpec # spec 模式（回传 spec_class 名）客户端读此 header 显示真实 API（不再显示 "custom"）。旧 server 不发此 header，客户端 fallback 到spec.api或 "custom"。
文件结构
ttk/remote/server/ ← 独立部署包（无 ttk.* 依赖，stdlib + numpy + 框架） ├── README.md 本文件 ├── xpu_server.py 主进程（HTTP + 子进程/容器派发） ├── xpu_server.yaml 服务端配置 ├── executor.py 子进程入口（算子执行） ├── execution_container.py 参数绑定 + device 格式化 ├── executor_main.py Docker 容器入口 ├── container.py Docker 后端 ├── config.py 配置加载器 ├── Dockerfile.torch Torch executor 镜像（示例） └── Dockerfile.tf TF executor 镜像（示例）【免费下载链接】ops-test-kitTTK（Ops Test Tool Kit）是CANN算子库提供的全链路、自动化、批量化算子测试框架，帮助开发者快速完成算子批量功能验证、性能评估以及Golden值比对，提升算子开发质量和效率。项目地址: https://gitcode.com/cann/ops-test-kit
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
