WebAuthn Passkey Entegrasyonu: Parolasız Giriş Nasıl Eklenir? (Adım Adım Rehber)

Passkey Nedir ve Neden Önemli?

Parolalar hem kullanıcılar hem de geliştiriciler için sorunlu: Zayıf şifreler, phishing saldırıları ve tekrar kullanım derken, güvenlik açıkları kaçınılmaz hale geliyor. Passkey (FIDO2/WebAuthn tabanlı parolasız kimlik doğrulama) bu tabloyu değiştiriyor. Kullanıcılar cihazlarının biyometrik doğrulamasıyla (Face ID, Touch ID, Windows Hello vb.) giriş yapıyor; sunucu tarafında ise yalnızca herkese açık anahtar saklanıyor. Bu yaklaşım phishing’e dirençli, kullanıcı deneyimi açısından zahmetsiz ve uzun vadede bakım maliyetini düşürüyor.

Mimari: Kısa Bir Genel Bakış

WebAuthn, iki ana akışa dayanır: kayıt (registration) ve giriş (authentication). Kayıt akışında sunucu, istemciye bir challenge ve parametreler gönderir; tarayıcı navigator.credentials.create() ile cihaz üzerinde bir anahtar çifti üretir ve herkese açık anahtarı sunucuya geri yollar. Giriş akışında ise sunucu challenge üretir, istemci navigator.credentials.get() ile imza alır ve sunucu bunu doğrular. Tüm süreçte parolayı ne ilettiğinizi ne de sakladığınızı düşünmeniz gerekmez.

Gereksinimler ve Dikkat Edilmesi Gerekenler

- Uygulamanızın HTTPS üzerinde çalışması gerekir (localhost hariç).
- RP ID alanı, genellikle alan adınızın köküdür (ör. example.com). Alt alanlar için doğru RP ID seçimi önemlidir.
- Tarayıcı ve platform desteği oldukça geniştir; yine de eski cihazları hedefliyorsanız geriye uygun bir strateji belirleyin.
- Passkey’lerin cihazlar arası senkronizasyonu (ör. iCloud Anahtar Zinciri, Google Password Manager) kullanıcı deneyimini iyileştirir, ancak kurumsal ortamlarda harici güven anahtarlarını da (security key) desteklemek isteyebilirsiniz.

Kayıt (Registration) Akışı: Adım Adım

1) Kullanıcı yeni hesap oluşturmak veya hesabına passkey eklemek istediğinde, sunucu bir challenge üretir ve publicKeyCredentialCreationOptions nesnesini oluşturur. Bu nesnede rp (adı ve id), user (id, name, displayName), pubKeyCredParams (COSE algoritmaları), authenticatorSelection (ör. residentKey, userVerification), timeout ve gerekiyorsa attestation alanları yer alır.

2) İstemci tarafında tarayıcıya navigator.credentials.create({ publicKey }) çağrısı yaptırılır. Kullanıcı biyometrik doğrulama ile onaylar. Tarayıcı size id, rawId, response.attestationObject ve response.clientDataJSON döndürür.

3) Sunucu bu verileri doğrular: clientDataJSON içindeki challenge, type ve origin kontrol edilir; attestationObject içinden sertifika zinciri ve anahtar bilgisi çıkarılır. Sonuçta kullanıcı kaydı için credential ID, public key ve signCount veritabanına kaydedilir.

4) Attestation politikanızı belirleyin: Çoğu tüketici uygulaması için none yeterlidir. Düzenlemeye tabi sektörlerde (finans, sağlık) cihaz kanıtı (attestation) şartları farklı olabilir.

Giriş (Authentication) Akışı: Adım Adım

1) Kullanıcı “Giriş Yap” dediğinde sunucu bir challenge üretir ve publicKeyCredentialRequestOptions oluşturur. Bu nesnede challenge, timeout, rpId ve varsa allowCredentials bulunur.

2) İstemci navigator.credentials.get({ publicKey }) çağrısı yapar. Tarayıcı kullanıcı doğrulamasını ister ve size id, rawId, response.authenticatorData, response.clientDataJSON, response.signature ve mümkünse userHandle döndürür.

3) Sunucu doğrulama yapar: clientDataJSON içindeki challenge ve origin kontrol edilir; authenticatorData içinden RP ID hash, bayraklar ve sayaç (signCount) okunur. signature, veritabanına kaydettiğiniz herkese açık anahtarla doğrulanır. Sayaç ileri gitmiyorsa tekrar kullanım şüphesiyle oturumu reddedin veya riske göre ek doğrulama isteyin.

Discoverable Credentials ve Kullanıcı Deneyimi

Passkey’lerin en güçlü yanlarından biri, discoverable credentials desteğidir. Bu sayede kullanıcı, e-posta veya kullanıcı adı girmeden doğrudan cihazındaki passkey ile giriş yapabilir. authenticatorSelection.residentKey = "required" ve userVerification = "required" ayarlarıyla modern bir “tek dokunuşla giriş” deneyimi sağlayabilirsiniz.

Güvenlik ve Uyum İpuçları

- Her istek için tek kullanımlık random challenge üretin ve kısa süreliğine geçerli kılın.
- RP ID ve origin eşleşmesini sıkı tutun; üretim ve test ortamlarını karıştırmayın.
- Rate limiting ve risk tabanlı kontroller (IP, cihaz parmak izi, olağandışı saat dilimi) ekleyin.
- Kullanıcının passkey kaybına karşı yedek faktör (TOTP, e-posta onayı, güvenlik anahtarı) sunun; ancak bu faktörleri de phishing’e dayanıklı hale getirmeyi hedefleyin.
- Veritabanınızda publicKey, credentialId, signCount, transports, aaguid gibi alanları saklayın; ileride politika kararları için faydalıdır.

Test, Hata Ayıklama ve Ölçüm

Geliştirme sırasında tarayıcının geliştirici araçlarındaki WebAuthn panelini kullanın; sanal güvenlik anahtarlarıyla senaryoları çoğaltabilirsiniz. Kayıt ve giriş akışlarında challenge ömrü, origin eşleşmesi ve base64url dönüşümleri en sık hata yapılan noktalardır. Üretimde ise başarısızlık oranı, adım terk ve cihaz/OS dağılımı gibi metrikleri izleyip sürtünme noktalarını azaltın.

Sonuç: Daha Güvenli ve Daha Hızlı Giriş

