نصب و راه‌اندازی جعبه ابزار برای Gen AI و AMP; برنامه های کاربردی در AlloyDB

1. بررسی اجمالی

Gen AI Toolbox for Databases یک سرور منبع باز از گوگل است که ساخت ابزارهای Gen AI را برای تعامل با پایگاه های داده آسان تر می کند. این به شما امکان می دهد تا با مدیریت پیچیدگی هایی مانند ادغام اتصال، احراز هویت و موارد دیگر، ابزارها را آسان تر، سریع تر و ایمن تر توسعه دهید. این به شما کمک می کند ابزارهای Gen AI بسازید که به عوامل شما اجازه می دهد به داده های پایگاه داده شما دسترسی داشته باشند. جعبه ابزار فراهم می کند:

توسعه ساده: ابزارها را در کمتر از 10 خط کد با عامل خود ادغام کنید، از ابزارها بین چندین عامل یا فریمورک استفاده مجدد کنید و نسخه های جدید ابزارها را راحت تر اجرا کنید.

عملکرد بهتر: بهترین روش‌ها مانند ادغام اتصال، احراز هویت و موارد دیگر.

امنیت پیشرفته: احراز هویت یکپارچه برای دسترسی ایمن تر به داده های شما.

قابلیت مشاهده سرتاسر: معیارهای خارج از جعبه و ردیابی با پشتیبانی داخلی برای OpenTelemetry.

جعبه ابزار بین چارچوب سازماندهی برنامه شما و پایگاه داده شما قرار می گیرد و یک صفحه کنترل را ارائه می دهد که برای اصلاح، توزیع یا فراخوانی ابزارها استفاده می شود. با ارائه یک مکان متمرکز برای ذخیره و به‌روزرسانی ابزارها، مدیریت ابزارهای شما را ساده می‌کند و به شما این امکان را می‌دهد که ابزارها را بین عوامل و برنامه‌ها به اشتراک بگذارید و آن ابزارها را بدون نیاز به استقرار مجدد برنامه خود به‌روزرسانی کنید.

چیزی که خواهی ساخت

به عنوان بخشی از این آزمایشگاه، برنامه‌ای می‌سازید که از ابزاری برای انجام یک پرس و جوی ساده پایگاه داده (AlloyDB) استفاده می‌کند که می‌تواند از عامل شما یا برنامه هوش مصنوعی مولد فراخوانی شود. برای این شما خواهد شد

1. Toolbox را نصب کنید
2. ابزار را (که برای انجام یک کار در AlloyDB طراحی شده است) روی سرور جعبه ابزار راه اندازی کنید
3. جعبه ابزار را در Cloud Run مستقر کنید
4. ابزار را با نقطه پایانی Cloud Run مستقر آن آزمایش کنید
5. برای فراخوانی جعبه ابزار، تابع اجرای ابری را بسازید

الزامات

• مرورگری مانند کروم یا فایرفاکس
• یک پروژه Google Cloud با فعال بودن صورت‌حساب (مراحل در بخش بعدی).

2. قبل از شروع

یک پروژه ایجاد کنید

1. در Google Cloud Console ، در صفحه انتخاب پروژه، یک پروژه Google Cloud را انتخاب یا ایجاد کنید.
2. مطمئن شوید که صورتحساب برای پروژه Cloud شما فعال است. با نحوه بررسی فعال بودن صورت‌حساب در پروژه آشنا شوید.
3. شما از Cloud Shell ، یک محیط خط فرمان که در Google Cloud اجرا می شود، استفاده خواهید کرد. روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید.

4. پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی کنید که آیا قبلاً احراز هویت شده اید و آیا پروژه روی شناسه پروژه صحیح تنظیم شده است یا خیر:

gcloud auth list

5. دستور زیر را در Cloud Shell اجرا کنید تا تأیید کنید که دستور gcloud از پروژه شما اطلاع دارد.

gcloud config list project

6. اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:

gcloud config set project <YOUR_PROJECT_ID>

7. با اجرای دستورات زیر یکی یکی در ترمینال Cloud Shell خود، API های مورد نیاز را فعال کنید:

همچنین یک فرمان برای اجرای دستور زیر وجود دارد، اما اگر کاربر آزمایشی حساب کاربری هستید، ممکن است در تلاش برای فعال کردن این موارد به صورت انبوه با مشکلات سهمیه مواجه شوید. به همین دلیل است که دستورات در هر خط یکی هستند.

gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com 
gcloud services enable cloudresourcemanager.googleapis.com 
gcloud services enable servicenetworking.googleapis.com 
gcloud services enable run.googleapis.com 
gcloud services enable cloudbuild.googleapis.com 
gcloud services enable cloudfunctions.googleapis.com 
gcloud services enable aiplatform.googleapis.com

جایگزین دستور gcloud از طریق کنسول با جستجوی هر محصول یا استفاده از این پیوند است.

اگر هر یک از API از دست رفته است، همیشه می توانید آن را در طول پیاده سازی فعال کنید.

برای دستورات و استفاده از gcloud به اسناد مراجعه کنید.

3. راه اندازی پایگاه داده

در این آزمایشگاه از AlloyDB به عنوان پایگاه داده برای نگهداری داده های خرده فروشی استفاده می کنیم. از خوشه‌ها برای نگهداری همه منابع مانند پایگاه‌های داده و گزارش‌ها استفاده می‌کند. هر خوشه دارای یک نمونه اولیه است که یک نقطه دسترسی به داده ها را فراهم می کند. جداول داده های واقعی را نگه می دارند.

بیایید یک خوشه، نمونه و جدول AlloyDB ایجاد کنیم که مجموعه داده تجارت الکترونیک در آن بارگذاری شود.

یک خوشه و نمونه ایجاد کنید

1. صفحه AlloyDB را در Cloud Console پیمایش کنید.

یک راه آسان برای یافتن بیشتر صفحات در Cloud Console این است که آنها را با استفاده از نوار جستجوی کنسول جستجو کنید.

2. CREATE CLUSTER را از آن صفحه انتخاب کنید:

3. صفحه ای مانند تصویر زیر خواهید دید. یک خوشه و نمونه با مقادیر زیر ایجاد کنید (مطمئن شوید که مقادیر مطابقت دارند در صورتی که کد برنامه را از مخزن شبیه سازی می کنید):

• شناسه خوشه: " vector-cluster "
• رمز عبور: " alloydb "
• سازگار با PostgreSQL 15
• منطقه: " us-central1 "
• شبکه سازی: " default "

4. وقتی شبکه پیش‌فرض را انتخاب می‌کنید، صفحه‌ای مانند تصویر زیر خواهید دید. SET UP CONNECTION را انتخاب کنید.
   
5. از آنجا، "Use an automatically allocated IP range" و Continue را انتخاب کنید. پس از بررسی اطلاعات، CREATE CONNECTION را انتخاب کنید.
6. هنگامی که شبکه شما راه اندازی شد، می توانید به ایجاد خوشه خود ادامه دهید. بر روی CREATE CLUSTER کلیک کنید تا تنظیمات خوشه را مطابق شکل زیر تکمیل کنید:

حتماً شناسه نمونه را به " تغییر دهید

vector-instance"

.

توجه داشته باشید که ایجاد Cluster حدود 10 دقیقه طول خواهد کشید. پس از موفقیت آمیز بودن، باید صفحه ای را ببینید که نمای کلی خوشه شما را که به تازگی ایجاد کرده اید نشان می دهد.

4. بلع داده ها

اکنون زمان اضافه کردن یک جدول با داده های مربوط به فروشگاه است. به AlloyDB بروید، خوشه اصلی و سپس AlloyDB Studio را انتخاب کنید:

ممکن است لازم باشد منتظر بمانید تا ایجاد نمونه شما به پایان برسد. پس از تکمیل، با استفاده از اعتبارنامه هایی که در طول ایجاد خوشه ایجاد کردید، وارد AlloyDB شوید. از داده های زیر برای احراز هویت در PostgreSQL استفاده کنید:

• نام کاربری: " postgres "
• پایگاه داده: " postgres "
• رمز عبور: " alloydb "

هنگامی که با موفقیت در AlloyDB Studio احراز هویت شدید، دستورات SQL را می توان در ویرایشگر وارد کرد. می‌توانید چندین پنجره ویرایشگر را با استفاده از علامت مثبت در سمت راست آخرین پنجره اضافه کنید.

می‌توانید با استفاده از گزینه‌های Run، Format و Clear در صورت لزوم، دستورات AlloyDB را در پنجره‌های ویرایشگر وارد کنید.

برنامه های افزودنی را فعال کنید

