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 aracılarını kullanarak karmaşık, çok araçlı ve çok adımlı akıl yürütme özellikleri için yapay zeka aracıları.
2. Vertex AI'daki Gemini modellerini kullanarak gelişmiş anlama, üretkenlik ve özetleme yapay zeka modelleri.

Hedefler

• Çözümün ne işe yaradığını anlayın.
• Çözümün nasıl uygulandığını anlayın.
• Vertex AI aracısını dağıtın.
• Komut dosyasını ayarlayın.
• Komut dosyasını çalıştırın.

Bu çözüm hakkında

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

• Kullanım:
  • =FACT_CHECK("Your statement here"), kısa ve özetlenmiş bir çıktı için kullanılır.
  • =FACT_CHECK("Your statement here", "Your output formatting instructions here") için belirli bir çıkış biçimi.
• Gerekçe: LLM Auditor ADK AI Agent (Python örneği).
• Çıkış 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:

• Google Hesabı (Google Workspace hesapları için yönetici onayı gerekebilir).

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

• LLM Auditor ADK aracısının ön koşulları

  • Python 3.11 ve sonraki sürümler: Yükleme için resmi Python web sitesindeki talimatları uygulayın.
  • Python Poetry: Yükleme için resmi Poetry web sitesindeki talimatları uygulayın.
  • 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 kimliği, proje oluşturulduktan sonra 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öz at'ı tıklayın. Ardından Seç'i 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 dokümanlarında açıklanan bazı özellikler yalnızca bir kuruluşla ilişkili projelerde kullanılabilir.
4. Oluştur'u tıklayın. Google Cloud Console, Kontrol Paneli sayfasına gider ve projeniz birkaç dakika içinde oluşturulur.

gcloud CLI

Aşağıdaki geliştirme ortamlarından birinde Google Cloud KSA'ya (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.
  Cloud 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 koyun.

Cloud projesi için faturalandırmayı etkinleştirme

Faturalandırma hesabı bağlayamıyorsanız bu değişikliği yapmak için gereken izinlere sahip değilsiniz. Daha fazla bilgi için Faturalandırmayı etkinleştirmek için gereken izinler başlıklı makaleyi inceleyin.

Google Cloud konsolu

1. Google Cloud Console'da 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 İşlemler menüsünü () açın, Faturalandırmayı değiştir'i tıklayın ve Cloud Faturalandırma 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. Bir faturalandırma hesabını Google Cloud projesiyle bağlama:

   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 Cloud projesinin proje kimliğidir.
   • BILLING_ACCOUNT_ID, Google Cloud projesiyle ilişkilendirilecek 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'yi doğru Cloud projesinde etkinleştirdiğinizi onaylayıp İleri'yi tıklayın.

3. Doğru API'yi etkinleştirdiğinizi onaylayın 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 kısmını, oluşturduğunuz Cloud projesinin proje kimliği ile değiştirin.

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

   gcloud services enable aiplatform.googleapis.com

Google Cloud Console'da hizmet hesabı oluşturma

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

Google Cloud konsolu

1. Google Cloud Console'da 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ı girip Oluştur ve devam et'i tıklayın.
   Not: Google, varsayılan olarak benzersiz bir hizmet hesabı kimliği oluşturur. Kimliği değiştirmek istiyorsanız 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 işlemleri yönetebilecek ve gerçekleştirebilecek kullanıcıları veya grupları girin. Daha fazla bilgi için Hizmet hesabı kimliğine bürünmeyi yönetme başlıklı makaleyi inceleyin.
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 için dışa aktarılmış bir hizmet hesabı anahtarı kullanılmaktadı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 anahtar oluşturmak ve indirmek üzere aşağıdaki adımları uygulayın:

1. Google Cloud Console'da 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çin ve Oluştur'u tıklayın.

   Yeni herkese açık/özel anahtar çiftiniz oluşturulur ve makinenize yeni bir dosya olarak indirilir. İndirilen JSON dosyasını çalışma dizininize credentials.json olarak kaydedin. Bu dosya, anahtarın tek kopyasıdır. Anahtarınızı güvenli ş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ı bölümünü inceleyin.

LLM Auditor ADK AI Agent'ı dağıtma

1. Henüz yapmadıysanız Google Cloud hesabınızla kimliğinizi doğrulayın ve Google Cloud CLI'yı Google Cloud projenizi kullanacak şekilde 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 kısmını, oluşturduğunuz Cloud 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 Cloud Storage paketi 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 ile 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. ADK aracısını sanal ortamdan yükleyip 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 düğmeyi tıklayın ve kapsayıcıya bağlı Apps Komut Dosyası projesi de dahil olmak üzere örnek Google E-Tablolar elektronik tablosunun tam bir kopyasını oluşturun.

   Google E-Tablolar elektronik tablosunu kopyalama

2. Yeni oluşturulan e-tabloda Uzantılar > Apps 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 modeliyle (ör. gemini-2.5-flash-lite)
   3. REASONING_ENGINE_ID ile önceki adımlarda dağıtılan LLM Auditor ADK aracısının kimliği (ör. 1234567890)
   4. SERVICE_ACCOUNT_KEY ile önceki adımlarda indirilen hizmet hesabının JSON anahtarı (ör. { ... })

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

Özel işlevi test etme

1. Yeni oluşturulan e-tabloya gidin.
2. A sütunundaki ifadeleri değiştirin.
3. B sütunundaki formüller çalıştırılır ve doğruluk kontrolü sonuçları gösterilir.

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 proje kullandıysanız projeyi sildiğinizde projede yaptığınız diğer tüm çalışmaları da silersiniz.
• Özel proje kimlikleri kaybolur. Bu projeyi oluştururken gelecekte kullanmak istediğ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 eğitici ve hızlı başlangıç kılavuzunu incelemeyi planlıyorsanız projeleri yeniden kullanmak proje kotası sınırlarını aşmanızı önleyebilir.

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 Sil'i tıklayın.
3. İletişim kutusunda proje kimliğini yazın ve ardından projeyi silmek için Kapat'ı tıklayın.

Sonraki adımlar

• Google E-Tablolar'daki özel işlevler
• Google E-Tablolar'ı genişletme