Passkey, hem güvenliği hem de kullanıcı deneyimini aynı anda iyileştiren nadir teknolojilerden biri. Parola sıfırlama süreçleri, bot saldırıları ve sahte giriş sayfalarıyla uğraşmak yerine, kökünden daha sağlam bir mimariye geçiyorsunuz. Küçük bir pilot kuvvetle başlayıp kullanıcı kitlenizin cihaz dağılımını ölçün; ardından parolasız girişe kademeli geçiş stratejisi belirleyin. Doğru uygulandığında, yardım masası yükü azalır, giriş süreleri kısalır ve dönüşüm oranları gözle görülür biçimde artar.

Passkeys (WebAuthn) ile Şifresiz Giriş: Next.js ve Node.js Üzerinde Adım Adım

Passkeys nedir ve neden şimdi?

Şifre yorgunluğu, kimlik avı ve parola sızıntıları artık sıradan hale geldi. Passkeys, yani WebAuthn ve FIDO2 tabanlı şifresiz kimlik doğrulama, bu sorunları kökten çözen modern bir yaklaşım. Apple, Google ve Microsoft ekosistemlerinde yerleşik çalışırken, kullanıcılar cihazlarının biyometrisini (Face ID, Touch ID, Windows Hello) veya güvenlik anahtarlarını kullanarak güvenli ve tek dokunuşla giriş yapabiliyor. Bu yazıda, Next.js ve Node.js üzerinde Passkeys entegrasyonunu adım adım anlatacağım.

Mimari ve çalışma mantığı

Passkeys, asimetrik kriptoya dayanır: cihaz üzerinde üretilen bir özel anahtar ve sunucuda saklanan açık anahtar. Kayıt (registration) sırasında cihaz, alan adınıza (RP ID) bağlı bir anahtar çifti üretir ve attestation ile birlikte sunucuya gönderir. Giriş (authentication) aşamasında ise sunucu bir challenge üretir; cihaz bu challenge’ı özel anahtarla imzalar ve sunucu açık anahtarla doğrular. Şifre yok, gizli veri sunucuya taşınmıyor ve kimlik avına dayanıklı bir akış elde ediliyor.

Önkoşullar

1) Üretimde mutlaka HTTPS kullanın.
2) RP ID, alan adınızla birebir uyumlu olmalı (örn. example.com).
3) Tarayıcı desteği: Modern Chrome, Safari, Firefox sürümleri WebAuthn destekliyor.
4) En az bir authenticator (platform: telefon/bilgisayar; roaming: YubiKey).
5) Node.js 18+ ve Next.js 13+ önerilir.
6) Sunucuda rastgele ve tekil challenge üretecek bir mekanizma (ör. crypto.randomBytes) ve doğrulama için bir kütüphane (örn. @simplewebauthn/server) kullanın.

Kayıt (Registration) akışı

1. Kullanıcıyı başlatın: Kullanıcı e-postası veya kullanıcı adıyla kayıt talebi gönderir.
2. Sunucu challenge üretir: RP bilgileriyle birlikte options döner: rp.id, rp.name, user.id (stabil benzersiz ID), user.name, pubKeyCredParams, attestation, timeout.
3. İstemci oluşturma isteği: Tarayıcıda navigator.credentials.create({ publicKey: options }) çağrısı yapılır.
4. Sunucu doğrular: İstemciden gelen attestation yanıtı (id, rawId, response.attestationObject, clientDataJSON) sunucuda doğrulanır. Başarılıysa credentialId, publicKey, signCount ve kullanıcıyla ilişkilendirilerek veritabanına kaydedilir.

Örnek sunucu mantığı (özet):
// /api/webauthn/register/options
const options = generateRegistrationOptions({ rpID, rpName, userID, userName });
storeChallenge(userID, options.challenge);
return options;

// /api/webauthn/register/verify
const verification = verifyRegistrationResponse({ response, expectedRPID: rpID, expectedOrigin, expectedChallenge });
if (verification.verified) saveCredential(userID, verification.registrationInfo);

Giriş (Authentication) akışı

1. Sunucu assertion options üretir: registered credentialId’leri, rpID ve challenge içeren options döndürür.
2. İstemci doğrulama isteği: navigator.credentials.get({ publicKey: options }) çağrısı çalışır. Kullanıcı biyometri/güvenlik anahtarıyla onay verir.
3. Sunucu doğrular: İmza (signature), authenticatorData ve clientDataJSON kullanılarak open-key üzerinde imza doğrulanır.
4. Sayaç kontrolü: authenticator signCount önceki değerden küçükse tekrar saldırısı şüphesi doğar; oturumu reddedin. Başarılıysa kullanıcıyı oturum açmış sayın.

Örnek sunucu mantığı (özet):
// /api/webauthn/login/options
const options = generateAuthenticationOptions({ rpID, allowCredentials: userCredIds });
storeChallenge(userID, options.challenge);
return options;

// /api/webauthn/login/verify
const verification = verifyAuthenticationResponse({ response, expectedRPID: rpID, expectedOrigin, expectedChallenge, authenticator });
if (verification.verified) updateSignCount(authenticator, verification.authenticationInfo.newCounter);

Next.js tarafında istemci akışı

Next.js App Router ile, client component içinde WebAuthn çağrılarını başlatabilirsiniz. Kayıtta: sunucudan options’ı fetch edin, navigator.credentials.create ile yanıtı alın ve verify endpoint’ine POST edin. Girişte: benzer şekilde options alıp navigator.credentials.get çağırın. Hata yönetimi için kullanıcıya net mesajlar gösterin (ör. “Bu cihazda passkey yok, lütfen yeni bir passkey oluşturun”).

Güvenlik ve en iyi uygulamalar

- Origin ve RP ID uyuşmazlıklarını önleyin; staging/prod için ayrı ayar kullanın.
- Challenge değerleri kriptografik rastgele ve tek kullanımlık olmalı.
- Attestation politikasını belirleyin: “none”, “indirect” veya belirli üretici politikaları.
- Çoklu cihaz desteği için bir kullanıcıya birden fazla credential bağlayın.
- Yedekleme/kurtarma senaryosu için platform passkey + güvenlik anahtarı kombinasyonunu teşvik edin.
- Oturum çerezi/Token için HttpOnly, Secure ve SameSite ayarlarını doğru yapılandırın.

Kullanıcı deneyimi ipuçları

- Conditional UI (Chrome) ile otomatik Passkey doldurma akışını etkinleştirin; login sayfasında kullanıcı adı sormadan hızlı giriş sunar.
- Parolayı gizli seçenek olarak sunun; öncelik Passkey akışında olsun.
- Kullanıcıya “Bu cihazda passkey oluştur” veya “Farklı cihazla tara” gibi net eylemler verin.
- Mobilde QR tabanlı çapraz cihaz akışlarını destekleyin; tarayıcılar yerleşik olarak buna hazır.