برای ساخت این برنامه از پسوندهای pgvector و google_ml_integration استفاده خواهیم کرد. پسوند pgvector به شما امکان می دهد جاسازی های برداری را ذخیره و جستجو کنید. پسوند google_ml_integration توابعی را ارائه می دهد که شما برای دسترسی به نقاط پایانی پیش بینی هوش مصنوعی Vertex برای دریافت پیش بینی در SQL استفاده می کنید. با اجرای DDL های زیر این افزونه ها را فعال کنید :

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

اگر می خواهید افزونه هایی را که در پایگاه داده شما فعال شده اند بررسی کنید، این دستور SQL را اجرا کنید:

select extname, extversion from pg_extension;

یک جدول ایجاد کنید

با استفاده از دستور DDL زیر یک جدول ایجاد کنید:

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

در صورت اجرای موفقیت آمیز دستور فوق، باید بتوانید جدول را در پایگاه داده مشاهده کنید.

داده ها را بلعید

برای این آزمایشگاه، ما داده های آزمایشی حدود 72 رکورد را در این فایل SQL داریم. این شامل فیلدهای id, name, description, quantity, price, image_url است. فیلدهای دیگر بعداً در آزمایشگاه پر خواهند شد.

خطوط/عبارات را از آنجا کپی کنید و سپس آن خطوط را در یک برگه ویرایشگر خالی قرار دهید و RUN را انتخاب کنید.

برای دیدن محتویات جدول، بخش Explorer را گسترش دهید تا زمانی که جدولی به نام apparels را ببینید. برای مشاهده گزینه Query جدول، سه ویرگول (⋮) را انتخاب کنید. یک عبارت SELECT در یک تب جدید ویرایشگر باز می شود.

اعطای مجوز

دستور زیر را اجرا کنید تا حقوق اجرای تابع embedding را به کاربر postgres اعطا کنید:

GRANT EXECUTE ON FUNCTION embedding TO postgres;

ROLE کاربر Vertex AI را به حساب سرویس AlloyDB اعطا کنید

به ترمینال Cloud Shell بروید و دستور زیر را بدهید:

PROJECT_ID=$(gcloud config get-value project)

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

5. تعبیه هایی برای زمینه ایجاد کنید

پردازش اعداد برای رایانه ها بسیار آسان تر از پردازش متن است. یک سیستم جاسازی متن را به یک سری اعداد ممیز شناور تبدیل می‌کند که به آن جاسازی‌های برداری گفته می‌شود، که باید متن را نشان دهند، مهم نیست که چگونه کلمه‌بندی شده باشد، از چه زبانی استفاده می‌کند و غیره.

به عنوان مثال، یک مکان ساحلی ممکن است «روی آب»، «کنار ساحل»، «از اتاق خود تا اقیانوس پیاده‌روی»، «سور لا مر»، «на берегу океана» و غیره نامیده شود.

اکنون که داده ها و زمینه آماده هستند، SQL را اجرا می کنیم تا جاسازی های توضیحات محصول را به جدول در فیلد embedding اضافه کنیم. انواع مدل های تعبیه شده وجود دارد که می توانید استفاده کنید. ما از text-embedding-005 از Vertex AI استفاده می کنیم. حتماً از همان مدل تعبیه در کل پروژه استفاده کنید!

توجه: اگر از یک پروژه قدیمی Google Cloud استفاده می‌کنید، ممکن است لازم باشد از نسخه‌های قدیمی‌تر مدل جاسازی متن مانند textembedding-gecko استفاده کنید.

به تب AlloyDB Studio برگردید و DML زیر را تایپ کنید:

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

دوباره به میز toys نگاه کنید تا چند جاسازی را ببینید. حتماً عبارت SELECT را دوباره اجرا کنید تا تغییرات را ببینید.

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

این باید بردار embeddings را که مانند آرایه ای از شناورها به نظر می رسد، برای توضیحات اسباب بازی که در زیر نشان داده شده است، برگرداند:

توجه: پروژه‌های Google Cloud جدید ایجاد شده در سطح رایگان ممکن است در مورد تعداد درخواست‌های جاسازی مجاز در هر ثانیه به مدل‌های Embedding با مشکلات سهمیه‌ای مواجه شوند. پیشنهاد ما این است که از یک پرس و جو فیلتر برای شناسه استفاده کنید و سپس همزمان با ایجاد جاسازی، 1-5 رکورد و غیره را انتخاب کنید.

6. جستجوی برداری را انجام دهید

