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

1. Giriş

Bu codelab'de, Rugged Terrain Guide adlı bir doğa sporu ekipmanı e-ticaret mağazasına akıllı bir müşteri desteği sohbet widget'ı ekleyeceksiniz. Bu ajanı 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ında 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.
  • Firebase hizmetlerini (ör. Firebase AI Logic) bir web uygulamasında ayarlama ve başlatma.
  • Firebase konsolunda sunucu tarafında 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 bilgi sahibi olmanız gerekir.
  • Seçtiğiniz bir IDE veya metin düzenleyici. Yerçekimsiz 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 proje adını 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.

  • Cloud Faturalandırma Hesabı için kredi kartı gibi bir ödeme yöntemi gerekir.
  • Özel promosyonlar sırasında veya bu codelab'i bir etkinliğin parçası olarak yapıyorsanız Google Cloud kredileri kullanılabilir.
  • Firebase ve Google Cloud'u kullanmaya yeni başladıysanız 300 ABD doları değerinde kredi ve ücretsiz deneme Cloud Faturalandırma hesabı için uygun olup olmadığınızı kontrol edin.

Projenizi Blaze planına yükseltmek 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. Cloud Faturalandırma Hesabı'nı projenize bağlamak için ekrandaki talimatları uygulayın.
    • Bu codelab için Google Cloud kredileri kullanıyorsanız faturalandırma hesabının adı büyük olasılıkla Google Cloud Platform Trial Billing Account veya My Billing Account'dır.
    • Bu yükseltme kapsamında bir Cloud Faturalandırma hesabı oluşturmanız gerekiyorsa yükseltmeyi tamamlamak için Firebase konsolundaki 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 depolama paketinizi oluşturmak için 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 Google Cloud Storage fiyatlandırması ve kullanımına tabidir.
  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. Grup 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ıç kodundan 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. Agent Platform 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 Agent Platform 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. Uygulamayı adlandırın (ö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 aşağıdaki gibi görünmelidir:

import { getAI, getTemplateGenerativeModel, AgentPlatformBackend } 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 AgentPlatformBackend() });

5. Sunucu tarafı istem şablonunu oluşturma

Karmaşık yapay zeka istemlerini istemci uygulamasına 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 AI Services (Yapay Zeka Hizmetleri) > AI Logic (Yapay Zeka Mantığı) > İstem şablonları sekmesine gidin.
  2. Şablon oluştur'u tıklayın ve Boş şablon'u seçin.
  3. Şablon adını Product Agent, kimliğini ise product-agent olarak ayarlayın.
  4. Modeli gemini-3.1-flash-lite (veya mevcut en yeni sürüm) olarak ayarlayın.
  5. Bu codelab için sağlanan başlangıç kodundan product-agent.prompt dosyasının içeriğini kopyalayın (bu dosyayı kök dizinde bulabilirsiniz). Ardından, bu içeriği Firebase konsolundaki sunucu istemi şablonunun İstem ve (isteğe bağlı) sistem talimatları alanına yapıştırın. Bu içerik, modele "Rugged Operator" olarak nasıl davranacağı ve ürün kataloğuna nasıl referans vereceği konusunda güvenli bir şekilde talimat verir.
  6. Test input (Test girişi) alanında giriş şemasını tam olarak aşağıdaki gibi tanımlayın:
    {
      "type": "object",
      "required": [
        "query"
      ],
      "properties": {
        "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"
              }
            }
          }
        }
      }
    }
    
  7. product-agent şablonunu kaydedip yayınlamak için Şablonu kaydet'i tıklayı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 korunmasız bırakılırsa kötüye kullanılabilir. Yalnızca gerçek web uygulamanızın Gemini API'ye başarılı istekler gönderebilmesini sağlamak için her zaman Firebase Uygulama Kontrolü'nü kullanmanız gerekir. Bu sayede botlar ve yetkisiz istemciler engellenir.

  1. Google Cloud Console'da Güvenlik > Sahtekarlığa Karşı Koruma'ya gidin.
  2. Anahtar Oluştur'u tıklayın ve alanları doldurun:
    • Görünen ad: Codelab Key
    • Uygulama Türü: Web
    • Alan adı listesi: Yerel Vite sunucunuzun istekte bulunmasına izin verilmesi için localhost ve 127.0.0.1 öğelerini ekleyin.
  3. Anahtarı kaydetmek için Anahtar oluştur'u tıklayın.
  4. Sahtekarlığa Karşı Koruma Anahtarı Ayrıntıları sayfasının üst kısmından site anahtarı kimliğini panonuza kopyalayın.
  5. Firebase konsolunda Güvenlik > App Check'e gidin.
  6. Uygulamalar sekmesini tıklayın, web uygulamanızı genişletin (Rugged Web) ve reCAPTCHA Enterprise sağlayıcısını tıklayın.
  7. reCAPTCHA Enterprise site key (reCAPTCHA Enterprise site anahtarı) alanına, Fraud Defense Key Details (Sahtekarlığa Karşı Koruma Anahtarı Ayrıntıları) sayfasındaki site anahtarı kimliğini yapıştırın ve Save'i (Kaydet) tıklayın.
  8. Kod düzenleyicinizde src/firebase.ts dosyasını tekrar açın.
  9. En üste aşağıdaki içe aktarma işlemlerini ekleyin:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
    
  10. App Check başlatma işlemini initializeApp(firebaseConfig) çağrınızın hemen ardından ekleyin ve kopyaladığınız site anahtarı kimliğini yapıştırın:
    // Initialize App Check
    const appCheck = initializeAppCheck(app, {
      provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
      isTokenAutoRefreshEnabled: true
    });
    
  11. Bu jetonları kullanmak için getAI() işlevi çağrınızı güncelleyin. Aşağıdaki değişikliği yapın:
    const ai = getAI(app, { backend: new AgentPlatformBackend(), 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ırın

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 itiraz etmeye devam edin.

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

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

  1. Firebase konsolunda Ayarlar > Genel sekmesine gidin.
  2. Görüntülediğiniz projenin bu codelab için kullandığınız proje olduğundan emin olun. Bu proje, codelab'inizin projesi değilse sol üst köşedeki proje seçici açılır listesini kullanarak projeleri değiştirebilirsiniz.
  3. Sayfanın en altına gidin ve Projeyi sil'i tıklayın.
  4. 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ı ve Agent Platform arka ucunu başlattı.
  • Temsilcinin karmaşık davranışını tanımlamak için Handlebars ve katı giriş şemaları kullanarak güvenli bir sunucu tarafı istem şablonu yapılandırdı.
  • Bir LLM'nin dinamik olarak çağrılması, istemciye dahili istem mantığını göstermeden sohbet geçmişini ve bağlamsal ürün kimliklerini güvenli bir şekilde iletir.

Sırada ne var?