Generator altów AI dla Magento: instalacja i konfiguracja

Moduł DockAccess AI Alt Generator tworzy teksty alternatywne zdjęć produktów w Magento Open Source, Adobe Commerce i Mage-OS, w języku każdego widoku sklepu. Możesz wygenerować opis pojedynczego zdjęcia w galerii produktu, przetworzyć zaznaczone zdjęcia na ekranie Zdjęcia produktów i synchronizować poprawki z DockAccess.

Wymagania i zakres

Moduł działa z Magento 2.4.4 lub nowszym, Adobe Commerce i Mage-OS oraz PHP od 8.1 do 8.4. Potrzebujesz konta DockAccess i dostępu do serwera (SSH), żeby zainstalować moduł; jeśli go nie masz, poproś osobę, która opiekuje się sklepem. Moduł obsługuje zdjęcia galerii produktu i ich pole Alt Text. Obrazy kategorii, strony i bloki CMS, treści Page Builder i grafiki motywu wymagają osobnej obsługi.

Krok 1. Przygotuj sklep w DockAccess

1. Zaloguj się do DockAccess lub załóż konto, a następnie potwierdź adres e-mail.
2. Otwórz Moje strony, wybierz Dodaj stronę i wpisz domenę produkcyjną, bez protokołu i ścieżki. Jeżeli strona już istnieje, otwórz jej konfigurację zamiast tworzyć duplikat.
3. Włącz Generator ALT dla tej strony i zapisz zmiany. Jeżeli usługa jest wstrzymana, najpierw rozwiąż problem z limitem stron na koncie.
4. Skopiuj token strony z jej konfiguracji. W formularzu połączenia w CMS-ie podaj ten token oraz login i hasło konta DockAccess, do którego należy strona. Wybierz Połącz.
5. Sprawdź status połączenia i adres strony, a następnie wygeneruj jeden opis próbny przed uruchomieniem większej partii. Wtyczka powinna być też widoczna wśród połączonych integracji tej strony w DockAccess.

Token strony identyfikuje witrynę. Różni się od klucza API konta i sekretu połączenia. Podaj dane logowania do DockAccess, a nie dane administratora CMS-a. Oficjalne wtyczki używają hasła przy żądaniu połączenia i go nie zapisują. Jeżeli logujesz się przez konto społecznościowe i nie masz hasła, najpierw ustaw je przez odzyskiwanie hasła.

Krok 2. Zainstaluj moduł

Pobierz ZIP modułu dla Magento i rozpakuj go do katalogu app/code/DockCodes/DockAccessAltGenerator instalacji Magento. Potem w katalogu Magento uruchom:

bin/magento module:enable DockCodes_DockAccessAltGenerator
bin/magento setup:upgrade
bin/magento cache:flush
Skopiuj tekst

Jeśli sklep działa w trybie produkcyjnym, przed wyczyszczeniem cache uruchom też bin/magento setup:di:compile i bin/magento setup:static-content:deploy.

Krok 3. Połącz sklep

1. W panelu Magento otwórz Katalog → DockAccess AI Alt Generator → Połączenie i ustawienia (Catalog → DockAccess AI Alt Generator → Connection and settings).
2. Wklej token strony i wpisz adres e-mail (albo nazwę użytkownika) oraz hasło konta DockAccess. Wybierz Połącz (Connect). Hasło służy tylko do połączenia i nie jest zapisywane.
3. Przy kilku witrynach wybierz adres sklepu, który jest jedną z domen strony w DockAccess. Jedno połączenie obsługuje całą instalację Magento.
4. Sprawdź plan, zużycie i endpoint push. Uruchom Przetestuj endpoint (Test the endpoint): przy sklepie za firewallem albo reverse proxy publiczny adres HTTPS sklepu musi przyjmować żądania POST.

Krok 4. Kontekst i ton

Na tym samym ekranie, w sekcji Ustawienia generowania (Generation defaults), ustaw kontekst, do 500 znaków, i ton. Kontekst powinien opisywać ofertę albo zastosowanie zdjęć, np. „Ręcznie robione dębowe meble do jadalni”. Unikaj poleceń wstawiania słów kluczowych. Zapisz ustawienia.

Krok 5. Generuj w galerii produktu

1. Otwórz produkt i u góry strony wybierz zakres: wszystkie widoki sklepu (All Store Views) albo konkretny widok. Tekst alternatywny powstanie w języku tego zakresu.
2. W sekcji Zdjęcia i wideo (Images And Videos) kliknij zdjęcie. Pod polem Alt Text wybierz Generuj tekst alternatywny. Opcje zmieniają kontekst, ton i język dla tego jednego zdjęcia.
3. Dla zapisanego już zdjęcia tekst zapisuje się od razu w wybranym zakresie. Dla nowo wgranego zdjęcia trafia do pola i zostaje zapisany razem z produktem.
4. Przejrzyj tekst, w razie potrzeby popraw go i zapisz produkt.

Krok 6. Generuj dla wielu zdjęć