اکنون که جدول، داده‌ها و جاسازی‌ها همه آماده هستند، بیایید جستجوی برداری واقعی را برای متن جستجوی کاربر انجام دهیم.

فرض کنید کاربر بپرسد:

" I want a white plush teddy bear toy with a floral pattern ."

با اجرای پرس و جو زیر می توانید موارد منطبق برای این مورد را پیدا کنید:

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

بیایید به این پرس و جو با جزئیات نگاه کنیم:

در این پرس و جو،

1. متن جستجوی کاربر این است: " I want a white plush teddy bear toy with a floral pattern. "
2. ما در حال تبدیل آن به embedding در متد embedding() با استفاده از مدل: text-embedding-005 هستیم. این مرحله باید بعد از آخرین مرحله آشنا به نظر برسد، جایی که ما تابع embedding را برای همه موارد در جدول اعمال کردیم.
3. " <=> " نشان دهنده استفاده از روش فاصله COSINE SIMILARITY است. شما می توانید تمام معیارهای شباهت موجود در مستندات pgvector را بیابید.
4. ما در حال تبدیل نتیجه روش embedding به نوع برداری هستیم تا آن را با بردارهای ذخیره شده در پایگاه داده سازگار کنیم.
5. LIMIT 5 نشان می دهد که ما می خواهیم 5 نزدیکترین همسایه را برای متن جستجو استخراج کنیم.

نتیجه به این صورت است:

همانطور که در نتایج خود مشاهده می کنید، مطابقت ها بسیار نزدیک به متن جستجو هستند. سعی کنید متن را تغییر دهید تا ببینید نتایج چگونه تغییر می کند.

7. آماده سازی AlloyDB برای تعامل جعبه ابزار

در آماده سازی برای راه اندازی جعبه ابزار، اجازه دهید اتصال IP عمومی را در نمونه AlloyDB خود فعال کنیم تا ابزار جدید بتواند به پایگاه داده دسترسی داشته باشد.

1. به نمونه AlloyDB خود بروید، روی EDIT کلیک کنید و در صفحه ویرایش نمونه اولیه قرار بگیرید.
2. به بخش اتصال IP عمومی بروید، چک باکس Enable IP public را علامت بزنید و آدرس IP دستگاه Cloud Shell خود را وارد کنید.
3. برای دریافت IP دستگاه Cloud Shell خود، به Cloud Shell Terminal بروید و ifconfig را وارد کنید. از نتیجه، آدرس inet eth0 را شناسایی کنید و 2 رقم آخر را با 0.0 با اندازه ماسک '/16' جایگزین کنید. به عنوان مثال به نظر می رسد "XX.XX.0.0/16" که در آن XX اعداد هستند.
4. این IP را در کادر متنی «شبکه‌ها» شبکه‌های خارجی مجاز صفحه ویرایش نمونه قرار دهید.

5. پس از اتمام روی UPDATE INSTANCE کلیک کنید.

چند دقیقه طول می کشد تا کامل شود.

8. نصب جعبه ابزار

1. می توانید یک پوشه پروژه برای ذخیره جزئیات ابزار ایجاد کنید. در این مورد از آنجایی که ما روی داده‌های فروشگاه اسباب‌بازی کار می‌کنیم، بیایید یک پوشه به نام "toystore" ایجاد کنیم و در آن حرکت کنیم. به Cloud Shell Terminal بروید و مطمئن شوید که پروژه شما انتخاب شده و در اعلان ترمینال نشان داده شده است. دستور زیر را از ترمینال Cloud Shell خود اجرا کنید:

mkdir toystore

cd toystore

2. دستور زیر را برای دانلود و نصب جعبه ابزار در پوشه جدید خود اجرا کنید:

# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

3. به ویرایشگر پوسته ابری بروید. پوشه جدید ایجاد شده "toystore" را گسترش دهید و یک فایل جدید به نام tools.yaml ایجاد کنید. مطالب زیر را کپی کنید YOUR_PROJECT_ID را جایگزین کنید و بررسی کنید که آیا سایر جزئیات اتصال دقیق هستند یا خیر.

sources:
    alloydb-toys:
        kind: "alloydb-postgres"
        project: "YOUR_PROJECT_ID"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

در این ابزار، ما فقط نزدیکترین مطابقت را با متن جستجوی کاربر (توضیحات اسباب بازی سفارشی) پیدا می کنیم و قیمت آن را برمی گردانیم. همچنین می‌توانید آن را تغییر دهید تا میانگین قیمت 5 اسباب‌بازی برتر مطابقت را پیدا کنید:

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