Performans ve gözlemleme

WebAuthn işlemleri genellikle milisaniyeler içinde biter, ancak ağ gecikmesi ve attestation doğrulaması süresini izleyin. Kayıt ve giriş sürelerini ölçmek için basit metrikler (options fetch süresi, create/get süresi, verify süresi) tutun. Başarısızlık oranlarını izlemek, cihaz/OS bazlı hataları hızlıca ayrıştırmanızı sağlar.

Sonuç

Passkeys, güvenliği artırırken kullanıcı deneyimini de iyileştirir. Next.js ve Node.js üzerinde WebAuthn/FIDO2 ile kuracağınız şifresiz giriş çözümü, kimlik avına dirençli, hızlı ve modern bir oturum açma deneyimi sunar. Yukarıdaki mimari ve akışla kısa sürede üretim seviyesinde bir entegrasyon geliştirebilir, parolalara veda ederken dönüşüm oranlarınızı artırabilirsiniz.

Docker Buildx ile Çok Mimarili (AMD64 + ARM64) Container İmajı Yayınlama: Adım Adım Rehber

Giriş

Apple Silicon (ARM64) makinelerin ve bulut ortamlarında ARM sunucuların yaygınlaşmasıyla, tek mimariye (örneğin yalnızca AMD64) derlenen imajlar kullanıcı deneyimini ve dağıtımı zorlaştırıyor. Docker Buildx, tek komutla birden fazla mimari için (AMD64, ARM64, ARMv7 vb.) imaj üretmeyi ve tek bir manifest altında yayımlamayı kolaylaştırıyor. Bu yazıda, yerelde ve GitHub Actions ile CI/CD hattında çok mimarili imaj oluşturmayı, cache kullanmayı, SBOM/provenance üretmeyi ve sık karşılaşılan sorunları çözmeyi adım adım ele alacağım.

Neden Çok Mimarili İmaj?

- Kullanıcı kapsama alanı: Hem x86_64 (AMD/Intel) hem ARM64 (Apple M-serisi, Graviton) sistemlerde sorunsuz çalışır.

- Performans ve maliyet: ARM altyapılarında daha düşük maliyet ve daha iyi watt başına performans elde edilebilir.

- Tek etiket, çok platform: Manifest listesi sayesinde docker pull myorg/app:latest komutu, çalıştığınız platforma uygun imajı otomatik çeker.

Ön Koşullar

- Docker 24+ ve Buildx etkin (Docker Desktop kullanıyorsanız Buildx varsayılan gelir).

- Registry erişimi: Docker Hub, GitHub Container Registry (GHCR) veya özel bir OCI uyumlu kayıt defteri.

- Yerel testlerde emülasyon gerekebilir; QEMU binfmt kurulu olmalı. Docker Desktop bunu genellikle otomatik sağlar.

Yerelde Buildx ile Çok Mimarili Build

1) Bir Buildx builder oluşturun ve kullanın: docker buildx create --name multiarch --use ve ardından docker buildx inspect --bootstrap. Bu adım BuildKit’i ve platform desteğini başlatır.

2) Emülasyon (gerekiyorsa): Linux makinelerde yoksa docker run --privileged --rm tonistiigi/binfmt --install all komutuyla QEMU kurabilirsiniz. Docker Desktop kullananlar çoğu zaman bu adımı atlayabilir.

3) Çoklu platform build ve push: Örneğin docker login ile kayıt defterine giriş yaptıktan sonra docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/kullanici/uygulama:1.0 -t ghcr.io/kullanici/uygulama:latest --push . komutunu çalıştırın. Bu komut, her iki mimari için imaj üretir, registry’ye yükler ve tek bir manifest altında birleştirir.

4) Doğrulama: docker buildx imagetools inspect ghcr.io/kullanici/uygulama:latest çıktısında manifest içinde AMD64 ve ARM64 platformlarını görmelisiniz.

Dockerfile İpuçları (TARGETPLATFORM ve BUILDPLATFORM)

- Çok mimaride tutarlı build’ler için Dockerfile’ın başına ARG TARGETPLATFORM ve ARG BUILDPLATFORM ekleyin. Bazı taban imajlarını seçerken bu argümanlar kritik olabilir.

- Derleme araçları içeren çok aşamalı bir yaklaşım kullanın: “builder” aşamasında derleyin, “runtime” aşamasında minimal taban imajına kopyalayın.

- Go/Node/Python gibi ekosistemlerde platforma duyarlı bağımlılıklar için koşullu adımlar planlayın. Örneğin Go’da CGO kullanıyorsanız uygun CC ve GOARCH ayarlarını set edin.

GitHub Actions ile Otomasyon

CI/CD sürecinde multi-arch build için tipik adımlar: QEMU kurulum, Buildx hazırlığı, registry’ye giriş, build-push ve cache. Örnek akış şu şekildedir:

- QEMU: docker/setup-qemu-action@v3 ile arm64 ve amd64 emülasyonunu etkinleştirin.

- Buildx: docker/setup-buildx-action@v3 ile bir builder oluşturun.

- Registry Login: docker/login-action@v3 ile Docker Hub veya GHCR’a giriş yapın.

- Build & Push: docker/build-push-action@v5 ile platforms=linux/amd64,linux/arm64, push=true, tags alanlarını doldurun. Ön bellek için cache-from=type=gha ve cache-to=type=gha,mode=max kullanın. Yazılım tedarik zinciri metadatası için provenance=mode=max ve sbom=true parametrelerini etkinleştirin.

- Semantik etiket: 1.2.3, 1.2 ve latest gibi çoklu etiket yayınlayarak tüketimi kolaylaştırın.

Cache ve Performans

- Build sürelerini kısaltmak için katmanları sabitleyin ve gereksiz dosyaları kopyalamayın (örn. .dockerignore kullanın).

- Registry tabanlı cache ile farklı runner’larda bile hız kazanın. BuildKit GHA cache, büyük monorepo’larda ciddi fayda sağlar.

- Dil/araç cache’leri (Go mod, npm ci, pip cache) için katman sırasını optimize edin; bağımlılıkların daha az değiştiği katmanları üstte tutun.

Güvenlik: SBOM ve Provenance

- SBOM (Software Bill of Materials) ve provenance, tedarik zinciri görünürlüğü sağlar. Buildx ile oluşturulan attestation’lar, imaj içeriğini ve nasıl üretildiğini kanıtlar.

