ADK yapay zeka aracısı ve Gemini modeliyle ifadelerin doğruluğunu kontrol etme

Kodlama düzeyi: İleri düzey
Süre: 30 dakika
Proje türü: Özel işlev

Genel Bakış

Vertex AI aracısı ve Gemini modeli tarafından desteklenen, bağlı bir Apps Script projesi olarak kullanılacak Google E-Tablolar için bir doğruluk kontrolü özel işlevi.

Bu örnekte, iki güçlü yapay zeka kaynağı türünü doğrudan Google E-Tablolar'da nasıl kullanabileceğiniz gösterilmektedir:

1. Vertex AI Agent Engine'de dağıtılan ADK temsilcilerini kullanarak gelişmiş, çok araçlı ve çok adımlı akıl yürütme özellikleri için yapay zeka temsilcileri.
2. Vertex AI'daki Gemini modellerini kullanarak gelişmiş anlama, üretme ve özetleme yapay zeka modelleri.

Hedefler

• Çözümün ne yaptığını anlayın.
• Çözümün nasıl uygulandığını anlayın.
• Vertex AI aracısını dağıtın.
• Senaryoyu kurun.
• Komut dosyasını çalıştırın.

Bu çözüm hakkında

E-Tablolar'daki özel işlevin adı FACT_CHECK olup uçtan uca çözüm olarak çalışır. Bir ifadeyi analiz eder, yanıtını en son web bilgilerini kullanarak temellendirir ve sonucu ihtiyacınız olan biçimde döndürür:

• Kullanım:
  • Kısa ve özet bir çıktı için =FACT_CHECK("Your statement here").
  • =FACT_CHECK("Your statement here", "Your output formatting instructions here") belirli bir çıkış biçimi için.
• Mantık: LLM Denetçisi ADK AI Aracısı (Python örneği).
• Çıktı biçimlendirmesi: Gemini modeli.

Bu çözüm, UrlFetchApp kullanarak Vertex AI REST API'lerini ister.

Mimari

Aşağıdaki şemada, özel işlev tarafından kullanılan Google Workspace ve Google Cloud kaynaklarının mimarisi gösterilmektedir.

Ön koşullar

Bu örneği kullanmak için aşağıdaki ön koşulları karşılamanız gerekir:

• Bir Google Hesabı (Google Workspace hesapları yönetici onayı gerektirebilir).

• İnternete erişimi olan bir web tarayıcısı.

• LLM Denetçi ADK aracısının ön koşulları

  • Python 3.11+: Kurulum için resmi Python web sitesindeki talimatları izleyin.
  • Python Poetry: Kurulum için resmi Poetry web sitesindeki talimatları izleyin.
  • Google Cloud KSA: Yükleme için resmi Google Cloud web sitesindeki talimatları uygulayın.

Ortamı hazırlama

Bu bölümde, Google Cloud projesinin nasıl oluşturulacağı ve yapılandırılacağı gösterilmektedir.

Google Cloud projesi oluşturma

Google Cloud konsolu

1. Google Cloud Console'da Menü > IAM & Admin > Proje Oluştur'a gidin.

   Proje oluşturma bölümüne gitme

2. Proje Adı alanına projeniz için açıklayıcı bir ad girin.

   İsteğe bağlı: Proje kimliğini düzenlemek için Düzenle'yi tıklayın. Proje oluşturulduktan sonra proje kimliği değiştirilemez. Bu nedenle, projenin kullanım ömrü boyunca ihtiyaçlarınızı karşılayacak bir kimlik seçin.

3. Konum alanında, projeniz için olası konumları görüntülemek üzere Gözat'a tıklayın. Ardından Seç'e tıklayın.
   Dikkat: Google Workspace kuruluşunuzu bulamıyor musunuz?
   Bu, bir Google Workspace hesabında oturum açmadığınız anlamına gelir. Google Workspace geliştirici belgelerinde açıklanan özelliklerin bazıları yalnızca bir kuruluşla ilişkili projelerde kullanılabilir.
