Firebase Extensions ile mobil uygulamalarınıza Firestore Vektör Arama'yı ekleyin

3. Mobil uygulamayı bağlama

Bu kod alanının bu bölümünde, basit bir not alma uygulamasının kaynak kodunu indirip yeni oluşturduğunuz Firebase projesine bağlayacaksınız.

Örnek uygulamayı indirin

1. https://github.com/FirebaseExtended/codelab-firestore-vectorsearch-ios adresine gidin ve deposu yerel makinenize klonlayın
2. Xcode'da Notes.xcodeproj projesini açın.

Uygulamayı Firebase projenize bağlayın

Uygulamanızın Firebase hizmetlerine erişebilmesi için Firebase konsolunda uygulamayı ayarlamanız gerekir. Aynı Firebase projesine birden fazla istemci uygulaması bağlayabilirsiniz. Örneğin, bir Android veya web uygulaması oluşturursanız bunları aynı Firebase projesine bağlamanız gerekir.

Firebase projeleri hakkında daha fazla bilgi edinmek için Firebase projelerini anlama başlıklı makaleyi inceleyin.

1. Firebase konsolunda, Firebase projenizin genel bakış sayfasına gidin.
2. iOS uygulamanızı eklemek için iOS+ simgesini tıklayın.
3. Firebase'i Apple uygulamanıza ekleyin ekranında, Xcode projesindeki paket kimliğini (com.google.firebase.codelab.Notes) ekleyin.
4. İsterseniz bir uygulama takma adı girebilirsiniz (iOS için Notlar).
5. Sonraki adıma geçmek için Uygulamayı kaydet'i tıklayın.
6. GoogleServices-Info.plist dosyasını indirin.
7. GoogleServices-Info.plist dosyasını Xcode projenizin Notlar klasörüne sürükleyin. Bunu yapmanın iyi bir yolu, dosyayı Assets.xcassets dosyasının altına bırakmaktır.
8. Gerekirse öğeleri kopyala'yı seçin, Hedeflere ekle bölümünde Notlar hedefinin seçildiğinden emin olun ve Son'u tıklayın.
9. Firebase konsolunda, kurulum işleminin geri kalanını tıklayabilirsiniz: Bu bölümün başında indirdiğiniz örnekte Firebase Apple SDK'sı zaten yüklü ve ilklendirme ayarlanmıştır. Konsol'a devam'ı tıklayarak işlemi tamamlayabilirsiniz.

Uygulamayı çalıştırma

Artık uygulamayı deneme zamanı geldi.

1. Xcode'a geri dönüp uygulamayı iOS simülatöründe çalıştırın. Çalıştırma Hedefleri açılır listesinde önce iOS simülasyon araçlarından birini seçin.
2. Ardından, Çalıştır düğmesini tıklayın veya ⌘ + R tuşlarına basın.
3. Uygulama Simülatör'de başarıyla başlatıldıktan sonra birkaç not ekleyin.
4. Uygulamaya yeni notlar eklerken oluşturulan yeni dokümanları görmek için Firebase konsolunda Firestore veri tarayıcısına gidin.

4. Firestore uzantısına sahip Vector Search'ü yükleyin

Codelab'in bu bölümünde, Firestore ile Vector Search uzantısını yükleyecek ve üzerinde çalıştığınız not alma uygulamasının gereksinimlerine göre yapılandıracaksınız.

Uzantıyı yüklemeyi başlatın

1. Yine Firestore bölümünde Uzantılar sekmesini tıklayın.
2. Uzantı Merkezi'ni Keşfet'i tıklayın.
3. "vector" yazın.
4. "Firestore uzantılı vektör arama" seçeneğini tıklayın. Bu işlem sizi uzantının ayrıntılar sayfasına yönlendirir. Bu sayfada uzantı, nasıl çalıştığı, hangi Firebase hizmetlerini gerektirdiği ve nasıl yapılandırabileceğiniz hakkında daha fazla bilgi edinebilirsiniz.
5. Firebase konsolunda yükle'yi tıklayın.
6. Tüm projelerinizin listesi gösterilir.
7. Bu kod laboratuvarının ilk adımında oluşturduğunuz projeyi seçin.

