news 2026/4/23 11:32:30

HY-Motion 1.0入门指南：如何修改start.sh适配自定义端口与GPU绑定

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
HY-Motion 1.0入门指南：如何修改start.sh适配自定义端口与GPU绑定

HY-Motion 1.0入门指南：如何修改start.sh适配自定义端口与GPU绑定

1. 为什么你需要改start.sh？——从默认启动到生产就绪的一步之遥

你刚下载完HY-Motion 1.0镜像，执行bash /root/build/HY-Motion-1.0/start.sh，浏览器打开http://localhost:7860/，界面出来了，模型也加载成功了。但很快你就遇到几个现实问题：

  • 公司内网环境里，7860端口已被其他服务占用；
  • 服务器上插着4张A100，但默认只用第0号GPU，显存浪费严重；
  • 团队多人协作时，需要同时跑多个实例，每个实例得对应不同端口和GPU；
  • 你想把服务暴露给局域网同事调试，但默认只监听127.0.0.1。

这些问题，都不需要重装模型、不需改Python代码、更不用碰模型权重——它们全在一行脚本里：start.sh。

这行看似简单的启动脚本，其实是连接你和HY-Motion能力的“控制闸门”。它不负责模型推理，却决定了谁能访问、用哪块卡、走哪个端口、是否支持跨域、日志怎么输出……换句话说：它管的是“怎么用”，而不是“能不能用”。

本文不讲DiT架构原理，也不展开Flow Matching数学推导。我们聚焦一个工程师每天都会面对的真实动作：打开终端，编辑一个shell文件，保存，运行，立刻生效。全程无需重启容器、不依赖Docker Compose编排、不涉及CUDA版本切换——就是最朴素的手动配置。

你会学到：

  • start.sh里真正起作用的5个关键变量；
  • 如何安全地绑定指定GPU（不止是CUDA_VISIBLE_DEVICES=0那种粗暴写法）；
  • 怎样让Gradio服务既能在本地访问，也能被同网段同事打开；
  • 为什么直接改端口可能报错，以及两个必须同步调整的位置；
  • 一个防手误的检查清单，避免改完启动失败却找不到原因。

所有操作均基于官方镜像原始结构，不破坏原有部署逻辑，改完即可复用社区提供的全部提示词模板和测试案例。

2. 拆解start.sh：5个决定服务行为的核心参数

先别急着改。我们先看清它的本来面目。进入镜像后执行：

cat /root/build/HY-Motion-1.0/start.sh

你会看到类似这样的内容（已简化注释，实际脚本更长）：

#!/bin/bash export PYTHONPATH="/root/build/HY-Motion-1.0:$PYTHONPATH" cd /root/build/HY-Motion-1.0 # 👇 这行才是真正启动Gradio的命令 python app.py \ --share \ --server-name 127.0.0.1 \ --server-port 7860 \ --enable-xformers \ --num-gpus 1

注意：这不是伪代码，而是真实脚本中最精简但完全可运行的核心片段。其中真正影响服务行为的，只有以下5个参数，其余如--enable-xformers属于性能优化项，不影响端口/GPU绑定逻辑。

2.1--server-name：谁可以访问你的服务？

  • 默认值：127.0.0.1
  • 含义：Gradio服务监听的网络接口地址
  • 常见误区：以为设成0.0.0.0就能外网访问 → 错！这只是放开监听范围，还受防火墙和云服务器安全组限制
  • 安全建议：
    • 本地单机开发：保持127.0.0.1（最安全）
    • 局域网协作调试：改为0.0.0.0
    • 生产环境暴露：必须配合Nginx反向代理 + Basic Auth，绝不直接暴露0.0.0.0

正确做法示例（局域网调试）：

--server-name 0.0.0.0

❌ 危险写法（暴露公网且无防护）：

--server-name 0.0.0.0 # 未配防火墙/Nginx时禁用

2.2--server-port：端口不是改一个地方就够

  • 默认值：7860
  • 关键事实：这个参数只控制Gradio内部HTTP服务端口，不控制外部映射端口
  • 隐形依赖：如果你用docker run -p 8080:7860启动容器，那么：
    • 外部访问用http://your-ip:8080
    • 脚本里--server-port仍必须是7860（否则容器内服务不响应）
  • 唯一例外：裸机部署（非Docker），此时改这里就等于改最终端口

