Generator altów AI dla Pythona: instalacja i konfiguracja

Pakiet dockaccess-alt-generator łączy aplikację w Pythonie z generatorem altów DockAccess. Daje synchronicznego i asynchronicznego klienta do dowolnego frameworka, polecenie dockaccess-alt do terminala i potoków CI oraz gotowe pomocniki dla FastAPI, Django i Flaska. Każdy obraz sprawdza i przebudowuje przed wysłaniem, a opisy zwraca jako czysty tekst. O tym, gdzie zapisać alt, decyduje Twoja aplikacja, która też wyświetla go w szablonach.

Wymagania

Potrzebujesz Pythona 3.10 lub nowszego, zweryfikowanego konta DockAccess i strony z włączonym generatorem altów; na początek wystarczy darmowy plan. pip instaluje dwie zależności: httpx i Pillow. Zdjęcia HEIC wymagają dodatku heif, a AVIF wymaga Pillow zbudowanego z obsługą AVIF.

Krok 1. Zainstaluj pakiet

pip install dockaccess-alt-generator
Skopiuj tekst

Dodatki doinstalowują to, czego potrzebuje dany pomocnik, jeśli projekt jeszcze tego nie ma: pip install "dockaccess-alt-generator[fastapi]", [django], [flask] albo [heif]. W uv lub Poetry użyj uv add dockaccess-alt-generator albo poetry add dockaccess-alt-generator. Pakiet importuje się jako dockaccess_alt.

Krok 2. Połącz aplikację

1. W DockAccess otwórz Moje strony, dodaj lub wybierz stronę, sprawdź jej domenę produkcyjną i włącz generator altów. Skopiuj token strony.
2. Uruchom poniższe polecenie w katalogu projektu. Podaj token strony, publiczny adres aplikacji oraz e-mail i hasło konta DockAccess. Hasło służy tylko do połączenia i nie jest zapisywane.

dockaccess-alt connect
dockaccess-alt status
Skopiuj tekst

Polecenie zapisuje DOCKACCESS_ALT_KEY, DOCKACCESS_ALT_SITE_TOKEN, DOCKACCESS_ALT_SECRET i DOCKACCESS_ALT_HOME_URL w pliku .env, który może czytać tylko jego właściciel. Wczytaj ten plik tak, jak projekt wczytuje konfigurację (python-dotenv, pydantic-settings, docker --env-file), albo przekaż env_file=".env" jak w przykładach poniżej. Przy menedżerze sekretów --show wypisuje wartości zamiast zapisywać plik; nie zostawiaj tego wyniku w publicznych logach.

Adres aplikacji musi być jedną z domen strony. Adres lokalny, na przykład http://localhost:8000, zadziała przy programowaniu, ale nie potwierdza domeny produkcyjnej: przed uruchomieniem produkcji połącz aplikację ponownie z adresem publicznym. W CI uruchom dockaccess-alt connect --no-input --token … --login … --url https://example.com z hasłem w zmiennej DOCKACCESS_PASSWORD. Opcji --overwrite używaj tylko wtedy, gdy świadomie zastępujesz istniejącą instalację; zmienia ona sekret połączenia. Połączona aplikacja pojawi się w DockAccess wśród integracji strony jako Python.

Krok 3. Wygeneruj pierwszy opis

from dockaccess_alt import AltGenerator

generator = AltGenerator.from_env(env_file=".env")

with open("media/products/plecak.jpg", "rb") as photo:
    result = generator.generate(
        photo,
        language="pl",
        tone="neutral",
        context="Strona produktu: plecak miejski, widok z przodu",
    )

alt = result.text
image_uuid = result.image_uuid
# Zapisz tekst, jego język i image_uuid przy właściwym obrazie w swojej bazie danych.
Skopiuj tekst

Utwórz jeden generator na proces i używaj go wielokrotnie; jest bezpieczny dla wątków. generate() przyjmuje bajty, otwarty plik binarny, obraz Pillow albo plik przesłany przez FastAPI, Django lub Flaska. Ścieżka nigdy nie jest czytana domyślnie: użyj ImageSource.from_path(path, within=MEDIA_ROOT), które odrzuca pliki spoza wskazanego katalogu, także te osiągnięte przez dowiązania symboliczne. language przyjmuje kody języków i ustawienia regionalne, na przykład pl_PL, context do 500 znaków, a variants od 1 do 3 propozycji. Zwracany tekst jest czystym tekstem; pozwól szablonowi zabezpieczyć go w atrybucie alt.

Krok 4. Użyj go w swoim frameworku

