| # Deploy the Document Q&A App to Hugging Face Spaces |
|
|
| This guide accompanies the 29 October 2026 manual RAG lesson. It uses the existing app and public teaching dataset loaded directly from Hugging Face. You do not need to build another app. |
|
|
| ## 1. Check account eligibility |
|
|
| Sign in at https://huggingface.co/. The standard route below uses a **Gradio Space on CPU Basic**. Hugging Face currently documents a subscription requirement for this combination: PRO for a personal account, or Team/Enterprise for an organization. CPU Basic itself has no hourly hardware charge. Model inference runs inside the Space and does not require a paid inference API or an HF_TOKEN. |
| |
| The overview also documents a limited ZeroGPU exception for eligible free personal accounts. That is a different hardware route. This package targets standard CPU Basic and does not claim to qualify for the exception. If creation is blocked by a payment or eligibility message, review the current account options. You can continue the lesson in Colab or locally without purchasing a hosting plan. |
| |
| ## 2. Extract the deployment ZIP |
| |
| Download and extract **Document_QA_Hugging_Face_Space.zip** on your computer. It contains these files directly at the top level: |
| |
| | File | Purpose | |
| |---|---| |
| | app.py | Gradio interface and web server startup | |
| | rag_core.py | Manual retrieval and answer generation | |
| | requirements.txt | Python dependencies, including a Linux CPU PyTorch wheel | |
| | README.md | Space configuration at the top, then app documentation | |
| | DATA_ATTRIBUTION.md | Dataset and Wikipedia attribution | |
| | Data_Provenance.md | Dataset revision and sampling provenance | |
| | Hugging_Face_Deployment_Guide.md | These deployment instructions | |
| |
| The app downloads its 30 selected SQuAD passages from Hugging Face when it starts. No passage JSON or other local data file is needed. Upload these files, not the ZIP itself. Do not add an enclosing folder around app.py. Do not upload model weights, your virtual environment, tokens, or the full class-materials archive. |
| |
| ## 3. Create the Space |
| |
| 1. Open https://huggingface.co/new-space. |
| 2. Choose the owner account or organization and a name such as `document-qa-manual-rag`. |
| 3. Select **Gradio** as the SDK. Use a blank Gradio starting point if the screen offers a template choice. |
| 4. Choose **CPU Basic** for this package. It does not need a GPU. Confirm the plan and hardware terms shown for your account. |
| 5. Choose the visibility you want. A public Space shares its app and source code. For a class demonstration, this bundle contains public sample text. A private Space is suitable for checking it before you decide to share it. |
| 6. Create the Space. |
| |
| ## 4. Upload and commit the app files |
| |
| 1. Open the Space's **Files** tab (sometimes labelled Files and versions). |
| 2. Choose **Add file > Upload files**. |
| 3. Select all seven extracted files. Put them at the repository root. |
| 4. Replace the starter README.md with the supplied README.md. Keep the YAML configuration at the very top, including the opening and closing `---` lines. |
| 5. Commit the upload. The Space should start building automatically. |
| |
| The YAML selects Python 3.12, Gradio 6.31.0, and app.py as the entry point. requirements.txt installs the model libraries. suggested_hardware is only a suggestion, so the hardware choice in the creation screen or Settings still matters. |
|
|
| ## 5. Wait for the build and first model load |
|
|
| Use the Space's status and **Logs** to follow progress. Build logs show package installation. Runtime logs show the Python app and model-loading messages. Wait for the app to become available. |
|
|
| The app loads the embedding model, streams the pinned SQuAD dataset from the Hub, selects 30 passages, and creates embeddings at startup. The first generated answer also downloads and loads FLAN-T5-small. Leave time for this before class. No secret or API key is required for either public model. |
|
|
| The launch code listens on 0.0.0.0, uses port 7860 by default, and sets share=False. Hugging Face hosts the app directly, so a temporary Gradio share link is unnecessary. The queue permits one model call at a time with up to 20 waiting requests. |
|
|
| ## 6. Check the deployed app |
|
|
| 1. Ask **Which company produces the iPod?** The answer should identify Apple, and the evidence should show the source passages. Check the exact text rather than treating this as a guaranteed output. |
| 2. Select **Retrieval only** and ask the same question. The app should explicitly report that it generated no answer. |
| 3. Submit an empty question. The app should ask for a question. |
| 4. Ask **What is the live price of Bitcoin in Nigerian naira right now?** Inspect whether the app acknowledges missing evidence. |
| 5. Run the remaining class evaluation questions. The small model can fail, including on missing details. Record actual results. |
| 6. Open the Space URL from another browser or device to check the access level you selected. |
|
|
| Share the real URL shown for your created Space. This package has been checked locally. It has not been deployed to your Hugging Face account and contains no invented live app URL. |
|
|
| ## Troubleshooting |
|
|
| | Symptom | What to check | |
| |---|---| |
| | Creation fails with a payment/eligibility message | Check the current plan requirement for the owner account and selected hardware. | |
| | App file not found | app.py must be at the repository root and match app_file in README.md. | |
| | ModuleNotFoundError | Upload requirements.txt, inspect the build logs, and restart the build after fixing it. | |
| | Dataset download fails | Check runtime logs, Hub access, the pinned revision, and the datasets dependency. No local data-file upload is needed. | |
| | Dependency installation fails | Preserve the supplied version pins. They target Linux and Python 3.12. Read the first error in the build log. | |
| | App starts, but first answer is slow | The generation model downloads on first use. Wait, then try again. | |
| | Model download fails | Check runtime logs and Hub availability. Try retrieval-only mode if the dataset and embeddings loaded. | |
| | Queue full | Wait for current requests to finish. This small CPU demo serializes model calls. | |
| | Space needs to wake up | CPU Basic Spaces may sleep after inactivity. Open it before class. | |
| | A confident answer is wrong | Inspect the evidence and use the evaluation worksheet. Hosting does not fix model limitations. | |
| |
| ## Updating your Space |
| |
| Edit the relevant file in the Files tab and commit the change, or upload a replacement file. Space commits trigger an automatic rebuild/restart. Preserve source IDs and attribution when changing the dataset-selection rules. Rebuild embeddings after source changes. |
| |
| ## Official references |
| |
| Checked 29 October 2026: |
| - Spaces overview and eligibility: https://huggingface.co/docs/hub/spaces-overview |
| - CPU Basic subscription requirement: https://huggingface.co/docs/huggingface_hub/guides/manage-spaces |
| - README configuration: https://huggingface.co/docs/hub/spaces-config-reference |
| - Dependencies: https://huggingface.co/docs/hub/spaces-dependencies |
| - Gradio queue: https://www.gradio.app/guides/queuing |
|
|
