Firebase AI Logic'i kullanarak yapay zeka destekli müşteri desteği temsilcisi oluşturma

1. Giriş

Bu codelab'de, Rugged Terrain Guide adlı doğa sporu ekipmanı e-ticaret mağazasına akıllı bir müşteri desteği sohbet widget'ı ekleyeceksiniz. Bu aracı oluşturmak için Firebase AI Logic'i kullanacak ve yapay zekanın karakterini, katı telafi bütçesi kurallarını işleyen ve ürün kataloğunu bağlam olarak dinamik bir şekilde kullanan sunucu tarafı istem şablonunu (product-agent) nasıl yapılandıracağınızı öğreneceksiniz.

Yapacaklarınız:

  • Bu codelab'in web uygulaması için başlangıç kodunu alın.
  • Firebase projesi oluşturun.
  • Web uygulamasında Firebase hizmetlerini (ör. Firebase AI Logic) ayarlama ve başlatma.
  • Firebase konsolunda sunucu taraflı bir istem şablonu yapılandırın.
  • React benzeri bir TypeScript ön ucundan üretken yapay zeka hizmetine yapılan bir çağrıdan şablona erişin.

Şunlara ihtiyacınız olacaktır:

  • Chrome gibi bir web tarayıcısı
  • TypeScript ve Node.js hakkında temel düzeyde bilgi sahibi olmanız gerekir.
  • Seçtiğiniz bir IDE veya metin düzenleyici. Antigravity iyi bir seçimdir.

2. Başlangıç kodunu alma

  1. Terminalinizde başlangıç deposunu klonlayın:
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
  2. Kod dizinine gidin ve bağımlılıkları yükleyin:
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
npm install

3. Firebase projesi oluşturma

Firebase projesi oluşturma

  1. Google Hesabınızı kullanarak Firebase konsolunda oturum açın.
  2. Yeni bir proje oluşturmak için düğmeyi tıklayın ve ardından bir proje adı girin (örneğin, rugged-terrain-ai).
  3. Devam'ı tıklayın.
  4. İstenirse Firebase şartlarını inceleyip kabul edin ve Devam'ı tıklayın.
  5. (İsteğe bağlı) Firebase konsolunda yapay zeka yardımını etkinleştirin ("Firebase'de Gemini" olarak adlandırılır).
  6. Bu codelab için Google Analytics'e ihtiyacınız yoktur. Bu nedenle, Google Analytics seçeneğini devre dışı bırakın.
  7. Proje oluştur'u tıklayın, projenizin hazırlanmasını bekleyin ve ardından Devam'ı tıklayın.

Firebase fiyatlandırma planınızı yükseltme

Bu codelab'deki Firebase hizmetlerini kullanmak için Firebase projenizin kullandıkça öde (Blaze) fiyatlandırma planında olması gerekir. Bu da projenin bir Cloud Faturalandırma hesabına bağlı olduğu anlamına gelir.

Projenizi Blaze planına geçirmek için aşağıdaki adımları uygulayın:

  1. Firebase konsolunda planınızı yükseltmeyi seçin.
  2. Blaze planını seçin. Bir Cloud Faturalandırma hesabını projenize bağlamak için ekrandaki talimatları uygulayın.
    Bu yükseltme kapsamında bir Cloud Faturalandırma hesabı oluşturmanız gerekiyorsa yükseltmeyi tamamlamak için Firebase Console'daki yükseltme akışına geri dönmeniz gerekebilir.

4. Firebase hizmetlerini ayarlama ve uygulamanızı bağlama

Bu codelab için Firebase projenizde Cloud Storage for Firebase ve Firebase AI Logic'i ayarlamanız gerekir. Ayrıca uygulamanızın kaynak kodunu Firebase projenize bağlamanız gerekir.

Cloud Storage for Firebase'i ayarlama

Bu codelab'de ürün açıklamalarını depolamak için Cloud Storage for Firebase kullanılır.

  1. Firebase konsolunda Veritabanları ve Depolama > Depolama'ya gidin.
  2. Başlayın'ı tıklayın.
  3. Varsayılan Storage paketinize bir konum seçin.
    US-WEST1, US-CENTRAL1 ve US-EAST1 bölgelerindeki paketler, Google Cloud Storage için "Daima Ücretsiz" katmanından yararlanabilir. Diğer tüm konumlardaki paketler için Google Cloud Storage fiyatlandırması ve kullanımı geçerlidir.
  4. Üretim modu'nu tıklayın. Hemen aşağıdaki adımlarda, bu güvenlik kurallarını bu codelab'e özel olacak şekilde güncelleyeceksiniz.
  5. Oluştur'u tıklayın.
  6. Güvenlik kurallarınızı güncelleyin:
    1. Paket sağlandıktan sonra Kurallar sekmesine gidin.
    2. Aşağıdaki kuralları kopyalayıp yapıştırın:
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. Yayınla'yı tıklayın.
  7. Başlangıç kodundan ürün açıklamalarını yükleyin:
    1. Depolama paketinize ait Dosyalar sekmesini tıklayın.
    2. Dosya Yükle'yi tıklayın ve başlangıç kodundaki products.txt dosyasını yükleyin. Bu dosyayı şu konumda bulabilirsiniz: src/data/products.txt.