FastAPI (i inne frameworki asyncio): otwórz jeden asynchroniczny generator dla aplikacji i odbieraj go jako zależność.

from contextlib import asynccontextmanager

from fastapi import FastAPI, UploadFile
from dockaccess_alt import AltGeneratorError
from dockaccess_alt.fastapi import AltGeneratorDep, alt_generator_exception_handler, alt_generator_lifespan


@asynccontextmanager
async def lifespan(app: FastAPI):
    async with alt_generator_lifespan(app):
        yield


app = FastAPI(lifespan=lifespan)
app.add_exception_handler(AltGeneratorError, alt_generator_exception_handler)


@app.post("/products/{product_id}/photo")
async def upload_photo(product_id: int, photo: UploadFile, generator: AltGeneratorDep):
    result = await generator.generate(photo, language="pl")
    return {"alt": result.text}
Skopiuj tekst

Obsługa wyjątków odpowiada kodem 422 na odrzucony obraz, 429 na wyczerpany limit i 503 na niedostępny generator, bez ujawniania szczegółów konta. Obrazy są przetwarzane w osobnym wątku, więc nie blokują pętli zdarzeń.

Django: dodaj "dockaccess_alt.django" do INSTALLED_APPS, aby komunikaty walidacji były po polsku. Język wynika z LANGUAGE_CODE; opcjonalne ustawienia trafiają do DOCKACCESS_ALT, na przykład {"CONTEXT": "Sklep z meblami"}.

from dockaccess_alt.django import get_alt_generator
from dockaccess_alt.django.validators import validate_image


class Product(models.Model):
    photo = models.ImageField(upload_to="products/", validators=[validate_image])
    photo_alt = models.CharField(max_length=500, blank=True)


result = get_alt_generator().generate(product.photo, context=product.name)
product.photo_alt = result.text
product.save(update_fields=["photo_alt"])
Skopiuj tekst

Flask: DockAccessAlt(app) czyta DOCKACCESS_ALT_* z app.config albo ze zmiennych środowiskowych, a get_alt_generator().generate(request.files["photo"]) generuje opis w widoku. register_error_handler(app) dodaje te same odpowiedzi JSON z błędami co w FastAPI.

Krok 5. Generuj w tle i zbiorczo

Przy wielu obrazach generuj w zadaniu, a nie w żądaniu. Przekaż do zadania identyfikator rekordu, a nie generator: kluczy celowo nie da się serializować.

from celery import shared_task
from dockaccess_alt import RateLimitedError, ServerError, TransportError
from dockaccess_alt.django import get_alt_generator


@shared_task(bind=True, max_retries=5)
def generate_alt(self, product_id):
    product = Product.objects.get(pk=product_id)
    try:
        result = get_alt_generator().generate(product.photo, context=product.name)
    except RateLimitedError as error:
        raise self.retry(countdown=error.retry_after)
    except (ServerError, TransportError) as error:
        raise self.retry(countdown=60) from error
    Product.objects.filter(pk=product_id).update(photo_alt=result.text)
Skopiuj tekst

generator.generate_many(items) przetwarza obrazy po kolei, czeka po chwilowym limicie liczby żądań, pomija odrzucone pliki i zatrzymuje się, gdy limit planu się wyczerpie albo generator zostanie wyłączony dla strony. Każdy wynik niesie klucz przekazany razem z obrazem, na przykład identyfikator rekordu.

Generowanie w potoku CI

Polecenie dockaccess-alt generate przetwarza pliki i katalogi, na przykład obrazy strony statycznej w GitLab CI albo GitHub Actions:

dockaccess-alt generate static/img -r --lang pl --manifest alts.json --format jsonl
Skopiuj tekst

Manifest alts.json przechowuje opisy dla każdego obrazu i języka razem z sumą SHA-256 pliku, więc kolejne uruchomienie generuje tylko nowe i zmienione obrazy. Trzymaj go w repozytorium albo w pamięci podręcznej CI i czytaj w generatorze strony. --max 200 ogranicza liczbę generowań w jednym uruchomieniu; --dry-run i dockaccess-alt check sprawdzają obrazy bez wysyłania. Zapisz DOCKACCESS_ALT_KEY, DOCKACCESS_ALT_SITE_TOKEN i DOCKACCESS_ALT_SECRET jako maskowane zmienne CI.

• Kod wyjścia 0: gotowe; 1: część obrazów odrzucono, pozostałe wygenerowano.
• 2: błąd konfiguracji, na przykład brak klucza albo brak pliku.
• 3: aplikacja nie jest połączona albo generator jest wyłączony lub wstrzymany dla strony.
• 4: limit się wyczerpał; uruchom ponownie po jego odnowieniu.
• 5: nie udało się połączyć z DockAccess.

