Generator altów AI dla Symfony: instalacja i konfiguracja

Pakiet dockcodes/dockaccess-alt-generator-symfony udostępnia bundle z połączeniem konta DockAccess, serwisem AltText, walidacją obrazów, obsługą Messenger i komendami konsoli. Obsługuje pliki lokalne, uploady oraz magazyny Flysystem. Twoja aplikacja odpowiada za zapis tekstu przy właściwej encji i wyświetlenie go jako alt.

Wymagania

Wymagane są Symfony 6.4, 7.4 lub 8 oraz 64-bitowe PHP 8.2+ z cURL i JSON. Wersja PHP musi też spełniać wymagania wybranej wersji Symfony. Zalecane jest GD. Funkcje opcjonalne wymagają odpowiednich pakietów: Validator do walidacji, Messenger do pracy w tle i Flysystem do obsługi jego magazynów.

Krok 1. Zainstaluj i zarejestruj bundle

composer require dockcodes/dockaccess-alt-generator-symfony
Skopiuj tekst

Sprawdź rejestrację w config/bundles.php. Jeżeli Symfony Flex nie dodał bundle’a automatycznie, dodaj poniższą pozycję do zwracanej tablicy:

Dock\AltGenerator\Symfony\DockAccessAltGeneratorBundle::class => ['all' => true],
Skopiuj tekst

Krok 2. Połącz aplikację

1. Na zweryfikowanym koncie DockAccess dodaj lub wybierz stronę, sprawdź domenę i włącz Generator ALT. Skopiuj token strony.
2. Ustaw publiczny adres aplikacji przez framework.router.default_uri albo podaj --url podczas łączenia.
3. Uruchom komendę i podaj token, adres e-mail oraz hasło DockAccess. Hasło jest używane przy połączeniu i nie jest zapisywane.

php bin/console dockaccess:alt:connect --url=https://example.com
php bin/console dockaccess:alt:status
Skopiuj tekst

Komenda zapisuje DOCKACCESS_ALT_KEY, DOCKACCESS_ALT_SITE_TOKEN i DOCKACCESS_ALT_SECRET w lokalnej konfiguracji środowiska aplikacji. W produkcji możesz użyć zmiennych środowiskowych lub sejfu Symfony; --show zwraca wartości bez zapisywania pliku. Nie umieszczaj tego wyniku w publicznych logach. Po zmianie sekretów odśwież środowisko i uruchom ponownie długotrwałe procesy Messenger.

Przed uruchomieniem produkcji połącz właściwą domenę. Połączenie z adresem lokalnym nie weryfikuje domeny produkcyjnej. Opcja --overwrite zastępuje istniejące połączenie i zmienia jego sekret.

Krok 3. Ustaw konfigurację

# config/packages/dockaccess_alt_generator.yaml
dockaccess_alt_generator:
    defaults:
        language: pl
        tone: neutral
        variants: 1
    allowed_directories:
        - '%kernel.project_dir%/public/uploads'
    verify:
        enabled: true
        ttl: 300
Skopiuj tekst

Bez jawnego języka pakiet korzysta z locale żądania, a następnie domyślnego locale kernela. set_ref domyślnie korzysta z tokenu strony. Pełny schemat pokaże php bin/console config:dump-reference dockaccess_alt_generator. Dodawaj wyłącznie katalogi, które faktycznie zawierają obrazy.

Krok 4. Wygeneruj opis przez serwis

Wstrzyknij Dock\AltGenerator\Symfony\AltText do kontrolera lub własnego serwisu. Przykład metody kontrolera:

use Dock\AltGenerator\Symfony\AltText;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\File\UploadedFile;

final class GenerateImageAltAction
{
    public function __invoke(Request $request, AltText $altText): JsonResponse
    {
        $file = $request->files->get('photo');
        if (!$file instanceof UploadedFile) {
            return new JsonResponse(['error' => 'Image required'], 422);
        }
        $result = $altText->generate($file, [
            'language' => 'pl',
            'context' => 'Karta produktu: plecak miejski',
            'variants' => 1,
        ]);
        // Zapisz wynik i identyfikatory przy właściwym obrazie w swojej bazie.
        return new JsonResponse(['alt' => $result->alt()->text()]);
    }
}
Skopiuj tekst

Przykład wymaga dodania trasy, autoryzacji i zapisu właściwych dla Twojej aplikacji. Opis jest zwykłym tekstem; Twig powinien escapować go przy renderowaniu atrybutu alt. Do walidacji formularza użyj constraintu Dock\AltGenerator\Symfony\Validator\GenuineImage. Walidacja sprawdza zawartość pliku bez wysyłania go do AI.

Dla magazynu Flysystem wywołaj $altText->generateFromFilesystem($storage, 'products/42.jpg'), gdzie $storage jest skonfigurowanym obiektem FilesystemOperator. Użycie S3 nie wymaga publikowania pliku w internecie: aplikacja odczytuje go z magazynu i przesyła do generatora.

Krok 5. Generuj w Messengerze

use Dock\AltGenerator\Symfony\Message\GenerateAltText;

$bus->dispatch(new GenerateAltText(
    'products/42.jpg',
    'default.storage',
    ['language' => 'pl', 'context' => 'Zdjęcie plecaka'],
    ['product_id' => 42]
));
Skopiuj tekst

default.storage jest przykładowym identyfikatorem usługi Flysystem; zastąp go własnym. Magazyn powinien mieć tag flysystem.storage lub być wymieniony w dockaccess_alt_generator.storages. Przekazanie null zamiast magazynu oznacza ścieżkę bezwzględną wewnątrz dozwolonego katalogu.

# config/packages/messenger.yaml
framework:
    messenger:
        routing:
            Dock\AltGenerator\Symfony\Message\GenerateAltText: async
Skopiuj tekst

Skonfiguruj transport async i uruchom php bin/console messenger:consume async. Obsłuż Dock\AltGenerator\Symfony\Event\AltTextGeneratedEvent: zapisz alt, locale, imageUuid i setUuid przy rekordzie wskazanym w context. Samo wysłanie wiadomości nie zapisuje opisu. AltTextFailedEvent informuje o ostatecznym niepowodzeniu.

Limity i diagnostyka

$altText->usage() udostępnia used(), limit(), remaining(), isMonthly() i resetsAt(). Przed generowaniem pakiet weryfikuje stan usługi, domyślnie z cache na 300 sekund. Rozłączenie, wyłączenie lub wstrzymanie usługi powoduje GeneratorUnavailableException. Chwilowa niedostępność konektora może pozostawić generowanie aktywne; limity sprawdza również generator.

Wyczerpany limit, odrzucony obraz i rozłączone konto wymagają poprawienia przyczyny. Błędy przejściowe mogą być ponawiane przez Messenger. W Symfony 7.4 i 8 obsługa limitu częstotliwości przekazuje żądany czas opóźnienia; dla Symfony 6.4 dostosuj strategię ponawiania transportu do Retry-After.

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.

Test wdrożenia i rozłączenie

Sprawdź kolejno połączenie, jeden obraz, zapis przez zdarzenie, zestaw na koncie i wynikowy HTML. W testach aplikacji możesz podmienić Dock\AltGenerator\Http\TransportInterface na Dock\AltGenerator\Symfony\Testing\FakeTransport; sprawdzanie plików nadal działa. Bundle nie tworzy automatycznie edytora altów ani odbiorcy poprawek z panelu. Własny mechanizm synchronizacji opisuje REST API.

Rozłącz aplikację przez php bin/console dockaccess:alt:disconnect albo na koncie DockAccess. Dobre praktyki pisania tekstów opisuje poradnik ogólny.