Vision API görsel analiz sistemi, Google Cloud kullanılarak bir resimdeki nesneleri ve etiketleri tanımlamak, metni OCR ile okumak veya güvenli arama sinyallerini incelemek için kullanılabilir. Bu rehberde Node.js ile çalışan küçük bir örnek kuracağız; yerel bir görseli analiz edecek, etiketleri güven skorlarıyla gösterecek ve aynı dosyadan metin çıkaracağız.
Buradaki yaklaşım doğrudan Google Cloud Vision istemci kitaplığı ile çalışır. Uygulamayı canlıya almadan önce faturalandırma, erişim yetkileri ve kişisel veri işleme gereksinimlerini kendi projenize göre değerlendirin.
Vision API Görsel Analiz Nedir ve Neler Yapar?
Cloud Vision, görselleri Google’ın önceden eğitilmiş modelleriyle analiz eden bir API’dir. Yaygın özellikleri şunlardır:
- Label Detection: Görseldeki genel nesne ve kavramları etiketler.
- Text Detection / Document Text Detection: Basılı metin ve belge yoğunluklu içerikler için OCR uygular.
- Object Localization: Nesneleri ve yaklaşık konumlarını döndürür.
- SafeSearch Detection: Belirli hassas içerik sinyalleri üretir; tek başına kesin moderasyon kararı olarak kullanılmamalıdır.
- Logo ve landmark algılama: Desteklenen logo ve önemli yerleri tanımaya çalışır.
Bir e-ticaret görselini otomatik etiketleme, yüklenen evraktan metin çıkarma ve medya arşivinde arama alanı oluşturma gibi işler için uygundur. Diğer yapay zekâ servisleriyle ilgili uygulama fikirleri için AI API rehberlerine de bakabilirsiniz.
Vision API Görsel Analiz Kurulumu
1. Projeyi ve API’yi hazırlayın
Google Cloud Console’da bir proje seçin veya oluşturun, faturalandırmayı bağlayın ve Cloud Vision API’yi etkinleştirin. Yerel geliştirmede Google Cloud CLI kurulduktan sonra aşağıdaki komutlarla oturum açabilir ve Application Default Credentials (ADC) oluşturabilirsiniz:
gcloud init
gcloud auth application-default loginResmî kimlik doğrulama belgesi, yerel geliştirme ile Google Cloud üzerindeki üretim ortamı için farklı seçenekleri açıklar. Üretimde uzun ömürlü servis hesabı anahtarlarını kod deposuna koymak yerine iş yüküne bağlı servis hesabı veya uygun olduğunda Workload Identity Federation kullanın.
2. Node.js projesini oluşturun
mkdir vision-analiz
cd vision-analiz
npm init -y
npm install @google-cloud/visionGoogle’ın güncel istemci kitaplığı kurulumu @google-cloud/vision paketini kullanır. Kimlik bilgilerini kaynak koda yazmayın ve JSON anahtar dosyalarını Git’e göndermeyin.
Node.js ile görsel etiketleme
Proje klasörüne ornek.jpg adlı bir görsel koyun ve index.js dosyasını oluşturun:
const vision = require('@google-cloud/vision');
async function etiketleriBul(dosyaYolu) {
const client = new vision.ImageAnnotatorClient();
const [result] = await client.labelDetection(dosyaYolu);
const labels = result.labelAnnotations || [];
return labels.map((item) => ({
etiket: item.description,
guven: Number((item.score || 0).toFixed(3)),
}));
}
etiketleriBul('./ornek.jpg')
.then(console.table)
.catch((error) => {
console.error('Vision API hatası:', error.message);
process.exitCode = 1;
});Komutu node index.js ile çalıştırdığınızda etiketler ve 0–1 aralığındaki güven değerleri listelenir. Güven skoru modelin tahminidir; hukuki, tıbbi veya güvenlik açısından kritik bir kararı insan kontrolü olmadan vermek için kullanılmamalıdır.
Görselden metin okuma (OCR)
Aynı istemciyle bir fotoğraf veya ekran görüntüsündeki metni çıkarabilirsiniz:
const vision = require('@google-cloud/vision');
async function metniOku(dosyaYolu) {
const client = new vision.ImageAnnotatorClient();
const [result] = await client.textDetection(dosyaYolu);
const ilkSonuc = result.textAnnotations?.[0];
return ilkSonuc?.description || 'Metin bulunamadı';
}
metniOku('./belge.jpg')
.then(console.log)
.catch(console.error);Yoğun belge sayfalarında documentTextDetection daha ayrıntılı sayfa, blok ve paragraf yapısı sağlar. Google’ın OCR belgesi, yerel dosya ve Cloud Storage örneklerini birlikte gösterir.
Vision API Görsel Analiz Güvenliği
- Yüklenen dosyanın yalnızca uzantısını değil MIME türünü ve gerçek içeriğini doğrulayın.
- Dosya boyutu ve istek sayısı için sınır koyun; aksi hâlde maliyet ve hizmet reddi riski oluşur.
- Kimlik bilgilerini tarayıcıya göndermeyin. Vision API çağrısını sunucu tarafında yapın.
- Yüklenen görseller kişisel veri içeriyorsa saklama süresi, erişim ve silme politikasını açıkça belirleyin.
- API hatasını kullanıcıya ham yığın iziyle göstermeyin; sunucuda istek kimliğiyle kaydedin.
Sık karşılaşılan hatalar
Could not load the default credentials
ADC oluşturulmamış veya uygulamanın çalıştığı ortamda uygun servis hesabı bağlanmamıştır. Yerelde gcloud auth application-default login adımını doğrulayın; üretimde çalıştırma ortamına yetkili bir servis hesabı bağlayın.
PERMISSION_DENIED veya API has not been used
Cloud Vision API etkin değildir, yanlış proje seçilmiştir ya da çağrıyı yapan kimliğin gerekli izni yoktur. Proje kimliğini, API durumunu ve IAM rollerini kontrol edin.
Sonuç boş geliyor
Görsel düşük çözünürlüklü, bulanık veya seçilen algılama türüne uygun olmayabilir. OCR için daha net görsel kullanın; etiketleme ile metin algılamanın farklı özellikler olduğunu unutmayın.
Sık sorulan sorular
Vision API ücretsiz mi?
Kullanım ve fiyatlandırma koşulları zamanla değişebilir. Projeyi açmadan önce Google Cloud’un güncel fiyatlandırma ve kota ekranını kontrol edin, bütçe uyarısı oluşturun.
API anahtarını JavaScript içinde kullanabilir miyim?
Tarayıcıya gönderilen bir anahtar kullanıcılar tarafından görülebilir. Sunucu tarafı istemci kitaplığı ve ADC kullanmak, kimlik bilgilerini istemciden uzak tutar.
Bir istekte hem etiket hem OCR yapılabilir mi?
REST images:annotate isteğinde aynı görsel için birden fazla özellik belirtilebilir. İstemci kitaplığında ise ihtiyaca göre ayrı yöntemler veya toplu istek kullanılabilir. Resmî istek biçimi belgesinde JSON yapısı gösterilir.
Sonuç
Vision API görsel analiz sisteminin temel akışı; API’yi etkinleştirmek, ADC ile güvenli kimlik doğrulama kurmak, @google-cloud/vision istemcisini yüklemek ve ihtiyaca uygun algılama yöntemini çağırmaktır. Canlı ortamda dosya doğrulama, kota, maliyet takibi ve kişisel veri yönetimi kod örneği kadar önemlidir.