همه شما با تعریف ابزار آماده هستید!

برای جزئیات بیشتر در مورد پیکربندی tools.yaml خود، به این مستندات مراجعه کنید.

4. به Cloud Shell Terminal بروید و دستور زیر را وارد کنید تا سرور جعبه ابزار با پیکربندی ابزار خود راه اندازی شود:

./toolbox --tools_file "tools.yaml"

5. اکنون اگر سرور را در حالت پیش‌نمایش وب در فضای ابری باز کنید، باید بتوانید سرور جعبه ابزار را با ابزار جدید خود به نام get-toy-price.

9. Cloud Run Deployment Toolbox

بیایید آن را در Cloud Run مستقر کنیم تا بتوانید از این ابزار استفاده واقعی کنید.

1. دستورالعمل های این صفحه را یکی یکی دنبال کنید تا به دستور gcloud run deploy toolbox که در نقطه سوم زیر بخش "Deploy to Cloud Run" است برسید. شما به گزینه اول نیاز دارید و نه گزینه دوم که برای زمانی که از روش شبکه VPC استفاده می کنید.
2. پس از استقرار موفقیت آمیز، یک نقطه پایانی نصب شده Cloud Run از سرور جعبه ابزار خود دریافت خواهید کرد. آن را با دستور CURL تست کنید.

شما آماده اید که از ابزار تازه مستقر شده خود در برنامه کاربردی خود استفاده کنید!!!

10. برنامه خود را با جعبه ابزار متصل کنید

در این قسمت، ما یک اپلیکیشن کوچک برای تست ابزار شما برای تعامل با نیازهای اپلیکیشن و بازیابی پاسخ می سازیم.

1. به Google Colab بروید و یک نوت بوک جدید باز کنید.
2. موارد زیر را در نوت بوک خود اجرا کنید

pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
tool = toolbox.load_tool("get-toy-price")

# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)

3. شما باید اینگونه نتیجه بگیرید:

این ابزاری است که به صراحت در یک برنامه پایتون فراخوانی می شود که از toolbox-langchain استفاده می کند .

4. اگر می خواهید از این ابزار استفاده کنید و آن را به یک عامل در یک برنامه یکپارچه LangGraph متصل کنید، می توانید این کار را به راحتی با جعبه ابزار langgraph انجام دهید.
5. برای این کار به قطعات کد مراجعه کنید.

11. ببرش تو ابر!!!

بیایید این قطعه کد پایتون را در یک Cloud Run Functions بپیچیم تا بدون سرور شود!

1. منبع را از پوشه کد مخزن کپی کنید تا آن را به Cloud Functions برسانید.
2. به کنسول Cloud Run Functions رفته و روی CREATE FUNCTION کلیک کنید.
3. آن را بدون احراز هویت برای برنامه آزمایشی نگه دارید و زمان اجرای Python 3.11 را در صفحه بعد انتخاب کنید.
4. فایل‌های main.py و requirements.txt را از منبع منبع اشتراک‌گذاری شده در مرحله 1 کپی کنید و در فایل‌های مربوطه جای‌گذاری کنید.
5. تابع را اجرا کنید و یک نقطه پایانی REST برای ابزار پیش‌بینی قیمت برای دسترسی به برنامه وب toystore دارید.
6. نقطه پایانی شما باید به این صورت باشد:

https://us-central1-*****.cloudfunctions.net/toolbox-toys

2. با رفتن به تب TESTING و وارد کردن موارد زیر به عنوان ورودی درخواست، می‌توانید آن را مستقیماً در کنسول Cloud Functions آزمایش کنید:

{

               "`search`"`:` "`White plush toy`"

}

3. روی TEST THE FUNCTION کلیک کنید یا هر آنچه را که انتخاب می کنید در Cloud Shell Terminal اجرا کنید. شما باید نتیجه را در سمت راست تحت عنوان "Output" ببینید:

12. تبریک می گویم

تبریک می گویم! شما با موفقیت یک ابزار قوی و واقعاً ماژولار ایجاد کرده‌اید که می‌تواند در بین پایگاه‌های داده، پلتفرم‌ها و چارچوب‌های ارکستراسیون هوش مصنوعی تولیدکننده تعامل داشته باشد تا به ایجاد برنامه کاربردی شما کمک کند.