|
1 | | -# 🚀 Creating Discord Bots from Gradio Apps 🚀 |
| 1 | +# 🚀 Creating Discord Bots with Gradio 🚀 |
2 | 2 |
|
3 | | -Tags: NLP, TEXT, CHAT |
| 3 | +Tags: CHAT, DEPLOY, DISCORD |
4 | 4 |
|
5 | | -We're excited to announce that Gradio can now automatically create a discord bot from a deployed app! 🤖 |
| 5 | +You can make your Gradio app available as a Discord bot to let users in your Discord server interact with it directly. |
6 | 6 |
|
7 | | -Discord is a popular communication platform that allows users to chat and interact with each other in real-time. By turning your Gradio app into a Discord bot, you can bring cutting edge AI to your discord server and give your community a whole new way to interact. |
| 7 | +## How does it work? |
8 | 8 |
|
9 | | -## 💻 How does it work? 💻 |
| 9 | +The Discord bot will listen to messages mentioning it in channels. When it receives a message (which can include text as well as files), it will send it to your Gradio app via Gradio's built-in API. Your bot will reply with the response it receives from the API. |
10 | 10 |
|
11 | | -With `gradio_client` version `0.3.0`, any gradio `ChatInterface` app on the internet can automatically be deployed as a discord bot via the `deploy_discord` method of the `Client` class. |
| 11 | +Because Gradio's API is very flexible, you can create Discord bots that support text, images, audio, streaming, chat history, and a wide variety of other features very easily. |
12 | 12 |
|
13 | | -Technically, any gradio app that exposes an api route that takes in a single string and outputs a single string can be deployed to discord. In this guide, we will focus on `gr.ChatInterface` as those apps naturally lend themselves to discord's chat functionality. |
| 13 | + |
14 | 14 |
|
15 | | -## 🛠️ Requirements 🛠️ |
| 15 | +## Prerequisites |
16 | 16 |
|
17 | | -Make sure you have the latest `gradio_client` and `gradio` versions installed. |
| 17 | +* Install the latest version of `gradio` and the `discord.py` libraries: |
18 | 18 |
|
19 | | -```bash |
20 | | -pip install gradio_client>=0.3.0 gradio>=3.38.0 |
| 19 | +``` |
| 20 | +pip install --upgrade gradio discord.py~=2.0 |
21 | 21 | ``` |
22 | 22 |
|
23 | | -Also, make sure you have a [Hugging Face account](https://huggingface.co/) and a [write access token](https://huggingface.co/docs/hub/security-tokens). |
24 | | - |
25 | | -⚠️ Tip ⚠️: Make sure you login to the Hugging Face Hub by running `huggingface-cli login`. This will let you skip passing your token in all subsequent commands in this guide. |
| 23 | +* Have a running Gradio app. This app can be running locally or on Hugging Face Spaces. In this example, we will be using the [Gradio Playground Space](https://huggingface.co/spaces/abidlabs/gradio-playground-bot), which takes in an image and/or text and generates the code to generate the corresponding Gradio app. |
26 | 24 |
|
27 | | -## 🏃♀️ Quickstart 🏃♀️ |
| 25 | +Now, we are ready to get started! |
28 | 26 |
|
29 | | -### Step 1: Implementing our chatbot |
30 | 27 |
|
31 | | -Let's build a very simple Chatbot using `ChatInterface` that simply repeats the user message. Write the following code into an `app.py` |
| 28 | +### 1. Create a Discord application |
32 | 29 |
|
33 | | -```python |
34 | | -import gradio as gr |
| 30 | +First, go to the [Discord apps dashboard](https://discord.com/developers/applications). Look for the "New Application" button and click it. Give your application a name, and then click "Create". |
35 | 31 |
|
36 | | -def slow_echo(message, history): |
37 | | - return message |
38 | | - |
39 | | -demo = gr.ChatInterface(slow_echo).queue().launch() |
40 | | -``` |
| 32 | + |
41 | 33 |
|
42 | | -### Step 2: Deploying our App |
| 34 | +On the resulting screen, you will see basic information about your application. Under the Settings section, click on the "Bot" option. You can update your bot's username if you would like. |
43 | 35 |
|
44 | | -In order to create a discord bot for our app, it must be accessible over the internet. In this guide, we will use the `gradio deploy` command to deploy our chatbot to Hugging Face spaces from the command line. Run the following command. |
| 36 | +Then click on the "Reset Token" button. A new token will be generated. Copy it as we will need it for the next step. |
45 | 37 |
|
46 | | -```bash |
47 | | -gradio deploy --title echo-chatbot --app-file app.py |
48 | | -``` |
| 38 | +Scroll down to the section that says "Privileged Gateway Intents". Your bot will need certain permissions to work correctly. In this tutorial, we will only be using the "Message Content Intent" so click the toggle to enable this intent. Save the changes. |
49 | 39 |
|
50 | | -This command will ask you some questions, e.g. requested hardware, requirements, but the default values will suffice for this guide. |
51 | | -Note the URL of the space that was created. Mine is https://huggingface.co/spaces/freddyaboulton/echo-chatbot |
| 40 | + |
52 | 41 |
|
53 | | -### Step 3: Creating a Discord Bot |
54 | 42 |
|
55 | | -Turning our space into a discord bot is also a one-liner thanks to the `gradio deploy-discord`. Run the following command: |
56 | 43 |
|
57 | | -```bash |
58 | | -gradio deploy-discord --src freddyaboulton/echo-chatbot |
59 | | -``` |
| 44 | +### 2. Write a Discord bot |
60 | 45 |
|
61 | | -❗️ Advanced ❗️: If you already have a discord bot token you can pass it to the `deploy-discord` command. Don't worry, if you don't have one yet! |
| 46 | +Let's start by writing a very simple Discord bot, just to make sure that everything is working. Write the following Python code in a file called `bot.py`, pasting the discord bot token from the previous step: |
62 | 47 |
|
63 | | -```bash |
64 | | -gradio deploy-discord --src freddyaboulton/echo-chatbot --discord-bot-token <token> |
65 | | -``` |
| 48 | +```python |
| 49 | +# bot.py |
| 50 | +import discord |
66 | 51 |
|
67 | | -Note the URL that gets printed out to the console. Mine is https://huggingface.co/spaces/freddyaboulton/echo-chatbot-gradio-discord-bot |
| 52 | +TOKEN = #PASTE YOUR DISCORD BOT TOKEN HERE |
68 | 53 |
|
69 | | -### Step 4: Getting a Discord Bot Token |
| 54 | +client = discord.Client() |
70 | 55 |
|
71 | | -If you didn't have a discord bot token for step 3, go to the URL that got printed in the console and follow the instructions there. |
72 | | -Once you obtain a token, run the command again but this time pass in the token: |
| 56 | +@client.event |
| 57 | +async def on_ready(): |
| 58 | + print(f'{client.user} has connected to Discord!') |
73 | 59 |
|
74 | | -```bash |
75 | | -gradio deploy-discord --src freddyaboulton/echo-chatbot --discord-bot-token <token> |
| 60 | +client.run(TOKEN) |
76 | 61 | ``` |
77 | 62 |
|
78 | | -### Step 5: Add the bot to your server |
| 63 | +Now, run this file: `python bot.py`, which should run and print a message like: |
79 | 64 |
|
80 | | -Visit the space of your discord bot. You should see "Add this bot to your server by clicking this link:" followed by a URL. Go to that URL and add the bot to your server! |
| 65 | +```text |
| 66 | +We have logged in as GradioPlaygroundBot#1451 |
| 67 | +``` |
81 | 68 |
|
82 | | -### Step 6: Use your bot! |
| 69 | +If that is working, we are ready to add Gradio-specific code. We will be using the [Gradio Python Client](https://www.gradio.app/guides/getting-started-with-the-python-client) to query the Gradio Playground Space mentioned above. Here's the updated `bot.py` file: |
83 | 70 |
|
84 | | -By default the bot can be called by starting a message with `/chat`, e.g. `/chat <your prompt here>`. |
| 71 | +```python |
| 72 | +import discord |
| 73 | +from gradio_client import Client, handle_file |
| 74 | +import httpx |
| 75 | +import os |
| 76 | + |
| 77 | +TOKEN = #PASTE YOUR DISCORD BOT TOKEN HERE |
| 78 | + |
| 79 | +intents = discord.Intents.default() |
| 80 | +intents.message_content = True |
| 81 | + |
| 82 | +client = discord.Client(intents=intents) |
| 83 | +gradio_client = Client("abidlabs/gradio-playground-bot") |
| 84 | + |
| 85 | +def download_image(attachment): |
| 86 | + response = httpx.get(attachment.url) |
| 87 | + image_path = f"./images/{attachment.filename}" |
| 88 | + os.makedirs("./images", exist_ok=True) |
| 89 | + with open(image_path, "wb") as f: |
| 90 | + f.write(response.content) |
| 91 | + return image_path |
| 92 | + |
| 93 | +@client.event |
| 94 | +async def on_ready(): |
| 95 | + print(f'We have logged in as {client.user}') |
| 96 | + |
| 97 | +@client.event |
| 98 | +async def on_message(message): |
| 99 | + # Ignore messages from the bot itself |
| 100 | + if message.author == client.user: |
| 101 | + return |
| 102 | + |
| 103 | + # Check if the bot is mentioned in the message and reply |
| 104 | + if client.user in message.mentions: |
| 105 | + # Extract the message content without the bot mention |
| 106 | + clean_message = message.content.replace(f"<@{client.user.id}>", "").strip() |
| 107 | + |
| 108 | + # Handle images (only the first image is used) |
| 109 | + files = [] |
| 110 | + if message.attachments: |
| 111 | + for attachment in message.attachments: |
| 112 | + if any(attachment.filename.lower().endswith(ext) for ext in ['png', 'jpg', 'jpeg', 'gif', 'webp']): |
| 113 | + image_path = download_image(attachment) |
| 114 | + files.append(handle_file(image_path)) |
| 115 | + break |
| 116 | + |
| 117 | + # Stream the responses to the channel |
| 118 | + for response in gradio_client.submit( |
| 119 | + message={"text": clean_message, "files": files}, |
| 120 | + ): |
| 121 | + await message.channel.send(response[-1]) |
| 122 | + |
| 123 | +client.run(TOKEN) |
| 124 | +``` |
85 | 125 |
|
86 | | -⚠️ Tip ⚠️: If either of the deployed spaces goes to sleep, the bot will stop working. By default, spaces go to sleep after 48 hours of inactivity. You can upgrade the hardware of your space to prevent it from going to sleep. See this [guide](https://huggingface.co/docs/hub/spaces-gpus#using-gpu-spaces) for more information. |
| 126 | +### 3. Add the bot to your Discord Server |
87 | 127 |
|
88 | | -<img src="https://gradio-builds.s3.amazonaws.com/demo-files/discordbots/guide/echo_slash.gif"> |
| 128 | +Now we are ready to install the bot on our server. Go back to the [Discord apps dashboard](https://discord.com/developers/applications). Under the Settings section, click on the "OAuth2" option. Scroll down to the "OAuth2 URL Generator" box and select the "bot" checkbox: |
89 | 129 |
|
90 | | -### Using the `gradio_client.Client` Class |
| 130 | + |
91 | 131 |
|
92 | | -You can also create a discord bot from a deployed gradio app with python. |
93 | 132 |
|
94 | | -```python |
95 | | -import gradio_client as grc |
96 | | -grc.Client("freddyaboulton/echo-chatbot").deploy_discord() |
97 | | -``` |
98 | 133 |
|
99 | | -## 🦾 Using State of The Art LLMs 🦾 |
| 134 | +Then in "Bot Permissions" box that pops up underneath, enable the following permissions: |
100 | 135 |
|
101 | | -We have created an organization on Hugging Face called [gradio-discord-bots](https://huggingface.co/gradio-discord-bots) containing several template spaces that explain how to deploy state of the art LLMs powered by gradio as discord bots. |
| 136 | + |
102 | 137 |
|
103 | | -The easiest way to get started is by deploying Meta's Llama 2 LLM with 70 billion parameter. Simply go to this [space](https://huggingface.co/spaces/gradio-discord-bots/Llama-2-70b-chat-hf) and follow the instructions. |
104 | 138 |
|
105 | | -The deployment can be done in one line! 🤯 |
| 139 | +Copy the generated URL that appears underneath, which should look something like: |
106 | 140 |
|
107 | | -```python |
108 | | -import gradio_client as grc |
109 | | -grc.Client("ysharma/Explore_llamav2_with_TGI").deploy_discord(to_id="llama2-70b-discord-bot") |
| 141 | +```text |
| 142 | +https://discord.com/oauth2/authorize?client_id=1319011745452265575&permissions=377957238784&integration_type=0&scope=bot |
110 | 143 | ``` |
111 | 144 |
|
112 | | -## 🦜 Additional LLMs 🦜 |
| 145 | +Paste it into your browser, which should allow you to add the Discord bot to any Discord server that you manage. |
113 | 146 |
|
114 | | -In addition to Meta's 70 billion Llama 2 model, we have prepared template spaces for the following LLMs and deployment options: |
115 | 147 |
|
116 | | -- [gpt-3.5-turbo](https://huggingface.co/spaces/gradio-discord-bots/gpt-35-turbo), powered by openai. Required OpenAI key. |
117 | | -- [falcon-7b-instruct](https://huggingface.co/spaces/gradio-discord-bots/falcon-7b-instruct) powered by Hugging Face Inference Endpoints. |
118 | | -- [Llama-2-13b-chat-hf](https://huggingface.co/spaces/gradio-discord-bots/Llama-2-13b-chat-hf) powered by Hugging Face Inference Endpoints. |
119 | | -- [Llama-2-13b-chat-hf](https://huggingface.co/spaces/gradio-discord-bots/llama-2-13b-chat-transformers) powered by Hugging Face transformers. |
| 148 | +### 4. That's it! |
120 | 149 |
|
121 | | -To deploy any of these models to discord, simply follow the instructions in the linked space for that model. |
| 150 | +Now you can mention your bot from any channel in your Discord server, optionally attach an image, and it will respond with generated Gradio app code! |
122 | 151 |
|
123 | | -## Deploying non-chat gradio apps to discord |
| 152 | +The bot will: |
| 153 | +1. Listen for mentions |
| 154 | +2. Process any attached images |
| 155 | +3. Send the text and images to your Gradio app |
| 156 | +4. Stream the responses back to the Discord channel |
124 | 157 |
|
125 | | -As mentioned above, you don't need a `gr.ChatInterface` if you want to deploy your gradio app to discord. All that's needed is an api route that takes in a single string and outputs a single string. |
126 | | - |
127 | | -The following code will deploy a space that translates english to german as a discord bot. |
128 | | - |
129 | | -```python |
130 | | -import gradio_client as grc |
131 | | -client = grc.Client("freddyaboulton/english-to-german") |
132 | | -client.deploy_discord(api_names=['german']) |
133 | | -``` |
| 158 | + This is just a basic example - you can extend it to handle more types of files, add error handling, or integrate with different Gradio apps. |
134 | 159 |
|
135 | | -## Conclusion |
| 160 | + |
136 | 161 |
|
137 | | -That's it for this guide! We're really excited about this feature. Tag [@Gradio](https://twitter.com/Gradio) on twitter and show us how your discord community interacts with your discord bots. |
| 162 | +If you build a Discord bot from a Gradio app, feel free to share it on X and tag [the Gradio account](https://x.com/Gradio), and we are happy to help you amplify! |
0 commit comments