Uzantıyı yapılandırma

1. Etkinleştirilen API'leri ve oluşturulan kaynakları inceleyin.
2. Gerekli hizmetleri etkinleştirin.
3. Tüm hizmetler etkinleştirildikten sonra İleri'yi tıklayın.
4. Bu uzantıya verilen erişimi inceleyin.
5. Uzantıyı yapılandırın:
   • LLM olarak Vertex AI'ı seçin
   • Koleksiyon yolu: notlar
   • Varsayılan sorgu sınırı: 3
   • Giriş alanı adı: text
   • Çıkış alanı adı: embedding
   • Durum alanı adı:* *durum*
   • Mevcut dokümanları yerleştirme: Evet
   • Mevcut dokümanları güncelle: Evet
   • Cloud Function'in konumu: us-central1
6. Yüklemeyi tamamlamak için Uzantıyı yükle'yi tıklayın.

Bu işlem birkaç dakika sürebilir. Kurulumun tamamlanmasını beklerken eğitimimizin bir sonraki bölümüne geçip vektör gömmeleriyle ilgili bazı temel bilgileri okuyabilirsiniz.

5. Arka plan

Kurulumun tamamlanmasını beklerken Firestore uzantılı vektör aramanın işleyiş şekli hakkında bazı temel bilgiler edinebilirsiniz.

Vektörler, yerleştirmeler ve vektör veritabanları nedir?

• Vektörler, bir miktarın büyüklüğünü ve yönünü temsil eden matematiksel nesnelerdir. Verileri karşılaştırmayı ve aramayı kolaylaştıracak şekilde göstermek için kullanılabilirler.
• Yerleşimler, bir kelimenin veya kelime öbeğinin anlamını temsil eden vektörlerdir. Bu modeller, büyük bir metin kümesinde eğitilen bir nöral ağ kullanılarak ve kelimeler arasındaki ilişkiler öğrenilerek oluşturulur.
• Vektör veritabanları, vektör verilerini depolamak ve aramak için optimize edilmiş veritabanlarıdır. Belirli bir sorgu vektörüne en benzer vektörleri bulma işlemi olan verimli en yakın komşu aramasına olanak tanır.

Vektör araması nasıl çalışır?

Vektör araması, sorgu vektörünü veritabanındaki tüm vektörlerle karşılaştırarak çalışır. Sorgu vektörüne en çok benzeyen vektörler, arama sonuçları olarak döndürülür.

İki vektör arasındaki benzerlik, çeşitli mesafe metrikleri kullanılarak ölçülebilir. En yaygın mesafe metriği, iki vektör arasındaki açıyı ölçen kosinüs benzerliğidir.

6. Firestore uzantısıyla Vector Search'i deneme

Bu codelab'de daha önce indirdiğiniz iOS uygulamasında Fictor Search with Firestore uzantısını kullanmadan önce uzantıyı Firebase konsolunda deneyebilirsiniz.

Belgeleri okuyun

Firebase Extensions'ın işleyişiyle ilgili belgelere yer verir.

1. Uzantı yüklendikten sonra Başlayın düğmesini tıklayın.
2. "Bu uzantı nasıl çalışır?" sekmesini inceleyin. Bu sekmede aşağıdaki açıklamalar yer alır:
   • Dokümanları notes koleksiyonuna ekleyerek yerleştirme işlemlerini nasıl hesaplayacağınızı,
   • ext-firestore-vector-search-queryCallable çağrılabilir işlevini çağırarak dizini sorgulama,
   • veya _firestore-vector-search/index/queries koleksiyonuna sorgu belgesi ekleyerek dizini nasıl sorgulayacağınızı öğrenebilirsiniz.
   • Ayrıca, özel bir yerleştirme işlevinin nasıl ayarlanacağı da açıklanmaktadır. Bu, uzantı tarafından desteklenen LLM'lerden hiçbiri gereksinimlerinizi karşılamıyorsa ve yerleştirmeleri hesaplamak için farklı bir LLM kullanmak istiyorsanız yararlıdır.