- Gerektiğinde imza eklemek için Cosign gibi araçları entegre edin. İmajlarınızı politikalarla (örn. Kyverno, Tekton Chains) doğrulayabilirsiniz.

Yaygın Hatalar ve Çözümleri

- Exec format error: Genellikle QEMU/binfmt kurulmadığında veya emülasyon devre dışı olduğunda görülür. QEMU’yu yeniden yükleyin ve Buildx builder’ı --bootstrap ile yenileyin.

- Yerel bağımlılıklar: Node-gyp, Python C uzantıları gibi bileşenler mimariye duyarlıdır. Derleme aşamasında uygun derleyicilerin ve kütüphanelerin kurulduğundan emin olun.

- Taban imaj uyumsuzluğu: Bazı hafif taban imajlar (distroless, alpine) belirli mimarilerde ek paket gerektirebilir. İmaj seçiminde --platform ile test edin, mümkünse resmi çok mimarili taban imajları tercih edin.

- Performans: Emülasyon ile derleme yavaştır. Mümkünse native ARM64 ve AMD64 runner’lar kullanın (örn. karma self-hosted runner filosu).

Sonuç

Docker Buildx, modern dağıtım ihtiyaçları için kritik olan çok mimarili imajları üretmenin en pratik yolu. Yerelde basit bir builder ve gerektiğinde QEMU ile başlayabilir, üretim ortamında GitHub Actions gibi bir CI/CD hattı üzerinden cache, SBOM ve provenance özellikleriyle güvenli ve hızlı yayın yapabilirsiniz. Sonuçta tek bir etiketle her platformda çalışan imajlar sunar, kullanıcı deneyimini iyileştirir ve operasyonel karmaşıklığı azaltırsınız.

OpenTelemetry ile Node.js Uygulamalarında Dağıtık İzleme: OTLP, Grafana Tempo ve Prometheus Entegrasyonu

OpenTelemetry Nedir ve Neden Önemli?

Modern mikroservis mimarilerinde tek bir isteğin birçok servis, kuyruk ve veri deposu üzerinden akması sıradan bir durum haline geldi. Bu akıştaki gecikmeleri, hataları ve dar boğazları anlamanın en güvenilir yolu, dağıtık izleme (distributed tracing), metrik ve log verilerini bir arada toplayıp ilişkilendirmektir. OpenTelemetry (OTel), bu ihtiyacı standartlaştıran açık kaynak bir çatı sunar. Node.js projelerinde OTel kullanarak HTTP isteklerini, veritabanı çağrılarını ve iç fonksiyonlarınızı otomatik veya manuel olarak izleyebilir, verileri OTLP üzerinden Grafana Tempo ve Prometheus gibi sistemlere aktarabilirsiniz.

Mimari: SDK, Collector ve Gözlemleme Katmanı

Basit ve güvenilir bir kurulum için üç katman önerilir: (1) Uygulama içinde @opentelemetry/sdk-node ve otomatik enstrümantasyon paketleri çalışır. (2) Veriler OTLP ile OpenTelemetry Collector’a gönderilir. (3) Collector, gelen trace’leri Tempo’ya, metric’leri Prometheus’a, tercihen log’ları da Loki’ye yönlendirir. Böylece uygulama sadece bir hedefi bilir ve detayları Collector yönetir; yapılandırma değişiklikleri için uygulamayı yeniden dağıtmanız gerekmez.

Ön Koşullar ve Temel Kurulum

- Node.js 18+ önerilir, çünkü AsyncLocalStorage ile bağlam yayılımı daha stabil ve hızlıdır. Paket yöneticisi olarak npm, pnpm ya da yarn kullanabilirsiniz.

- Projenizde hizmet adını ve ortamı belirlemek için şu ortam değişkenlerini ayarlayın: OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod. OTLP hedefi için Collector URL’niz genelde http://otel-collector:4318 (HTTP) veya 4317 (gRPC) olacaktır.

- OTel’i uygulamanın en erken aşamasında, sunucu başlatılmadan önce başlatın. Örneğin tracing.js dosyanızı ilk import eden dosya yapın; aksi halde bazı framework etkinlikleri enstrümante edilemez.

Otomatik ve Manuel Enstrümantasyon

Node.js tarafında @opentelemetry/auto-instrumentations-node HTTP, gRPC, Express, Fastify, MySQL, PostgreSQL, Redis gibi popüler bileşenleri otomatik izler. Bu sayede hiçbir kod yazmadan gelen istekler, giden HTTP çağrıları ve DB sorguları için span’ler oluşturulur. Kritik işlevlerinizde daha detaylı görünürlük istiyorsanız manuel enstrümantasyonla özel span’ler açıp önemli değişkenleri attribute olarak ekleyebilirsiniz. Örneğin sipariş tutarı, sepet boyutu veya kampanya kodu gibi iş metriklerini PII içermeyecek şekilde iliştirmek, kök nedeni çözmede büyük avantaj sağlar.

Örnek Yapılandırma Prensipleri

- Sampler: Üretimde yüzde 100 örnekleme pahalı olabilir. ParentBasedTraceIdRatio gibi oran bazlı sampler kullanın; giriş noktalarında yüzde 5-10, hata kodlarında ise koşullu olarak yüzde 100 örnekleme tercih edebilirsiniz.

- Propagator: Varsayılan W3C Trace Context yeterlidir. Hizmet zincirindeki tüm servislerin aynı propagatörü kullanması span bağlarının korunmasını sağlar.

- Resource Nitelikleri: service.name, service.version, deployment.environment, cloud.region gibi alanları doldurun. Sürüm numarası (örn. git SHA) hata takibinde altın değerindedir.

- OTLP Exporter: HTTP veya gRPC kullanılabilir. Kurumsal ağlarda HTTP genellikle daha sorunsuzdur. Timeouts ve yeniden deneme ayarlarını Collector’a bırakmak, uygulama üzerinde yükü azaltır.

OpenTelemetry Collector İpuçları

Collector, performans ve güvenilirlik için kritik bir bileşendir. Girişte otlp receiver, ortada batch ve attributes processor’ları, çıkışta tempo ve prometheus exporter’ları kullanılır. Batch, küçük span’lerin birikerek verimli gönderilmesini sağlar. Attributes processor ile gereksiz ya da hassas alanları (örn. e-posta, telefon) maskeleyebilir veya kaldırabilirsiniz. Tempo tarafında multi-tenant ihtiyaç varsa tenant başına service.name veya header tabanlı ayırma stratejisi kullanın.

Grafana Tempo ve Prometheus Entegrasyonu

