如何为Modly编写模型扩展从manifest.json到generator.py完整教程【免费下载链接】modlyDesktop app to generate 3D models from images or prompt using local AI — runs entirely on your GPU项目地址: https://gitcode.com/GitHub_Trending/mo/modlyModly 是一款开源的本地 AI 3D 模型生成桌面应用可以在你自己的 GPU 上把图片或提示词变成 3D 网格模型。它的核心能力来自一套开放的扩展系统只要按照规范提交manifest.json和generator.py两个文件你封装的 3D 生成模型就能出现在 Modly 的模型列表中。本教程带你从零写一个可用的 Modly 模型扩展并讲清楚运行时是如何发现、加载和隔离执行它的。先搞懂Modly 扩展系统怎么运转Modly 的后端是一个 FastAPI 服务api/所有模型扩展都存放在统一的extensions/目录中由 Electron 主进程通过EXTENSIONS_DIR环境变量注入默认位于用户数据目录内置扩展由 builtin-sync.ts 同步过来。启动时generator_registry.py 会扫描该目录发现规则非常直接每个扩展是一个独立文件夹必须同时包含manifest.json和generator.py缺一个就跳过扫描逻辑写在 _discover_extensions() 中注释里就写着添加新模型在 extensions/ 建一个文件夹放 manifest.json generator.py其他任何文件都不需要改扩展分为两类type: model模型扩展本文主角和type: process流程节点扩展供工作流使用见文末。运行时有两种模式这一点新手很容易踩坑模式触发条件特点直接模式legacy扩展文件夹内没有venvgenerator.py 被直接 import 到后端进程子进程模式推荐扩展内有venv/通常由setup.py创建每个扩展跑在独立虚拟环境的子进程里通过 stdin/stdout 的换行分隔 JSON 通信子进程模式由 extension_process.py 和 runner.py 实现ExtensionProcess为每个扩展拉起独立 Python等待ready信号之后用load/generate/cancel等动作指令调度。好处是依赖互不冲突、崩溃互不影响还能对缺失模块做自动修复。第一步编写 manifest.json —— 扩展的身份证manifest.json描述扩展的元信息、模型仓库和 UI 参数。一个典型模型扩展的 manifest 长这样{ id: my-3d-model, name: My 3D Model, description: 基于开源模型的图片转 3D 扩展, version: 1.0.0, type: model, generator_class: MyGenerator, vram_gb: 8, hf_repo: your-org/your-repo, download_check: model.safetensors, hf_skip_prefixes: [data/], params_schema: [ { name: steps, label: 生成步数, type: number, default: 20, min: 10, max: 50 } ] }关键字段速查对照 generator_registry.py 的读取逻辑id必填。扩展唯一标识也决定模型权重下载目录~/.modly/models/id附近generator_classgenerator.py中生成器类名模型扩展必填安装校验见 extension-install-utils.tshf_repoHuggingFace 仓库地址。后端会用snapshot_download自动下载权重到本地模型目录配合download_check某个文件存在即视为已下载和hf_skip_prefixes跳过不需要的目录vram_gb推荐显存会显示在模型卡片上方便用户判断能不能跑params_schema声明 UI 上的参数项名称、类型、默认值、范围生成面板会自动渲染出对应控件nodes可选一个扩展可以暴露多个模型节点每个节点有独立id、name和自己的hf_repo/params_schema注册后显示为ext_id/node_id的复合 ID相当于一个扩展、多个变体。⚠️ 注意type不写或写model才走模型注册表写成process的扩展会被 registry 跳过交给 Electron 的工作流节点机制处理。第二步实现 generator.py —— 模型适配器的核心generator.py里要实现一个继承自BaseGeneratorgenerators/base.py的类。基类已经替你处理了权重自动下载、内存释放unload会调用torch.cuda.empty_cache()、进度上报工具等你主要实现两个方法from pathlib import Path from services.generators.base import BaseGenerator, GenerationCancelled class MyGenerator(BaseGenerator): MODEL_ID my-3d-model DISPLAY_NAME My 3D Model VRAM_GB 8 def load(self) - None: 模型加载进 GPU/CPU必须实现。 # self.model_dir 指向权重目录 self._model load_my_model(self.model_dir) def generate(self, image_bytes, params, progress_cbNone, cancel_eventNone) - Path: 输入图片字节 面板参数返回生成的 .glb 文件路径。 self._report(progress_cb, 10, 预处理图像) volume self._model.run(image_bytes, stepsparams.get(steps, 20)) self._report(progress_cb, 70, 解码网格) out self.outputs_dir / result.glb export_glb(volume, out) self._report(progress_cb, 100, 完成) return out编写时把握四个要点load()负责把权重放进显存。后端在生成前调用get_active()未下载会先触发_auto_download()见 base.py未加载会调load()generate()接收图片字节和params由params_schema驱动的值必须返回.glb文件路径进度回传调用self._report(progress_cb, 百分比, 阶段名)HUD 进度条就靠它更新。若某一步耗时很长且无法回调可用基类的smooth_progress()平滑推进度支持取消在长循环中检查cancel_event置位时抛GenerationCancelled。子进程模式下后端还会发cancel指令并保留 3 秒宽限期之后强制结束子进程见 extension_process.py。如果模型文件布局特殊比如权重分仓、需要合并可以重写is_downloaded()和_auto_download()实现自定义下载逻辑。第三步安装、运行与热重载扩展开发好之后有三种方式装进 ModlyUI 安装在 Models 页面点Install from GitHub粘贴扩展仓库地址安装器会校验 manifest 并自动执行setup.py用 Modly 内嵌 Python 检测到的 GPU SM 参数逻辑在 routers/extensions.py直接放目录把扩展文件夹拷入extensions/目录开发时可通过EXTENSIONS_DIR环境变量指定内置扩展打包进应用资源启动时由 builtin-sync.ts 全量同步到用户数据目录。开发调试时最有用的是两个热重载端点routers/extensions.pyPOST /extensions/reload不重启 FastAPI 就重新扫描extensions/目录并重建注册表返回当前所有模型 ID 和加载错误GET /extensions/errors返回各扩展的加载错误清单manifest 非法、import 失败、venv 缺失等。带setup.py的扩展会在安装后创建独立 venv自动进入子进程模式——这是官方推荐的写法能让你的 PyTorch / CUDA 版本与 Modly 主进程彻底解耦。进阶把工作流节点扩展也做出来模型扩展之外Modly 的 Workflows 页还支持type: process的流程节点扩展例如网格修复、减面、UV 展开等后处理步骤。流程扩展不需要generator.py而是提供processor.tsTypeScript或processor.pyPythonmanifest 里用entry字段指定入口文件。项目自带的参考实现可以参考 src/workflows/nodes/ 下的mesh-exporter/、mesh-remesher/、mesh-smoother/等节点目录。常见坑与排查清单现象原因与解决扩展根本没出现缺manifest.json或generator.py文件夹名以.开头或存在.modly-incomplete标记安装未完成提示 venv not found子进程模式的扩展必须先运行setup.py或在 Models 页面点 Repair模型一直显示未下载download_check指定的文件不在权重根目录检查hf_repo和该字段No module named xxx直接模式 import 失败。优先改用 venv 子进程模式少量白名单模块如 PIL→Pillow会自动补装生成卡住无法取消generate()里没检查cancel_event长时间原生调用会触发 3 秒宽限后的强杀 想快速验证自己的扩展最小路径是建文件夹 → 写好两个文件 → 调一次POST /extensions/reload→ 看GET /extensions/errors是否为空。小结为 Modly 编写模型扩展的完整链路只有三步manifest.json声明id、generator_class、hf_repo、vram_gb、params_schema等元信息generator.py继承 BaseGenerator实现load()和generate()接住进度与取消回调隔离运行配一个setup.py创建独立 venv让扩展以子进程方式安全跑在 Modly 的 ExtensionProcess 沙箱里。写完放进extensions/目录或发布为独立仓库即可让所有 Modly 用户一键安装你的 3D 生成模型——这正是这个项目本地、开源、可扩展理念的落点。【免费下载链接】modlyDesktop app to generate 3D models from images or prompt using local AI — runs entirely on your GPU项目地址: https://gitcode.com/GitHub_Trending/mo/modly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何为Modly编写模型扩展？从manifest.json到generator.py完整教程
如何为Modly编写模型扩展从manifest.json到generator.py完整教程【免费下载链接】modlyDesktop app to generate 3D models from images or prompt using local AI — runs entirely on your GPU项目地址: https://gitcode.com/GitHub_Trending/mo/modlyModly 是一款开源的本地 AI 3D 模型生成桌面应用可以在你自己的 GPU 上把图片或提示词变成 3D 网格模型。它的核心能力来自一套开放的扩展系统只要按照规范提交manifest.json和generator.py两个文件你封装的 3D 生成模型就能出现在 Modly 的模型列表中。本教程带你从零写一个可用的 Modly 模型扩展并讲清楚运行时是如何发现、加载和隔离执行它的。先搞懂Modly 扩展系统怎么运转Modly 的后端是一个 FastAPI 服务api/所有模型扩展都存放在统一的extensions/目录中由 Electron 主进程通过EXTENSIONS_DIR环境变量注入默认位于用户数据目录内置扩展由 builtin-sync.ts 同步过来。启动时generator_registry.py 会扫描该目录发现规则非常直接每个扩展是一个独立文件夹必须同时包含manifest.json和generator.py缺一个就跳过扫描逻辑写在 _discover_extensions() 中注释里就写着添加新模型在 extensions/ 建一个文件夹放 manifest.json generator.py其他任何文件都不需要改扩展分为两类type: model模型扩展本文主角和type: process流程节点扩展供工作流使用见文末。运行时有两种模式这一点新手很容易踩坑模式触发条件特点直接模式legacy扩展文件夹内没有venvgenerator.py 被直接 import 到后端进程子进程模式推荐扩展内有venv/通常由setup.py创建每个扩展跑在独立虚拟环境的子进程里通过 stdin/stdout 的换行分隔 JSON 通信子进程模式由 extension_process.py 和 runner.py 实现ExtensionProcess为每个扩展拉起独立 Python等待ready信号之后用load/generate/cancel等动作指令调度。好处是依赖互不冲突、崩溃互不影响还能对缺失模块做自动修复。第一步编写 manifest.json —— 扩展的身份证manifest.json描述扩展的元信息、模型仓库和 UI 参数。一个典型模型扩展的 manifest 长这样{ id: my-3d-model, name: My 3D Model, description: 基于开源模型的图片转 3D 扩展, version: 1.0.0, type: model, generator_class: MyGenerator, vram_gb: 8, hf_repo: your-org/your-repo, download_check: model.safetensors, hf_skip_prefixes: [data/], params_schema: [ { name: steps, label: 生成步数, type: number, default: 20, min: 10, max: 50 } ] }关键字段速查对照 generator_registry.py 的读取逻辑id必填。扩展唯一标识也决定模型权重下载目录~/.modly/models/id附近generator_classgenerator.py中生成器类名模型扩展必填安装校验见 extension-install-utils.tshf_repoHuggingFace 仓库地址。后端会用snapshot_download自动下载权重到本地模型目录配合download_check某个文件存在即视为已下载和hf_skip_prefixes跳过不需要的目录vram_gb推荐显存会显示在模型卡片上方便用户判断能不能跑params_schema声明 UI 上的参数项名称、类型、默认值、范围生成面板会自动渲染出对应控件nodes可选一个扩展可以暴露多个模型节点每个节点有独立id、name和自己的hf_repo/params_schema注册后显示为ext_id/node_id的复合 ID相当于一个扩展、多个变体。⚠️ 注意type不写或写model才走模型注册表写成process的扩展会被 registry 跳过交给 Electron 的工作流节点机制处理。第二步实现 generator.py —— 模型适配器的核心generator.py里要实现一个继承自BaseGeneratorgenerators/base.py的类。基类已经替你处理了权重自动下载、内存释放unload会调用torch.cuda.empty_cache()、进度上报工具等你主要实现两个方法from pathlib import Path from services.generators.base import BaseGenerator, GenerationCancelled class MyGenerator(BaseGenerator): MODEL_ID my-3d-model DISPLAY_NAME My 3D Model VRAM_GB 8 def load(self) - None: 模型加载进 GPU/CPU必须实现。 # self.model_dir 指向权重目录 self._model load_my_model(self.model_dir) def generate(self, image_bytes, params, progress_cbNone, cancel_eventNone) - Path: 输入图片字节 面板参数返回生成的 .glb 文件路径。 self._report(progress_cb, 10, 预处理图像) volume self._model.run(image_bytes, stepsparams.get(steps, 20)) self._report(progress_cb, 70, 解码网格) out self.outputs_dir / result.glb export_glb(volume, out) self._report(progress_cb, 100, 完成) return out编写时把握四个要点load()负责把权重放进显存。后端在生成前调用get_active()未下载会先触发_auto_download()见 base.py未加载会调load()generate()接收图片字节和params由params_schema驱动的值必须返回.glb文件路径进度回传调用self._report(progress_cb, 百分比, 阶段名)HUD 进度条就靠它更新。若某一步耗时很长且无法回调可用基类的smooth_progress()平滑推进度支持取消在长循环中检查cancel_event置位时抛GenerationCancelled。子进程模式下后端还会发cancel指令并保留 3 秒宽限期之后强制结束子进程见 extension_process.py。如果模型文件布局特殊比如权重分仓、需要合并可以重写is_downloaded()和_auto_download()实现自定义下载逻辑。第三步安装、运行与热重载扩展开发好之后有三种方式装进 ModlyUI 安装在 Models 页面点Install from GitHub粘贴扩展仓库地址安装器会校验 manifest 并自动执行setup.py用 Modly 内嵌 Python 检测到的 GPU SM 参数逻辑在 routers/extensions.py直接放目录把扩展文件夹拷入extensions/目录开发时可通过EXTENSIONS_DIR环境变量指定内置扩展打包进应用资源启动时由 builtin-sync.ts 全量同步到用户数据目录。开发调试时最有用的是两个热重载端点routers/extensions.pyPOST /extensions/reload不重启 FastAPI 就重新扫描extensions/目录并重建注册表返回当前所有模型 ID 和加载错误GET /extensions/errors返回各扩展的加载错误清单manifest 非法、import 失败、venv 缺失等。带setup.py的扩展会在安装后创建独立 venv自动进入子进程模式——这是官方推荐的写法能让你的 PyTorch / CUDA 版本与 Modly 主进程彻底解耦。进阶把工作流节点扩展也做出来模型扩展之外Modly 的 Workflows 页还支持type: process的流程节点扩展例如网格修复、减面、UV 展开等后处理步骤。流程扩展不需要generator.py而是提供processor.tsTypeScript或processor.pyPythonmanifest 里用entry字段指定入口文件。项目自带的参考实现可以参考 src/workflows/nodes/ 下的mesh-exporter/、mesh-remesher/、mesh-smoother/等节点目录。常见坑与排查清单现象原因与解决扩展根本没出现缺manifest.json或generator.py文件夹名以.开头或存在.modly-incomplete标记安装未完成提示 venv not found子进程模式的扩展必须先运行setup.py或在 Models 页面点 Repair模型一直显示未下载download_check指定的文件不在权重根目录检查hf_repo和该字段No module named xxx直接模式 import 失败。优先改用 venv 子进程模式少量白名单模块如 PIL→Pillow会自动补装生成卡住无法取消generate()里没检查cancel_event长时间原生调用会触发 3 秒宽限后的强杀 想快速验证自己的扩展最小路径是建文件夹 → 写好两个文件 → 调一次POST /extensions/reload→ 看GET /extensions/errors是否为空。小结为 Modly 编写模型扩展的完整链路只有三步manifest.json声明id、generator_class、hf_repo、vram_gb、params_schema等元信息generator.py继承 BaseGenerator实现load()和generate()接住进度与取消回调隔离运行配一个setup.py创建独立 venv让扩展以子进程方式安全跑在 Modly 的 ExtensionProcess 沙箱里。写完放进extensions/目录或发布为独立仓库即可让所有 Modly 用户一键安装你的 3D 生成模型——这正是这个项目本地、开源、可扩展理念的落点。【免费下载链接】modlyDesktop app to generate 3D models from images or prompt using local AI — runs entirely on your GPU项目地址: https://gitcode.com/GitHub_Trending/mo/modly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考