Barcodie nasıl çalışır,
neden böyle kurduk?

Bu doküman Barcodie'nin nasıl çalıştığını, hangi teknolojiyi neden seçtiğimizi ve iddialarımızın arkasındaki ölçümleri anlatır. Her iddianın yanında kaynağı yazıyor: 📏 Ölçtük (kendi verimiz ve kodumuz, tekrar üretilebilir) veya 📚 Gerekçe (literatür, mühendislik değerlendirmesi — henüz ölçmedik). Ölçmediğimiz şeyleri ayrıca §9 Bilinen sınırlar bölümünde listeledik.

1. Özet

Fırın, manav, şarküteri ve kafeterya ürünlerinin barkodu yok. Bugün kasada bu ürünler dokunmatik ekranda onlarca ürünlük bir ızgaradan elle seçiliyor: yavaş, hataya açık, yeni personel için zor.

Barcodie kasaya bakan bir kameranın karesini alır ve POS'un kendi ürün kodunu (sku) döner. Fiyatı POS hesaplar, ağırlığı onaylı terazi verir; biz sadece "bu hangi ürün" sorusunu cevaplarız. Model eğitimi yoktur: yaygın ürünler POS kataloğu senkronlanınca otomatik tanınır, geri kalanı için kasada 3 fotoğraf yeter. Emin olmadığımızda tahmin yazmayız — kasiyere en olası adayları gösteririz.

¹ Model karşılaştırmasındaki (Benchmark 1) çapraz doğrulamalı sonuç. Aynı veriyle servisin kendisi (Qdrant + DINOv2-base, güncel kalibrasyon) %42,6 otomatik onay ve %99,3 doğruluk veriyor; bkz. §5.1.

2. Ürün ve entegrasyon modeli

Barcodie kendi başına bir POS değil, POS'un içine giren bir servistir. Müşterimiz POS sağlayıcısı (entegratör), onun müşterileri işletmelerdir.

 Kasa                                         Barcodie (bulut API)
 ┌───────────────────────────┐   HTTPS +     ┌──────────────────────────────────┐
 │ Sabit kamera ──┐          │   API anahtarı│  /v1 uçları                      │
 │ Onaylı terazi ─┼─▶ POS ───┼──────────────▶│  ├ katalog eşleme (ad -> sınıf)  │
 │                │  katalog │  kare,        │  ├ görüntü: ROI · boş kare farkı │
 │                │  fiyat   │  device_id,   │  ├ DINOv2 embedding              │
 │                │  ödeme   │  weight_g     │  ├ Qdrant: en yakın komşu        │
 │                │          │◀──────────────│  └ kalibre güven + karar         │
 └───────────────────────────┘  sku + güven  └──────────────────────────────────┘
                                + adaylar

Entegrasyon akışı (POS tarafının yapacakları):

Sözleşmenin tamamı: api-contract/plugin-api.v1.yaml (OpenAPI 3). Kasada canlı tetik için isteğe bağlı bir edge ajanı var: kamerayı izler, ürün yerleşip el çekildiğinde (veya terazi sabitlendiğinde) API'yi kendisi çağırır, sonucu yerel WebSocket ile POS'a iletir. Model çalıştırmaz. Sözleşmesi: api-contract/edge-events.v1.asyncapi.yaml.

3. Tanıma nasıl çalışır

1. Görüntü hazırlığı — kalibrasyonda verilen ilgi alanı (ROI) kırpılır. Boş terazi karesiyle fark alınır: değişim yoksa "terazi boş" denir ve model hiç çalıştırılmaz.
2. Embedding — kare, DINOv2 ile 768 boyutlu bir vektöre çevrilir.
3. Arama — vektör, Qdrant'ta sadece o işletmenin kataloğunda olan ürünler arasında aranır: işletmenin kendi fotoğrafları + kataloğa eşlenmiş global sınıflar.
4. Kalibre güven — ham benzerlik skoru olasılık değildir (ölçümde yanlış tahminlerin medyan skoru 0,83, doğruların 0,85 — neredeyse aynı). Bu yüzden skoru ve ilk iki aday arasındaki farkı, ölçülmüş doğruluğa göre öğrenilmiş bir lojistik modelden geçiririz: confidence = sigmoid(a·benzerlik + b·fark + c). Sonuç: "0,95 güven" gerçekten "bu düzeydeki 100 tahminin ~95'i doğru" demek. 📏
5. Karar — üç durum:

"Sık karışan benzer ürün" listesi de ölçümden gelir (golden ↔ yeşil elma, şeftali ↔ nektarin, limon ↔ misket limonu…): bu çiftlerde güven yüksek olsa bile varsayılan kural otomatik onay vermez. status bir öneridir; POS isterse kendi kuralını confidence üzerine kurar.

4. Teknoloji kararları

Her karar için: ne seçtik, alternatifler neydi, neden, kanıt ve production'da ne olacak.

4.1 Model eğitmiyoruz: embedding + en yakın komşu

4.2 Görsel temsil: DINOv2

• CLIP ilk tahminde ~16 puan geride: elendi.
• İlk dört model ilk tahminde istatistiksel olarak berabere (340 görselde ±4 puan belirsizlik). DINOv2-base'i en iyi doğruluk / en düşük gecikme dengesi için seçtik; small neredeyse aynı doğrulukta 2,3× hızlı — GPU'suz ucuz sunucu için güçlü aday.
• SigLIP2 gerçek bir rakip: ilk 3'te ve otomatik onayda daha iyi, CPU'da 2× yavaş. Pilot verisiyle yeniden karşılaştıracağız. Model değişikliği tek ayardır (EMBEDDING_MODEL) + galeriyi yeniden yükleme.

4.3 Ürün kutulama (detector): pilotta yok, yol haritasında var

Kutulama, bir karede birden fazla ürünü ayırıp saymak için gerekir. Terazide tek ürün senaryosunda gerekmez.