Tempo, span verilerini ölçeklenebilir şekilde tutar ve Grafana ile mükemmel entegredir. Grafana’da “Explore” bölümünden trace ID ile arama yapabilir, isteklerin gecikme dağılımını görebilir ve sorunlu hizmeti hızlıca belirleyebilirsiniz. Metrikler için Prometheus, Node.js ve Collector’dan gelen ölçümleri toplayarak p95/p99 gecikme, hata oranı ve istek hacmini panolarda görselleştirir. Traces ile metrics arasında exemplar köprüleri kurduğunuzda, grafikteki bir pik noktasından ilgili trace’e tek tıkla bağlanabilirsiniz.

Performans, Maliyet ve Güvenlik

- Overhead: Otomatik enstrümantasyonun CPU/GC etkisi genellikle düşüktür, ancak sıcak yol (hot path) fonksiyonlarda manuel span açmayı sınırlayın. Toplayıcıda batch boyutlarını ve flush aralıklarını gözden geçirerek ağ trafiğini optimize edin.

- Maliyet: Oran bazlı örnekleme ve hata odaklı dinamik örnekleme ile depolama ve sorgu maliyetlerini kontrol altında tutun. Geliştirme ve staging ortamlarında daha yüksek oran, üretimde daha düşük oran kullanmak iyi bir dengedir.

- Gizlilik: PII ve gizli anahtarları span attribute’larına koymayın. Collector’da maskeleme kuralları ekleyin. Log ve trace korelasyonu yaparken veri minimizasyonuna dikkat edin.

Hata Ayıklama ve Yaygın Sorunlar

- Bağlam Kaybı: Özellikle eski Promise zincirlerinde veya üçüncü taraf kütüphanelerde bağlam kaybı olabilir. Node 18+ ve AsyncLocalStorage ile bu sorun büyük ölçüde azalır. Framework düzeyinde middleware sırasını kontrol edin.

- Eksik Span’ler: Uygulamada OTel başlatma dosyasının en önce import edildiğinden emin olun. Sunucu başlatma komutunuzda -r ./tracing.js gibi bir preload yaklaşımı kullanmak güvenilirdir.

- Gönderim Hataları: Collector’a ulaşamıyorsanız firewall veya servis keşfi sorunlarını kontrol edin. OTLP gRPC ile MTLS yapılandırıyorsanız sertifika yollarını ve SNI ayarlarını doğrulayın.

Sonuç

OpenTelemetry, Node.js uygulamalarınızda uçtan uca görünürlük sağlayarak sorun tespiti ve performans optimizasyonunu hızlandırır. Uygulama içinde hafif bir SDK, merkezde güçlü bir Collector ve gözlemleme katmanında Tempo/Prometheus kombinasyonu ile maliyet-etkin, taşınabilir ve geleceğe dönük bir çözüm elde edersiniz. Doğru örnekleme, sağlam kaynak nitelikleri ve sıkı gizlilik politikaları ile ekipler hem geliştirici deneyimini hem de kullanıcı memnuniyetini anlamlı biçimde artırabilir.

WebGPU ile Tarayıcıda Gerçek Zamanlı Nesne Tespiti: ONNX Runtime Web ile Adım Adım

Giriş

Tarayıcıda yapay zekâ çalıştırmak, yerel gizlilik, düşük gecikme ve kurulum gerektirmeyen dağıtım gibi avantajlar sunuyor. WebGPU’nun olgunlaşması ve ONNX Runtime Web’in hızla gelişmesi sayesinde, bugün artık masaüstü veya sunucuya gerek duymadan tarayıcı içinde gerçek zamanlı nesne tespiti mümkün. Bu yazıda, WebGPU ve ONNX Runtime Web kullanarak YOLO tabanlı hafif bir modelle, sıfırdan çalışan bir demo kurulumunun nasıl yapılacağını, performans ipuçlarını ve dikkat edilmesi gereken noktaları adım adım anlatıyorum.

Gereksinimler ve Hazırlık

Öncelikle güncel bir tarayıcıya ihtiyacınız var. WebGPU için Chrome/Edge 121+ tavsiye edilir; bazı cihazlarda WebGPU devre dışı olabilir, bu durumda ONNX Runtime Web otomatik olarak WASM (WebAssembly) yürütücüsüne düşebilir. Uygulamanızı HTTPS üzerinden ve mümkünse yerel geliştirmede localhost ile çalıştırın. Kamera erişimi için getUserMedia iznine de ihtiyaç olacak.

Proje Kurulumu

Hızlı başlamak için Vite kullanacağız. Terminalde aşağıdaki adımları izleyin:
1) npm create vite@latest webgpu-onnx-demo -- --template vanilla
2) cd webgpu-onnx-demo
3) npm install onnxruntime-web
4) npm install ve ardından npm run dev ile geliştirme sunucusunu başlatın.

Model Seçimi ve Dosya Yapısı

Tarayıcı için hafif bir model seçmek kritik. YOLO ailesinden yolov8n veya benzeri küçük bir ONNX modeli başlangıç için ideal. Model dosyasını projenizde public/models/yolov8n.onnx gibi bir yola koyun. Eğer int8/FP16 gibi quantized sürüm elinizde varsa performans kazanabilirsiniz; WebGPU bu tür ağlarda ciddi hız kazandırır.

ONNX Runtime Web ile Oturum Oluşturma

Tarayıcıda model çalıştırmak için onnxruntime-web kütüphanesi tek noktadan çözüm sunar. Basit bir başlatma şeması şöyle olabilir: import * as ort from 'onnxruntime-web' ardından const session = await ort.InferenceSession.create('/models/yolov8n.onnx', { executionProviders: ['webgpu', 'wasm'] }). Bu yapı, WebGPU destekliyse GPU’yu, değilse WASM’ı kullanır. Uygulama açılışında bir kez oturum oluşturup bellekte tutmak başlangıç gecikmesini azaltır.

Görüntü Kaynağı ve Ön İşleme

Kameradan akış almak için navigator.mediaDevices.getUserMedia({ video: { facingMode: 'environment' } }) kullanın. Video karesini bir canvas üzerine çizip modelin beklediği çözünürlüğe (örneğin 640x640) yeniden boyutlandırın. Piksel verisini canvas.getContext('2d').getImageData(...) ile alın, RGB sırasına getirip 0-1 aralığına normalize edin ve tensörü NCHW formatında Float32Array olarak oluşturun. ONNX’a beslemek için new ort.Tensor('float32', data, [1, 3, 640, 640]) şeklinde bir tensör üretin.

Çıktı Sonrası İşleme (Post-Processing)