3. Firestore örneğinize gitmek için Cloud Firestore kontrol paneli bağlantısını tıklayın.
4. _firestore-vector-search/index belgesine gidin. Uzantının, bu codelab'in önceki adımlarından birinde oluşturduğunuz tüm not dokümanları için yerleştirme işlemlerini tamamladığı gösterilir.
5. Bunu doğrulamak için not belgelerinden birini açın. vector<768> türüne sahip embedding adlı ek bir alanın yanı sıra bir status alanı görürsünüz.

Örnek doküman oluşturma

Uzantıyı çalışırken görmek için Firebase konsolunda yeni bir doküman oluşturabilirsiniz.

1. Firestore veri tarayıcısında notes koleksiyonuna gidin ve orta sütunda + Doküman ekle'yi tıklayın.
2. Yeni bir benzersiz doküman kimliği oluşturmak için Auto-ID'yi (Otomatik Kimlik) tıklayın.
3. text adlı, dize türüne sahip bir alan ekleyin ve değer alanına metin yapıştırın. Bu metnin lorem ipsum veya başka bir rastgele metin olmaması önemlidir. Örneğin, bir haber makalesi seçin.
4. Kaydet'i tıklayın.
   • Uzantı, veri işlediğini belirtmek için nasıl bir durum alanı eklediğine dikkat edin.
   • Kısa bir süre sonra, değeri vector<768> olan yeni bir embedding alanı görürsünüz.
   

Sorgu yapma

Firestore uzantılı Vektör Arama, uygulama bağlamanıza gerek kalmadan doküman dizinindeki verileri sorgulamanıza olanak tanıyan kullanışlı bir özelliğe sahiptir.

1. Firebase konsolunun Firestore bölümünde _firestore-vector-search/index belgesine gidin.
2. + Koleksiyon başlat'ı tıklayın
3. queries adında yeni bir alt koleksiyon oluşturun
4. Yeni bir doküman oluşturun ve query alanını dokümanlarınızdan birinde bulunan bir metne ayarlayın. Bu yöntem, "Firestore belgelerini Swift ile nasıl eşleyebilirim?" gibi anlamsal sorgular için en iyi sonucu verir (Eklediğiniz notlardan en az biri bu konuyu ele alan metin içeriyorsa).
5. Durumla ilgili bir hata görebilirsiniz
6. Bu durum, eksik bir dizinden kaynaklanmaktadır. Eksik dizin yapılandırmasını ayarlamak için bu bağlantıyı takip ederek projenizin Google Cloud Console'una gidin ve listeden projenizi seçin
7. Cloud Log Explorer'da, artık "FAILED_PREKOŞ: Vektör dizini yapılandırması eksik. Lütfen aşağıdaki gcloud komutuyla gerekli dizini oluşturun: ..."
8. Hata mesajında, eksik dizini yapılandırmak için çalıştırmanız gereken bir gcloud komutu da bulunur.
9. Komut satırınızda aşağıdaki komutu çalıştırın. Makinenizde gcloud KSA yüklü değilse yüklemek için buradaki talimatları uygulayın.

   gcloud alpha firestore indexes composite create --project=INSERT-YOUR=PROJECT-ID-HERE --collection-group=notes --query-scope=COLLECTION --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=embedding
   

   Dizinin oluşturulması birkaç dakika sürer. İlerleme durumunu Firebase konsolunun Firestore bölümündeki Dizinler sekmesinden kontrol edebilirsiniz.