推荐做法（Docker环境）：

  • 容器外映射端口由docker run -p决定
  • start.sh中--server-port保持默认7860，避免混淆

推荐做法（裸机部署）：

  • 直接修改此处为你想要的端口，例如--server-port 8000

2.3--num-gpus：控制并行推理卡数，不是显存分配开关

  • 默认值：1
  • 真实作用：告诉HY-Motion主程序“启动几个GPU进程”，每个进程独占一块卡
  • 重要限制：该值不能超过你物理GPU数量，也不能超过CUDA_VISIBLE_DEVICES可见设备数
  • 常见错误：设成--num-gpus 2但没设置CUDA_VISIBLE_DEVICES="0,1"→ 程序报错找不到设备

正确组合示例（用第1、2号GPU）：

export CUDA_VISIBLE_DEVICES="1,2" python app.py --num-gpus 2 ...

注意：--num-gpus值必须与CUDA_VISIBLE_DEVICES中逗号分隔的ID数量严格一致。

2.4CUDA_VISIBLE_DEVICES：GPU可见性控制的黄金法则

  • 默认：未显式设置 → 系统自动识别所有GPU
  • 本质：Linux环境变量，在进程启动前屏蔽/暴露特定GPU
  • 为什么不能只靠--num-gpus？因为HY-Motion底层PyTorch调用torch.cuda.device_count()获取可用卡数，而这个函数读取的就是CUDA_VISIBLE_DEVICES的值

安全写法（绑定第0、3号GPU）：

export CUDA_VISIBLE_DEVICES="0,3" python app.py --num-gpus 2 ...

单卡极致性能写法（强制只用第1号GPU，避免多卡通信开销）：

export CUDA_VISIBLE_DEVICES="1" python app.py --num-gpus 1 ...

❌ 危险写法（ID不存在）：

export CUDA_VISIBLE_DEVICES="99" # 服务器根本没有99号GPU

2.5--share：临时公网链接的双刃剑

  • 默认：启用（生成xxx.gradio.live链接）
  • 用途：快速分享给他人体验，适合演示/临时评审
  • 风险：生成的链接可被任何人访问，且无法设置密码
  • 替代方案：局域网内用--server-name 0.0.0.0+ 内网IP访问，更可控

生产环境建议：删除--share参数，改用内网IP访问

3. 实战修改：三步完成端口与GPU绑定定制

现在我们动手改。整个过程不需要任何编译、不安装新包、不重启系统，改完即生效。

3.1 第一步：备份原脚本（防手抖）

cp /root/build/HY-Motion-1.0/start.sh /root/build/HY-Motion-1.0/start.sh.bak

小技巧：.bak后缀能让大多数编辑器自动识别为备份文件，避免误删

3.2 第二步：编辑start.sh，注入自定义配置

用你喜欢的编辑器打开（推荐nano或vim）：

nano /root/build/HY-Motion-1.0/start.sh

找到python app.py \这一行（通常在文件末尾），将其替换为以下模板（根据你的需求选择一种）：

场景A：单机开发，想用8000端口 + 只用第2号GPU
export CUDA_VISIBLE_DEVICES="2" python app.py \ --server-name 127.0.0.1 \ --server-port 8000 \ --num-gpus 1 \ --enable-xformers
场景B：团队服务器，4张A100，需同时跑2个实例（实例1用卡0/1，实例2用卡2/3）

提示：两个实例需分别放在不同目录，或修改各自start.sh中的端口

实例1（卡0/1，端口7860）：

export CUDA_VISIBLE_DEVICES="0,1" python app.py \ --server-name 0.0.0.0 \ --server-port 7860 \ --num-gpus 2 \ --enable-xformers

实例2（卡2/3，端口7861）：