4. Oluştur'u tıklayın. Google Cloud konsolu Pano sayfasına yönlendirilir ve projeniz birkaç dakika içinde oluşturulur.

gcloud CLI

Aşağıdaki geliştirme ortamlarından birinde Google Cloud CLI'ye (gcloud) erişin:

• Cloud Shell: gcloud KSA'nın önceden ayarlandığı bir online terminal kullanmak için Cloud Shell'i etkinleştirin.
  Cloud Shell'i etkinleştirin.
• Yerel kabuk: Yerel geliştirme ortamı kullanmak için gcloud CLI'yı yükleyin ve başlatın.
  Bir Bulut projesi oluşturmak için gcloud projects create komutunu kullanın:

  gcloud projects create PROJECT_ID

  Oluşturmak istediğiniz projenin kimliğini ayarlayarak PROJECT_ID yerine kendi kimliğinizi girin.

Bulut projesi için faturalandırmayı etkinleştirin

Bir faturalandırma hesabını bağlayamıyorsanız, bu değişikliği yapmak için gereken izinlere sahip değilsiniz demektir. Daha fazla bilgi için Faturalandırmayı etkinleştirmek için gereken izinler bölümüne bakın.

Google Cloud konsolu

1. Google Cloud konsolunda Faturalandırma'ya gidin. Şunu tıklayın: Menü > Faturalandırma > Projelerim.

   Projelerim için Faturalandırma'ya gitme

2. Bir kuruluş seçin bölümünde Google Cloud projenizle ilişkili kuruluşu seçin.
3. Proje satırında Eylemler menüsünü () açın, Faturalandırmayı değiştir'e tıklayın ve Cloud Billing hesabını seçin.
4. Hesap belirle'yi tıklayın.

gcloud CLI

1. Kullanılabilir faturalandırma hesaplarını listelemek için şu komutu çalıştırın:

   gcloud billing accounts list

2. Faturalandırma hesabını bir Google Cloud projesine bağlayın:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Aşağıdakini değiştirin:

   • PROJECT_ID, faturalandırmayı etkinleştirmek istediğiniz Bulut projesinin Proje Kimliğidir.
   • BILLING_ACCOUNT_ID, Google Cloud projesiyle bağlantı kurmak için kullanılacak faturalandırma hesabı kimliğidir.

Vertex AI API'yi etkinleştirme

Google Cloud konsolu

1. Google Cloud Console'da Vertex AI API'yi etkinleştirin.

   API'leri etkinleştirme

2. Vertex AI API'sini doğru Cloud projesinde etkinleştirdiğinizi onaylayın ve ardından İleri'ye tıklayın.

3. Doğru API'yi etkinleştirdiğinizden emin olun ve Etkinleştir'i tıklayın.

gcloud CLI

1. Gerekirse, mevcut Cloud projesini gcloud config set project komutuyla oluşturduğunuz projeye ayarlayın:

   gcloud config set project PROJECT_ID

   PROJECT_ID değerini, oluşturduğunuz Bulut projesinin Proje Kimliği ile değiştirin.

2. Vertex AI API'sini gcloud services enable komutuyla etkinleştirin:

   gcloud services enable aiplatform.googleapis.com

Google Cloud konsolunda bir hizmet hesabı oluşturun

Aşağıdaki adımları izleyerek Vertex AI User rolüyle yeni bir hizmet hesabı oluşturun:

Google Cloud konsolu

1. Google Cloud konsolunda Menü > IAM ve Yönetici > Hizmet Hesapları'na gidin.

   Hizmet Hesapları'na gitme

2. Hizmet hesabı oluştur'u tıklayın.
3. Hizmet hesabı ayrıntılarını girin ve ardından Oluştur ve devam et'e tıklayın.
   Not: Varsayılan olarak Google, benzersiz bir hizmet hesabı kimliği oluşturur. Kimliği değiştirmek isterseniz, hizmet hesabı kimliği alanındaki kimliği değiştirin.