YOLO benzeri modellerin çıktısı genellikle kutular, sınıf olasılıkları ve skorlar içerir. Sigmoid/Softmax dönüşümlerini uyguladıktan sonra bir Non-Maximum Suppression (NMS) adımı gerekir. NMS için IoU eşiğini (ör. 0.45) ve skor eşiğini (ör. 0.25) kendiniz belirleyin. Tarayıcı performansı için döngüleri optimize edin, mümkünse tek tip diziler (Float32Array) ve önceden ayrılmış tamponlar kullanın.

Çalıştırma Döngüsü ve Çizim

Her karede sırasıyla: videodan canvas’a çizim → ön işleme → session.run(feeds) → post-processing → kutuları ve etiketleri ikinci bir overlay canvas’ına çizim. Çizim için requestAnimationFrame kullanarak akıcı bir döngü yakalayın. WebGPU yürütücüsü açıkken orta sınıf bir dizüstünde 30 FPS ve üzeri değerlere ulaşmak mümkün; WASM yolunda ise 8-15 FPS aralığı gerçekçi bir beklentidir.

Performans İpuçları

1) Web Worker + OffscreenCanvas: Ön işleme ve NMS’i bir Worker içine alarak ana iş parçacığını boşaltabilirsiniz. OffscreenCanvas ile çizimleri de iş parçacığı dışında yapmak mümkün.
2) Isınma (Warm-up): Uygulama açılışında bir yapay girişle bir kez session.run çağırarak ilk kare gecikmesini düşürün.
3) Boyut ve Oran: Giriş çözünürlüğünü cihaz gücüne göre 320, 480, 640 şeklinde seçin. Düşük çözünürlük daha yüksek FPS demektir.
4) Kuantizasyon: FP16 veya INT8 modellerle hem bant genişliği hem de hesap yükünü azaltırsınız. WebGPU ile özellikle FP16 iyi sonuç verir.
5) Bellek Yönetimi: Her karede yeni dizi oluşturmak yerine tamponları yeniden kullanın; gereksiz GC duraklamalarını önleyin.

WebGPU Özel Notlar

Bazı cihazlarda navigator.gpu görünse bile adaptör kısıtları performansı etkileyebilir. adapter = await navigator.gpu.requestAdapter() ve device = await adapter.requestDevice() çağrılarında hata yakalama koyun. Uzun süren işlemlerde device.lost olayını dinleyip yeniden kurulum yapın. Ayrıca, farklı GPU sürücülerinde küçük nüanslar olabilir; kritik bölümlerde tarayıcı konsolunu takip edin.

WASM Yürütücüsü İçin Ek Ayarlar

WebGPU devre dışıysa ONNX Runtime Web’in WASM yürütücüsü devreye girer. graphOptimizationLevel: 'all' gibi seçeneklerle optimizasyonu artırın. Bazı SIMD hızlandırmaları için COOP/COEP başlıkları gereklidir; üretimde sunucu yapılandırmanızı Cross-Origin-Opener-Policy: same-origin ve Cross-Origin-Embedder-Policy: require-corp ile güncellemeyi düşünün. Bu sayede WASM SIMD ve bazı paralel özellikler etkin hale gelir.

Hata Ayıklama ve Ölçüm

FPS’i ölçmek için basit bir sayaç yazın ya da PerformanceObserver kullanın. ONNX katman sürelerini anlamak için giriş/çıkış zamanlarını konsola basmak yeterli olur. Çıktılar boşsa ilk bakacağınız yer ön işleme adımıdır: kanal sırası (NCHW/NHWC), normalize edilmemiş değerler veya çözünürlük uyuşmazlığı genellikle sorumludur.

WebGL mi, WebGPU mu?

WebGL tabanlı çözümler hâlâ iş görse de, makine öğrenmesi iş yüklerinde WebGPU ile daha tutarlı ve modern bir performans elde ediliyor. ONNX Runtime Web’in WebGPU yürütücüsü, operator kapsamını genişlettikçe fark daha da açılıyor. Kısacası, uzun vadede WebGPU tercih etmek mantıklı.

Sonuç

Bu rehberle, WebGPU ve ONNX Runtime Web kullanarak tarayıcıda gerçek zamanlı nesne tespiti uygulamasını uçtan uca kurmanın temel adımlarını gördük. Doğru model, dikkatli ön/post-işleme ve küçük optimizasyonlarla akıcı bir deneyim elde edebilirsiniz. Üstelik tümü istemci tarafında çalıştığı için gizlilik ve dağıtım kolaylığı cabası. Bir sonraki adım olarak, izleme (tracking), bölütleme (segmentation) veya metin çıkarımı (OCR) gibi ek yetenekleri aynı altyapı üzerinde denemeyi düşünebilirsiniz.

Laptopta Yerel LLM Çalıştırma Rehberi: Ollama ile GPU Hızlandırmalı RAG Kurulumu (2025)

Giriş

Üretken yapay zekâ servislerini bulut yerine kendi bilgisayarınızda çalıştırmak hem gizliliği artırıyor hem de maliyeti düşürüyor. Son aylarda adını sıkça duyduğumuz Ollama, yerel LLM çalıştırmayı son derece pratik hâle getiriyor. Bu rehberde, laptop veya masaüstünüzde GPU hızlandırmalı bir kurulum yapacak, ardından basit bir RAG (Retrieval Augmented Generation) akışı kurgulayarak kendi belgeleriniz üzerinde akıllı arama ve soru-cevap deneyimi oluşturacağız. Tüm adımlar sade ve SEO dostu bir “how-to” olarak planlandı.

Sistem Gereksinimleri ve Model Seçimi

Modern bir CPU ve en az 16 GB RAM önerilir. GPU tarafında NVIDIA (CUDA) veya Apple Silicon (Metal) destekleri performansı ciddi biçimde artırır. Disk alanınızın en az 10–20 GB boş olması faydalıdır. Model seçerken boyut-kalite dengesine dikkat edin: llama3:8b veya mistral:7b gibi 7–8B modeller, 4-bit kuantizasyonla çoğu senaryoda iyi sonuç verir. Daha ciddi analizler için 13B üstü modellere yönelebilirsiniz, ancak VRAM ve RAM kullanımınız artacaktır.

Ollama Kurulumu

macOS üzerinde brew install ollama ile kurulumu tamamlayabilirsiniz. Windows için resmi yükleyiciyi tercih edin (Ollama sitesinden .exe indirerek). Linux’ta ise curl -fsSL https://ollama.com/install.sh | sh komutu işinizi görecektir. Kurulumdan sonra servisi başlatmak için ollama serve komutunu çalıştırın; arka planda http://localhost:11434 adresinde bir API sunucusu açılır.

