pocro

Instrukcja instalacji

Ten przewodnik przeprowadzi Cię przez proces konfiguracji systemu do przetwarzania faktur z wykorzystaniem OCR i LLM.

Spis treści

Wymagania wstępne
Szybki start
Instalacja krok po kroku
Konfiguracja
Weryfikacja instalacji
Rozwiązywanie problemów
Dodatkowe zasoby

Uwaga: W razie problemów z instalacją, zapoznaj się z przewodnikiem rozwiązywania problemów.

Wymagania wstępne

Python 3.10+
pip (menedżer pakietów Pythona)
(Opcjonalnie) Karta graficzna z obsługą CUDA dla lepszej wydajności
(Opcjonalnie) Docker i Docker Compose do uruchomienia w kontenerze
(Opcjonalnie) Połączenie z internetem do pobrania modeli

Szybki start

Sklonuj repozytorium

git clone git@github.com:fin-officer/pocro.git
cd pocro

Skonfiguruj środowisko

# Skopiuj przykładowy plik środowiskowy
cp .env.example .env

Zmodyfikuj plik .env zgodnie ze swoimi potrzebami. Minimalna konfiguracja:

MODEL_NAME=facebook/opt-125m  # lub inny preferowany model
OCR_ENGINE=easyocr  # lub paddleocr
LOG_LEVEL=INFO

Zainstaluj zależności

# Utwórz i aktywuj środowisko wirtualne (zalecane)
python -m venv .venv
source .venv/bin/activate  # Na Windows: .venv\Scripts\activate

# Zainstaluj zależności za pomocą Poetry
poetry install  # Dla środowiska developerskiego
# lub
poetry install --no-dev  # Tylko zależności produkcyjne

Uruchom aplikację

make run  # Używa Uvicorn z automatycznym przeładowaniem
# lub ręcznie:
# uvicorn src.main:app --host 0.0.0.0 --port 8088 --reload

API będzie dostępne pod adresem: http://localhost:8088

Sprawdź działanie:

curl http://localhost:8088/health

Konfiguracja

Zmienne środowiskowe

Kluczowe opcje konfiguracyjne w pliku .env:

Konfiguracja modelu LLM

MODEL_NAME - Nazwa modelu z Hugging Face (np. facebook/opt-125m)
QUANTIZATION - Metoda kwantyzacji modelu (domyślnie: awq)
MAX_MODEL_LENGTH - Maksymalna długość generowanego tekstu (domyślnie: 2048)
TEMPERATURE - Parametr temperatury generowania

Przetwarzanie faktur

Aby przetworzyć fakturę, użyj komendy pocro:

# Przetwarzanie pojedynczej faktury
pocro process ścieżka/do/faktura.pdf

# Z określonym plikiem wyjściowym
pocro process ścieżka/do/faktura.pdf --output wynik.json

# Wyświetlenie pomocy
pocro --help
pocro process --help

Dostępne opcje dla komendy process:

--output, -o: Określa plik wyjściowy (domyślnie: <nazwa_pliku_wejsciowego>.json)
--format, -f: Format wyjściowy (json lub csv, domyślnie: json)

Konfiguracja serwera

HOST - Adres, na którym ma działać serwer (domyślnie: 0.0.0.0)
PORT - Port serwera (domyślnie: 8088)
DEBUG - Tryb debugowania (domyślnie: False)
LOG_LEVEL - Poziom logowania (DEBUG, INFO, WARNING, ERROR)
CACHE_DIR - Katalog na cache modeli (domyślnie: ./.cache)

Przykładowa konfiguracja

# Konfiguracja modelu
MODEL_NAME=facebook/opt-125m
QUANTIZATION=awq
MAX_MODEL_LENGTH=2048

# Konfiguracja OCR
OCR_ENGINE=easyocr
OCR_LANGUAGES=pl,en,de

# Konfiguracja serwera
HOST=0.0.0.0
PORT=8088
DEBUG=False
LOG_LEVEL=INFO
CACHE_DIR=./.cache

Instalacja z Dockerem

Zbuduj obraz Dockera

make docker-build

lub ręcznie:

docker build -t pocro .

Uruchom kontener

make docker-run

lub ręcznie:

docker run -d --name pocro -p 8088:8088 --env-file .env pocro

Zatrzymaj kontener
```
make docker-stop
```

Weryfikacja instalacji

Sprawdź stan API
```
curl http://localhost:8088/health
```
Powinno zwrócić: {"status":"ok"}

Przetestuj rozpoznawanie faktury

curl -X POST http://localhost:8088/process \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "FV/2023/1234",
    "issue_date": "2023-05-15",
    "due_date": "2023-06-14",
    "total_amount": 1234.56,
    "currency": "PLN",
    "supplier": {
      "name": "Przykładowy Dostawca Sp. z o.o.",
      "tax_id": "1234567890"
    },
    "customer": {
      "name": "Klient Przykładowy",
      "tax_id": "0987654321"
    },
    "items": [
      {
        "description": "Usługa przykładowa",
        "quantity": 1,
        "unit_price": 1000.00,
        "tax_rate": 23,
        "amount": 1230.00
      }
    ]
  }'

Rozwiązywanie problemów

Typowe problemy i rozwiązania

Brak modułów Pythona

# Zainstaluj brakujące zależności
poetry install

Błąd ładowania modelu
- Sprawdź, czy MODEL_NAME w .env wskazuje na poprawny model
- Upewnij się, że masz dostęp do internetu do pobrania modelu
- Sprawdź uprawnienia do katalogu cache (domyślnie ~/.cache/)
Błędy CUDA
- Upewnij się, że masz zainstalowane odpowiednie sterowniki NVIDIA
- Sprawdź zgodność wersji CUDA z wymaganiami bibliotek
- Spróbuj wyłączyć akcelerację GPU ustawiając OCR_GPU=False
Port zajęty
- Zmień port w zmiennej PORT w pliku .env
- Sprawdź, czy inna aplikacja nie używa tego samego portu: lsof -i :8088

Problemy z zależnościami

# Wyczyść środowisko i zainstaluj ponownie
rm -rf .venv
python -m venv .venv
source .venv/bin/activate
poetry install

W przypadku dalszych problemów, zapoznaj się z przewodnikiem Rozwiązywanie problemów.

Następne kroki

This site is open source. Improve this page.