Obrazy i ochrona danych

Pakiet rozpoznaje format po zawartości, a nie po nazwie pliku, i odrzuca SVG, uszkodzone pliki oraz obrazy o zbyt dużych wymiarach, zanim je zdekoduje. Obsługiwane formaty to JPEG, PNG, GIF, WebP, AVIF i HEIC. Każdy obraz jest obracany do właściwej orientacji, zmniejszany do 2048 pikseli na dłuższym boku i budowany od nowa z pikseli jako JPEG albo WebP, więc lokalizacja GPS, dane aparatu, autor, profil ICC i komentarze zostają na Twoim serwerze. generator.prepare(image) wykonuje te kontrole bez wysyłania czegokolwiek, na przykład przy walidacji przesłanego pliku.

Limity, weryfikacja i błędy

generator.usage() zwraca used, limit, remaining, is_monthly i resets_at. Przed generowaniem pakiet pyta DockAccess, czy generator jest nadal aktywny dla strony, i zapamiętuje odpowiedź na 300 sekund. Odłączona, wyłączona albo wstrzymana usługa kończy się wyjątkiem GeneratorUnavailableError. Jeśli DockAccess jest chwilowo nieosiągalny, generowanie trwa dalej, a generator nadal pilnuje limitów konta.

• InvalidImageError: plik odrzucono lokalnie i nic nie zostało wysłane; reason mówi dlaczego.
• AuthenticationError: klucz nie został przyjęty; uruchom ponownie dockaccess-alt connect.
• LimitReachedError: limit się wyczerpał; period odróżnia okno dzienne od miesięcznego.
• RateLimitedError: odczekaj retry_after sekund i ponów.
• ServerError i TransportError: chwilowe problemy; ponów później.

Standardowy plan bezpłatny obejmuje 10 generowań opisów obrazów na dobę UTC i 1 stronę z włączonym Generatorem ALT. Gotowe integracje CMS działają również w planie bezpłatnym.

Płatne plany generatora altów mają limit na miesiąc kalendarzowy, dostępny w całości, bez podziału na dni. Limit stron jest niezależny od limitu generowania. Aktualny limit i wykorzystanie sprawdzisz na pulpicie konta. Sprawdź aktualne plany

Limit generowania jest wspólny dla całego konta: narzędzie online, połączone strony i API korzystają z tej samej puli. Ponowne wygenerowanie opisu też zużywa limit; ręczna edycja zapisanego tekstu nie generuje nowego opisu.

Limit dobowy odnawia się o 00:00 UTC, a miesięczny o 00:00 UTC pierwszego dnia kolejnego miesiąca kalendarzowego. Nie zależy to od daty płatności za subskrypcję. W Polsce 00:00 UTC przypada o 01:00 zimą i o 02:00 latem. Usługa zużycia zwraca dokładny termin odnowienia w polu resets_at.

Generowanie zbiorcze przetwarza obrazy kolejno. Po wyczerpaniu limitu konta gotowe opisy pozostają zapisane, a partia się zatrzymuje. Pozostałe obrazy przetwórz po odnowieniu limitu lub zmianie planu. Chwilowy limit częstotliwości powoduje oczekiwanie i ponowienie próby. Starsze wersje wtyczek mogą opisywać miesięczny licznik jako „dzienny”; sprawdzaj okres i termin odnowienia na koncie DockAccess.

Testy i synchronizacja

W testach FakeAltApi("Zielony plecak z dwiema przednimi kieszeniami") z dockaccess_alt.testing odpowiada jak DockAccess, bez sieci, klucza i zużywania limitu; obrazy są nadal sprawdzane jak na produkcji. Jego generator() albo async_generator() zastępuje prawdziwy generator, a assert_generated(1) sprawdza liczbę generowań.

Aby odesłać do konta opis poprawiony w aplikacji, wywołaj generator.update_alts(image_uuid, [(alt, "pl")]). Pakiet zawiera też podpisane odbiorniki opisów edytowanych w koncie (FastAPI, Django, Flask), ale edycja w koncie nie wysyła obecnie zmian do aplikacji; zapisuj poprawki także u siebie. Protokół opisuje przewodnik po REST API.

Odłącz aplikację poleceniem dockaccess-alt disconnect, które usuwa też klucze z pliku .env. Po zmianie wartości połączenia uruchom ponownie długo działające procesy. Przed produkcją wygeneruj jeden obraz i sprawdź opis według przewodnika ogólnego.