HUGGINGFACE_DEBUG.md

🔍 Debugging Hugging Face Spaces Deployment

Częste Problemy i Rozwiązania

Problem 1: Runtime Error - Exit code: 0

Objawy:

Container logs:
===== Application Startup at 2025-12-13 12:09:26 =====
2025-12-13 13:09:40.467 | INFO | __main__:<module>:161 - 🚀 Starting Gradio app...
[aplikacja się zawiesza]

Przyczyny:

1. Podwójny start aplikacji - HF Spaces uruchamia aplikację dwukrotnie podczas budowy kontenera
2. Blokada na połączeniu z bazą danych - Próba zapisu do LanceDB bez uprawnień
3. Brak API key - Walidacja konfiguracji blokuje inicjalizację
4. Timeout - Inicjalizacja trwa zbyt długo (>60s)

Rozwiązania zastosowane w projekcie:

1. Leniwą inicjalizację połączenia z bazą

# ❌ PRZED - blokujące połączenie
vector_store = VectorStoreClient(uri="./lancedb")
vector_store.connect()  # Blokuje na HF Spaces!

# ✅ PO - leniwe połączenie
vector_store = VectorStoreClient(uri="./lancedb")
# Połączenie następuje przy pierwszym użyciu

2. Warunkową walidację API key

@field_validator("openai_api_key")
@classmethod
def validate_api_key(cls, v):
    v = v or ""
    v = v.strip()
    if not v:
        # Nie rzucaj błędu na HF Spaces
        if not os.getenv("SPACE_ID"):
            raise ValueError("OPENAI_API_KEY is required")
    return v

3. Background thread initialization

def initialize_agent_background():
    """Inicjalizacja agenta w tle bez blokowania startu UI."""
    global agent_instance, agent_ready, agent_error
    
    try:
        logger.info("🔄 Starting agent initialization in background...")
        time.sleep(2)  # Unikaj race condition
        agent_instance = create_agent()
        agent_ready = True
        logger.success("✅ A11y Expert Agent is ready!")
    except Exception as e:
        logger.error(f"❌ Failed to initialize agent: {e}")
        agent_error = str(e)
        agent_instance = None

# Start w osobnym wątku (daemon)
init_thread = threading.Thread(target=initialize_agent_background, daemon=True)
init_thread.start()

4. Bezpieczne tworzenie katalogów

@property
def db(self):
    if self._db is None:
        try:
            os.makedirs(self.uri, exist_ok=True)
        except Exception as e:
            logger.warning(f"Could not create directory: {e}")
        
        self._db = lancedb.connect(self.uri)
    return self._db

Problem 2: Aplikacja startuje ale nie odpowiada

Przyczyna: Agent nie zainicjalizował się w tle

Rozwiązanie:

• Sprawdź logi w HF Spaces - szukaj ✅ A11y Expert Agent is ready!
• Jeśli brak, sprawdź czy nie ma błędu inicjalizacji
• Aplikacja pokazuje status inicjalizacji w interfejsie

Problem 3: Brak dostępu do bazy danych

Przyczyna: Katalog lancedb/ nie jest w repozytorium lub nie jest śledzony przez Git LFS

Rozwiązanie:

# Sprawdź czy lancedb jest w repo
git lfs ls-files | grep lancedb

# Jeśli nie, dodaj do LFS
git lfs track "lancedb/**"
git add .gitattributes lancedb/
git commit -m "Add LanceDB to LFS"
git push

Problem 4: API Key nie jest ustawiony

Objawy:

❌ Failed to initialize agent: OPENAI_API_KEY is required

Rozwiązanie:

1. Idź do ustawień swojego Space
2. Wybierz zakładkę Settings → Repository secrets
3. Dodaj secret OPENAI_API_KEY z wartością twojego klucza
4. Zrestartuj Space

Testowanie lokalne przed wdrożeniem

# Test wszystkich komponentów
python test_startup.py

# Test aplikacji Gradio
python app.py

Sprawdzanie logów na HF Spaces

1. Podczas budowy:

   • Kliknij na swój Space
   • Przejdź do zakładki Logs
   • Szukaj błędów podczas Building i Running

2. Podczas działania:

   • Logi są na żywo w zakładce Logs
   • Szukaj komunikatów ERROR lub stacktrace'ów

Debugowanie z kodem

Dodaj więcej logowania:

import traceback
try:
    # twój kod
except Exception as e:
    logger.error(f"Error: {e}")
    logger.error(traceback.format_exc())

Sprawdź zmienne środowiskowe:

import os
logger.info(f"SPACE_ID: {os.getenv('SPACE_ID')}")
logger.info(f"HF environment: {os.getenv('SYSTEM')}")

Checklist przed wdrożeniem

• python test_startup.py przechodzi bez błędów
• Baza danych lancedb/ jest w repo i śledzona przez Git LFS
• Secret OPENAI_API_KEY jest ustawiony w HF Spaces
• README.md ma prawidłową konfigurację YAML na górze
• .gitignore nie blokuje ważnych plików
• requirements.txt zawiera wszystkie zależności

Przydatne komendy

# Sprawdź rozmiar bazy danych
du -sh lancedb/

# Sprawdź pliki LFS
git lfs ls-files

# Wymuś rebuild Space na HF
# (w ustawieniach Space → Factory reboot)

Kontakt i Wsparcie

Jeśli nadal masz problemy:

1. Sprawdź pełne logi w zakładce Logs na HF Spaces
2. Porównaj z working example na https://huggingface.co/spaces/jacekAI/a11y-expert
3. Otwórz issue w repozytorium z pełnymi logami