Yüklenen her görsel kendini nasıl anlatıyor: alt metin ve anlamsal arama hattımız

Bir işletme panele yüzlerce fotoğraf yüklüyor. Çoğunun adı "IMG_4821.jpg". Hiçbirine alt metin yazılmıyor. Bu hem erişilebilirlik hem de arama motorları için bir kayıp. Üç ay sonra "dükkânın önündeki o fotoğraf" aranırken de klasör klasör gezmek gerekiyor.

Marcapony'de yüklenen her görsel, kimse bir şey yapmadan kendine bir açıklama ve anlamla aranabilen bir iz kazanıyor. Bu yazıda o hattın nasıl çalıştığını anlatıyoruz.

Yükleme: "yüklendi" ile "hazır" ayrı şeyler

Tarayıcı dosyayı parçalar halinde, API'nin ürettiği önceden imzalı adreslerle doğrudan S3'e yüklüyor. Dosya API sunucusundan geçmiyor. Yükleme tamamlanınca dosya {hesap}/raw/ altına kopyalanıyor.

Bu raw/ öneki hattın tetiği. Bir dosyanın yüklenmiş olması ile servise hazır olması iki ayrı durum ve iki ayrı yolda duruyorlar.

Tetik hızlı olmalı, iş yavaş olabilir

raw/ altına düşen her dosya için bir EventBridge kuralı, medya işleme servisimizin tetik adresine bir olay gönderiyor. EventBridge yanıtı 5 saniye bekliyor. Video dönüştürmek ise dakikalar sürebilir. Bu yüzden tetik adresi hiçbir işi kendisi yapmıyor: dosyanın hangi işlemlerden geçeceğine karar veriyor, Cloud Tasks kuyruğuna bir görev bırakıyor ve hemen yanıt veriyor.

Asıl iş Google Cloud Run üzerinde, Frankfurt bölgesinde çalışan bir Bun servisinde yapılıyor. Kuyruk, yeniden denemeleri ve eşzamanlılığı bizim yerimize yönetiyor.

Görseller ve videolar

Görseller WebP'ye çevriliyor. Sıkıştırma kalitesi sabit değil, kademeli seçiliyor. Her görsel için bir blurhash üretiliyor; görsel yüklenene kadar yerinde bulanık bir önizleme duruyor. Genişlik, yükseklik ve en boy oranı da kayda geçiyor.

Videolar varsayılan olarak 1080p H.264 MP4'e, ayrıca 720p bir sürüme dönüştürülüyor. Başta VP9 WebM kullanıyorduk. 4K VP9 videoların iOS'taki WebKit'i çökerttiğini görünce H.264'e geçtik. Bu, "en verimli format" ile "her cihazda çalışan format" arasındaki farkı bize iyi öğretti.

Alt metin: görsele bakıp iki cümle

Görsel 1024 pikseli geçmeyecek şekilde küçültülüp JPEG olarak Vertex AI üzerindeki Gemini 2.5 Flash-Lite modeline gönderiliyor. Modelden istediğimiz şey kısa: görselin ana konusunu ve görsel öğelerini bir iki cümleyle anlatması, başka hiçbir şey eklememesi. Küçültme hem isteği hafifletiyor hem de maliyeti düşük tutuyor. Alt metin üretmek için tam çözünürlüğe ihtiyaç yok.

Açıklamadan anlama: vektörler

Üretilen alt metin, Cloudflare Workers AI üzerindeki bge-base-en-v1.5 modeliyle 768 boyutlu bir vektöre çevriliyor. Vektör, alt metinle birlikte Postgres'te pgvector ile saklanıyor ve kosinüs benzerliği için bir HNSW indeksiyle aranıyor.

Görselin kendisini değil, açıklamasını vektörlüyoruz. Tek bir model çağrısı iki iş görmüş oluyor: aynı metin hem sitede alt metin olarak kullanılıyor hem de aramanın temelini oluşturuyor.

Arama ve en önemli kural

Kullanıcı "ofisin önünde ekip fotoğrafı" diye arattığında, API sorguyu aynı modelle vektöre çeviriyor ve en yakın görselleri belirli bir benzerlik eşiğinin üstünde döndürüyor.

Bu hattaki en önemli kural iki tarafın aynı modeli kullanması. İşleme servisi bir modelle, API başka bir modelle vektör üretseydi hiçbir şey hata vermezdi. Arama yalnızca sessizce anlamsız sonuçlar döndürürdü. Bu tür hatalar en tehlikeli olanlar: her şey çalışıyor görünür ama yanlış çalışır. Bu yüzden model adı iki serviste de koda sabitlenmiş durumda ve yanında bu kuralı hatırlatan bir not var.

Gizlilik: modele hiç gitmeyenler

Her dosya bu hattan geçmiyor. Bir işletme bir klasörü özel olarak işaretlediğinde (müşterinin henüz yayınlanmamış fotoğrafları, bir formla gelen özgeçmiş gibi), o klasördeki dosyalar hiçbir modele gönderilmiyor ve vektörleri oluşmuyor. Ziyaretçilerin yüklediği dosyalar için de alt metin üretilmiyor. Arama tarafında ikinci bir emniyet daha var: sorgu yalnızca herkese açık dosyaları döndürüyor.

AI ajanları da arayabiliyor

Aynı arama, Marcapony'nin MCP sunucusu üzerinden Claude gibi AI istemcilerine de açık. Claude bir sayfa hazırlarken "dükkânın vitrin fotoğrafı" diye arıyor, bulduğu görseli doğrudan bölüme yerleştiriyor. Dosya adını bilmesine gerek kalmıyor.

Bilinen bir sınır

Alt metinler şimdilik İngilizce üretiliyor ve kullandığımız vektör modeli İngilizce odaklı. Türkçe aramalar çalışıyor ama İngilizce kadar isabetli değil. Çok dilli alt metin ve arama henüz yok; hattın sıradaki doğal adımı bu.