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ı 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 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ıları 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.

  • 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 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. 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 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 depolama 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 AI Services (Yapay Zeka Hizmetleri) > AI Logic'e (Yapay Zeka Mantığı) 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 ayarlama kapsamında, 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, 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 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 AI Hizmetleri > AI Logic > İ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ği 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 "Sağlam Operatör" olarak nasıl davranacağı ve ürün kataloğuna nasıl başvuracağı konusunda güvenli bir şekilde talimat verir.
  6. 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ı 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 istek göndermesine 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 > Uygulama Kontrolü'ne 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 anahtarı alanına, Sahtekarlığa Karşı Koruma Anahtarı Ayrıntıları sayfasındaki site anahtarı kimliğini yapıştırın ve Kaydet'i 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ı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 itiraz etmeye devam edin.

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 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, codelab'inizin projesi değilse projeleri değiştirmek için sol üst köşedeki proje seçici açılır listesini kullanabilirsiniz.
  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 ve Agent Platform arka ucunu başlattıysanız.
  • Temsilcinin karmaşık davranışını tanımlamak için Handlebars ve katı giriş şemaları kullanılarak güvenli bir sunucu tarafı istem şablonu yapılandırıldı.
  • Bir 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?