From 5c8915b11308756c3b7279864d240ea85f5a0b4a Mon Sep 17 00:00:00 2001 From: Abubakar Abid Date: Tue, 4 Jun 2024 18:32:13 -0700 Subject: [PATCH] Add cURL to view API Page and add a dedicated Guide (#8445) * curl docs * add changeset * curl * guide complete * rename * more details * add changeset * add changeset * Update guides/08_gradio-clients-and-lite/03_querying-gradio-apps-with-curl.md Co-authored-by: Ali Abdalla * Update guides/08_gradio-clients-and-lite/03_querying-gradio-apps-with-curl.md Co-authored-by: Ali Abdalla * changes * add support for curl in view api docs * add support for files * format frontend * lint * Update js/app/src/api_docs/img/bash.svg Co-authored-by: Ali Abdalla * remove api recorder on bash * fixes * changes * fix --------- Co-authored-by: gradio-pr-bot Co-authored-by: Ali Abdalla --- .changeset/ripe-tires-nail.md | 6 + .config/.prettierignore | 3 +- gradio/routes.py | 4 +- .../03_querying-gradio-apps-with-curl.md | 262 ++++++++++++++++++ ... 07_fastapi-app-with-the-gradio-client.md} | 0 js/app/src/api_docs/ApiBanner.svelte | 17 +- js/app/src/api_docs/ApiDocs.svelte | 62 +++-- js/app/src/api_docs/CodeSnippet.svelte | 61 +++- js/app/src/api_docs/InstallSnippet.svelte | 10 +- js/app/src/api_docs/ParametersSnippet.svelte | 10 +- js/app/src/api_docs/RecordingSnippet.svelte | 2 +- js/app/src/api_docs/ResponseSnippet.svelte | 2 +- js/app/src/api_docs/img/bash.svg | 8 + js/app/src/api_docs/utils.ts | 32 ++- 14 files changed, 429 insertions(+), 50 deletions(-) create mode 100644 .changeset/ripe-tires-nail.md create mode 100644 guides/08_gradio-clients-and-lite/03_querying-gradio-apps-with-curl.md rename guides/08_gradio-clients-and-lite/{03_fastapi-app-with-the-gradio-client.md => 07_fastapi-app-with-the-gradio-client.md} (100%) create mode 100644 js/app/src/api_docs/img/bash.svg diff --git a/.changeset/ripe-tires-nail.md b/.changeset/ripe-tires-nail.md new file mode 100644 index 0000000000000..e4098a2df7d9f --- /dev/null +++ b/.changeset/ripe-tires-nail.md @@ -0,0 +1,6 @@ +--- +"@gradio/app": patch +"gradio": patch +--- + +feat:Add cURL to view API Page and add a dedicated Guide diff --git a/.config/.prettierignore b/.config/.prettierignore index e3520114c0701..34269d0901340 100644 --- a/.config/.prettierignore +++ b/.config/.prettierignore @@ -29,4 +29,5 @@ sweep.yaml **/src/lib/json/**/* **/playwright/.cache/**/* **/theme/src/pollen.css -**/venv/** \ No newline at end of file +**/venv/** +../js/app/src/api_docs/CodeSnippet.svelte \ No newline at end of file diff --git a/gradio/routes.py b/gradio/routes.py index 525b1da717890..5db32b4d0f76e 100644 --- a/gradio/routes.py +++ b/gradio/routes.py @@ -768,7 +768,9 @@ async def simple_predict_post( request: fastapi.Request, username: str = Depends(get_current_user), ): - full_body = PredictBody(**body.model_dump(), simple_format=True) + full_body = PredictBody( + **body.model_dump(), request=request, simple_format=True + ) fn = route_utils.get_fn( blocks=app.get_blocks(), api_name=api_name, body=full_body ) diff --git a/guides/08_gradio-clients-and-lite/03_querying-gradio-apps-with-curl.md b/guides/08_gradio-clients-and-lite/03_querying-gradio-apps-with-curl.md new file mode 100644 index 0000000000000..e8be790f56456 --- /dev/null +++ b/guides/08_gradio-clients-and-lite/03_querying-gradio-apps-with-curl.md @@ -0,0 +1,262 @@ +# Querying Gradio Apps with Curl + +Tags: CURL, API, SPACES + +It is possible to use any Gradio app as an API using cURL, the command-line tool that is pre-installed on many operating systems. This is particularly useful if you are trying to query a Gradio app from an environment other than Python or Javascript (since specialized Gradio clients exist for both [Python](/guides/getting-started-with-the-python-client) and [Javascript](/guides/getting-started-with-the-js-client)). + +As an example, consider this Gradio demo that translates text from English to French: https://abidlabs-en2fr.hf.space/. + +Using `curl`, we can translate text programmatically. + +Here's the code to do it: + +```bash +$ curl -X POST https://abidlabs-en2fr.hf.space/call/predict -H "Content-Type: application/json" -d '{ + "data": ["Hello, my friend."] +}' + +> {"event_id": $EVENT_ID} +``` + +```bash +$ curl -N https://abidlabs-en2fr.hf.space/call/predict/$EVENT_ID + +> event: complete +> data: ["Bonjour, mon ami."] +``` + + +Tip: making a prediction and getting a result requires two `curl` requests: a `POST` and a `GET`. The `POST` request returns an `EVENT_ID` and prints it to the console , which is used in the second `GET` request to fetch the results. We'll cover these two steps in more detail in the Guide below. + + +**Prerequisites**: For this Guide, you do _not_ need to know the `gradio` library in great detail. However, it is helpful to have general familiarity with Gradio's concepts of input and output components. + +## Installation + +You generally don't need to install cURL, as it comes pre-installed on many operating systems. Run: + +```bash +curl --version +``` + +to confirm that `curl` is installed. If it is not already installed, you can install it by visiting https://curl.se/download.html. + + +## Step 0: Get the URL for your Gradio App + +To query a Gradio app, you'll need its full URL. This is usually just the URL that the Gradio app is hosted on, for example: https://bec81a83-5b5c-471e.gradio.live + + +**Hugging Face Spaces** + +However, if you are querying a Gradio on Hugging Face Spaces, you will need to use the URL of the embedded Gradio app, not the URL of the Space webpage. For example: + +```bash +❌ Space URL: https://huggingface.co/spaces/abidlabs/en2fr +✅ Gradio app URL: https://abidlabs-en2fr.hf.space/ +``` + +You can get the Gradio app URL by clicking the "view API" link at the bottom of the page. Or, you can right-click on the page and then click on "View Frame Source" or the equivalent in your browser to view the URL of the embedded Gradio app. + +While you can use any public Space as an API, you may get rate limited by Hugging Face if you make too many requests. For unlimited usage of a Space, simply duplicate the Space to create a private Space, +and then use it to make as many requests as you'd like! + +Note: to query private Spaces, you will need to pass in your Hugging Face (HF) token. You can get your HF token here: https://huggingface.co/settings/tokens. In this case, you will need to include an additional header in both of your `curl` calls that we'll discuss below: + +```bash +-H "Authorization: Bearer $HF_TOKEN" +``` + +Now, we are ready to make the two `curl` requests. + +## Step 1: Make a Prediction (POST) + +The first of the two `curl` requests is `POST` request that submits the input payload to the Gradio app. + +The syntax of the `POST` request is as follows: + +```bash +$ curl -X POST $URL/call/$API_NAME -H "Content-Type: application/json" -d '{ + "data": $PAYLOAD +}' +``` + +Here: + +* `$URL` is the URL of the Gradio app as obtained in Step 0 +* `$API_NAME` is the name of the API endpoint for the event that you are running. You can get the API endpoint names by clicking the "view API" link at the bottom of the page. +* `$PAYLOAD` is a valid JSON data list containing the input payload, one element for each input component. + +When you make this `POST` request successfully, you will get an event id that is printed to the terminal in this format: + +```bash +> {"event_id": $EVENT_ID} +``` + +This `EVENT_ID` will be needed in the subsequent `curl` request to fetch the results of the prediction. + +Here are some examples of how to make the `POST` request + +**Basic Example** + +Revisiting the example at the beginning of the page, here is how to make the `POST` request for a simple Gradio application that takes in a single input text component: + +```bash +$ curl -X POST https://abidlabs-en2fr.hf.space/call/predict -H "Content-Type: application/json" -d '{ + "data": ["Hello, my friend."] +}' +``` + +**Multiple Input Components** + +This [Gradio demo](https://huggingface.co/spaces/gradio/hello_world_3) accepts three inputs: a string corresponding to the `gr.Textbox`, a boolean value corresponding to the `gr.Checkbox`, and a numerical value corresponding to the `gr.Slider`. Here is the `POST` request: + +```bash +curl -X POST https://gradio-hello-world-3.hf.space/call/predict -H "Content-Type: application/json" -d '{ + "data": ["Hello", true, 5] +}' +``` + +**Private Spaces** + +As mentioned earlier, if you are making a request to a private Space, you will need to pass in a [Hugging Face token](https://huggingface.co/settings/tokens) that has read access to the Space. The request will look like this: + +```bash +$ curl -X POST https://private-space.hf.space/call/predict -H "Content-Type: application/json" -H "Authorization: Bearer $HF_TOKEN" -d '{ + "data": ["Hello, my friend."] +}' +``` + +**Files** + +If your Gradio application requires file inputs, you can pass in files as URLs through `curl`. The URL needs to be enclosed in a dictionary in this format: + +```bash +{"path": $URL} +``` + +Here is an example `POST` request: + +```bash +$ curl -X POST https://gradio-image-mod.hf.space/call/predict -H "Content-Type: application/json" -d '{ + "data": [{"path": "https://raw.githubusercontent.com/gradio-app/gradio/main/test/test_files/bus.png"}] +}' +``` + + +**Stateful Demos** + +If your Gradio demo [persists user state](/guides/interface-state) across multiple interactions (e.g. is a chatbot), you can pass in a `session_hash` alongside the `data`. Requests with the same `session_hash` are assumed to be part of the same user session. Here's how that might look: + +```bash +# These two requests will share a session + +curl -X POST https://gradio-chatinterface-random-response.hf.space/call/chat -H "Content-Type: application/json" -d '{ + "data": ["Are you sentient?"], + "session_hash": "randomsequence1234" +}' + +curl -X POST https://gradio-chatinterface-random-response.hf.space/call/chat -H "Content-Type: application/json" -d '{ + "data": ["Really?"], + "session_hash": "randomsequence1234" +}' + +# This request will be treated as a new session + +curl -X POST https://gradio-chatinterface-random-response.hf.space/call/chat -H "Content-Type: application/json" -d '{ + "data": ["Are you sentient?"], + "session_hash": "newsequence5678" +}' +``` + + + +## Step 2: GET the result + +Once you have received the `EVENT_ID` corresponding to your prediction, you can stream the results. Gradio stores these results in a least-recently-used cache in the Gradio app. By default, the cache can store 2,000 results (across all users and endpoints of the app). + +To stream the results for your prediction, make a `GET` request with the following syntax: + +```bash +$ curl -N $URL/call/$API_NAME/$EVENT_ID +``` + + +Tip: If you are fetching results from a private Space, include a header with your HF token like this: `-H "Authorization: Bearer $HF_TOKEN"` in the `GET` request. + +This should produce a stream of responses in this format: + +```bash +event: ... +data: ... +event: ... +data: ... +... +``` + +Here: `event` can be one of the following: +* `generating`: indicating an intermediate result +* `complete`: indicating that the prediction is complete and the final result +* `error`: indicating that the prediction was not completed successfully +* `heartbeat`: sent every 15 seconds to keep the request alive + +The `data` is in the same format as the input payload: valid JSON data list containing the output result, one element for each output component. + +Here are some examples of what results you should expect if a request is completed successfully: + +**Basic Example** + +Revisiting the example at the beginning of the page, we would expect the result to look like this: + +```bash +event: complete +data: ["Bonjour, mon ami."] +``` + +**Multiple Outputs** + +If your endpoint returns multiple values, they will appear as elements of the `data` list: + +```bash +event: complete +data: ["Good morning Hello. It is 5 degrees today", -15.0] +``` + +**Streaming Example** + +If your Gradio app [streams a sequence of values](/guides/streaming-outputs), then they will be streamed directly to your terminal, like this: + +```bash +event: generating +data: ["Hello, w!"] +event: generating +data: ["Hello, wo!"] +event: generating +data: ["Hello, wor!"] +event: generating +data: ["Hello, worl!"] +event: generating +data: ["Hello, world!"] +event: complete +data: ["Hello, world!"] +``` + +**File Example** + +If your Gradio app returns a file, the file will be represented as a dictionary in this format (including potentially some additional keys): + +```python +{ + "orig_name": "example.jpg", + "path": "/path/in/server.jpg", + "url": "https:/example.com/example.jpg", + "meta": {"_type": "gradio.FileData"} +} +``` + +In your terminal, it may appear like this: + +```bash +event: complete +data: [{"path": "/tmp/gradio/359933dc8d6cfe1b022f35e2c639e6e42c97a003/image.webp", "url": "https://gradio-image-mod.hf.space/c/file=/tmp/gradio/359933dc8d6cfe1b022f35e2c639e6e42c97a003/image.webp", "size": null, "orig_name": "image.webp", "mime_type": null, "is_stream": false, "meta": {"_type": "gradio.FileData"}}] +``` \ No newline at end of file diff --git a/guides/08_gradio-clients-and-lite/03_fastapi-app-with-the-gradio-client.md b/guides/08_gradio-clients-and-lite/07_fastapi-app-with-the-gradio-client.md similarity index 100% rename from guides/08_gradio-clients-and-lite/03_fastapi-app-with-the-gradio-client.md rename to guides/08_gradio-clients-and-lite/07_fastapi-app-with-the-gradio-client.md diff --git a/js/app/src/api_docs/ApiBanner.svelte b/js/app/src/api_docs/ApiBanner.svelte index 9507ea678dc2f..1aa27a9686c32 100644 --- a/js/app/src/api_docs/ApiBanner.svelte +++ b/js/app/src/api_docs/ApiBanner.svelte @@ -6,6 +6,7 @@ export let root: string; export let api_count: number; + export let current_language: "python" | "javascript" | "bash"; const dispatch = createEventDispatcher(); @@ -21,13 +22,15 @@ {api_count} API endpoint{#if api_count > 1}s{/if}
- + {#if current_language !== "bash"} + + {/if} diff --git a/js/app/src/api_docs/ApiDocs.svelte b/js/app/src/api_docs/ApiDocs.svelte index 816245e1978bb..cfcffe40671f3 100644 --- a/js/app/src/api_docs/ApiDocs.svelte +++ b/js/app/src/api_docs/ApiDocs.svelte @@ -15,6 +15,7 @@ import python from "./img/python.svg"; import javascript from "./img/javascript.svg"; + import bash from "./img/bash.svg"; import ResponseSnippet from "./ResponseSnippet.svelte"; export let dependencies: Dependency[]; @@ -40,11 +41,12 @@ } export let api_calls: Payload[] = []; - let current_language: "python" | "javascript" = "python"; + let current_language: "python" | "javascript" | "bash" = "python"; const langs = [ ["python", python], - ["javascript", javascript] + ["javascript", javascript], + ["bash", bash] ] as const; let is_running = false; @@ -93,17 +95,19 @@ {#if info} {#if api_count}
-

- Use the gradio_client - Python library or the - @gradio/client - Javascript package to query the app - via API. +

+ Choose a language to see the code snippets for interacting with the + API.

@@ -119,7 +123,7 @@ {/each}
- {#if api_calls.length} + {#if api_calls.length && current_language !== "bash"}

{:else}

- 1. Install the client if you don't already have it installed. + {#if current_language == "python" || current_language == "javascript"} + 1. Install the {current_language} client if you don't already have it installed. + {:else} + 1. Confirm that you have cURL installed on your system. + {/if}

@@ -168,15 +178,24 @@ spaces_docs_suffix} class="underline" target="_blank">read more).{/if} Or - - to automatically generate your API requests. + >).{/if} + {#if current_language == "bash"}Note: making a prediction and + getting a result requires 2 requests: a + POST + and a GET request. The POST request + returns an EVENT_ID, which is used in the second + GET request to fetch the results. + {:else}Or + + to automatically generate your API requests. + {/if} {#each endpoint_parameters as { python_type, example_input, parameter_name, parameter_has_default, parameter_default }, i} -const client = await Client.connect("{root}"); +const client = await Client.connect("{space_id || root}"); const result = await client.predict({#if named}"/{dependency.api_name}"{:else}{dependency_index}{/if}, { {:else} - {parameter_name}: {represent_value( example_input, python_type.type, @@ -119,9 +128,39 @@ const result = await client.predict({#if named}
- {/if} - - + + + {:else if current_language === "bash"} + + +
+ +
+ +
+ 
curl -X POST {root}call/{dependency.api_name} -H "Content-Type: application/json" -d '{"{"}
+  "data": [{#each endpoint_parameters as { label, parameter_name, type, python_type, component, example_input, serializer }, i}
+    {represent_value(example_input, python_type.type, "bash")}{#if i < endpoint_parameters.length - 1},
+							{/if}
+						{/each}
+]{"}"}'
+
+ + + + + +
+ +
+ +
+ 
curl -N {root}call/{dependency.api_name}/$EVENT_ID
+
+ + + {/if}
+ + + + \ No newline at end of file diff --git a/js/app/src/api_docs/utils.ts b/js/app/src/api_docs/utils.ts index df29787da8892..155a14d659bc7 100644 --- a/js/app/src/api_docs/utils.ts +++ b/js/app/src/api_docs/utils.ts @@ -2,7 +2,7 @@ export function represent_value( value: string, type: string | undefined, - lang: "js" | "py" | null = null + lang: "js" | "py" | "bash" | null = null ): string | null | number | boolean | Record { if (type === undefined) { return lang === "py" ? "None" : null; @@ -18,7 +18,7 @@ export function represent_value( if (lang === "py") { value = String(value); return value === "true" ? "True" : "False"; - } else if (lang === "js") { + } else if (lang === "js" || lang === "bash") { return value; } return value === "true"; @@ -38,6 +38,9 @@ export function represent_value( } return value; } + if (lang === "bash") { + value = simplify_file_data(value); + } if (lang === "py") { value = replace_file_data_with_file_function(value); } @@ -69,6 +72,31 @@ export function is_potentially_nested_file_data(obj: any): boolean { return false; } +function simplify_file_data(obj: any): any { + if (typeof obj === "object" && obj !== null && !Array.isArray(obj)) { + if ( + "url" in obj && + obj.url && + "meta" in obj && + obj.meta?._type === "gradio.FileData" + ) { + return { path: obj.url }; + } + } + if (Array.isArray(obj)) { + obj.forEach((item, index) => { + if (typeof item === "object" && item !== null) { + obj[index] = simplify_file_data(item); // Recurse and update array elements + } + }); + } else if (typeof obj === "object" && obj !== null) { + Object.keys(obj).forEach((key) => { + obj[key] = simplify_file_data(obj[key]); // Recurse and update object properties + }); + } + return obj; +} + function replace_file_data_with_file_function(obj: any): any { if (typeof obj === "object" && obj !== null && !Array.isArray(obj)) { if (