4. İsteğe bağlı: Google Cloud projenizin kaynaklarına erişim izni vermek için hizmet hesabınıza roller atayın. Daha ayrıntılı bilgi için Kaynaklara erişim verme, erişimi değiştirme ve iptal etme başlıklı makaleyi inceleyin.
5. Devam'ı tıklayın.
6. İsteğe bağlı: Bu hizmet hesabıyla eylemleri yönetebilen ve gerçekleştirebilen kullanıcıları veya grupları girin. Daha fazla ayrıntı için Hizmet hesabı taklitlerini yönetme konusuna bakın.
7. Bitti'yi tıklayın. Hizmet hesabının e-posta adresini not edin.

gcloud CLI

1. Hizmet hesabını oluşturun:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. İsteğe bağlı: Google Cloud projenizin kaynaklarına erişim izni vermek için hizmet hesabınıza roller atayın. Daha ayrıntılı bilgi için Kaynaklara erişim verme, erişimi değiştirme ve iptal etme başlıklı makaleyi inceleyin.

Hizmet hesabı, hizmet hesabı sayfasında görünür. Ardından, hizmet hesabı için özel anahtar oluşturun.

Özel anahtar oluşturma

Uyarı: Bu örnekte basitlik adına dışa aktarılmış bir hizmet hesabı anahtarı kullanılmıştır. Özel anahtarın dışa aktarılması, kaynak kontrolü gibi güvenli olmayan bir konumda depolanmaması gerektiğinden üretimde önerilmez.

Güvenli hizmet hesabı uygulamaları ve en iyi uygulamalar hakkında daha fazla bilgi edinmek için Hizmet hesaplarını ne zaman kullanacağınızı seçme başlıklı makaleyi inceleyin.

Hizmet hesabı için özel bir anahtar oluşturmak ve indirmek için şu adımları izleyin:

1. Google Cloud konsolunda Menü > IAM ve Yönetici > Hizmet Hesapları'na gidin.

   Hizmet Hesapları'na gitme

2. Hizmet hesabınızı seçin.
3. Anahtarlar > Anahtar ekle > Yeni anahtar oluştur'u tıklayın.
4. JSON'ı seçip Oluştur'u tıklayın.

   Yeni genel/özel anahtar çiftiniz oluşturulur ve bilgisayarınıza yeni bir dosya olarak indirilir. İndirdiğiniz JSON dosyasını çalışma dizininize credentials.json olarak kaydedin. Bu dosya, anahtarın tek kopyasıdır. Anahtarınızı güvenli bir şekilde depolama hakkında bilgi edinmek için Hizmet hesabı anahtarlarını yönetme başlıklı makaleyi inceleyin.

5. Kapat'ı tıklayın.

Hizmet hesapları hakkında daha fazla bilgi için Google Cloud IAM belgelerindeki Hizmet hesapları başlıklı makaleyi inceleyin.

LLM Auditor ADK AI Agent'ı dağıtın

1. Henüz yapmadıysanız, Google Cloud hesabınızla kimlik doğrulaması yapın ve Google Cloud projenizi kullanmak için Google Cloud CLI'yi yapılandırın.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   PROJECT_ID değerini oluşturduğunuz Bulut projesinin kimliğiyle değiştirin.

2. Bu GitHub deposunu indirin

   İndir

3. Tercih ettiğiniz yerel geliştirme ortamında, indirilen arşiv dosyasını çıkarın ve adk-samples/python/agents/llm-auditor dizinini açın.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/llm-auditor

4. ADK aracısına özel yeni bir Bulut Depolama kovası oluşturun.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   Aşağıdakini değiştirin:

   1. CLOUD_STORAGE_BUCKET_NAME ile kullanmak istediğiniz benzersiz bir paket adı.
   2. PROJECT_ID kısmını, oluşturduğunuz Cloud projesinin kimliğiyle değiştirin.
   3. PROJECT_LOCATION kısmını, oluşturduğunuz Cloud projesinin konumuyla değiştirin.

