Using TypeSafe AI's Jev model with AlloyDB AI Functions for High-Speed AI Queries

۱. مقدمه

در این codelab، مدل Jev از TypeSafe AI را بااستفاده از توابع هوش مصنوعی بومی AlloyDB (‏ai.if،‏ ai.analyze_sentiment، و ml_predict_row) به AlloyDB AI متصل خواهید کرد. این کار به شما امکان می‌دهد تا استنتاج دسته‌ای کارآمد را بااستفاده از مدل Jev مستقیماً روی داده‌های عملیاتی خود در AlloyDB اجرا کنید، بدون اینکه نیاز به انتقال داده‌ها یا نوشتن کد پیچیده در سمت برنامه داشته باشید.

آنچه انجام خواهید داد

  • تأمین کردن «دسترسی به سرویس خصوصی» (PSA) و خوشه و نمونه اصلی AlloyDB برای PostgreSQL
  • ایجاد قانون دیوار آتش VPC که به Cloudshell و اتصال‌پذیری داخلی اجازه می‌دهد
  • بار کردن مجموعه داده نمونه تجارت الکترونیک بااستفاده از gcloud alloydb clusters import
  • فعال کردن Google Secret Manager و افزونه google_ml_integration AlloyDB
  • ذخیره کردن و اعطای دسترسی به کلید TypeSafe AI API در Secret Manager
  • Create PL/pgSQL input and output transformation functions for Jev's noul (boolean) and choice (sentiment) primitives
  • ثبت کردن نقطه پایان مدل jev-model سفارشی در AlloyDB
  • اجرای پُرسمان‌های معنایی دسته‌ای آرایه‌ای و اسکالر (ai.if و ai.analyze_sentiment) مستقیماً در SQL
  • پرس‌وجو کردن مرورهای واقعی مشتریان درباره محصول برای طبقه‌بندی احساسات بااستفاده از ai.analyze_sentiment
  • (Bonus) Register a generic endpoint (jev-systemone) and evaluate continuous customer satisfaction intensity using Jev's score primitive

آنچه نیاز خواهید داشت

  • مرورگر وب مانند Chrome
  • پروژه Google Cloud با صورت‌حساب فعال‌شده
  • کلید TypeSafe AI API (از TypeSafe AI)

۲. قبل‌از شروع

پروژه Google Cloud خود را انتخاب کنید

در کنسول Google Cloud، پروژه Google Cloud موردنظرتان را برای استفاده انتخاب یا ایجاد کنید.

شروع Cloud Shell

در بالا سمت چپ کنسول Google Cloud، روی فعال‌سازی Cloud Shell کلیک کنید.

تأیید کنید که جلسه Cloud Shell شما اصالت‌سنجی شده است:

gcloud auth list

شناسه پروژه و متغیرهای محیطی‌تان را تنظیم کنید:

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID

export REGION="us-west4"
export ADBCLUSTER="my-alloydb-cluster"
export ADBINSTANCE="my-alloydb-primary"

فعال کردن میاناهای برنامه‌سازی کاربردی Google Cloud موردنیاز

این فرمان را اجرا کنید تا همه میاناهای برنامه‌سازی کاربردی سرویس Google Cloud لازم فعال شود:

gcloud services enable \
  alloydb.googleapis.com \
  servicenetworking.googleapis.com \
  secretmanager.googleapis.com \
  compute.googleapis.com

۳. تأمین کردن خوشه AlloyDB و نمونه اصلی

در این مرحله، محدوده IP «دسترسی به سرویس خصوصی» را در شبکه VPC خود اختصاص می‌دهید، همتاسازی خصوصی برقرار می‌کنید، و خوشه AlloyDB و نمونه اصلی خود را با دسترسی به اینترنت برون‌سو فراهم می‌کنید.

۱. ایجاد کردن محدوده IP «دسترسی به سرویس خصوصی» (PSA)

AlloyDB به تخصیص محدوده IP خصوصی در شبکه Virtual Private Cloud (VPC) شما نیاز دارد. با فرض اینکه از شبکه VPC default استفاده می‌کنید:

تخصیص محدوده IP خصوصی را ایجاد کنید:

gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default

اتصال همتای VPC خصوصی را برقرار کنید:

gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default

۲. ایجاد کردن خوشه AlloyDB

