Generator altów AI dla Laravel: instalacja i konfiguracja

Pakiet dockcodes/dockaccess-alt-generator-laravel dodaje do aplikacji Laravel połączenie z DockAccess, fasadę AltText, regułę walidacji plików, zadanie kolejki i komendy Artisan. Możesz generować opisy dla uploadów oraz plików na dyskach Storage, także S3. Zapis wyniku w modelu i umieszczenie altu w szablonie należą do Twojej aplikacji.

Wymagania

Wymagane są Laravel 12 lub 13, 64-bitowe PHP 8.2+ oraz rozszerzenia cURL i JSON. Zalecane jest GD z obsługą JPEG, PNG, GIF i WebP. Potrzebujesz zweryfikowanego konta DockAccess oraz strony z włączonym Generatorem ALT. Biblioteka PHP jest instalowana jako zależność pakietu.

Krok 1. Zainstaluj pakiet

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

Laravel automatycznie wykrywa service provider. Jeżeli w aplikacji wyłączono wykrywanie pakietów, zarejestruj Dock\AltGenerator\Laravel\AltGeneratorServiceProvider zgodnie z konfiguracją swojej wersji Laravel.

Krok 2. Połącz aplikację z kontem

1. W DockAccess otwórz Moje strony, dodaj lub wybierz stronę, sprawdź domenę produkcyjną i włącz Generator ALT. Skopiuj token tej strony.
2. Sprawdź, czy APP_URL wskazuje publiczny adres aplikacji zgodny z domeną tokenu.
3. Uruchom poniższą komendę. Podaj token strony oraz adres e-mail i hasło konta DockAccess. Hasło jest używane przy połączeniu i nie jest zapisywane.

php artisan dockaccess-alt:connect
php artisan dockaccess-alt:status
Skopiuj tekst

Komenda zapisuje w konfiguracji środowiska aplikacji wartości DOCKACCESS_ALT_KEY, DOCKACCESS_ALT_SITE_TOKEN i DOCKACCESS_ALT_SECRET. Jeżeli używasz cache konfiguracji, po połączeniu odśwież go przez php artisan config:cache. W środowisku z menedżerem sekretów opcja --show pozwala odebrać wartości bez zapisywania pliku; wyniku tej komendy nie publikuj w logach.

Opcja --url=https://example.com nadpisuje adres aplikacji dla żądania połączenia. Połączenie lokalne nie potwierdza domeny produkcyjnej: przed uruchomieniem produkcji połącz aplikację z właściwym adresem. Opcji --overwrite używaj tylko przy świadomym zastąpieniu istniejącej instalacji; zmienia ona sekret połączenia.

Krok 3. Ustaw domyślne parametry

php artisan vendor:publish --tag=dockaccess-alt-config
Skopiuj tekst

Plik config/dockaccess-alt.php zawiera język, ton, kontekst ustawiany przy wywołaniu, liczbę wariantów, dozwolone katalogi, ustawienia HTTP i kolejki. Język domyślnie wynika z locale aplikacji, ton to neutral, a set_ref korzysta z tokenu strony. Przekazuj kontekst konkretnego obrazu, maksymalnie 500 znaków, i język treści, a nie język administratora.

Krok 4. Wygeneruj jeden opis

Przykład wewnątrz akcji obsługującej formularz:

use Dock\AltGenerator\Laravel\Facades\AltText;
use Dock\AltGenerator\Laravel\Rules\GenuineImage;

$request->validate([
    'photo' => ['required', 'file', new GenuineImage],
]);

$result = AltText::generate($request->file('photo'), [
    'language' => 'pl',
    'tone' => 'neutral',
    'context' => 'Karta produktu: plecak miejski, widok z przodu',
    'variants' => 1,
]);

$alt = $result->alt()->text();
$imageUuid = $result->imageUuid();
$setUuid = $result->setUuid();
// Zapisz tekst, język i identyfikatory przy właściwym obrazie w swojej bazie.
Skopiuj tekst

Reguła GenuineImage sprawdza rzeczywistą zawartość pliku lokalnie, bez generowania i bez połączenia z kontem. Dla pliku na dysku użyj AltText::generateFromDisk('products/42.jpg', 'public'); nazwa dysku musi istnieć w konfiguracji Storage. Ścieżki bezwzględne są ograniczone do allowed_directories, domyślnie storage/app/public. Nie uruchamiaj generowania podczas każdego renderowania strony.

Krok 5. Generuj w tle i zapisz wynik

use Dock\AltGenerator\Laravel\Jobs\GenerateAltText;

GenerateAltText::dispatch(
    'products/42.jpg',
    'public',
    ['language' => 'pl', 'context' => 'Zdjęcie plecaka'],
    ['product_id' => 42]
);
Skopiuj tekst

Ostatnia tablica to dane dla odbiorcy wyniku; użyj identyfikatora własnego rekordu. Skonfiguruj trwałe połączenie kolejki i uruchom worker przez php artisan queue:work. Przy sterowniku sync zadanie wykona się w bieżącym żądaniu.

Obsłuż zdarzenie Dock\AltGenerator\Laravel\Events\AltTextGenerated. Pola alt, locale, imageUuid, setUuid oraz context pozwalają zapisać wynik przy właściwym obrazie. AltTextFailed informuje o niepowodzeniu. Samo dodanie zadania do kolejki nie zapisuje altu w modelu.

Limity, weryfikacja i błędy

AltText::usage() zwraca obiekt z metodami used(), limit(), remaining(), isMonthly() i resetsAt(). Przed generowaniem pakiet sprawdza stan usługi i domyślnie pamięta odpowiedź przez 300 sekund. Po rozłączeniu, wyłączeniu lub wstrzymaniu usługi zgłasza GeneratorUnavailableException. Jeżeli sam konektor chwilowo nie odpowiada, pakiet może kontynuować generowanie; limit nadal egzekwuje usługa generatora.

Wyczerpany limit to DailyLimitReachedException, także dla planu miesięcznego; okres odczytaj przez getPeriod(). Zadanie kolejki ponawia błędy przejściowe i respektuje oczekiwanie po limicie częstotliwości. Nie ponawia bez końca wyczerpanej puli, odrzuconego pliku ani rozłączonej aplikacji.

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 i kontrola wdrożenia

Do testów użyj AltText::fake('Zielony plecak z dwiema kieszeniami') i assertGenerated(1). Atrapa pomija połączenie sieciowe, ale nadal sprawdza plik. Na środowisku testowym wygeneruj jeden prawdziwy obraz, sprawdź zapis zdarzenia, zestaw na koncie i wynikowy img alt. Blade powinien escapować tekst w atrybucie. Pakiet nie dodaje automatycznego odbioru poprawek z panelu ani panelu do edycji altów; własną synchronizację opisuje instrukcja REST API.

Do rozłączenia użyj php artisan dockaccess-alt:disconnect i odśwież cache konfiguracji. Jeżeli rotujesz dane połączenia w działającej aplikacji, uruchom ponownie długotrwałe workery. Zasady redakcyjne znajdziesz w poradniku ogólnym.