Spaces:
Sleeping
Sleeping
|
Download docs/05_debugging_common_problems.md from UWRFR/UWaterlooRFRChatBot: direct link, hf CLI and curl.
- Browser
- Download file 4.68 kB
-
https://huggingface.co/spaces/UWRFR/UWaterlooRFRChatBot/resolve/main/docs/05_debugging_common_problems.md
- Command line
-
hf download hf://spaces/UWRFR/UWaterlooRFRChatBot/docs/05_debugging_common_problems.md
-
curl -L -o 05_debugging_common_problems.md https://huggingface.co/spaces/UWRFR/UWaterlooRFRChatBot/resolve/main/docs/05_debugging_common_problems.md
4.68 kB
| # 05 - Debugging Common Problems | |
| This guide lists common failures and what to check first. | |
| ## The Website Does Not Load | |
| Check Hugging Face logs: | |
| ```text | |
| Hugging Face Space -> Logs | |
| ``` | |
| Common causes: | |
| - Build failed. | |
| - Missing dependency in `requirements.txt`. | |
| - Python syntax error. | |
| - Missing required file. | |
| - Space is still rebuilding. | |
| CLI check: | |
| ```bash | |
| hf spaces info UWRFR/UWaterlooRFRChatBot | |
| ``` | |
| If the Space is building, wait and refresh. | |
| ## Ask Tab Fails with an LLM Error | |
| Common messages: | |
| ```text | |
| credit balance is too low | |
| ANTHROPIC_API_KEY is not set | |
| OPENAI_API_KEY is not set | |
| APIConnectionError | |
| invalid_api_key | |
| ``` | |
| Check: | |
| - The correct key exists in Hugging Face secrets. | |
| - The key has credits. | |
| - The app is configured for the provider you expect. | |
| - The Space was restarted after changing secrets. | |
| If Anthropic credits are unavailable, switch the app to OpenAI only if | |
| `OPENAI_API_KEY` is available and configured. | |
| ## New Case Study Request Upload Fails | |
| The request tab uploads to Google Drive using: | |
| ```text | |
| GOOGLE_OAUTH_CLIENT_ID | |
| GOOGLE_OAUTH_CLIENT_SECRET | |
| GOOGLE_OAUTH_REFRESH_TOKEN | |
| ``` | |
| Check: | |
| - The three OAuth secrets exist in Hugging Face. | |
| - The refresh token was generated by signing in as the Google account that | |
| should own uploaded request folders, usually `rfr.rag.uwaterloo@gmail.com`. | |
| - The intake folder is owned by or shared with that Google account. | |
| - The intake folder ID is correct: | |
| ```text | |
| 10n_-uOCT2GXu_G3r1qi5qJr8hHoy-E_y | |
| ``` | |
| If using a different folder, set: | |
| ```text | |
| RFR_REQUESTS_DRIVE_FOLDER_ID | |
| ``` | |
| If the error says service accounts do not have storage quota, the app is falling | |
| back to `GOOGLE_SERVICE_ACCOUNT_JSON`. Add the OAuth secrets above, or move the | |
| intake folder to a Google Shared Drive. | |
| ## New Case Does Not Appear in Case Studies | |
| Usually one of these files was not rebuilt or committed: | |
| ```text | |
| data/extracted/CSxx.json | |
| data/extracted/case_summaries.json | |
| data/extracted/precomputed_embeddings.json | |
| ``` | |
| Run: | |
| ```bash | |
| python3 ingest/ingest_pipeline_outputs.py --case-id CSxx | |
| python3 ingest/create_summary_chunks.py | |
| python3 ingest/embed_and_index.py | |
| ``` | |
| Then commit and push the changed files. | |
| ## Case Appears but Sources Are Missing | |
| The Case Studies tab reads source links from each case's `source_links` field in | |
| `data/extracted/CSxx.json`. | |
| Source links come from: | |
| - `sources.txt` | |
| - `sources.json` | |
| - `dois.txt` | |
| - `ingest/source_link_overrides.json` | |
| Fix: | |
| 1. Add APA-style links to `ingest/source_link_overrides.json`. | |
| 2. Re-run: | |
| ```bash | |
| python3 ingest/ingest_pipeline_outputs.py --case-id CSxx --force | |
| python3 ingest/create_summary_chunks.py | |
| python3 ingest/embed_and_index.py | |
| ``` | |
| 3. Commit and push. | |
| ## Case Summary Looks Wrong | |
| Check the canonical Ver2 memo: | |
| ```text | |
| data/raw/CSxx/pipeline_output/CSxx_Ver2.md | |
| ``` | |
| If the wrong paper was processed, replace the source files in: | |
| ```text | |
| data/raw/CSxx/ | |
| ``` | |
| Then rerun: | |
| ```bash | |
| python3 -m case_study_pipeline.run_case_study \ | |
| --case-folder data/raw/CSxx \ | |
| --case-id CSxx \ | |
| --llm-provider claude \ | |
| --max-chars-per-source 150000 \ | |
| --force | |
| ``` | |
| Then select, ingest, summarize, and embed: | |
| ```bash | |
| python3 -m case_study_pipeline.select_best_run --case-id CSxx | |
| python3 ingest/ingest_pipeline_outputs.py --case-id CSxx --force | |
| python3 ingest/create_summary_chunks.py | |
| python3 ingest/embed_and_index.py | |
| ``` | |
| ## Hugging Face Shows Old Content | |
| Check the deployed commit: | |
| ```bash | |
| hf spaces info UWRFR/UWaterlooRFRChatBot | |
| ``` | |
| Compare the `sha` with: | |
| ```bash | |
| git log --oneline -5 | |
| ``` | |
| If the Hugging Face SHA is old, push again: | |
| ```bash | |
| git push uwrfr-chatbot HEAD:main | |
| ``` | |
| ## Git Push Fails | |
| Check remotes: | |
| ```bash | |
| git remote -v | |
| ``` | |
| Expected remotes: | |
| ```text | |
| shared-github https://github.com/rfrraguwaterloo-cmyk/UWaterlooManagedRetreatChatbot.git | |
| uwrfr-chatbot https://huggingface.co/spaces/UWRFR/UWaterlooRFRChatBot | |
| ``` | |
| If authentication fails: | |
| - For GitHub, sign in with GitHub credentials or a GitHub token. | |
| - For Hugging Face, run: | |
| ```bash | |
| hf auth login --add-to-git-credential | |
| ``` | |
| Use a Hugging Face token with write access to the Space. | |
| ## Drive Pipeline Output Upload Fails | |
| The extraction pipeline can still run locally even if Drive output uploads fail. | |
| Common warning: | |
| ```text | |
| [Drive] Warning: could not initialize uploader | |
| Drive uploads will be skipped for this run. | |
| ``` | |
| This means the local files were created, but the PDF outputs were not uploaded | |
| to Drive. | |
| Check: | |
| - `GOOGLE_CREDENTIALS_FILE` points to an OAuth client credential file. | |
| - Your browser completed Google login. | |
| - The target case folder exists in `case_study_pipeline/drive_folders.json`. | |
| - The Google account has permission to write to the Drive folder. | |