# ArcFace Modellerinde ONNX ve CTranslate2 > ArcFace ile eğitilmiş bir ONNX yüz embedding modelinin CTranslate2’ye doğrudan taşınamamasının nedeni dosya uzantısı değil, desteklenen model mimarisi ile çıkarım grafiği arasındaki farktır. - Author: Muhammet Ali Köker - Language: tr - Canonical: https://alikoker.com.tr/arcface-onnx-ctranslate2 - Translation: https://alikoker.com.tr/en/onnx-ctranslate2-arcface-architectural-comparison - Published: 2026-08-04T12:00:00+03:00 - Modified: 2026-09-08T02:30:00+03:00 - Verified: 2026-09-08T02:30:00+03:00 - Type: article ## ArcFace kaybı ve yüz embedding çıkarımı [ArcFace](/wiki/arcface), yüz görüntüsünü işleyen convolutional omurganın adı değil, eğitimde kullanılan eklemeli açısal marj kaybıdır (Additive Angular Margin Loss). Amaç, aynı kişiye ait yüz temsillerini açısal uzayda yakınlaştırırken farklı sınıflar arasındaki açısal ayrımı artırmaktır. Normalize edilmiş özellikler ve sınıf ağırlıkları üzerinde doğru sınıf açısına sabit bir marj eklenir. Yüz tanıma sistemlerinde Dlib ve InsightFace tabanlı modellerle, [ONNX](/wiki/onnx) tabanlı çıkarım hatları üzerinde çalışırken ArcFace adının çoğu kez model omurgasıyla karıştırıldığını gördüm. Bu makaleyi bu pratik ayrımdan hareketle; eğitim kaybı, embedding omurgası, model değişim biçimi ve çalışma zamanı desteğini birbirinden ayırmak için hazırladım. Basitleştirilmiş ArcFace kaybı şöyledir: ```text exp(s · cos(θyi + m)) Lᵢ = -log ------------------------------------------------ exp(s · cos(θyi + m)) + Σj≠yi exp(s · cos θj) ``` Burada: - `θyi`, örneğin gerçek sınıf ağırlığı ile özellik vektörü arasındaki açıdır. - `m`, eklemeli açısal marjdır. - `s`, normalize edilmiş logit değerlerini ölçekleyen katsayıdır. - `yi`, örneğin gerçek kimlik sınıfıdır. Eğitim sonrasında sınıflandırma başlığı, birçok yüz doğrulama sisteminde kullanılmaz. Çıkarımda gerekli bölüm; hizalanmış yüz görüntüsünü sabit boyutlu embedding vektörüne dönüştüren omurgadır: ```text x ∈ R^(3×112×112) → f(x) ∈ R^512 ``` [Embedding](/wiki/embedding) çoğunlukla L2 normuyla normalize edilir: ```text f(x) f̂(x) = ------------- ||f(x)||₂ ``` İki yüz arasındaki benzerlik, normalize edilmiş embedding vektörlerinin iç çarpımıyla hesaplanabilir: ```text similarity(a, b) = f̂(a)ᵀ f̂(b) ``` Dolayısıyla dönüştürülmek istenen nesne bir "ArcFace katmanı" değildir. Bu nesne; ResNet, iResNet, MobileFaceNet veya benzeri bir görüntü omurgasının ArcFace kaybıyla eğitilmiş ağırlıklara sahip çıkarım grafiğidir. ## ONNX biçimi, genel dönüşüm garantisi değildir Bir modelin ONNX biçiminde bulunması, onun herhangi bir çıkarım motoruna dönüştürülebileceği anlamına gelmez. ONNX, hesaplama grafiğini ve ağırlıkları ortak bir gösterimle taşır. Hedef çalışma zamanının grafiği ayrıştırabilmesi, düğümleri desteklemesi ve yürütme semantiğini karşılayabilmesi ayrıca gerekir. Bu nedenle aşağıdaki ayrımlar korunmalıdır: - Model biçimi, model mimarisi değildir. - Operatör desteği, bütün grafik desteği değildir. - Ağırlık nicemleme, model dönüştürme değildir. - Çıktı boyutu, çalışma zamanı uyumluluğu değildir. ArcFace tabanlı InsightFace modeli geçerli bir `.onnx` dosyası olabilir ve 512 boyutlu yüz temsili üretebilir. Buna rağmen mevcut CTranslate2 dönüştürme araçlarıyla doğrudan CTranslate2 modeline dönüştürülemez. Genel amaçlı ONNX çalışma zamanları farklı bir yürütme yaklaşımı kullanır: ```text ONNX grafiğini oku ↓ her düğümün operatörünü ve özniteliklerini çöz ↓ grafiği topolojik sırada planla ↓ uygun kernel veya donanım sağlayıcısına dağıt ↓ ara tensorleri üret ``` ONNX Çalışma zamanı, desteklenen grafikleri yükleyebilir, optimize edebilir ve alt grafikleri CPU, CUDA, TensorRT, OpenVINO veya başka Execution Sağlayıcı bileşenlerine dağıtabilir. Ancak opset sürümü, özel operatörler, dinamik şekiller ve donanım sağlayıcısının operatör kapsamı yine de yürütmeyi engelleyebilir. ## CTranslate2'nin mimari sınırı CTranslate2, genel amaçlı bir ONNX grafik yorumlayıcısı değildir. [Transformer](/wiki/transformer) tabanlı modellerin verimli çıkarımı için geliştirilmiş özelleşmiş bir C++ ve Python çıkarım kütüphanesidir. Ağırlık nicemleme, katman birleştirme ve batch yeniden sıralama gibi optimizasyonları Transformer yürütme düzenine yöneliktir. Mevcut dönüştürücüler, keyfî ONNX grafiklerini kabul eden genel bir giriş noktası sağlamaz. OpenNMT, Fairseq ve Hugging Face Transformers ekosistemlerindeki belirli model aileleri için mimariye duyarlı dönüştürücüler bulunur. Desteklenen aileler arasında BERT, T5, Llama, Whisper ve NLLB gibi seçilmiş Transformer modelleri yer alır; genel CNN görüntü modelleri bu kapsamda değildir. CTranslate2 dönüşümü kabaca şu akışı izler: ```text kaynak framework modeli ↓ bilinen model sınıfını tanı ↓ beklenen parametreleri adlarıyla eşleştir ↓ CTranslate2 model belirtimini oluştur ↓ ağırlıkları hedef biçimde sakla ``` Bu yaklaşım, model ailesini ve çıkarım akışını önceden bilir. InsightFace yüz tanıma grafiği için yerleşik bir `ArcFaceConverter`, `ResNetConverter` veya genel `ONNXConverter` bulunmaz. Dönüştürücünün yalnızca ağırlıkları okuyup benzer katmanlara aktarması yeterli değildir; hedefte aynı grafiği temsil edecek model belirtimi ve yürütme sınıfı da bulunmalıdır. ## Operatör, topoloji ve dönüşüm doğrulaması Uyumluluğu yalnızca operatör adlarıyla değerlendirmek yanıltıcıdır. Bir çalışma zamanında matris çarpımı, aktivasyon, normalizasyon veya bazı convolution işlemlerinin bulunması, keyfî bir CNN grafiğinin yürütülebileceğini göstermez. ### Operatör semantiği Aynı adlı işlemler farklı veri düzenleri, eksenler, dolgulama veya broadcasting kuralları kullanabilir. Bir convolution düğümünde örneğin aşağıdaki parametreler yer alabilir: - `kernel_size` - `stride` - `padding` - `dilation` - `groups` - `input_layout` - `weight_layout` Görüntü modellerinde yaygın giriş düzeni `[N, C, H, W]` biçimindedir. Kod tabanında bir `Conv` işleminin bulunması, ONNX `Conv` operatörünün bütün öznitelik birleşimlerinin desteklendiği anlamına gelmez. ### Grafik topolojisi ve model belirtimi InsightFace omurgaları yalnızca sıralı convolution katmanlarından oluşmaz. Residual bağlantılar, normalizasyon katmanları, aktivasyonlar ve şekil dönüşümleri içerir: ```text x ────────────────┐ │ Conv → BN → PReLU → Conv → BN │ Add → çıktı ``` Hedef çalışma zamanı, düğümleri tek tek uygulayabilse dahi dallanma, birleşme ve tensor yaşam süresi kurallarını desteklemelidir. CTranslate2 ise serbest operatör grafiklerinden çok, desteklenen model türlerinin tanımlı yapılarıyla çalışır. Bir yüz embedding omurgası için yerleşik model sınıfının şu soruları tanımlaması gerekir: - Giriş görüntüsünün şekli nedir? - Residual bloklar nasıl sıralanır? - Feature map boyutları nerede küçültülür? - Son embedding katmanı nasıl oluşturulur? - Batch normalleştirme parametreleri nasıl uygulanır? - Çıktı normalize edilecek midir? Dönüşümden sonra yüklenebilirlik de yeterli değildir. Sayısal eşdeğerlik sınanmalıdır: ```text yONNX = fONNX(x) yhedef = fhedef(x) max_abs_error = max |yONNX - yhedef| ``` Embedding sistemlerinde yönsel sapma ayrıca önemlidir: ```text cosine_drift = 1 - cosine_similarity(yONNX, yhedef) ``` Yüz doğrulama kararları [cosine similarity](/wiki/cosine-similarity) eşiğine yakın örneklerde veriliyorsa küçük sayısal farklar kabul-ret sonucunu değiştirebilir. Dönüşümün çalışması, biyometrik karar davranışının korunduğu anlamına gelmez. ## Uygun çıkarım motoru ve embedding sözleşmesi ArcFace tabanlı ONNX yüz embedding modeli için doğal başlangıç noktası ONNX Çalışma zamanıdır. Model biçimini değiştirmeden aynı API altında CPU, CUDA, TensorRT ve OpenVINO gibi Execution Sağlayıcı seçenekleri kullanılabilir. NVIDIA GPU üzerinde sabit giriş şekli ve yüksek batch yükünde TensorRT ayrıca değerlendirilebilir. Intel CPU, iGPU veya NPU hedeflerinde OpenVINO modeli doğrudan yükleyebilir ya da kendi model biçimine önceden dönüştürebilir. ARM tabanlı edge cihazlarda ONNX Çalışma zamanının uygun CPU sağlayıcıları veya mobil odaklı ncnn gibi çalışma zamanları karşılaştırılabilir. ncnn, ONNX modellerinin `pnnx` aracılığıyla kendi model biçimine dönüştürülmesine yönelik bir yol sunar. Motor seçimi tek görüntü çıkarım süresine göre yapılmamalıdır. Değerlendirmede aşağıdaki metrikler ölçülmelidir: - Tek istek gecikmesi - Sürdürülebilir işlem hacmi - Batch ölçeklenmesi - p95 ve p99 gecikmesi - Model yükleme süresi - Çalışma zamanı bellek tüketimi - Host-device kopya maliyeti - Çoklu oturum davranışı - Precision değişiminde embedding sapması Yüz tanıma hattındaki toplam gecikme yalnızca embedding modelinden oluşmaz: ```text Ttoplam = Tdecode + Tdetect + Talign + Tcopy + Tembedding + Tsearch ``` Embedding çıkarımındaki hızlanma, yüz tespiti veya vektör arama aşaması baskınsa toplam sistemde sınırlı etki yaratabilir. Ayrıca iki modelin 512 elemanlı vektör üretmesi, bu vektörlerin aynı embedding uzayında bulunduğunu göstermez: ```text f₁(x) ∈ R^512 f₂(x) ∈ R^512 ``` Bu ifadelerden `f₁(x) ≈ f₂(x)` sonucu çıkarılamaz. Embedding uzayı; eğitim verisi, omurga, kayıp fonksiyonu, ön işleme, hizalama, renk kanal sırası ve normalizasyon kurallarıyla birlikte oluşur. Çalışma zamanı değiştirilirken aşağıdaki sözleşme korunmalıdır: - Giriş boyutu - RGB/BGR sırası - Piksel ölçekleme - Ortalama ve standart sapma - Yüz hizalama geometrisi - Çıktı tensor adı ve sırası - L2 normalizasyonu - Benzerlik ölçütü - Karar eşiği [INT8](/wiki/int8) nicemlemede yalnızca model boyutu veya çıkarım süresi değerlendirilmemelidir. Benzerlik skorları, karar eşikleri ve nearest-neighbor aramasındaki sıralama davranışı da doğrulanmalıdır. CTranslate2'ye CNN yüz embedding desteği eklemek kaynak kod düzeyinde teorik olarak mümkündür; ancak bunun için yeni model belirtimi, dönüştürücü, CPU ve GPU kernel yolları, bellek planlaması, API genişletmeleri ve farklı omurgalar için eşdeğerlik testleri gerekir. Bu maliyet, CNN ve ONNX grafikleri için zaten optimize edilmiş bir motorun kullanılmasından büyük olasılıkla daha yüksektir. ONNX genel hesaplama grafiğini, tensorleri ve operatörleri taşırken CTranslate2 modeli desteklenen model ailesini, bilinen çıkarım akışını ve optimize ağırlık düzenini temsil eder. Bu soyutlama düzeyleri arasında genel bir çevirmen bulunmadığı sürece `.onnx` uzantısı CTranslate2 uyumluluğu sağlamaz. ## Model, Format ve Runtime İddialarını Ayrı Doğrulamak Bu yazıdaki üç teknik nesnenin kanıt kaynağı da ayrıdır. ArcFace, yüz tanıma eğitiminde kullanılan additive angular margin loss olarak [CVPR 2019 çalışmasında](https://doi.org/10.1109/CVPR.2019.00482) tanımlanır. ONNX dosyasının anlamı ONNX IR belirtimindeki graph/operator sözleşmesine bağlıdır. CTranslate2 ise hangi model ailelerini ve operatörleri hangi yürütme yolu ile desteklediğini kendi runtime belgelerinde tanımlar. Bu nedenle “export başarılı” sonucu sayısal eşdeğerlik kanıtı değildir. Dönüşüm sonrası aynı girdi üzerinde `max_abs_error`, cosine similarity/drift ve nihai eşik kararları ölçülmelidir. Bu metinde kullanılan bu karşılaştırma ölçüleri doğrulama yöntemidir; kabul edilebilir toleransın tek evrensel değeri olduğu iddia edilmez. Tolerans, modelin kullanım senaryosuna ve karar eşiğine göre belirlenmelidir. ## Dönüştürülebilir Model ile Eşdeğer Model Aynı Şey Değildir Bir modelin ONNX'e aktarılabilmesi, farklı bir inference runtime'ında aynı embedding uzayını koruyacağı anlamına gelmez. Preprocessing sırası, normalization, tensor layout, operator karşılığı ve sayısal precision küçük görünse de yüz doğrulama gibi eşik tabanlı sistemlerde skor dağılımını değiştirebilir. Bu yüzden dönüştürme testi yalnız tek örnekte yakın çıktı aramamalıdır. Aynı veri kümesinde embedding normları, cosine benzerlik dağılımı ve karar eşiği çevresindeki örnekler karşılaştırılmalıdır. [Embedding Drift](/wiki/embedding-drift) bu tür kaymaların üretim sisteminde neden model dosyası düzeyinden daha geniş bir doğrulama gerektirdiğini açıklar. ## Kaynakça - Jiankang Deng; Jia Guo; Niannan Xue; Stefanos Zafeiriou. (2019). ArcFace: Additive Angular Margin Loss for Deep Face Recognition. 2019 IEEE/CVF Conference on Computer Vision and Pattern Recognition. [doi:10.1109/CVPR.2019.00482](https://doi.org/10.1109/CVPR.2019.00482) - ONNX Project. (n.d.). Open Neural Network Exchange Intermediate Representation (ONNX IR) Specification. ONNX Project. [URL](https://onnx.ai/onnx/repo-docs/IR.html) - OpenNMT. (n.d.). CTranslate2 Documentation. OpenNMT. [URL](https://opennmt.net/CTranslate2/) ## Bu Çalışmaya Atıf Köker, M. A. (2026). ArcFace Modellerinde ONNX ve CTranslate2. alikoker.com.tr. https://alikoker.com.tr/arcface-onnx-ctranslate2 - BibTeX: https://alikoker.com.tr/arcface-onnx-ctranslate2.bib - RIS: https://alikoker.com.tr/arcface-onnx-ctranslate2.ris - CSL-JSON: https://alikoker.com.tr/arcface-onnx-ctranslate2.csl.json