İlk Modeli İndirme ve Çalıştırma

Örnek olarak Llama 3’ün 8B sürümünü indirelim: ollama pull llama3:8b. Ardından hızlı bir test için ollama run llama3:8b komutunu çalıştırın. Komut satırında modele doğrudan soru sorabilirsiniz. Türkçe anlama ve yanıt üretimi konusunda tatmin edici sonuçlar için sistem talimatını kısa bir bağlamla başlatmanız iyi olur; örneğin “Türkçe, kısa ve teknik yanıt ver” gibi bir içerikle diyaloğu yönlendirin.

GPU Hızlandırma İpuçları

Apple Silicon (M1/M2/M3) cihazlarda Metal desteği otomatik devreye girer. NVIDIA tarafında en iyi sonuç için güncel CUDA ve cuDNN sürümlerini kurun, ardından ortam değişkenleriyle ince ayar yapın. Örneğin, OLLAMA_NUM_GPU=1 ile kaç GPU kullanılacağını sınırlandırabilir, OLLAMA_MAX_LOADED_MODELS=1 ile aynı anda yüklenen model sayısını azaltarak VRAM taşmalarını önleyebilirsiniz. Ayrıca 4-bit kuantize sürümler (Q4_K_M benzeri) daha az bellek tüketir; ilk denemelerde bunları tercih etmek stabilite sağlar.

RAG Nedir ve Neden Gerekli?

RAG, modelin kendi parametrelerinde olmayan güncel veya özel bilgiyi, harici bir bilgi tabanından anlık olarak alıp yanıtları zenginleştirmesini sağlar. Örneğin, şirket içi dokümanlarınızı veya notlarınızı vektör dizinine (vector store) dönüştürür, sorgu anında en uygun parçaları çekip modele “bağlam” olarak verirsiniz. Böylece hallucination azalır, doğruluk artar.

Basit RAG Akışı: Adım Adım

1) Belgeleri Hazırla: PDF, Markdown veya düz metin dosyalarınızı tek bir klasörde toplayın. Büyük dosyaları ~500–1000 token’lık parçalara bölmek arama kalitesini artırır.

2) Embedding Modelini Çek: Ollama içinden bir gömme modeli indirin: ollama pull nomic-embed-text veya çok dilli kullanım için all-minilm benzeri alternatifleri deneyin.

3) Vektör Üret: Hızlı bir test için Ollama’nın HTTP API’sini kullanabilirsiniz. Örnek bir istek: curl -s http://localhost:11434/api/embeddings -d '{"model":"nomic-embed-text","input":"Merhaba dünya"}'. Script ile belgelerinizi satır satır embed ederek bir JSONL çıktısı oluşturabilirsiniz.

4) Vektör Dizini Kur: Hafif bir çözüme ihtiyaç varsa Chroma veya FAISS gibi kütüphaneleri tercih edin. Python tarafında pip install chromadb ile başlayabilir, vektörleri ve metin parçalarını koleksiyonlara ekleyebilirsiniz. Alternatif olarak SQLite tabanlı vektör eklentileri (ör. sqlite-vss) yerel, dosya tabanlı bir yaklaşım sunar.

5) Sorgu ve Geri Getirme: Kullanıcı sorgusunu aynı embedding modeliyle vektöre çevirin, en benzer N doküman parçasını bulun ve bu parçaları model istemine (prompt) “bağlam” olarak ekleyin. Ardından curl -s http://localhost:11434/api/generate veya ollama run llama3:8b üzerinden, oluşturduğunuz bağlamı içeren bir istemle yanıt üretin.

Performans ve Doğruluk İçin İnce Ayar

- Daha hızlı yanıt için kısa bağlam ve az sayıda parça ile deneyin; gerekirse N değerini 3–5 aralığında tutun. Uzun bağlamlar, özellikle küçük modellerde kaliteyi bazen düşürebilir.

- Top-k ve top-p örnekleme ayarları ile yaratıcılık/kararlılık dengesini kurun. Kritik teknik metinlerde deterministikliğe yakın ayarlar tercih edin.

- Kaynak parçaları yanıtın sonunda listeler veya dipnotlar olarak ekletin. Bu hem şeffaflık sağlar hem de güveni artırır. İstemde “Kaynaklardan alıntı yap ve bağlantı ver” gibi net talimatlar verin.

Güvenlik ve Gizlilik

Yerel kurulumun en büyük artısı verilerin bilgisayarı terk etmemesidir. Yine de hassas belgelerle çalışırken disk şifrelemesi, güçlü oturum açma yöntemleri ve düzenli yedekleme kullanın. Eğer API’nizi ağ üzerinden açacaksanız bir ters proxy arkasında kimlik doğrulama ekleyin. Model ve embedding versiyonlarını not edin; üretim senaryosunda değişikliklerin etkisini takip etmek için versiyonlama kritiktir.

Sonuç

Ollama ile yerel LLM kurmak, düşündüğünüzden daha hızlı ve verimli. Küçük bir embedding modeli ve hafif bir vektör diziniyle kuracağınız RAG katmanı, kişisel notlarınızdan teknik dokümanlara kadar geniş bir bilgi tabanını akıllıca sorgulamanıza imkân tanır. Donanımınıza göre doğru model ve kuantizasyonu seçip GPU hızlandırmayı aktifleştirdiğinizde, bulut bağımlılığını azaltan, düşük gecikmeli ve gizlilik dostu bir üretken yapay zekâ deneyimi elde edersiniz. İlk POC’yi başarıyla tamamladıktan sonra; bir REST arayüzü ekleyip arka planda planlanmış yeniden indeksleme görevleri ve log analiziyle yapınızı olgunlaştırabilirsiniz.

Tarayıcıda Yerel Yapay Zeka: WebGPU ve ONNX Runtime Web ile Görsel Sınıflandırma Nasıl Çalıştırılır?

Özet ve Neden Önemli?

Tarayıcıda çalışan yapay zeka, gizlilik, gecikme ve kullanıcı deneyimi açısından oyunun kurallarını değiştiriyor. WebGPU ile birlikte ONNX Runtime Web kullanarak bir görsel sınıflandırma modelini tamamen istemcide, yani kullanıcının cihazında çalıştırabilirsiniz. Böylece veriler sunucuya gönderilmez, ağ gecikmesi azalır ve uygulama çevrimdışı senaryolarda dahi işlevini sürdürür. Bu yazıda, sıfırdan bir ön yüz projesine WebGPU destekli ONNX Runtime Web ekleyerek, bir görüntüyü sınıflandırma adımlarını sade ama teknik açıdan tatmin edici bir şekilde ele alacağız.

