Gradio 自定义组件 5 分钟上手：用 `gradio cc` 完成从脚手架到发布的全流程

Gradio 自定义组件 5 分钟上手用gradio cc完成从脚手架到发布的全流程【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio本指南基于 Gradio 官方文档《Custom Components in 5 minutes》展开核心目标是在 5 分钟内建立自定义组件开发的完整心智模型如何用gradio cc子命令执行create创建→ dev开发→ build构建→ publish发布四步工作流以及每一步背后仓库源码是如何实现的。读完你就能从零创建一个可热重载调试、可打包成 wheel、可发布到 PyPI/Hugging Face Spaces 的 Gradio 自定义组件并理解其backend/ frontend/ pyproject.toml的标准工程结构。Custom Components 是什么Gradio 为开发者开放了自定义组件能力你可以在组件中自由实现前端交互与后端逻辑之后像使用gr.Textbox、gr.Image等内置组件一样把它放进任意gr.Blocks、gr.Interface应用中同时保留 Gradio 全部既有能力例如事件监听、API 调用Client、主题themes与示例examples等。自定义组件本质上是一个可发布的 Python 包前端代码Svelte会被打包进去。因此用户可以像安装普通依赖一样通过pip install安装你发布的组件然后在自己的代码中import使用。环境准备依赖最低版本检查命令Python3.10python --versionpip21.3python -m pip install --upgrade pipNode.js20node --versionnpm9npm --versionGradio5本指南基于 Gradio 5/6 开发线pip install --upgrade gradio提示本仓库开发分支内置的组件脚手架pyproject.toml模板将运行时依赖写为gradio6.0,7.0说明模板会随 Gradio 大版本演进自动锁定匹配的依赖范围见 pyproject 模板。四步工作流总览Custom Components 的 CLI 全部收敛在gradio cc或等价的gradio component之下。仓库中的入口分发逻辑位于 gradio/cli/cli.py当第一个参数为cc或component时会移交到独立的 Typer 应用gradio/cli/commands/components/app.py该应用注册了create、build、dev、show、install、publish、docs共 7 个子命令。步骤命令作用1. creategradio cc create生成组件模板骨架并安装为开发模式2. devgradio cc dev启动带热重载的示例应用进行开发调试3. buildgradio cc build构建包含 Python 与 JS 代码的分发包4. publishgradio cc publish发布到 PyPI 与 Hugging Face Spaces先记住两个万能提示运行gradio cc --help查看全部可用命令还有若干命令本指南未覆盖如install、docs任意子命令后追加--help可查看该命令帮助页例如gradio cc create --help、gradio cc build --help。所有 CLI 参数均基于 Typer 定义帮助信息来自源码中的参数注解。第 1 步 create从模板脚手架你的组件在任意工作目录执行gradio cc create MyComponent --template SimpleTextboxMyComponent是组件名官方建议使用驼峰命名camel case例如MyTextBox--template指定用哪个组件作为模板需要写组件的 Python 类名。如何选择模板SimpleTextbox是Textbox组件的精简版去掉了大量可选配置非常适合第一次创建自定义组件时阅读与修改。仓库中它的实现位于 gradio/_simple_templates/simpletextbox.py代码非常直观继承FormComponent通过类属性EVENTS声明支持change、input、submit三个事件preprocess()/postprocess()仅在str与None之间转换是整个「后端函数数据流」的最简实现通过api_info()返回{type: string}声明 API 端点的 JSON Schema使组件开箱即用地支持 Gradio 的 API 访问。如果你希望一开始就用更「真实」的组件练手可以选用SimpleDropdown、SimpleImage或者功能更完整的File。运行gradio cc show可以列出当前环境所有可作为模板的组件源码见 gradio/cli/commands/components/show.py该命令会扫描gradio._simple_templates、gradio.components与gradio.layouts三个模块并为Simple*类以及Slider、Radio、Checkbox、Number、CheckboxGroup、File等组件标注Beginner Friendly新手友好标签同时区分Form Component与Layout类型。create 会做什么create命令源码见 gradio/cli/commands/components/create.py依次完成两件事1. 生成组件目录目录名取组件名的小写形式结构如下mycomponent/ ├── backend/ ← 组件的 Python 代码 ├── frontend/ ← 组件的 JavaScriptSvelte代码 ├── demo/ ← 使用该组件的示例应用改这里来开发调试 ├── pyproject.toml ← 打包配置与包元数据 ├── README.md └── .gitignore其中pyproject.toml由仓库内模板 gradio/cli/commands/components/files/pyproject_.toml 生成采用hatchling作为构建后端声明了包名、0.0.1初始版本、Apache-2.0许可证并通过[tool.hatch.build]段把backend/中的模板与 Python 代码打进 wheel。2. 开发模式安装默认会在生成骨架后自动执行安装对应独立命令gradio cc install让当前 Python 环境能直接import你的组件包。这也是后续build的前置条件。create 的常用参数参数默认值说明name位置参数—组件名建议驼峰命名--template空作为模板的组件 Python 类名留空则从零生成--directoryname 小写目录组件创建的目标目录--package-namegradio_name 小写Python 包名例如gradio_mycomponent--install / --no-install安装是否在当前环境执行开发模式安装--overwriteFalse目录已存在时是否覆盖--configure-metadataTrue是否交互式配置项目元数据create结束时通常还会弹出4 个交互式元数据问题用于完善pyproject.toml一句话组件描述description软件许可证license留空默认apache-2.0允许的 Python 版本requires-python留空默认3.10帮助他人发现该组件的关键词keywords可连续添加留空停止。这些内容也可以稍后直接编辑pyproject.toml补充生成的demo/requirements.txt会自动写入包名方便后续部署示例应用。第 2 步 dev热重载开发调试进入组件目录后启动开发服务器cd mycomponent gradio cc dev控制台会打印若干行日志其中最需要关注的是Frontend Server (Go here): http://localhost:7861/端口号可能因本机占用而不同。点击该链接即可打开运行在热重载模式下的示例应用之后你修改backend/的 Python 代码或frontend/的前端代码改动都会实时反映在示例页面上无需手动重启。从仓库源码gradio/cli/commands/components/dev.py可以还原它的内部机制dev 模式下后端以 reload 模式启动日志中以Backend Server标记前端则通过 Node 调用gradio/preview以dev模式启动 Vite 开发服务器命令会同时监听frontend/目录的变更并持续把Watching:列表打印到控制台默认查找的示例应用是demo/app.py因此「进入组件目录执行gradio cc dev」即可也可以把应用路径作为位置参数传入开发模式默认参数为demo/app.py组件源码目录则用--component-directory指定前端服务地址可用--host修改。需要注意dev依赖 Node.js 及前端目录中的gradio/preview依赖若未安装CLI 会给出明确的修复提示npm i -D gradio/preview。第 3 步 build打包并生成文档组件实现满意后即可脱离开发服务器构建正式产物。在组件目录执行gradio cc build构建完成后dist/子目录下会生成.tar.gz源码包与.whlwheel 安装包两个文件mycomponent/dist/ ├── gradio_mycomponent-0.0.1.tar.gz └── gradio_mycomponent-0.0.1-py3-none-any.whl任何人拿到.whl后执行pip install path-to-whl即可在自己的 Gradio 应用中import使用该组件。也就是说build让组件从「开发模式」走向「可分发状态」。build还会默认自动生成组件文档产物包含两部分一个可交互的 Space 应用以及一份静态README.md含徽章、安装方式、示例应用链接等。如果你暂时不需要文档可以追加--no-generate-docs关闭。关于文档生成器的详细配置见 guides/08_custom-components/09_documenting-custom-components.md。构建过程源码见 gradio/cli/commands/components/build.py还包含几条硬性约束与实用参数值得提前了解组件目录必须存在pyproject.toml且包必须已安装到当前环境否则 CLI 会报错并提示先执行gradio cc install前端构建走 Node gradio/preview的build模式最终 Python 打包执行的是python -m build产物落在dist/--bump-version可在每次构建时自动递增 patch 版本号0.0.1 → 0.0.2不传则使用pyproject.toml中[project] version字段定义的版本--no-build-frontend可跳过前端构建如果你没有改动过前端代码可显著加速额外的gradio cc docs子命令专门用于重新生成文档gradio/cli/commands/components/docs.py。第 4 步 publish发布到 PyPI 与 Spaces此时你的包还只是本机的一个.whl文件想分享给全世界使用就轮到publish命令gradio cc publish在组件目录下运行后命令会以向导形式引导你完成两步操作可选上传分发包到 PyPI把dist/下的文件上传到 PyPI。上传后把 demo 部署到 Hugging Face Spaces 会更容易因为依赖可以直接写你的 PyPI 包名如果跳过 PyPI则你的包必须位于一个公开可访问的 URL 上Spaces 才能安装它。选择上传 PyPI 时需要提前准备 PyPI 账号的用户名与密码。所有用户都可以免费注册 PyPI 账号。可选上传组件示例应用到 Hugging Face Spaces让其他人不用本地安装就能在浏览器里直接体验你的组件效果。发布之后使用者只需pip install gradio-mycomponent即可安装然后在gr.Blocks/gr.Interface中像内置组件一样使用它。结语与下一步到这里你已经掌握了自定义组件的高层工作流——create 搭骨架、dev 热重载调试、build 产出 wheel、publish 分发到社区并且知道了每一步背后的 CLI 源码实现。由于backend/与frontend/的分工贯穿始终建议接下来按顺序精读本目录下的系列指南guides/08_custom-components/02_key-component-concepts.md组件核心概念Config、Value、事件系统如何打通前后端guides/08_custom-components/04_backend.md 与 guides/08_custom-components/05_frontend.md分别深入 backend 与 frontend 的实现细节guides/08_custom-components/06_frequently-asked-questions.md如果不想从零开始也可以在 FAQ 中找到如何基于别人的现有组件起步guides/08_custom-components/07_pdf-component-example.md一个端到端的 PDF 组件实战案例。阅读官方指南之外直接阅读仓库源码是最快的进阶方式从 gradio/_simple_templates/simpletextbox.py 理解最小组件需要实现什么再到 gradio/cli/commands/components/app.py 掌握 CLI 命令的全貌你的第一个自定义组件很快就能发布并被社区使用。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考