Firebase AI Logic'i yapılandırma

Firebase AI Logic, bu codelab'de kullanacağınız temel Firebase hizmetidir.

  1. Firebase konsolunda Yapay Zeka Hizmetleri > AI Logic'e gidin.
  2. Başlayın'ı tıklayın.
  3. Vertex AI Gemini API kartında Bu API'yi kullanmaya başlayın'ı tıklayın ve ekrandaki talimatları uygulayın. Bu akış, Firebase AI Logic'i Vertex AI Gemini API ile kullanabilmeniz için gerekli API'leri etkinleştirir.
  4. (İsteğe bağlı) Firebase AI Logic aracılığıyla istekleriniz hakkında kapsamlı görünürlük elde etmek için çeşitli uygulama düzeyindeki metrikleri ve kullanımı gözlemleyebilmek üzere Yapay zeka izlemeyi etkinleştir'i seçin.

Kodunuzu Firebase projenize bağlama

Firebase AI Logic'i ayarlarken bir Firebase web uygulaması oluşturmanız ve yapılandırmanızı kaynak kodunuza eklemeniz istenir.

  1. Firebase AI Logic kurulum akışında istendiğinde yeni bir web uygulaması kaydetmek için Web () simgesini tıklayın.
  2. Uygulamaya ad verin (örneğin, Rugged Web).
  3. Kurulum talimatlarından firebaseConfig nesnesini kopyalayın.

Ardından, başlangıç kodunu güncelleyin:

  1. Kod düzenleyicinizde src/firebase.ts dosyasını açın.
  2. Mevcut firebaseConfig değerini, Firebase konsolundan kopyaladığınız değerle değiştirin.

Dosyanız şu şekilde görünmelidir:

import { getAI, getTemplateGenerativeModel, VertexAIBackend } from "firebase/ai";
import { initializeApp } from "firebase/app";

// Your web app's Firebase configuration
const firebaseConfig = {
    apiKey: "YOUR_API_KEY",
    authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
    projectId: "YOUR_PROJECT_ID",
    storageBucket: "YOUR_PROJECT_ID.firebasestorage.app",
    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
    appId: "YOUR_APP_ID"
};

// Initialize Firebase
export const app = initializeApp(firebaseConfig);

const ai = getAI(app, { backend: new VertexAIBackend() });

5. Sunucu taraflı istem şablonunu oluşturma

İstemci uygulamasına karmaşık yapay zeka istemlerini sabit kodlamak yerine, sunucudaki talimatları güvenli bir şekilde yönetmek için Dotprompt söz dizimini kullanacaksınız.

Bu sayede son kullanıcıların gizli "Telafi Bütçesi" kurallarını görmesi engellenir.

  1. Firebase konsolunda Vertex AI veya İstem Yönetimi bölümüne gidin.
  2. Yeni bir istem şablonu oluşturun ve product-agent olarak adlandırın.
  3. Modeli gemini-2.5-flash olarak ayarlayın.
  4. Giriş şemasını tam olarak aşağıdaki gibi tanımlayın:
    input:
  schema:
    query:
      type: string
      description: the customers ask of the robot
    productId?:
      type: string
      description: the product the customer is looking at right now
    history?:
      type: array
      description: list of previous history between the user and system
      items:
        type: object
        required: [role, contents]
        properties:
          role:
            type: string
          contents:
            type: string
  5. Kök dizindeki agent-product.prompt içeriğini kopyalayıp İstem ve isteğe bağlı sistem talimatları alanına yapıştırın. Bu, modele "Rugged Operator" olarak nasıl davranması gerektiğini güvenli bir şekilde bildirir ve ürün kataloğunu ekler.
  6. Firebase konsolunda product-agent şablonunu kaydedip yayınlayın.

6. Yapay zeka modelini çağırma

Şablon sunucuda güvenli bir şekilde tanımlandığına göre artık şablonu uygulamanızın ön ucundan çağırmanız yeterlidir.

  1. Kod düzenleyicinizde src/firebase.ts bölümüne dönün.
  2. Başlatma işleminden sonra şablona bağlanmak için getTemplateGenerativeModel simgesini kullanın:
    const model = getTemplateGenerativeModel(ai);