5. Aşağıdaki ortam değişkenlerini ayarlayın:

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

   Aşağıdakini değiştirin:

   1. CLOUD_STORAGE_BUCKET_NAME ifadesini oluşturduğunuz paketin adıyla değiştirin.
   2. PROJECT_ID kısmını, oluşturduğunuz Cloud projesinin kimliğiyle değiştirin.
   3. PROJECT_LOCATION kısmını, oluşturduğunuz Cloud projesinin konumuyla değiştirin.

6. Sanal ortamdan ADK aracısını kurun ve dağıtın.

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. Aracı kimliğini alın. Özel işlevi yapılandırmak için daha sonra bu kimliğe ihtiyacınız olacak.

   python3 deployment/deploy.py --list

Örnek kodu inceleme

İsteğe bağlı olarak, yeni e-tabloyu oluşturmadan önce GitHub'da barındırılan örnek kodu inceleyip kendinizi alıştırmak için biraz zaman ayırın.

GitHub'da göster

Yeni bir e-tabloda oluşturma ve yapılandırma

1. Aşağıdaki butona tıklayın ve kapsayıcıya bağlı Apps Script projesi de dahil olmak üzere örnek Google E-Tablolar elektronik tablosunun tam bir kopyasını oluşturun.

   Google E-Tablolar e-tablosunu kopyalama

2. Yeni oluşturulan elektronik tabloda Uzantılar > Uygulama Komut Dosyası'na gidin.

3. Apps Komut Dosyası projesinde Proje Ayarları'na gidin, Komut dosyası özelliklerini düzenle'yi ve ardından Komut dosyası özelliği ekle'yi tıklayarak aşağıdaki komut dosyası özelliklerini ekleyin:

   1. LOCATION kısmını, önceki adımlarda oluşturulan Google Cloud projesinin konumuyla (ör. us-central1) değiştirin.
   2. GEMINI_MODEL_ID ile kullanmak istediğiniz Gemini modeli (ör. gemini-2.5-flash-lite)
   3. Önceki adımlarda dağıtılan LLM Denetçi ADK Aracısının kimliğiyle REASONING_ENGINE_ID, örneğin 1234567890.
   4. SERVICE_ACCOUNT_KEY ile önceki adımlarda indirilen hizmet hesabının JSON anahtarı (ör. { ... })

4. Komut dosyası özelliklerini kaydet'e tıklayın

Özel işlevi test etme

1. Yeni oluşturulan elektronik tabloya gidin.
2. A sütunundaki ifadeleri değiştirin.
3. B sütunundaki formüller yürütülür ve ardından gerçeklik kontrolü sonuçları görüntülenir.

Temizleme

Bu eğitimde kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini önlemek istiyorsanız Cloud projesini silmenizi öneririz.

Dikkat: Bir projenin silinmesinin etkileri şunlardır:

• Projedeki her şey silinir. Bu eğitim için mevcut bir projeyi kullandıysanız, onu sildiğinizde projede yaptığınız diğer çalışmaları da silmiş olursunuz.
• Özel proje kimlikleri kaybolur. Bu projeyi oluşturduğunuzda, gelecekte kullanmak isteyebileceğiniz özel bir proje kimliği oluşturmuş olabilirsiniz. Proje kimliğini kullanan URL'leri (ör. appspot.com'daki bir URL) korumak için projenin tamamını silmek yerine proje içindeki seçili kaynakları silin.

Birden fazla öğretici ve hızlı başlangıç kılavuzunu incelemeyi planlıyorsanız, projeleri yeniden kullanmak proje kotası sınırlarını aşmanızı önlemeye yardımcı olabilir.

1. Google Cloud Console'da Kaynakları yönetin sayfasına gidin. Şunu tıklayın: Menü > IAM ve Yönetici > Kaynakları Yönetin.

   Resource Manager'a gidin

2. Proje listesinde silmek istediğiniz projeyi seçin ve ardından Sil'e tıklayın.
3. İletişim kutusunda proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.

Sonraki adımlar

• Google Workspace genelinde erişilebilen bir yapay zeka temsilcisiyle seyahatlerinizi planlayın
• Google E-Tablolar'daki özel işlevler
• Google E-Tablolar'ı Genişletme