Gereksinimler ve Mimari

WebGPU, modern tarayıcılarda donanım hızlandırmalı hesaplamaya erişmek için tasarlanmış, Vulkan/Metal/DX12 benzeri bir grafik ve hesap arayüzüdür. Chrome ve Edge’de kararlı; Safari’de Technology Preview; Firefox’ta ise genellikle bayrakla etkinleştirilmektedir. ONNX Runtime Web (kısaca ort), ONNX formatındaki modelleri tarayıcıda WASM, WebGL veya WebGPU üzerinde çalıştırır. Mimari şu şekilde işler: model dosyası (örn. mobilenetv3.onnx), tarayıcıya indirilir; preprocess aşamasıyla görüntü tensöre dönüştürülür; WebGPU yürütücüsü ile ileri besleme yapılır; sonuçlar postprocess ile insan tarafından anlaşılır etiketlere çevrilir.

Kurulum ve Dosya Yapısı

Basit bir yapı için bir HTML dosyası (index.html), bir JavaScript dosyası (app.js) ve model/etiket dosyalarınız (models/mobilenetv3.onnx, labels.txt) yeterlidir. Paket yöneticisi kullanacaksanız onnxruntime-web paketini ekleyebilir veya CDN üzerinden import edebilirsiniz. Yerel geliştirme için npm create vite@latest ile hafif bir iskelet kurup, npm i onnxruntime-web komutuyla kütüphaneyi dahil edebilirsiniz. Veya basit bir HTML sayfasında <script type="module"> ile ESM import yapabilirsiniz.

WebGPU’nun Etkinliği ve Geri Dönüş Planı

Önce tarayıcının WebGPU desteğini kontrol edin: if ('gpu' in navigator). ONNX Runtime Web oturumunu başlatırken yürütücüleri öncelik sırasına koyabilirsiniz: executionProviders: ['webgpu', 'webgl', 'wasm']. Böylece WebGPU yoksa WebGL, o da yoksa WASM’a otomatik düşülür. Bu yaklaşım, geniş bir cihaz/tarayıcı yelpazesini hedeflemenizi sağlar.

Modeli Yükleme ve Oturum Oluşturma

Bir InferenceSession başlatırken, graphOptimizationLevel ve preferredOutputLocation gibi seçeneklerle performansı iyileştirebilirsiniz. Örnek bir akış şu şekildedir: modeli fetch ile indirip await ort.InferenceSession.create çağırarak oturumu hazırlayın; etiket dosyasını (labels.txt) satır satır belleğe alın; giriş tensörünü uygun boyuta (ör. 224x224), kanal sırasına ve normalizasyona getirip Float32Array içine yerleştirin; ardından session.run(feeds) ile çıktı alın.

Ön İşleme: Doğru Tensör, Doğru Sonuç

Ön işleme aşaması, modelden iyi sonuç almak için kritiktir. Tipik olarak aşağıdaki adımları uygularsınız: resmi canvas üzerinde 224x224’e yeniden boyutlandırma; RGB kanallarını çıkarma; piksel değerlerini 0–1 aralığına ölçekleme; modelin beklediği ortalama ve standart sapma ile normalizasyon; kanal sırasını HWC’den CHW’ye çevirme. Son olarak tensörü new ort.Tensor('float32', data, [1, 3, 224, 224]) şeklinde oluşturursunuz.

Çıktının İşlenmesi ve Etiketleme

Modelden alınan ham skorları (logit) softmax ile olasılığa çevirmek, ardından en yüksek değere sahip sınıfı ve olasılığını bulmak temel adımdır. Etiket dosyanızla eşleyip kullanıcıya en olası ilk üç sonucu gösterebilirsiniz. Basit bir kullanıcı arayüzü için bir dosya yükleme alanı ve sonuç listesini güncelleyen kısa bir fonksiyon yeterlidir.

Performans İpuçları

1) WebGPU seçimi: Cihaz destekliyse WebGPU belirgin hız sağlar. 2) Kantizasyon: INT8 veya FP16 kantize modeller daha küçük ve hızlıdır; doğruluk/performans dengesini ölçün. 3) Toplu işleme: Birden fazla görseli ardışık yerine mini-batch olarak çalıştırmak throughput’u artırabilir. 4) WASM ayarları: Geri dönüş halinde ort.env.wasm.numThreads gibi ayarlarla CPU tarafını hızlandırın. 5) IO binding: Gelişmiş senaryolarda giriş/çıkışları GPU belleğinde bağlamak kopyalama maliyetini düşürür. 6) Önyükleme: İlk yüklemede modeli önbelleğe almak (Service Worker, HTTP caching) deneyimi iyileştirir.

Uyumluluk ve Sorun Giderme

Eğer “WebGPU desteklenmiyor” uyarısı alırsanız tarayıcınızı güncelleyin veya geçici olarak WebGL/WASM geri dönüş yolu kullanın. CORS hataları için model ve etiket dosyalarınızı aynı origin’den servis edin veya uygun başlıkları ayarlayın. Bozuk sonuçlar genelde ön işleme hatalarından kaynaklanır: kanal sırası (CHW vs HWC), normalizasyon değerleri ve giriş boyutunu iki kez kontrol edin. Performans düşükse geliştirici araçlarında GPU işlem kullanımını izleyin; entegre GPU’larda FP16/INT8 kazancı değişebilir.

Gizlilik ve Güvenlik

Yerel çıkarım, görsellerin cihazdan çıkmaması sayesinde gizliliği güçlendirir. Yine de kullanıcı izni olmadan dosya okuma, kalıcı depolama veya kamera erişimi gibi API’ler kullanılmamalıdır. Büyük modeller için indirme boyutunu küçültmek (sıkıştırma, kantizasyon) hem veri kullanımı hem de ilk yükleme süresini azaltır.

Sonuç

WebGPU ve ONNX Runtime Web ile tarayıcıda görsel sınıflandırma, artık bir prototipten öteye geçmiş durumda. Doğru model, sağlam ön işleme ve akıllı geri dönüş stratejileriyle, yüksek performanslı ve gizliliğe saygılı deneyimler oluşturabilirsiniz. Küçük bir demoyla başlayın; ardından etkileşimli görsel arama, canlı kamera üzerinde etiketleme veya tamamen çevrimdışı çalışan PWA gibi senaryolara genişleyin. Gelecek, kullanıcıların cihazında—ve siz bugün bunun temelini atabilirsiniz.