pocro

Przewodnik rozwiązywania problemów

Ten przewodnik zawiera rozwiązania typowych problemów, z którymi możesz się spotkać podczas korzystania z systemu do przetwarzania faktur.

Problemy ze środowiskiem i konfiguracją

Problem z ładowaniem modelu

Objawy: Aplikacja nie uruchamia się, wyświetlając błędy związane z ładowaniem modelu lub “None is not a valid model”.

Rozwiązanie:

1. Sprawdź, czy plik .env istnieje i zawiera poprawny MODEL_NAME:

   cat .env | grep MODEL_NAME
   

2. Upewnij się, że nazwa modelu jest poprawnym identyfikatorem modelu z Hugging Face (np. facebook/opt-125m)
3. Dla modeli prywatnych upewnij się, że jesteś uwierzytelniony:

   huggingface-cli login
   

4. Sprawdź logi aplikacji pod kątem szczegółowych informacji o błędach

Zmienne środowiskowe nie są ładowane

Objawy: Zmiany w pliku .env nie są uwzględniane.

Rozwiązanie:

1. Upewnij się, że plik .env znajduje się w katalogu głównym projektu
2. Sprawdź, czy nazwy zmiennych są zapisane WIELKIMI_LITERAMI
3. Uruchom ponownie aplikację po wprowadzeniu zmian
4. Sprawdź literówki w nazwach zmiennych
5. Upewnij się, że nie ma błędów składniowych w pliku .env

Problemy z CUDA/GPU

Objawy: Błędy związane z CUDA lub komunikaty o przejściu na tryb CPU.

Rozwiązanie:

1. Sprawdź, czy CUDA jest zainstalowane:

   nvidia-smi  # Powinien wyświetlić informacje o karcie graficznej
   nvcc --version  # Powinien wyświetlić wersję CUDA
   

2. Sprawdź zgodność PyTorch z CUDA:

   import torch
   print(torch.cuda.is_available())  # Powinno zwrócić True
   print(torch.version.cuda)  # Powinno pasować do wersji CUDA
   

3. Spróbuj ustawić CUDA_VISIBLE_DEVICES w pliku .env:

   CUDA_VISIBLE_DEVICES=0
   

4. Jeśli używasz Dockera, upewnij się, że kontener ma dostęp do GPU:

   docker run --gpus all ...
   

Problemy z API

Port jest już w użyciu

Objawy: Błąd informujący, że port 8088 (lub inny skonfigurowany port) jest już używany.

Rozwiązanie:

1. Zmień port w pliku .env:

   PORT=8080
   

2. Lub znajdź i zakończ proces używający portu:

   # Linux/macOS
   sudo lsof -i :8088
   kill -9 <PID>
      
   # Windows
   netstat -ano | findstr :8088
   taskkill /PID <PID> /F
   

3. Sprawdź, czy inna instancja aplikacji nie jest już uruchomiona

Błędy CORS

Objawy: W konsoli przeglądarki pojawiają się błędy CORS przy wykonywaniu żądań do API.

Rozwiązanie:

1. Upewnij się, że adres URL frontendu znajduje się na liście CORS_ORIGINS w pliku .env:

   CORS_ORIGINS=http://localhost:3000,http://localhost:8080
   

2. W środowisku deweloperskim możesz zezwolić na wszystkie źródła (niezalecane w produkcji):

   CORS_ORIGINS=*
   

3. Sprawdź, czy nagłówki CORS są prawidłowo ustawione w odpowiedziach serwera

Problemy z wydajnością

Wolne działanie aplikacji

Objawy: Aplikacja działa zbyt wolno.

Rozwiązanie:

1. Sprawdź wykorzystanie GPU:

   watch -n 1 nvidia-smi  # Monitoruj wykorzystanie GPU co sekundę
   

2. Spróbuj użyć mniejszego modelu lub włącz kwantyzację w pliku .env:

   QUANTIZATION=awq  # lub nf4 dla nowszych kart
   

3. Zwiększ rozmiar wsadu (batch size) przy przetwarzaniu wielu dokumentów:

   BATCH_SIZE=8
   

4. Sprawdź, czy aplikacja korzysta z GPU zamiast CPU
5. Zoptymalizuj rozmiar obrazów przed przetwarzaniem OCR

Wysokie zużycie pamięci

Objawy: Aplikacja ulega awarii z powodu braku pamięci.

Rozwiązanie:

1. Zmniejsz wykorzystanie pamięci GPU w pliku .env:

   GPU_MEMORY_UTILIZATION=0.8
   

2. Użyj mniejszego modelu
3. Włącz sprawdzanie gradientu (gradient checkpointing) jeśli trenujesz model:

   GRADIENT_CHECKPOINTING=True
   

4. Ogranicz rozmiar przetwarzanych danych jednorazowo
5. Sprawdź wycieki pamięci w kodzie

Debugowanie

Włączanie szczegółowych logów

Ustaw poziom logowania w pliku .env:

LOG_LEVEL=DEBUG

Sprawdzanie logów

Domyślnie logi są zapisywane w pliku logs/app.log. Sprawdź je w poszukiwaniu szczegółowych komunikatów o błędach.

Najczęstsze komunikaty błędów

“No module named ‘transformers’”

Zainstaluj wymagane pakiety:

poetry install

“CUDA out of memory”

1. Zmniejsz rozmiar wsadu (batch size)
2. Użyj mniejszego modelu
3. Włącz zarządzanie pamięcią CUDA w pliku .env:

   GPU_MEMORY_UTILIZATION=0.8
   

4. Spróbuj włączyć kwantyzację:

   QUANTIZATION=awq
   

“ConnectionError: Couldn’t reach server”

1. Sprawdź połączenie z internetem
2. Upewnij się, że masz dostęp do Hugging Face Hub
3. Sprawdź ustawienia proxy, jeśli korzystasz z niego w sieci firmowej

“Error loading shared libraries: libcuda.so.1”

1. Upewnij się, że sterowniki NVIDIA są poprawnie zainstalowane
2. Sprawdź, czy ścieżka do bibliotek CUDA jest dodana do zmiennej środowiskowej LD_LIBRARY_PATH

Uzyskiwanie pomocy

Jeśli wypróbowałeś powyższe rozwiązania i nadal występują problemy:

1. Sprawdź zgłoszenia na GitHubie pod kątem podobnych problemów
2. Przy zgłaszaniu błędu uwzględnij:
   • Zawartość pliku .env (z usuniętymi danymi wrażliwymi)
   • Pełny komunikat błędu i stos wywołań (stack trace)
   • Kroki prowadzące do odtworzenia problemu
   • Informacje o środowisku (system operacyjny, wersja Pythona, wersja CUDA jeśli używane jest GPU)
   • Logi aplikacji

Przydatne komendy

Sprawdzanie wersji Pythona i pakietów

python --version
poetry show

Czyszczenie pamięci podręcznej PyTorch

# Usuwa załadowane modele z pamięci podręcznej
torch.cuda.empty_cache()

Sprawdzanie wykorzystania dysku przez modele

du -sh ~/.cache/huggingface/hub/
du -sh ~/.cache/torch/

Resetowanie środowiska

# Usuń środowisko wirtualne i zainstaluj ponownie
rm -rf .venv
python -m venv .venv
source .venv/bin/activate
poetry install

Aktualizacja zależności

# Zaktualizuj wszystkie zależności do najnowszych wersji
poetry update

Wsparcie

W razie pytań lub problemów, skontaktuj się z zespołem wsparcia lub utwórz nowe zgłoszenie w repozytorium projektu.

This site is open source. Improve this page.