گذرواژه پایگاه داده ایمنی برای کاربر سرپرست اولیه postgres ایجاد کنید:

export PGPASSWORD="$(openssl rand -hex 8)@1aA"
echo "Your generated AlloyDB postgres password is: $PGPASSWORD"

ایجاد کردن خوشه «دوره آزمایشی رایگان AlloyDB»:

gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION 

۳. ایجاد نمونه اصلی با پرچم‌های هوش مصنوعی و اتصال برون‌مرزی

‫AlloyDB مستقیماً ازطریق HTTPS برون‌سو به نقطه پایانی SaaS امن TypeSafe AI (https://api.typesafe.ai/v1/systemone) متصل می‌شود. بنابراین، باید --outbound-public-ip را مشخص کنید. علاوه‌براین، پرچم‌های پایگاه داده AlloyDB AI را برای محیط پیکربندی کنید:

gcloud alloydb instances create $ADBINSTANCE \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --cluster=$ADBCLUSTER \
    --outbound-public-ip \
    --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED \
    --database-flags=\
google_ml_integration.enable_model_support=on,\
google_ml_integration.enable_ai_query_engine=on,\
google_ml_integration.enable_ai_function_acceleration=on,\
google_ml_integration.enable_cost_optimized_ai_functions=on,\
parameterized_views.enabled=on,\
password.enforce_complexity=on,\
password.min_uppercase_letters=1,\
password.min_numerical_chars=1,\
password.min_pass_length=10

۴. بار کردن داده‌های نمونه تجارت الکترونیک

برای آزمایش پُرسمان‌های معنایی واقع‌گرایانه، یک مجموعه داده نمونه تجارت الکترونیک حاوی کاتالوگ‌های محصول و نقدهای مشتری را مستقیماً از Cloud Storage وارد کنید:

gcloud alloydb clusters import $ADBCLUSTER \
    --region=$REGION \
    --project=$PROJECT_ID \
    --gcs-uri="gs://sample-data-and-media/ecomm-retail/ecom_generic.sql" \
    --sql \
    --database=postgres \
    --user=postgres

۴. ذخیره کردن کلید TypeSafe AI API در Secret Manager

‫Model Endpoint Management در AlloyDB به‌طور بومی با Google Secret Manager ادغام می‌شود تا فراخوانی‌های میانای برنامه‌سازی کاربردی خارجی را بدون افشای اطلاعات اعتباری متن ساده در کد پایگاه داده یا گزارش‌های پیکربندی اصالت‌سنجی کند.

۱. ایجاد کردن رمز

در Cloud Shell، رمز جدیدی به‌نام typesafe-jev-api-key ایجاد کنید:

gcloud secrets create typesafe-jev-api-key \
  --replication-policy="automatic"

کلید TypeSafe AI API خود را به‌عنوان نسخه محرمانه اضافه کنید:

echo -n "<YOUR_TYPESAFE_API_KEY>" | \
  gcloud secrets versions add typesafe-jev-api-key --data-file=-

۲. اعطای دسترسی به عامل سرویس AlloyDB

AlloyDB از عامل سرویس پروژه خود برای بازیابی اطلاعات محرمانه درطول اجرای پُرسمان استفاده می‌کند. شماره پروژه‌تان را پیدا کنید و نقش «دسترسی‌دهنده به راز» را اعطا کنید:

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
ALLOYDB_SA="service-${PROJECT_NUMBER}@gcp-sa-alloydb.iam.gserviceaccount.com"

gcloud secrets add-iam-policy-binding typesafe-jev-api-key \
  --member="serviceAccount:${ALLOYDB_SA}" \
  --role="roles/secretmanager.secretAccessor"

باید خروجی‌ای ببینید که تأیید می‌کند نماینده خدمات roles/secretmanager.secretAccessor را دریافت کرده است.

۵. متصل شدن به AlloyDB ازطریق AlloyDB Studio و مقداردهی اولیه افزونه‌های پایگاه داده

برای تعامل با پایگاه داده AlloyDB مستقیماً از مرورگرتان بدون پیکربندی ابزارهای کارخواه محلی یا تونل‌های پراکسی، از AlloyDB Studio در «کنسول Google Cloud» استفاده کنید.

۱. باز کردن «استودیوِ AlloyDB»

  1. در کنسول Google Cloud، به AlloyDB برای PostgreSQL > خوشه‌ها بروید.
  2. روی خوشه (my-alloydb-cluster) کلیک کنید.
  3. در منو پیمایش سمت راست، روی AlloyDB Studio کلیک کنید.
  4. اصالت‌سنجی در پایگاه داده:
    • پایگاه داده: postgres
    • کاربر: postgres
    • گذرواژه: $PGPASSWORD تولیدشده درطول ایجاد خوشه را وارد کنید (برای مثال، echo $PGPASSWORD را در Cloud Shell اجرا کنید تا آن را ببینید).
  5. روی اصالت‌سنجی کلیک کنید.

اکنون در ویرایشگر پُرسمان SQL تعاملی AlloyDB Studio هستید.

۲. فعال کردن پرچم‌ها و افزونه‌های پایگاه داده

در ویرایشگر پُرسمان AlloyDB Studio، عبارت‌های زیر را جای‌گذاری و اجرا کنید تا افزونه google_ml_integration فعال شود و تنظیمات زمان اجرا پیکربندی شود:

-- Enable the AlloyDB AI integration extension
CREATE EXTENSION IF NOT EXISTS google_ml_integration;

-- Enable preview AI functions (ai.analyze_sentiment, ai.classify)
SET google_ml_integration.enable_preview_ai_functions = 'on';

-- Disable async batching for the session to use custom transform functions directly
SET google_ml_integration.enable_async_operation = 'off';

برای اجرای پُرسمان، روی اجرا کلیک کنید.

۳. ثبت کردن «رمز» در AlloyDB MEM

به AlloyDB بگویید کلید TypeSafe AI API شما را کجا پیدا کند:

CALL google_ml.create_sm_secret(
    secret_id => 'jev_api_key',
    secret_path => 'projects/<YOUR_PROJECT_ID>/secrets/typesafe-jev-api-key/versions/latest'
);

‫۶. ایجاد توابع تبدیل SQL

‫System One API از TypeSafe AI،‏ JSON ساختاریافته را با اصول استدلال متمایز (noul برای محدودیت‌های بولی، choice برای طبقه‌بندی چندکلاسی) می‌پذیرد.

«مدیریت نقطه پایانی مدل» در AlloyDB از چهار تابع تبدیل (ورودی اسکالر، خروجی اسکالر، ورودی دسته‌ای، خروجی دسته‌ای) برای پل زدن بین امضاهای تابع استاندارد PostgreSQL ai.* و قالب Jev REST API استفاده می‌کند.

۱. تبدیل ورودی اسکالر

تابع زیر را برای تبدیل فراخوانی‌های تک‌ردیفی ai.if و ai.analyze_sentiment به بار داده‌های درخواست Jev اضافه کنید:

CREATE OR REPLACE FUNCTION public.jev_model_input_transform(
    model_id VARCHAR(100),
    input_text TEXT,
    generation_config JSON,
    system_instruction TEXT
) RETURNS JSON
LANGUAGE plpgsql IMMUTABLE AS $$
DECLARE
    full_instruction TEXT;
    enum_json JSON;
    criteria_obj JSONB := '{}'::JSONB;
    elem TEXT;
    q_obj JSON;
BEGIN
    -- Combine optional system instructions with the input prompt
    IF system_instruction IS NOT NULL AND length(trim(system_instruction)) > 0 THEN
        full_instruction := system_instruction || E'\n\n' || input_text;
    ELSE
        full_instruction := input_text;
    END IF;

    -- Inspect generation_config to determine whether caller expects a multi-class choice or boolean
    enum_json := COALESCE(
        generation_config->'generationConfig'->'responseSchema'->'enum',
        generation_config->'responseSchema'->'enum'
    );

    IF enum_json IS NOT NULL AND json_typeof(enum_json) = 'array' THEN
        -- Multi-class classification (ai.analyze_sentiment) -> Jev choice primitive
        FOR elem IN SELECT json_array_elements_text(enum_json) LOOP
            criteria_obj := criteria_obj || jsonb_build_object(elem, 'Category: ' || elem);
        END LOOP;
        q_obj := json_build_object(
            'type', 'choice',
            'instructions', full_instruction,
            'criteria', criteria_obj::JSON
        );
    ELSE
        -- Boolean filtering (ai.if) -> Jev noul primitive
        q_obj := json_build_object(
            'type', 'noul',
            'instructions', full_instruction
        );
    END IF;

    RETURN json_build_object(
        'model', 'jev-latest',
        'state', COALESCE(generation_config->>'state', 'Evaluate the question accurately based on the provided text.'),
        'questions', json_build_object('q_1', q_obj)
    );
END;
$$;

۲. تبدیل خروجی اسکالر

تابع را اضافه کنید تا پاسخ JSON جِو را دوباره به نتیجه PostgreSQL TEXT باز کند:

CREATE OR REPLACE FUNCTION public.jev_model_output_transform(
    model_id VARCHAR(100),
    response_json JSON
) RETURNS TEXT
LANGUAGE plpgsql IMMUTABLE AS $$
DECLARE
    q_ans JSON := response_json->'answers'->'q_1';
    ans_type TEXT := q_ans->>'type';
BEGIN
    IF ans_type = 'choice' THEN
        RETURN q_ans->>'choice';
    ELSIF ans_type = 'noul' THEN
        -- Convert probability score (0.00 to 1.00) to boolean text
        RETURN CASE WHEN (q_ans->>'noul')::FLOAT >= 0.50 THEN 'true' ELSE 'false' END;
    ELSE
        RAISE EXCEPTION 'Unexpected Jev response payload: %', response_json::TEXT;
    END IF;
END;
$$;

۳. تبدیل ورودی دسته‌ای

Jev می‌تواند ده‌ها سؤال را به‌طور هم‌زمان در یک رفت‌وبرگشت HTTP بدون افت کیفیت تولیدی ارزیابی کند.

تبدیل ورودی دسته‌ای را برای تبدیل آرایه‌های prompts TEXT[] PostgreSQL به سؤالات موازی q_1 .. q_N Jev اضافه کنید:

CREATE OR REPLACE FUNCTION public.jev_model_batch_input_transform(
    model_id VARCHAR(100),
    prompts TEXT[],
    generation_config JSON,
    system_instructions JSON
) RETURNS JSON
LANGUAGE plpgsql IMMUTABLE AS $$
DECLARE
    questions_obj JSONB := '{}'::JSONB;
    enum_json JSON;
    criteria_obj JSONB := '{}'::JSONB;
    elem TEXT;
    is_choice BOOLEAN := FALSE;
    i INT;
BEGIN
    enum_json := COALESCE(
        generation_config->'generationConfig'->'responseSchema'->'items'->'enum',
        generation_config->'generationConfig'->'responseSchema'->'enum',
        generation_config->'responseSchema'->'items'->'enum',
        generation_config->'responseSchema'->'enum'
    );

    IF enum_json IS NOT NULL AND json_typeof(enum_json) = 'array' THEN
        IF NOT (enum_json::JSONB = '["true", "false"]'::JSONB OR enum_json::JSONB = '["false", "true"]'::JSONB) THEN
            is_choice := TRUE;
            FOR elem IN SELECT json_array_elements_text(enum_json) LOOP
                criteria_obj := criteria_obj || jsonb_build_object(elem, 'Category: ' || elem);
            END LOOP;
        END IF;
    END IF;

    -- Construct parallel questions for every prompt in the array
    FOR i IN 1 .. COALESCE(array_length(prompts, 1), 0) LOOP
        IF is_choice THEN
            questions_obj := questions_obj || jsonb_build_object(
                'q_' || i::TEXT,
                jsonb_build_object(
                    'type', 'choice',
                    'instructions', prompts[i],
                    'criteria', criteria_obj
                )
            );
        ELSE
            questions_obj := questions_obj || jsonb_build_object(
                'q_' || i::TEXT,
                jsonb_build_object(
                    'type', 'noul',
                    'instructions', prompts[i]
                )
            );
        END IF;
    END LOOP;

    RETURN json_build_object(
        'model', 'jev-latest',
        'state', COALESCE(generation_config->>'state', 'Evaluate each question independently based on the record data.'),
        'questions', questions_obj::JSON
    );
END;
$$;

۴. تبدیل خروجی دسته‌ای

تابع را برای استخراج پاسخ‌ها در ترتیب صحیح نمایه آرایه 1..N اضافه کنید:

CREATE OR REPLACE FUNCTION public.jev_model_batch_output_transform(
    model_id VARCHAR(100),
    response JSON
) RETURNS TEXT[]
LANGUAGE plpgsql IMMUTABLE AS $$
DECLARE
    results TEXT[] := ARRAY[]::TEXT[];
    answers JSON := response->'answers';
    i INT := 1;
    q_ans JSON;
    ans_type TEXT;
BEGIN
    LOOP
        q_ans := answers->('q_' || i::TEXT);
        EXIT WHEN q_ans IS NULL;
        ans_type := q_ans->>'type';
        IF ans_type = 'choice' THEN
            results := array_append(results, q_ans->>'choice');
        ELSE
            results := array_append(results, CASE WHEN (q_ans->>'noul')::FLOAT >= 0.50 THEN 'true' ELSE 'false' END);
        END IF;
        i := i + 1;
    END LOOP;
    RETURN results;
END;
$$;

‫۷. ثبت کردن نقطه پایان مدل سفارشی در AlloyDB

اکنون توابع تبدیل، اطلاعات کاربری محرمانه، و نقطه پایانی TypeSafe AI REST را در یک مدل ثبت‌شده به‌نام jev-model به هم متصل خواهید کرد.

۱. ثبت کردن jev-model

در ویرایشگر پُرسمان AlloyDB Studio، این کد را جای‌گذاری و اجرا کنید:

-- Drop previous registration if updating
DO $$
BEGIN
    IF EXISTS (SELECT 1 FROM google_ml.model_info_view WHERE model_id = 'jev-model') THEN
        CALL google_ml.drop_model('jev-model');
    END IF;
END $$;

-- Register custom LLM endpoint
CALL google_ml.create_model(
    model_id => 'jev-model',
    model_request_url => 'https://api.typesafe.ai/v1/systemone',
    model_provider => 'custom',
    model_type => 'llm',
    model_qualified_name => 'jev-latest',
    model_auth_type => 'secret_manager',
    model_auth_id => 'jev_api_key',
    model_in_transform_fn => 'jev_model_input_transform',
    model_out_transform_fn => 'jev_model_output_transform',
    model_batch_in_transform_fn => 'jev_model_batch_input_transform',
    model_batch_out_transform_fn => 'jev_model_batch_output_transform'
);

۲. به‌تأیید رساندن ثبت‌نام

نمای ثبت مدل را پُرسمان کنید تا مطمئن شوید jev-model فعال است و شناسایی می‌شود:

SELECT model_id, model_type, model_provider, model_auth_type 
FROM google_ml.model_info_view 
WHERE model_id = 'jev-model';

باید بروندادی مشابه زیر ببینید:

 model_id | model_type | model_provider | model_auth_type 
----------+------------+----------------+-----------------
 jev-model  | llm        | custom         | secret_manager
(1 row)

‫۸. اجرای پُرسمان‌های آزمایشی دربرابر Jev

با ثبت jev-model، اکنون می‌توانید عملیات معنایی را مستقیماً در پرسمان‌های استاندارد PostgreSQL اجرا کنید.

۱. Test Scalar Boolean Filtering (ai.if)

ارزیابی یک عبارت نوشتاری بااستفاده از ai.if:

SELECT ai.if(
    prompt => 'Is the product "North Face Waterproof Gore-Tex Hiking Jacket ($249)" suitable for rainy outdoor conditions?',
    model_id => 'jev-model'
) AS is_suitable;

باید بروندادی مشابه زیر ببینید:

 is_suitable 
-------------
 true
(1 row)

۲. Test Scalar Sentiment Analysis (ai.analyze_sentiment)

بازخورد مشتری را در برچسب دسته‌ای (positive، negative، یا neutral) ارزیابی کنید:

SET google_ml_integration.enable_preview_ai_functions = 'on';
SELECT ai.analyze_sentiment(
    input => 'The stitching on this jacket tore on the second day and the zipper jammed completely.',
    model_id => 'jev-model'
) AS sentiment;

باید بروندادی مشابه زیر ببینید:

 sentiment 
-----------
 negative
(1 row)

۳. Test Array-Batched Boolean Filtering

با ارسال آرایه‌ای از پیام‌واره‌ها، چندین مورد را در یک پُرسمان ارزیابی کنید:

SET google_ml_integration.enable_async_operation = 'off';
SELECT unnest(prompts) AS product_prompt,
       unnest(ai.if(prompts => prompts, model_id => 'jev-model')) AS is_cold_weather
FROM (
    SELECT ARRAY[
        'Is "Arctic Expedition Down Parka (-30F)" cold-weather winter outerwear?',
        'Is "Men''s Boardshorts Beach Swim Trunk" cold-weather winter outerwear?',
        'Is "Merino Wool Thermal Base Layer" cold-weather winter outerwear?'
    ] AS prompts
) b;

باید بروندادی مشابه زیر ببینید:

                             product_prompt                              | is_cold_weather 
-------------------------------------------------------------------------+-----------------
 Is "Arctic Expedition Down Parka (-30F)" cold-weather winter outerwear? | true
 Is "Men's Boardshorts Beach Swim Trunk" cold-weather winter outerwear?  | false
 Is "Merino Wool Thermal Base Layer" cold-weather winter outerwear?      | false
(3 rows)

۴. آزمایش کردن پُرسمان‌های جدول با گروه‌بندی آرایه

اکنون جدول ecomm.products را که قبلاً درطول آماده‌سازی خوشه بار شده است بااستفاده از ai.if روی دسته‌ای از موارد پُرسمان کنید تا بررسی کنید کدام‌یک از محصولات موجود در کاتالوگ تجهیزات هوای سرد هستند.

برای اجرای فیلتر معنایی با توان گذرداد بالا روی داده‌های جدول (مثلاً ۵۰ ردیف در هر دسته)، از تابع پنجره row_number() در PostgreSQL برای تقسیم ردیف‌ها به دسته‌ها استفاده کنید:

-- Evaluate a 50-row batch of real catalog items from ecomm.products
WITH numbered AS (
    SELECT 
        id, 
        name, 
        category,
        product_description,
        ((row_number() OVER (ORDER BY id) - 1) / 50) AS batch_id
    FROM ecomm.products
    ORDER BY id DESC
    LIMIT 50
),
batched AS (
    SELECT 
        batch_id,
        array_agg(id ORDER BY id) AS ids,
        array_agg(name ORDER BY id) AS names,
        array_agg(category ORDER BY id) AS categories,
        array_agg(product_description ORDER BY id) AS descs,
        ai.if(
            prompts => array_agg('Is "' || name || '" designed for cold weather winter outerwear?' ORDER BY id),
            model_id => 'jev-model'
        ) AS decisions
    FROM numbered
    GROUP BY batch_id
),
unrolled AS (
    SELECT 
        b.batch_id,
        u.id,
        u.name,
        u.category,
        u.product_description,
        u.decision AS cold_weather_gear
    FROM batched b
    CROSS JOIN LATERAL unnest(b.ids, b.names, b.categories, b.descs, b.decisions) 
      AS u(id, name, category, product_description, decision)
)
SELECT id, name, category, product_description, cold_weather_gear
FROM unrolled
WHERE cold_weather_gear = TRUE
LIMIT 5;

باید بروندادی مشابه زیر ببینید:

  id   |                                 name                                 |  category   |                                                product_description                                                 | cold_weather_gear 
-------+----------------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------+-------------------
 29071 | Winter Striped Beanie with Pom                                       | Accessories | Brave the chill in style with the SoleStyle Winter Striped Beanie! This cozy beanie adds a pop of personality...  | true
 29077 | Knit Collegiate Rugby Stripe Winter Scarf & Beanie Hat Set           | Accessories | Stay cozy and show off your sporty side with our Knit Collegiate Rugby Stripe Scarf & Beanie Set...               | true
 29083 | Junction Finds Men's Muscle Wool Blend Trapper Hat                   | Accessories | Brave the elements in style with the Junction Finds Trapper Hat! This wool-blend hat will keep you warm...        | true
 29086 | Mens Soft Thermal Insulated Wrist Length Leather Gloves - Black      | Accessories | Brave the chill in style with these supple leather gloves from Gavel Goods! Lined with a soft, thermal knit...    | true
 29090 | Long Beanie-Red W16S24E                                              | Accessories | Stay cozy and stylish all season long with this vibrant red beanie from Enchant! This isn't just any hat...       | true
(5 rows)

۵. پرس‌وجو از مرورهای محصول مشتری برای احساسات

اکنون مرورهای مشتری را از جدول ecomm.product_reviews بااستفاده از ai.analyze_sentiment که توسط choice اولیه Jev پشتیبانی می‌شود تجزیه‌وتحلیل کنید:

SET google_ml_integration.enable_preview_ai_functions = 'on';
SELECT 
    r.id,
    p.name AS product_name,
    r.rating AS customer_star_rating,
    substring(r.review_text FROM 1 FOR 70) || '...' AS review_snippet,
    ai.analyze_sentiment(
        input => r.review_text,
        model_id => 'jev-model'
    ) AS detected_sentiment
FROM ecomm.product_reviews r
JOIN ecomm.products p ON r.product_id = p.id
ORDER BY r.id
LIMIT 5;

باید بروندادی مشابه زیر ببینید:

 id |                  product_name                  | customer_star_rating |                             review_snippet                              | detected_sentiment 
----+------------------------------------------------+----------------------+-------------------------------------------------------------------------+--------------------
  1 | Hugs & Kisses Juniors Peplum Skirt             |                    1 | This skirt was poorly made and the fabric felt extremely cheap for for...| negative
  2 | Bonkers Larry Full Length Pull on Pants        |                    1 | These pants are way too expensive for the terrible quality you get. Th...| negative
  3 | Gifts and Garb Brah Bra Extenders              |                    3 | These extenders are okay but nothing special. They do add a bit of ext...| neutral
  4 | Auto Forge Men's Tall Duck Traditional Coat    |                    1 | This coat is terribly stiff and heavy, making it very uncomfortable to...| negative
  5 | Weaver's Way Men's Shetland Zip Neck Sweater   |                    2 | This sweater is just okay and not really worth the high price tag. The...| negative
(5 rows)

‫۹. Bonus: Continuous Sentiment Scoring with Jev score

درحالی‌که توابع هوش مصنوعی AlloyDB مانند ai.analyze_sentiment دسته‌های طبقه‌بندی‌شده (positive، negative، neutral) را برمی‌گردانند، نوع اولیه score در TypeSafe AI تفاوت‌های ظریف را در یک معیار مرتب‌شده ارزیابی می‌کند و رتبه‌بندی پیوسته و وزن‌دار براساس انتظار را از ۰ تا ۱۰۰ برمی‌گرداند.

چون score فراداده عددی برمی‌گرداند و نه برچسب طبقه‌بندی نوشتار، می‌توانید نقطه پایانی مدل generic سفارشی (jev-systemone) را ثبت کنید و آن را بااستفاده از google_ml.predict_row فراخوانی کنید.

۱. ثبت نقطه پایان عمومی

در AlloyDB Studio،‏ jev-systemone را با model_type => 'generic' ثبت کنید:

DO $$
BEGIN
    IF EXISTS (SELECT 1 FROM google_ml.model_info_view WHERE model_id = 'jev-systemone') THEN
        CALL google_ml.drop_model('jev-systemone');
    END IF;
EXCEPTION WHEN OTHERS THEN
    NULL;
END $$;

CALL google_ml.create_model(
    model_id => 'jev-systemone',
    model_request_url => 'https://api.typesafe.ai/v1/systemone',
    model_provider => 'custom',
    model_type => 'generic',
    model_qualified_name => 'jev-latest',
    model_auth_type => 'secret_manager',
    model_auth_id => 'jev_api_key'
);

۲. اجرای ارزیابی چندتکلیفی (بولی + امتیاز پیوسته)

هم بررسی بولی نقص (noul) و هم شدت احساسات مداوم (score) را به‌طور هم‌زمان در یک فراخوانی HTTP ارزیابی کنید:

SELECT jsonb_pretty(google_ml.predict_row(
    model_id => 'jev-systemone',
    request_body => json_build_object(
        'model', 'jev-latest',
        'state', 'Review for North Face Parka: "The zipper broke on day 3 and customer service refused an exchange, though the fabric itself is very soft."',
        'questions', json_build_object(
            'has_defect', json_build_object(
                'type', 'noul',
                'instructions', 'Does this review report a physical product defect or failure?'
            ),
            'satisfaction_score', json_build_object(
                'type', 'score',
                'instructions', 'Rate the customer sentiment and satisfaction on a 1-5 scale.',
                'criteria', json_build_array(
                    '1: Extremely dissatisfied / defect failure',
                    '2: Dissatisfied',
                    '3: Mixed or neutral',
                    '4: Satisfied',
                    '5: Delighted'
                )
            )
        )
    )
)::jsonb) AS jev_analysis;

باید خروجی مشابهی با این ببینید (نتایج شما ممکن است متفاوت باشد):

{
  "model": "jev-1.13.0",
  "usage": {
    "input_tokens": 388,
    "output_tokens": 39
  },
  "answers": {
    "has_defect": {
      "noul": 0.98,
      "type": "noul"
    },
    "satisfaction_score": {
      "type": "score",
      "score": 0.11,
      "legend": {
        "0": "1: Extremely dissatisfied / defect failure",
        "1": "2: Dissatisfied",
        "2": "3: Mixed or neutral",
        "3": "4: Satisfied",
        "4": "5: Delighted"
      },
      "confidence": 0.91,
      "probabilities": {
        "0": 0.9,
        "1": 0.08,
        "2": 0.02,
        "3": 0.0,
        "4": 0.0
      }
    }
  }
}

توجه کنید که satisfaction_score به 11 / 100 ارزیابی شده است، که به‌درستی نشان می‌دهد مشتری با وجود تأیید نرمی پارچه، تجربه عمدتاً منفی داشته است!

‫۱۰. مرتب‌سازی

برای جلوگیری از متحمل شدن هزینه‌های جاری برای منابع ایجادشده درطول این codelab، اشیای رمز و پایگاه داده را پاک کنید و خوشه AlloyDB را حذف کنید.

۱. حذف منابع «مدیر رمز»

در Cloud Shell، رمز ایجادشده برای کلید TypeSafe AI API را حذف کنید:

gcloud secrets delete typesafe-jev-api-key --quiet

۲. حذف کردن «نمونه اصلی» و «خوشه» AlloyDB

ابتدا نمونه اصلی را حذف کنید:

gcloud alloydb instances delete $ADBINSTANCE \
  --cluster=$ADBCLUSTER \
  --region=$REGION \
  --quiet

پس‌از تکمیل حذف نمونه، خوشه را حذف کنید:

gcloud alloydb clusters delete $ADBCLUSTER \
  --region=$REGION \
  --quiet

‫۱۱. تبریک می‌گوییم

تبریک! خوشه‌های Google Cloud AlloyDB را با موفقیت تأمین کردید و آن را با TypeSafe AI System One (Jev) ادغام کردید.

آنچه آموخته‌اید

  • نحوه ایجاد کردن «دسترسی سرویس خصوصی» (PSA) و تدارک دیدن خوشه AlloyDB برای PostgreSQL و نمونه اصلی.
  • نحوه فعال کردن --outbound-public-ip تا AlloyDB بتواند به میاناهای برنامه‌سازی کاربردی SaaS خارجی HTTPS دسترسی پیدا کند.
  • نحوه ذخیره کردن ایمن اطلاعات اعتباری ارائه‌دهنده هوش مصنوعی طرف سوم در Google Secret Manager و متصل کردن آن‌ها به AlloyDB.
  • نحوه نوشتن توابع تبدیل PL/pgSQL که توابع هوش مصنوعی استاندارد PostgreSQL (ai.if و ai.analyze_sentiment) را به میاناهای برنامه‌سازی کاربردی REST خارجی متصل می‌کند.
  • نحوه ثبت کردن نقاط پایانی LLM سفارشی در AlloyDB بااستفاده از google_ml.create_model.
  • نحوه اجرای پُرسمان‌های SQL معنایی دسته‌ای با توان گذرداد بالا و اسکالر مستقیماً در PostgreSQL.
  • نحوه تجزیه‌وتحلیل مرورهای واقعی مشتریان درباره محصول برای تشخیص احساسات دسته‌ای.
  • نحوه ثبت نقطه پایانی مدل عمومی و ارزیابی امتیازهای رضایت مستمر مشتری (0..100) ازطریق google_ml.predict_row.

مراحل بعدی

  • در اسناد AlloyDB AI درباره قابلیت‌های «توابع هوش مصنوعی AlloyDB» بیشتر بدانید.
  • برای کسب اطلاعات بیشتر درباره منطق محدودیت Noul و امتیازدهی احساسات، مرجع TypeSafe AI API را بخوانید.

اسناد مرجع