10. Dizin oluşturulduktan sonra yeni bir sorgu dokümanı oluşturabilirsiniz.
11. Artık sonuçlar alanında eşleşen doküman kimliklerinin listesini göreceksiniz
12. Bu kimliklerden birini kopyalayın ve notes koleksiyonuna geri dönün.
13. Kopyaladığınız doküman kimliğini aramak için ⌘+F tuşlarını kullanın. Bu doküman, sorgunuzla en iyi eşleşen dokümandır.

7. Anlamsal aramayı uygulama

Artık mobil uygulamanızı Firestore uzantılı Vektör Arama'ya bağlamanın ve kullanıcılarınızın notlarını doğal dil sorguları kullanarak aramalarına olanak tanıyacak bir anlamsal arama özelliği uygulamanın zamanı geldi.

Sorgu yürütmek için çağrılabilir işlevi bağlama

Firestore uzantılı Vektör Arama, bu kod laboratuvarının önceki aşamalarında oluşturduğunuz dizini sorgulamak için mobil uygulamanızdan çağırabileceğiniz bir Cloud Functions içerir. Bu adımda, mobil uygulamanız ile bu çağrılabilir işlev arasında bir bağlantı kuracaksınız. Firebase'in Swift SDK'sı, uzak işlevlerin çağrılmasını sorunsuz hale getiren API'ler içerir.

1. Xcode'a geri dönün ve bu codelab'in önceki adımında klonladığınız projede olduğunuzdan emin olun.
2. NotesRepository.swift dosyasını açın.
3. private lazy var vectorSearchQueryCallable: Callable = functions.httpsCallable("") içeren satırı bulun

Çağrılabilir bir Cloud Functions işlevini çağırmak için, çağırmak istediğiniz işlevin adını belirtmeniz gerekir.

4. Projenizin Firebase konsoluna gidin ve Derleme bölümündeki İşlevler menü öğesini açın.
5. Uzantı tarafından yüklenen işlevlerin listesini görürsünüz.
6. ext-firestore-vector-search-queryCallable adlı dosyayı arayın ve adını kopyalayın.
7. Adı kodunuza yapıştırın. Şimdi burada

   private lazy var vectorSearchQueryCallable: Callable<String, String> = functions.httpsCallable("ext-firestore-vector-search-queryCallable")
   

Sorgu işlevini çağırma

1. performQuery yöntemini bulun
2. Aşağıdakileri çağırarak çağrılabilir işlevinizi çağırın:

   let result = try await vectorSearchQueryCallable(searchTerm)
   

Bu bir uzaktan arama olduğu için başarısız olabilir.

3. Hataları yakalamak ve Xcode'un konsoluna kaydetmek için bazı temel hata işleme işlemleri ekleyin.

   private func performQuery(searchTerm: String) async -> [String] {
     do {
       let result = try await vectorSearchQueryCallable(searchTerm)
       return [result]
     }
     catch {
       print(error.localizedDescription)
       return []
     }
   }
   

Kullanıcı arayüzünü bağlama

Kullanıcıların notlarını aramasına izin vermek için not listesi ekranına bir arama çubuğu ekleyeceksiniz. Kullanıcı bir arama terimi girdiğinde, önceki adımda uyguladığınız performQuery yöntemini çağırmanız gerekir. SwiftUI tarafından sağlanan searchable ve task görünüm değiştiricileri sayesinde bu işlem için yalnızca birkaç satır kod gerekir.

1. Öncelikle NotesListScreen.swift
2. Liste görünümüne arama kutusu eklemek için .searchable(text: $searchTerm, prompt: "Search") görünüm değiştiricisini .navigationTitle("Notes") satırının hemen üstüne ekleyin.
3. Ardından, aşağıdaki kodu ekleyip arama işlevini çağırın:

.task(id: searchTerm, debounce: .milliseconds(800)) {
  await notesRepository.semanticSearch(searchTerm: searchTerm)
}