export CUDA_VISIBLE_DEVICES="2,3" python app.py \ --server-name 0.0.0.0 \ --server-port 7861 \ --num-gpus 2 \ --enable-xformers
场景C：云服务器部署，需通过域名访问（假设已配Nginx反代到80端口）
export CUDA_VISIBLE_DEVICES="0" python app.py \ --server-name 127.0.0.1 \ --server-port 7860 \ --num-gpus 1 \ --enable-xformers

此时Nginx配置示例（供参考）：

location / { proxy_pass http://127.0.0.1:7860; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }

3.3 第三步：验证修改是否生效

执行修改后的脚本：

bash /root/build/HY-Motion-1.0/start.sh

观察终端输出，重点确认三处：

  1. GPU识别日志：应出现类似
    Found 1 CUDA device(s): [GeForce RTX 4090]（数字与你设置的CUDA_VISIBLE_DEVICES一致）

  2. 端口监听日志：应显示
    Running on local URL: http://127.0.0.1:8000（端口号与你设置一致）

  3. 无报错启动：最后几行应是Gradio的To create a public link, set --share提示，而非CUDA out of memory或Address already in use

验证访问：

  • 本地开发：打开http://localhost:8000
  • 局域网：打开http://[服务器IP]:7860
  • Nginx反代：打开https://your-domain.com

4. 进阶技巧：让配置更灵活、更健壮

上面的修改已满足90%场景，但如果你希望更工程化，可以加入这些增强项。

4.1 使用环境变量替代硬编码（推荐）

修改start.sh，把端口/GPU等参数抽成变量：

#!/bin/bash # 👇 自定义配置区（只需改这里） export SERVER_PORT=${SERVER_PORT:-7860} export GPU_IDS=${GPU_IDS:-"0"} export SERVER_NAME=${SERVER_NAME:-"127.0.0.1"} export CUDA_VISIBLE_DEVICES="$GPU_IDS" python app.py \ --server-name "$SERVER_NAME" \ --server-port "$SERVER_PORT" \ --num-gpus $(echo "$GPU_IDS" | tr ',' '\n' | wc -l) \ --enable-xformers

启动时这样用，无需改脚本：

SERVER_PORT=8000 GPU_IDS="1,2" bash /root/build/HY-Motion-1.0/start.sh

4.2 添加GPU健康检查（防静默失败）

在python app.py前插入检测逻辑：

# 检查CUDA_VISIBLE_DEVICES指定的GPU是否存在 for gpu_id in $(echo "$GPU_IDS" | tr ',' ' '); do if ! nvidia-smi -i "$gpu_id" --query-gpu=name --format=csv,noheader 2>/dev/null; then echo "❌ GPU $gpu_id not found. Check nvidia-smi output." exit 1 fi done

4.3 日志分离：避免终端刷屏干扰

将Gradio日志重定向到文件，方便排查：

python app.py ... 2>&1 | tee -a /root/build/HY-Motion-1.0/logs/start_$(date +%Y%m%d).log

5. 常见问题速查表（改完启动失败？先看这里）

现象最可能原因快速解决
Address already in use端口被占用，或上一个进程未退出lsof -i :7860→kill -9 <PID>，或换端口
CUDA out of memory--num-gpus>CUDA_VISIBLE_DEVICES中GPU数检查nvidia-smi，确保--num-gpus与可见GPU数量一致
页面空白/加载失败--server-name设为0.0.0.0但防火墙拦截sudo ufw allow 7860（Ubuntu）或检查云服务器安全组
启动后立即退出app.py路径错误或权限不足ls -l /root/build/HY-Motion-1.0/app.py，确认存在且可执行
GPU识别为0块CUDA_VISIBLE_DEVICES格式错误（空格/中文逗号）改为英文逗号，如"0,1"，不要"0，1"

终极排查命令（一行搞定）：
echo "GPU可见数: $(nvidia-smi -L \| wc -l), 当前可见: $CUDA_VISIBLE_DEVICES, Python检测: $(python3 -c "import torch; print(torch.cuda.device_count())")"

6. 总结：你掌握的不只是改脚本，而是服务治理的第一课

改一个start.sh，表面看是技术操作，背后是你对AI服务部署逻辑的完整理解：

  • 你明白了网络层（server-name/port）与资源层（CUDA_VISIBLE_DEVICES/num-gpus）的分离设计；
  • 你区分了开发便利性（--share）与生产安全性（0.0.0.0 + 防火墙）的本质差异；
  • 你建立了配置即代码的意识——所有环境差异，都应收敛到可版本管理的文本中；
  • 你获得了故障自愈能力——当服务异常，不再盲目重启，而是看日志、查GPU、验端口、比配置。

HY-Motion 1.0的强大，在于十亿参数带来的动作表现力；而你的强大，在于能把它稳稳地、恰当地、按需地，落到每一台服务器、每一块GPU、每一个端口上。

下一步，你可以：

  • 把修改后的start.sh提交到Git，实现配置版本化；
  • 编写stop.sh脚本，用pkill -f "python app.py"优雅终止；
  • 尝试用systemd将服务注册为系统守护进程；
  • 或者，直接跳到提示词工程，用你刚刚搭好的服务，生成第一个电影级3D动作。

真正的AI落地，从来不在模型参数里，而在你敲下的每一行配置中。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/4/16 9:59:05

开源生命周期评估工具技术指南：从环境评估痛点到实战解决方案

开源生命周期评估工具技术指南&#xff1a;从环境评估痛点到实战解决方案 【免费下载链接】olca-app Source code of openLCA 项目地址: https://gitcode.com/gh_mirrors/ol/olca-app 环境评估痛点与工具选择决策 行业普遍面临的LCA实施障碍 环境工程师在进行生命周期…

作者头像 李华
网站建设 2026/4/16 17:15:06

手把手教学：在ComfyUI中运行Qwen-Image-2512全流程

手把手教学&#xff1a;在ComfyUI中运行Qwen-Image-2512全流程 Qwen-Image-2512是阿里最新发布的开源图像生成模型&#xff0c;相比前代在细节还原、构图合理性与多轮提示理解能力上均有明显提升。它支持更长文本描述、更复杂的场景组合&#xff0c;并能在单卡4090D&#xff0…

作者头像 李华
网站建设 2026/4/18 12:34:40

Retinaface+CurricularFace开源模型教程：ONNX导出与TensorRT加速部署

RetinafaceCurricularFace开源模型教程&#xff1a;ONNX导出与TensorRT加速部署 人脸识别技术在实际业务中早已不是新鲜事&#xff0c;但真正能“开箱即用、又快又准”的方案却不多。今天要分享的这个镜像&#xff0c;把两个经典模型——RetinaFace&#xff08;人脸检测&#…

作者头像 李华
网站建设 2026/4/19 21:09:45

mPLUG图文问答镜像弹性伸缩：K8s HPA根据QPS自动扩缩VQA推理Pod

mPLUG图文问答镜像弹性伸缩&#xff1a;K8s HPA根据QPS自动扩缩VQA推理Pod 1. 为什么需要为VQA服务做弹性伸缩&#xff1f; 你有没有遇到过这样的情况&#xff1a; 早上刚上线的图文问答服务&#xff0c;只有零星几个用户上传图片、提几个英文问题&#xff0c;CPU利用率不到1…

作者头像 李华
网站建设 2026/4/18 12:29:33

YOLOE支持检测+分割，统一架构优势解析

YOLOE支持检测分割&#xff0c;统一架构优势解析 你是否经历过这样的困境&#xff1a;一个项目既要识别图像中所有目标的位置&#xff08;检测&#xff09;&#xff0c;又要精准勾勒每个目标的轮廓&#xff08;分割&#xff09;&#xff0c;结果却不得不部署两个独立模型——Y…

作者头像 李华
网站建设 2026/4/17 17:54:48

Qwen3-Reranker-0.6B部署实战：vLLM+Gradio一键启动重排序服务

Qwen3-Reranker-0.6B部署实战&#xff1a;vLLMGradio一键启动重排序服务 你是不是也遇到过这样的问题&#xff1a;检索系统返回了100个候选文档&#xff0c;但真正相关的可能只有前5个&#xff1f;靠关键词匹配或基础向量相似度排序&#xff0c;结果总是差一口气——这时候&am…

作者头像 李华