gradio-app--gradio
wehub-resource-sync
233 行
13 KiB
Markdown
233 行
13 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/gradio-app/gradio) · [上游 README](https://github.com/gradio-app/gradio/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<!-- 请勿直接编辑此文件。请改为编辑 `readme_template.md` 或 `guides/01_getting-started/01_quickstart.md` 模板，然后运行 `render_readme.py` 脚本。 -->
|
||
|
||
<div align="center">
|
||
<a href="https://gradio.app">
|
||
<img src="readme_files/gradio.svg" alt="gradio" width=350>
|
||
</a>
|
||
</div>
|
||
|
||
<div align="center">
|
||
<span>
|
||
<a href="https://www.producthunt.com/posts/gradio-5-0?embed=true&utm_source=badge-featured&utm_medium=badge&utm_souce=badge-gradio-5-0" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=501906&theme=light" alt="Gradio 5.0 - the easiest way to build AI web apps | Product Hunt" style="width: 150px; height: 54px;" width="150" height="54" /></a>
|
||
<a href="https://trendshift.io/repositories/2145" target="_blank"><img src="https://trendshift.io/api/badge/repositories/2145" alt="gradio-app%2Fgradio | Trendshift" style="width: 150px; height: 55px;" width="150" height="55"/></a>
|
||
</span>
|
||
|
||
[](https://github.com/gradio-app/gradio/actions/workflows/test-python.yml)
|
||
[](https://github.com/gradio-app/gradio/actions/workflows/tests-js.yml)
|
||
[](https://pypi.org/project/gradio/)
|
||
[](https://pypi.org/project/gradio/)
|
||
|
||
[](https://twitter.com/gradio)
|
||
|
||
[官网](https://gradio.app)
|
||
| [文档](https://gradio.app/docs/)
|
||
| [指南](https://gradio.app/guides/)
|
||
| [入门](https://gradio.app/getting_started/)
|
||
| [示例](demo/)
|
||
|
||
</div>
|
||
|
||
<div align="center">
|
||
|
||
English | [中文](readme_files/zh-cn#readme)
|
||
|
||
</div>
|
||
|
||
# Gradio：用 Python 构建机器学习 Web 应用
|
||
|
||
|
||
|
||
Gradio 是一个开源 Python 包，可让你快速**构建**机器学习模型、API 或任意 Python 函数的演示或 Web 应用。随后，你还可以借助 Gradio 内置的分享功能，在几秒钟内**分享**演示或 Web 应用的链接。*无需 JavaScript、CSS 或 Web 托管经验！*
|
||
|
||
<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/gradio-guides/gif-version.gif" style="padding-bottom: 10px">
|
||
|
||
只需几行 Python 代码即可创建你自己的演示，让我们开始吧 💫
|
||
|
||
|
||
### 安装
|
||
|
||
**前提条件**：Gradio 需要 [Python 3.10 或更高版本](https://www.python.org/downloads/).
|
||
|
||
|
||
我们建议使用 `pip` 安装 Gradio，Python 默认已包含该工具。请在终端或命令提示符中运行：
|
||
|
||
```bash
|
||
pip install --upgrade gradio
|
||
```
|
||
|
||
|
||
> [!TIP]
|
||
> 最好在虚拟环境中安装 Gradio。所有常见操作系统的详细安装说明<a href="https://www.gradio.app/main/guides/installing-gradio-in-a-virtual-environment">请见此处</a>。
|
||
|
||
### 构建你的第一个 Demo
|
||
|
||
你可以在常用的代码编辑器、Jupyter notebook、Google Colab，或任何编写 Python 的地方运行 Gradio。让我们编写你的第一个 Gradio 应用：
|
||
|
||
|
||
```python
|
||
import gradio as gr
|
||
|
||
def greet(name, intensity):
|
||
return "Hello, " + name + "!" * int(intensity)
|
||
|
||
demo = gr.Interface(
|
||
fn=greet,
|
||
inputs=["text", "slider"],
|
||
outputs=["text"],
|
||
api_name="predict"
|
||
)
|
||
|
||
demo.launch()
|
||
```
|
||
|
||
|
||
|
||
> [!TIP]
|
||
> 我们将导入名从 <code>gradio</code> 简写为 <code>gr</code>。这是广泛采用的约定，可提高代码可读性。
|
||
|
||
现在，运行你的代码。如果你将 Python 代码写在名为 `app.py` 的文件中，则应在终端运行 `python app.py`。
|
||
|
||
如果从文件运行，下面的演示将在浏览器中的 [http://localhost:7860](http://localhost:7860) 上打开。如果在 notebook 中运行，演示将嵌入显示在 notebook 内。
|
||
|
||
|
||
|
||
在左侧文本框中输入你的名字，拖动滑块，然后点击 Submit 按钮。右侧应会显示友好的问候语。
|
||
|
||
> [!TIP]
|
||
> 在本地开发时，你可以以<strong>热重载模式（hot reload mode）</strong>运行 Gradio 应用，这样每当你修改文件时，应用都会自动重新加载。为此，只需在文件名前输入 <code>gradio</code>，而不是 <code>python</code>。在上面的示例中，你应在终端输入：`gradio app.py`。你也可以使用 <code>--vibe</code> 标志启用<strong>vibe 模式（vibe mode）</strong>，例如 <code>gradio --vibe app.py</code>，它会提供浏览器内聊天功能，可用自然语言编写或编辑 Gradio 应用。更多信息请参阅<a href="https://www.gradio.app/guides/developing-faster-with-reload-mode">热重载指南（Hot Reloading Guide）</a>。
|
||
|
||
|
||
**理解 `Interface` 类**
|
||
|
||
你会注意到，要创建第一个演示，你需要实例化 `gr.Interface` 类。`Interface` 类用于为机器学习模型创建演示，这些模型接受一个或多个输入，并返回一个或多个输出。
|
||
|
||
`Interface` 类有三个核心参数：
|
||
|
||
- `fn`：要为其包装用户界面（UI）的函数
|
||
- `inputs`：用于输入的 Gradio 组件。组件数量应与函数参数数量一致。
|
||
- `outputs`：用于输出的 Gradio 组件。组件数量应与函数返回值数量一致。
|
||
|
||
`fn` 参数非常灵活——你可以传入*任意*需要用 UI 包装的 Python 函数。在上面的示例中，我们看到的是一个相对简单的函数，但该函数可以是音乐生成器、税务计算器，或预训练机器学习模型的预测函数等任何功能。
|
||
|
||
`inputs` 和 `outputs` 参数接受一个或多个 Gradio 组件。正如我们将看到的，Gradio 包含超过 [30 个内置组件](https://www.gradio.app/docs/gradio/introduction)（例如 `gr.Textbox()`、`gr.Image()` 和 `gr.HTML()` 组件），专为机器学习应用而设计。
|
||
|
||
> [!TIP]
|
||
> 对于 `inputs` 和 `outputs` 参数，你可以将这些组件的名称作为字符串传入（`"textbox"`），或传入类的实例（`gr.Textbox()`）。
|
||
|
||
如果你的函数接受多个参数（如上例所示），请向 `inputs` 传入输入组件列表，每个输入组件按顺序对应函数的一个参数。如果函数返回多个值，做法相同：只需向 `outputs` 传入组件列表即可。这种灵活性使 `Interface` 类成为创建演示的非常强大的方式。
|
||
|
||
我们将在[构建 Interface](https://www.gradio.app/main/guides/the-interface-class). 系列中更深入地介绍 `gr.Interface`
|
||
|
||
### 分享你的 Demo
|
||
|
||
再漂亮的演示，若无法分享也意义不大。Gradio 让你轻松分享机器学习演示，而无需操心在 Web 服务器上托管的麻烦。只需在 `launch()` 中设置 `share=True`，就会为你的演示创建一个可公开访问的 URL。让我们回到示例演示，但将最后一行修改如下：
|
||
|
||
```python
|
||
import gradio as gr
|
||
|
||
def greet(name):
|
||
return "Hello " + name + "!"
|
||
|
||
demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox")
|
||
|
||
demo.launch(share=True) # Share your demo with just 1 extra parameter 🚀
|
||
```
|
||
|
||
运行此代码后，几秒钟内就会为你的演示生成一个公开 URL，类似：
|
||
|
||
👉 `https://a23dsf231adb.gradio.live`
|
||
|
||
现在，世界各地的任何人都可通过浏览器试用你的 Gradio 演示，而机器学习模型及所有计算仍在你本地计算机上运行。
|
||
|
||
要了解更多分享演示的方法，请阅读我们关于[分享 Gradio 应用](https://www.gradio.app/guides/sharing-your-app). 的专门指南
|
||
|
||
### Gradio 概览
|
||
|
||
到目前为止，我们一直在讨论 `Interface` 类，这是一个高级类，可让你用 Gradio 快速构建 demo。但 Gradio 还包含哪些内容呢？
|
||
|
||
#### 使用 `gr.Blocks` 构建自定义 Demo
|
||
|
||
Gradio 提供了一种低级方法，借助 `gr.Blocks` 类，可设计具有更可定制布局和数据流的 Web 应用。Blocks 支持例如控制组件在页面中的位置、处理多条数据流以及更复杂的交互（例如输出可作为其他函数的输入），并根据用户交互更新组件的属性/可见性——这一切都仍在 Python 中完成。
|
||
|
||
你可以使用 `gr.Blocks()` 构建非常定制且复杂的应用。例如，流行的图像生成 [Automatic1111 Web UI](https://github.com/AUTOMATIC1111/stable-diffusion-webui) 就是使用 Gradio Blocks 构建的。我们在关于 [使用 Blocks 构建](https://www.gradio.app/guides/blocks-and-event-listeners). 的系列文章中更深入地介绍了 `gr.Blocks`。
|
||
|
||
#### 使用 `gr.ChatInterface` 构建聊天机器人
|
||
|
||
Gradio 还包含另一个高级类 `gr.ChatInterface`，专门用于创建 Chatbot UI。与 `Interface` 类似，你提供一个函数，Gradio 就会创建一个完整可用的 Chatbot UI。如果你想创建聊天机器人，可以直接跳转到 [我们关于 `gr.ChatInterface` 的专用指南](https://www.gradio.app/guides/creating-a-chatbot-fast).
|
||
|
||
#### Gradio Python 与 JavaScript 生态系统
|
||
|
||
以上就是核心 `gradio` Python 库的要点，但 Gradio 实际上远不止如此！它是一个完整的 Python 和 JavaScript 库生态系统，让你可以用 Python 或 JavaScript 构建机器学习应用，或以编程方式查询它们。以下是 Gradio 生态系统的其他相关部分：
|
||
|
||
* [Gradio Python Client](https://www.gradio.app/guides/getting-started-with-the-python-client) (`gradio_client`)：在 Python 中以编程方式查询任何 Gradio 应用。
|
||
* [Gradio JavaScript Client](https://www.gradio.app/guides/getting-started-with-the-js-client) (`@gradio/client`)：在 JavaScript 中以编程方式查询任何 Gradio 应用。
|
||
* [Hugging Face Spaces](https://huggingface.co/spaces): 托管 Gradio 应用最受欢迎的平台——而且是免费的！
|
||
* [Server mode](https://www.gradio.app/guides/server-mode) (`gradio.Server`)：使用 Gradio 的后端构建自定义前端——包含队列、流式传输、MCP、ZeroGPU 和 Spaces 托管。
|
||
|
||
### 接下来做什么？
|
||
|
||
继续按顺序通过 Gradio Guides 学习 Gradio，其中包含说明、示例代码以及嵌入式交互式 demo。下一篇：[让我们更深入地了解 Interface 类](https://www.gradio.app/guides/the-interface-class).
|
||
|
||
或者，如果你已掌握基础知识并在寻找特定内容，可以搜索更 [技术性的 API 文档](https://www.gradio.app/docs/).
|
||
|
||
|
||
### AI 编程技能（Skills）
|
||
|
||
Gradio 提供了一个「skill」，可为 AI 编程助手（如 Cursor、Claude Code、Codex 等）补充 Gradio 专属知识，使其更高效地构建 Gradio 应用。这在创建自定义 Gradio 组件或样式时尤其有用。只需一条命令即可为你的编程助手安装 Gradio skill：
|
||
|
||
```bash
|
||
gradio skills add --cursor # or --claude, --codex, --opencode
|
||
```
|
||
|
||
使用 `--global` 在用户级别安装（适用于所有项目）。该 skill 将自动对相应的编程 agent 可用。
|
||
|
||
你也可以为**特定的 Gradio Space** 安装 skill，它会动态生成 API 使用文档（Python、JS、cURL）：
|
||
|
||
```bash
|
||
gradio skills add abidlabs/en2fr --cursor
|
||
```
|
||
|
||
## 有问题？
|
||
|
||
如果你想报告 bug 或提出功能请求，请在 GitHub 上创建 [issue](https://github.com/gradio-app/gradio/issues/new/choose).。关于使用的一般性问题，我们在 [Discord 服务器](https://discord.com/invite/feTf9x3ZSB) 上随时提供帮助。
|
||
|
||
如果你喜欢 Gradio，欢迎在 GitHub 上给我们点个 ⭐！
|
||
|
||
## 开源技术栈
|
||
|
||
Gradio 构建在许多优秀的开源库之上！
|
||
|
||
[<img src="readme_files/huggingface_mini.svg" alt="huggingface" height=40>](https://huggingface.co)
|
||
[<img src="readme_files/python.svg" alt="python" height=40>](https://www.python.org)
|
||
[<img src="readme_files/fastapi.svg" alt="fastapi" height=40>](https://fastapi.tiangolo.com)
|
||
[<img src="readme_files/encode.svg" alt="encode" height=40>](https://www.encode.io)
|
||
[<img src="readme_files/svelte.svg" alt="svelte" height=40>](https://svelte.dev)
|
||
[<img src="readme_files/vite.svg" alt="vite" height=40>](https://vitejs.dev)
|
||
[<img src="readme_files/pnpm.svg" alt="pnpm" height=40>](https://pnpm.io)
|
||
[<img src="readme_files/tailwind.svg" alt="tailwind" height=40>](https://tailwindcss.com)
|
||
[<img src="readme_files/storybook.svg" alt="storybook" height=40>](https://storybook.js.org/)
|
||
[<img src="readme_files/chromatic.svg" alt="chromatic" height=40>](https://www.chromatic.com/)
|
||
|
||
## 许可证
|
||
|
||
Gradio 根据 Apache License 2.0 许可，许可证文本位于本仓库根目录的 [LICENSE](LICENSE) 文件中。
|
||
|
||
## 引用
|
||
|
||
另请参阅论文 _[Gradio: Hassle-Free Sharing and Testing of ML Models in the Wild](https://arxiv.org/abs/1906.02569), ICML HILL 2019_，若你在工作中使用 Gradio，请引用此文。
|
||
|
||
```
|
||
@article{abid2019gradio,
|
||
title = {Gradio: Hassle-Free Sharing and Testing of ML Models in the Wild},
|
||
author = {Abid, Abubakar and Abdalla, Ali and Abid, Ali and Khan, Dawood and Alfozan, Abdulrahman and Zou, James},
|
||
journal = {arXiv preprint arXiv:1906.02569},
|
||
year = {2019},
|
||
}
|
||
```
|