Bu kod snippet'i, semanticSearch yönteminizi eşzamansız olarak çağırır. 800 milisaniyelik bir zaman aşımı sağlayarak görev değiştiriciye, kullanıcının girişini 0,8 saniye boyunca debounce etmesini talimat verirsiniz. Bu, semanticSearch işlevinin yalnızca kullanıcı yazma işlemini 0,8 saniyeden uzun süre duraklattığında çağrılacağı anlamına gelir.

Kodunuz şu şekilde görünecektir:

...
List(repository.notes) { note in
  NavigationLink(value: note) {
    NoteRowView(note: note)
  }
  .swipeActions {
    Button(role: .destructive, action: { deleteNote(note: note) }) {
      Label("Delete", systemImage: "trash")
    }
  }
}
.searchable(text: $searchTerm, prompt: "Search")
.task(id: searchTerm, debounce: .milliseconds(800)) {
  await notesRepository.semanticSearch(searchTerm: searchTerm)
}
.navigationTitle("Notes")
...

Uygulamayı çalıştırma

1. Uygulamayı iOS Simülatöründe başlatmak için ⌘ + R tuşlarına basın (veya Çalıştır düğmesini tıklayın)
2. Bu kod laboratuvarının önceki aşamalarında uygulamaya eklediğiniz notların yanı sıra Firebase konsolu üzerinden eklediğiniz notları da görürsünüz.
3. Notlar listesinin en üstünde bir arama alanı görürsünüz.
4. Eklediğiniz dokümanlardan birinde görünen bir terim yazın. Bu yöntem, "Swift'ten eşzamansız Firebase API'lerini nasıl çağırabilirim?" gibi anlamsal sorgular için en iyi sonucu verir (Eklediğiniz notlardan en az birinin bu konuyu ele alan metin içermesi gerekir).
5. Muhtemelen arama sonucunu görmeyi beklersiniz ancak liste görünümü boştur ve Xcode konsolu şu hata mesajını gösterir: "İşlev geçersiz bir bağımsız değişkenle çağrıldı"

Bu durum, verileri yanlış biçimde gönderdiğiniz anlamına gelir.

Hata mesajını analiz etme

1. Sorunun ne olduğunu öğrenmek için Firebase konsoluna gidin
2. İşlevler bölümüne gidin
3. ext-firestore-vector-search-queryCallable işlevini bulun, üç dikey noktayı tıklayarak taşma menüsünü açın
4. Günlük gezginine gitmek için Günlükleri görüntüle'yi seçin.
5. Bir hata görürsünüz.

Unhandled error ZodError: [
  {
    "code": "invalid_type",
    "expected": "object",
    "received": "string",
    "path": [],
    "message": "Expected object, received string"
  }
]

Bu, verileri yanlış biçimde gönderdiğiniz anlamına gelir.

Doğru veri türlerini kullanma

Uzantının parametrelerin hangi biçimde olmasını beklediğini öğrenmek için uzantının belgelerine göz atın.

1. Firebase konsolundaki Uzantılar bölümüne gidin.
2. Yönet -> seçeneğini tıklayın.
3. Bu uzantının çalışma şekli bölümünde, giriş ve çıkış parametrelerinin bir tanımını bulabilirsiniz.
4. Xcode'a geri dönün ve NotesRepository.swift sayfasına gidin
5. Dosyanın başına aşağıdaki kodu ekleyin:

   private struct QueryRequest: Codable {
     var query: String
     var limit: Int?
     var prefilters: [QueryFilter]?
   }
   
   private struct QueryFilter: Codable {
     var field: String
     var `operator`: String
     var value: String
   
   }
   
   private struct QueryResponse: Codable {
     var ids: [String]
   }
   

   QueryRequest, dokümanlarına göre uzantının beklediği giriş parametresinin yapısıyla eşleşir. Ayrıca, daha sonra ihtiyacınız olacak iç içe yerleştirilmiş bir prefilter özelliği içerir.QueryResponse, uzantının yanıtının yapısıyla eşleşir.