export const callCustomerSupportModel = async (query: string, productId?: string, history?: { role: string, contents: string }[]) => {
    // Generate content using the published 'product-agent' template
    const result = await model.generateContent('product-agent', {
        query,
        productId,
        history,
    });
    return result.response.text();
}

7. Firebase Uygulama Kontrolü ile aracıyı güvenli hale getirme

Yapay zeka modelleri güçlüdür ancak herkese açık uç noktalar korunmadığında kötüye kullanılabilir. Yalnızca gerçek web uygulamanızın Vertex AI üretken modelini çağırabildiğinden emin olmak için her zaman Firebase Uygulama Kontrolü'nü kullanmanız gerekir. Bu sayede botlar ve yetkisiz istemciler engellenir.

  1. Firebase konsolunda Oluştur > App Check'e gidin.
  2. Uygulamalar sekmesini tıklayın, web uygulamanızı genişletin (Rugged Web) ve reCAPTCHA Enterprise sağlayıcısını tıklayın.
  3. Yeni reCAPTCHA Enterprise anahtarı oluştur'u seçin ve istemi doldurun:
    • Ad: Codelab Key
    • Alanlar: Yerel Vite sunucunuzun istekte bulunmasına izin verilmesi için localhost ve 127.0.0.1 değerlerini ekleyin.
  4. Uygulamayı kaydetmek için Kaydet'i tıklayın.
  5. Kaydolduktan sonra Firebase konsolunda Site Anahtarınız gösterilir. Bu dizeyi kopyalayın.
  6. Kod düzenleyicinizde src/firebase.ts dosyasını tekrar açın.
  7. En üste aşağıdaki içe aktarma işlemlerini ekleyin:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  8. Uygulama Kontrolü başlatma işlemini initializeApp(firebaseConfig) çağrınızın hemen ardından ekleyin ve kopyaladığınız site anahtarını yapıştırın:
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  useLimitedUseAppCheckTokens: true
});
  9. Bu jetonları kullanmak için getAI() işlev çağrınızı güncelleyin. Aşağıdaki değişikliği yapın:
    const ai = getAI(app, { backend: new VertexAIBackend(), useLimitedUseAppCheckTokens: true });
    useLimitedUseAppCheckTokens değerini doğru olarak ayarlayarak, arka uçunuzun maruz kalabileceği kötüye kullanımı sınırlamaya yardımcı olmak için kısa ömürlü jetonların uygulanmasını sağlarsınız.

8. Uygulamayı çalıştırma

Firebase yapılandırmanız hazır ve destek sohbeti widget'ı bağlıyken uygulamayı çalıştırmanın zamanı geldi.

  1. Terminalinizde Vite geliştirme sunucusunu çalıştırın:
    npm run dev
  2. Sağlanan yerel URL'yi (genellikle http://localhost:5173/) açın.
  3. Sağ alt köşedeki Taktik Destek Kayan İşlem Düğmesi'ni (FAB) tıklayın.
  4. Ürünlerle ilgili sorular sormayı deneyin. Örneğin:
    • "Hava koşullarına dayanıklı bir dış giyim arıyorum"
    • "My sub-zero beanie is defective, what can I do?" (Sıfırın altındaki sıcaklıklar için olan berem arızalı, ne yapabilirim?)
    • Yapay zekanın "yatıştırma bütçesi" mantığını tetiklemek için sürekli olarak karşı çıkın.

9. (İsteğe bağlı) Codelab'deki kaynakları temizleme

Google Cloud faturalandırma hesabınızın olası ücretlendirilmesini önlemek için bu codelab sırasında oluşturulan kaynakları silebilirsiniz.

  1. Firebase konsoluna gidin.
  2. rugged-terrain-ai projesini seçin.
  3. Proje ayarları'na (dişli simgesi) gidin.
  4. En alta kaydırıp Projeyi sil'i tıklayın.
  5. Silme işlemini onaylamak için ekrandaki talimatları uygulayın.

10. Tebrikler!

🎊 Görev Tamamlandı! Güçlü ve şablon odaklı bir yapay zeka müşteri desteği temsilcisini başarıyla entegre ettiniz.

Başarılarınız:

  • Bir istemci uygulamasında Firebase'i başlattıysanız ve Vertex AI arka ucunu kullanıyorsanız.
  • Aracının karmaşık davranışını tanımlamak için Handlebars ve katı giriş şemaları kullanarak güvenli bir sunucu tarafı istem şablonu yapılandırdı.
  • LLM'yi dinamik olarak çağırma: Dahili istem mantığını istemciye göstermeden sohbet geçmişini ve bağlamsal ürün kimliklerini güvenli bir şekilde iletir.

Sırada ne var?