1. Otwórz Katalog → DockAccess AI Alt Generator → Zdjęcia produktów i wybierz widok sklepu. Zakres wszystkich widoków przechowuje teksty, które pokazuje każdy widok bez własnego; w konkretnym widoku teksty oznaczone „domyślny” pochodzą z wszystkich widoków.
2. Wyszukaj po nazwie produktu albo SKU lub zaznacz Tylko zdjęcia bez tekstu alternatywnego.
3. Zaznacz zdjęcia i wybierz Generuj dla zaznaczonych zdjęć. Zdjęcia są wysyłane po jednym, a każdy tekst zapisuje się, gdy jest gotowy. Zatrzymaj kończy pracę po bieżącym zdjęciu.
4. Gdy limit planu się wyczerpie, praca się zatrzymuje: wygenerowane teksty zostają, pozostałe zdjęcia są oznaczone jako niewygenerowane. Powtórz pracę dla innych widoków i języków, których potrzebujesz.

Synchronizacja i kontrola na stronie produktu

Dla zdjęć wygenerowanych przez moduł teksty alternatywne zmienione na stronie produktu trafiają do DockAccess po zapisaniu produktu, po jednym tekście na język. Moduł potrafi też odbierać podpisane aktualizacje i zapisuje każdy język w widokach sklepu w tym języku, ale edycja na koncie obecnie ich nie wysyła: poprawkę z konta zapisz również w Magento. Motyw sklepu musi używać pola Alt Text galerii w atrybucie alt: po wyczyszczeniu cache sprawdź stronę produktu, galerię i listę produktów.

Limity

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.

Diagnostyka i utrzymanie

Odmowa połączenia: logowanie lub potwierdzenie e-maila

Użyj konta DockAccess, do którego należy token strony, potwierdź adres e-mail i sprawdź login oraz hasło. Powtarzające się błędne próby mogą czasowo zablokować kolejne połączenia.

Adres strony się nie zgadza

Sprawdź, czy produkcyjny adres CMS-a znajduje się wśród domen tokenu. Połączenie środowiska testowego nie potwierdza domeny produkcyjnej. Przed ponownym połączeniem sprawdź HTTPS, ustawienia reverse proxy i główny adres witryny.

Generator wyłączony (alt_disabled)

Włącz Generator ALT dla tej konkretnej strony w DockAccess i zapisz zmiany. Sama instalacja wtyczki nie uruchamia usługi.

Generator wstrzymany (alt_paused)

Przekroczono limit stron na koncie, np. po zmianie planu. Zwolnij miejsce, wyłączając usługę na innej stronie, lub zwiększ limit. Wstrzymane strony i wcześniej wygenerowane teksty nie są usuwane.

Strona jest już połączona

Zastąp połączenie tylko wtedy, gdy chcesz ponownie połączyć tę instalację. Potwierdzenie zastąpienia zmienia sekret połączenia, więc inne kopie korzystające z poprzedniego sekretu trzeba połączyć ponownie.

Wyczerpany limit dobowy lub miesięczny

Sprawdź pulpit konta i termin odnowienia. Gotowe teksty pozostają zapisane. Poczekaj na rozpoczęcie kolejnego okresu UTC lub wybierz wyższy plan; ponowne połączenie nie zeruje zużycia.

Zbyt wiele żądań w krótkim czasie

Pozwól, aby partia odczekała i ponowiła próbę. We własnej integracji uwzględniaj Retry-After i rozróżniaj X-Alt-Reason: rate_limited od limit_reached. Unikaj wielokrotnego klikania Generuj.

Nie można wygenerować opisu obrazu

Sprawdź, czy CMS może odczytać oryginalny plik lokalny. Użyj poprawnego obsługiwanego pliku rastrowego, np. JPEG, PNG lub WebP. Samo rozszerzenie nie wystarczy; nieobsługiwane lub uszkodzone pliki przekonwertuj albo zastąp. Joomla nie generuje opisów obrazów artykułów pobieranych z obcych serwerów.

Zmiany nie docierają do CMS-a

Obecna edycja na koncie nie wysyła zmian automatycznie do CMS-a; poprawkę zapisz również tam. Wtyczki mają przygotowany odbiór push. Przy wdrażaniu własnego nadawcy uruchom test endpointu, sprawdź publiczny HTTPS, trasy, zaporę, nagłówki podpisu i zegary serwerów. Podpisane żądania dopuszczają pięć minut różnicy czasu i wymagają powiązania z lokalnym obrazem.

Zapisany alt nie jest widoczny na stronie

Sprawdź wynikowy element img i wyczyść cache strony, szablonu oraz CDN. Pole obrazu w CMS-ie nie zawsze aktualizuje HTML zapisany wcześniej w artykule lub kreatorze stron. Popraw dane użycie obrazu albo szablon. Nie uzupełniaj zbiorczo celowo pustych altów obrazów dekoracyjnych.

Magento pokazuje komunikat systemowy, gdy generator jest wyłączony albo wstrzymany dla sklepu albo gdy nie udało się wysłać zmienionego tekstu. Żeby usunąć moduł, najpierw wybierz Odłącz na ekranie Połączenie i ustawienia (poprosi o login DockAccess), a potem uruchom bin/magento module:uninstall --non-composer DockCodes_DockAccessAltGenerator. Teksty alternatywne zostają na zdjęciach. Szersze zasady pracy opisuje poradnik obsługi generatora.