6. Çağırılabilir işlev spesifikasyonunu bulun ve giriş ile çıkış türlerini güncelleyin

   private lazy var vectorSearchQueryCallable: Callable<QueryRequest, QueryResponse> = functions.httpsCallable("ext-firestore-vector-search-queryCallable")
   

7. performQuery'te çağrılabilir işlevin çağrılmasını güncelleyin

   private func performQuery(searchTerm: String) async -> [String] {
     do {
       let queryRequest = QueryRequest(query: searchTerm,
                                       limit: 2)
       let result = try await vectorSearchQueryCallable(queryRequest)
       print(result.ids)
       return result.ids
     }
     catch {
       print(error.localizedDescription)
       return []
     }
   }
   

Uygulamayı tekrar çalıştırma

1. Uygulamayı tekrar çalıştırma
2. Notlarınızdan birine dahil edilen terimleri içeren bir arama sorgusu yazın
3. Filtrelenmiş not listesini göreceksiniz.

Kullanıcı verilerini önceden filtreleme

Kutlama etkinliğinde dans etmeye başlamadan önce, uygulamanın mevcut sürümünde bir sorun vardır: Sonuç kümesi, tüm kullanıcılara ait verileri içerir.

Uygulamayı farklı bir simülatörde çalıştırıp daha fazla doküman ekleyerek bunu doğrulayabilirsiniz. Yeni dokümanlar yalnızca bu simülatörde gösterilir. Uygulamayı diğer simülatörde tekrar çalıştırırsanız yalnızca ilk kez oluşturduğunuz dokümanları görürsünüz.

Arama yaparsanız vectorSearchQueryCallable için yapılan çağrının, diğer kullanıcıya ait olabilecek doküman kimliklerini döndürdüğünü fark edersiniz. Bunu önlemek için bir ön filtre kullanmamız gerekir.

performQuery ürününde, kodunuzu aşağıdaki şekilde güncelleyin:

  let prefilters: [QueryFilter] = if let uid = user?.uid {
    [QueryFilter(field: "userId", operator: "==", value: uid)]
  }
  else {
    []
  }

  let queryRequest = QueryRequest(query: searchTerm,
                                  limit: 2,
                                  prefilters: prefilters)

Bu işlem, verileri giriş yapmış kullanıcının kimliğine göre ön filtreler. Tahmin edebileceğiniz gibi, bunun için Firestore dizininin güncellenmesi gerekir.

embedding alanındaki hem userId değerini hem de vektör yerleştirmelerini içeren yeni bir Firestore dizini tanımlamak için komut satırından aşağıdaki komutu çalıştırın.

gcloud alpha firestore indexes composite create --project=INSERT-YOUR-PROJECT-ID-HERE --collection-group=notes --query-scope=COLLECTION --field-config=order=ASCENDING,field-path=userId --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=embedding

Dizin oluşturulduktan sonra, beklendiği gibi çalıştığını doğrulamak için uygulamayı tekrar çalıştırın.

8. Tebrikler

Tebrikler, bu codelab'i başarıyla tamamladınız!

Bu kod laboratuvarında şunları öğrendiniz:

• Anlamsal aramanın etkin olduğu bir Cloud Firestore veritabanı oluşturun.
• Veritabanı ile etkileşimde bulunmak için basit bir SwiftUI uygulaması oluşturun.
• SwiftUI'nin aranabilir görünüm değiştiricisini ve görev değiştiricisini kullanarak bir arama çubuğu uygulayın.
• Firestore SDK'sının Callable arayüzünü kullanarak veritabanında semantik arama yapmak için bir Cloud Functions işlevi çağırın.

Bu codelab'de edindiğiniz bilgilerle artık Cloud Firestore'un anlamsal arama özelliklerinden faydalanan güçlü uygulamalar oluşturarak kullanıcılara daha sezgisel ve verimli bir arama deneyimi sunabilirsiniz.

Firestore'un yeni vektör alanı ve vektör yerleştirmelerinin nasıl hesaplanacağı hakkında daha fazla bilgi edinmek için dokümanlara göz atın.