• Teknik olarak en iyisi YOLO-World; ayrıca 50× hızlı (CPU'da 115 ms, OWLv2 1,4 sn).
• Ama lisansı AGPL-3.0: ağ üzerinden hizmet olarak sunulursa servisin kaynak kodu kullanıcılara açılmalı. Ticari kullanımı yasaklamaz; POS'un kodunu etkilemez (HTTP ile konuşuyoruz). Yine de kapalı kaynak bir ticari serviste kullanmıyoruz.
• Yol: (1) pilot detector'süz → lisans sorunu yok; (2) karışık tepsi için kendi tepeden verimizle Apache lisanslı bir detector (RT-DETR / YOLOX / D-FINE) eğitmek; (3) ara çözüm olarak Ultralytics ticari lisansı. YOLO-World'ün %93'ü hedef çıtamız.
• 📏 Raf fotoğrafı galeride ise detector zarar veriyor (ilk tahmin %85,9 → %76,5): yığından tek meyve kırpıyor. Bu yüzden galeri her zaman kırpımsız yüklenir; detector yalnızca kasadaki sorgu karesine uygulanır.

4.4 Vektör veritabanı: Qdrant

Ölçek hesabı 📚 (varsayım: 10.000 işletme × 20 kendi ürünü × 5 foto):

Tek bir Qdrant düğümüne (veya pgvector'lu bir Postgres'e) rahatça sığar. Arama işletme filtresiyle yapıldığı için her sorgu fiilen birkaç yüz vektöre bakar; vektör DB darboğaz değildir — darboğaz embedding'dir.

4.5 İlişkisel veri: SQLite → Postgres

4.6 Fiyatı ve kiloyu biz hesaplamıyoruz

• Fiyat dönmüyoruz, sadece sku. Fiyatlar günlük değişir, şube/kampanya fiyatı vardır; fiyatı senkron tutmak bizi hata kaynağı yapar. Fiyat otoritesi POS'tur.
• Kiloyu fotoğraftan tahmin etmiyoruz. 📚 Tek fotoğraftan ağırlık tahmini laboratuvarda bile %11–20 hata verir; tartıyla satışta onaylı terazi yasal zorunluluk (Otomatik Olmayan Tartı Aletleri Yönetmeliği, 2014/31/AB). weight_g istekten aynen yansıtılır.

4.7 Servis katmanı

5. Ölçümler

İki benchmark, iki farklı soru. Her ikisi de repoda tek komutla tekrar üretilir; Docker veya vektör DB gerekmez (arama, Qdrant'ın bu ölçekteki sonucuyla aynı olan kesin kosinüs ile yapılır — servis yoluyla çapraz kontrol edildi, sonuç birebir aynı çıktı).

5.1 Benchmark 1 — Model seçimi (raf fotoğrafı)

• Veri: Grocery Store Dataset (Klasson vd., WACV 2019, MIT) + Fruits-360 (MIT). Galeri 419 görsel / 42 sınıf; test 340 görsel / 34 sınıf, galeriyle çakışmaz.
• Karar kuralı: servisle aynı; kalibrasyon çapraz doğrulamalı (yarısında öğren, diğer yarısında ölç).
• Sonuçlar: §4.2 ve §4.3. Ayrıntı: benchmarks/2026-09-30/summary.md.
• Servisin kendisiyle (Qdrant + DINOv2-base, kırpımsız): ilk tahmin %85,9, ilk 3 %97,4; kalibre güven 0,95 eşiğinde tahminlerin %42,6'sı otomatik onaylanıyor, bunların %99,3'ü doğru (çapraz doğrulamada %99,2). Güven ölçeği tutarlı: 0,99 üstü güvenle verilen tahminlerin gerçek doğruluğu %99,2.
• Tekrar: cd ai && python -m scripts.benchmark_models --latency-devices cpu mps

5.2 Benchmark 2 — Kasa açısı (tepeden, sabit kamera)

• Veri: sabit tepeden telefon kamerası, tek tezgâh. 40 tekli kare (11 tür), 30 karışık tepsi (88 ürün), 1 boş tezgâh. Galeri yine raf fotoğrafı — yani "kurulum günü" durumunu ölçüyor.
• "3 foto sonra": her ürüne kendi kasasından en fazla 3 foto eklenir; birini-dışarıda-bırak — test edilen kare hiçbir zaman galeride değildir.

Tek ürün, pilot ayarı (DINOv2-base, detector'süz). Servis, boş kare kalibrasyonu varsa kareyi değişen bölgeye kırpar ("boş kare farkı"), yoksa tüm kareyi kullanır; ikisini de ölçtük:

Boş kare farkı bu sette dezavantajlı: kareler farklı videolardan alındığı için kamera hafifçe kaydı, sabit montajlı gerçek kurulumda bu olmaz.

Kurulum günü hataları büyük ölçüde makul karışmalar: yeşil mandalina → misket limonu (galerideki mandalinalar turuncu), kuru soğan → kırmızı soğan, Türk salatalığı → kabak. Diğer modellerde (detector'süz) kurulum günü ilk tahmin %73–90 (SigLIP2 %90), 3 foto sonrası %92,5–100. Ayrıntı: benchmarks/2026-10-02-overhead/summary.md.

Satış cümlesi buradan çıkıyor: "Kurulum günü yaygın ürünlerde doğru ürünü kasiyere ilk 3 aday içinde sunar; her ürün için kasada 3 foto çekildiğinde neredeyse kusursuz tanır."

• Tekrar: cd ai && python -m scripts.benchmark_overhead (veri ai/data/overhead/ + labels.json)

5.3 Gecikme

📏 Tek kare, ısınmadan sonra medyan (Apple M5 dizüstü; sunucu CPU/GPU'sunda henüz ölçülmedi):

Ağ gidiş-dönüşü ve görüntü yükleme bunlara eklenir. Edge ajanının hedefi tetikten sonuca p50 ≤ 700 ms. 📚

6. Güvenlik, çok kiracılık ve KVKK

Çok kiracılık. Kiracı = (API anahtarının sahibi entegratör, merchant_id). Her SQL sorgusu ve her vektör araması kiracıyla filtrelenir; bir işletmenin ürünleri başka bir işletmenin tanımasını etkileyemez.

Kimlik ve sınırlar. Bearer API anahtarı (sabit zamanlı karşılaştırma), entegratör başı dakikada 600 istek (429 + Retry-After), dosya 4 MB, çözünürlük 40 MP (dekompresyon bombasına karşı çözmeden önce kontrol), istek gövdesi sınırı kimlik doğrulamadan önce. ENVIRONMENT=prod iken varsayılan anahtar, bellek içi vektör DB veya korumasız eski uçlar varsa servis açılmaz.

KVKK.

Yüz tanıma yapmayız; kamera ROI ile sadece tartı/tezgâh alanına bakar. Çıkarımın bulutta mı kasada mı yapılacağı entegratörle birlikte netleşecek açık bir sorudur (§9).

Lisanslar.

Ticari kullanıma kapalı veri setleri (RPC, SKU-110K, D2S) bilinçli olarak kullanılmadı.

7. Production'a geçiş

Veri döngüsü. Kasiyerin her düzeltmesi (/feedback), izin varsa etiketli bir kasa karesidir. Asıl rekabet avantajımız hazır veri setleri değil, sahadan gelen bu veridir: kalibrasyon, benzer ürün listesi ve ileride kendi detector'ımız bununla iyileşir.

8. Yol haritası

1. Pilot — tek ürün, terazili kasa. Detector'süz, lisans temiz. Ölçülecekler: kasa süresi, otomatik onay oranı, kasiyer düzeltme oranı, gecikme. Kalibrasyon pilot verisiyle yeniden öğrenilir.
2. Karışık tepsi. Pilot karelerinden etiketli veri → Apache lisanslı kendi detector'ımız. Çıta: YOLO-World + ürün adları ile ölçtüğümüz %93 adet doğruluğu.
3. Model güncellemesi. SigLIP2 / DINOv2-small, pilot verisiyle yeniden karşılaştırılır.
4. Tek fotoğrafla ürün tanıtma. Üretken görsel modelle tek fotodan çeşitleme + "benziyor ama değil" negatifleri (plans/AI_AUTO_ENROLL_PLAN.md).

9. Bilinen sınırlar ve açık sorular

Ölçüm sınırları.

• Benchmark 2 küçük: 70 kare, tek tezgâh, tek ışık; ürün bazında oranlar güvenilir değil. "Yön gösteren ilk sonuç" olarak okunmalı. "3 foto sonra" testinde kurulum ve test kareleri aynı oturumdan — iyimser.
• "Katalogla sınırlı" sonuçlarda katalog 12 ürünlüktü; gerçek bir manav kataloğu daha büyük olacak ve benzer ürünleri (kırmızı soğan, misket limonu) birlikte içerecek — oranlar düşebilir.
• Benchmark 1'in verisi market rafı fotoğrafı, kasa açısı değil.
• Gecikme sunucu donanımında ölçülmedi.
• Pastane ürünleri (simit, poğaça, açma) için global galeri yok; bunlar işletme fotoğrafıyla tanıtılır ve bu senaryo henüz ayrıca ölçülmedi.

Bilinen zayıflıklar.

• Görsel olarak çok benzeyen ürünler (şeftali/nektarin, golden/yeşil elma, limon/misket limonu) — sistem bunlarda otomatik onay vermez, kasiyere sorar.
• Aynı global sınıfa eşlenmiş iki ürün ("Domates" ve "Organik Domates") ayırt edilemez; biri için işletme fotoğrafı gerekir.
• Pilotta bir karede tek ürün.

Entegratörle netleşecekler.

• Çıkarım bulutta mı, kasada mı?
• Terazi bağlantısı (POS üzerinden mi, seri port mu)?
• Kamera donanımı ve montaj standardı.
• KVKK aydınlatma metni ve veri işleme sözleşmesi.

Barcodie, Moka United AI Ideathon & Hackathon'da 400 başvuru arasından ikincilik aldı. Kod ve tüm ölçüm script'leri talep halinde paylaşılabilir.