استخدام نموذج Jev من TypeSafe AI مع "دوال AlloyDB AI" لتنفيذ طلبات بحث الذكاء الاصطناعي العالية السرعة

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية ربط نموذج Jev من TypeSafe AI بـ AlloyDB AI باستخدام دوال الذكاء الاصطناعي الأصلية في AlloyDB (ai.if وai.analyze_sentiment وml_predict_row). يتيح لك ذلك تشغيل استنتاج مجمّع فعّال باستخدام نموذج Jev مباشرةً على بياناتك التشغيلية في AlloyDB، بدون نقل بياناتك أو كتابة رمز معقّد من جهة التطبيق.

الإجراءات التي ستنفذّها

  • توفير إمكانية الوصول إلى الخدمات الخاصة (PSA) ومجموعة AlloyDB for PostgreSQL والمثيل الأساسي
  • إنشاء قاعدة جدار حماية لشبكة VPC تسمح باتصال Cloudshell والاتصال الداخلي
  • تحميل نموذج مجموعة بيانات للتجارة الإلكترونية باستخدام gcloud alloydb clusters import
  • تفعيل Google Secret Manager وإضافة google_ml_integration في AlloyDB
  • تخزين مفتاح واجهة برمجة التطبيقات TypeSafe AI ومنح إذن الوصول إليه في Secret Manager
  • إنشاء دوال تحويل الإدخال والإخراج في PL/pgSQL للقيم الأساسية noul (منطقية) وchoice (المشاعر) في Jev
  • تسجيل نقطة نهاية نموذج jev-model المخصّص في AlloyDB
  • تنفيذ طلبات البحث الدلالية العددية والمجمّعة في مصفوفات (ai.if وai.analyze_sentiment) مباشرةً في SQL
  • الاستعلام عن مراجعات المنتجات من قِبل العملاء الحقيقيين لتصنيف الآراء باستخدام ai.analyze_sentiment
  • (مكافأة) سجِّل نقطة نهاية عامة (jev-systemone) وقيِّم مستوى رضا العملاء المستمر باستخدام دالة Jev's score الأساسية

المتطلبات

  • متصفّح ويب، مثل Chrome
  • مشروع على Google Cloud تم تفعيل الفوترة فيه
  • مفتاح واجهة برمجة تطبيقات TypeSafe AI (من TypeSafe AI)

2. قبل البدء

اختيار مشروعك على Google Cloud

في Google Cloud Console، اختَر مشروع Google Cloud الذي تريد استخدامه أو أنشِئه.

بدء Cloud Shell

انقر على تفعيل Cloud Shell في أعلى يسار صفحة Google Cloud Console.

تأكَّد من مصادقة جلسة 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 API المطلوبة

نفِّذ هذا الأمر لتفعيل جميع واجهات برمجة التطبيقات اللازمة لخدمات Google Cloud:

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

3- توفير مجموعة AlloyDB والمثيل الأساسي

في هذه الخطوة، ستخصّص نطاق عناوين IP لاتصال الخدمات الخاصة في شبكة VPC، وتنشئ اتصالاً خاصًا، وتوفّر مجموعة AlloyDB والمثيل الأساسي مع إمكانية الوصول إلى الإنترنت الصادر.

1. إنشاء نطاق عناوين IP لخدمة "الوصول إلى الخدمات الخاصة" (PSA)

يتطلّب AlloyDB تخصيص نطاق عناوين IP خاصة في شبكة السحابة الإلكترونية الخاصة الافتراضية (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

2. إنشاء مجموعة 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 

3- إنشاء المثيل الأساسي باستخدام علامات الذكاء الاصطناعي وإمكانية الاتصال الصادر

يتصل AlloyDB مباشرةً بنقطة نهاية SaaS الآمنة في TypeSafe AI ‏ (https://api.typesafe.ai/v1/systemone) عبر بروتوكول HTTPS الصادر. لذلك، يجب تحديد السمة --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

4. تحميل نموذج بيانات التجارة الإلكترونية

لاختبار طلبات البحث الدلالية الواقعية، استورِد مجموعة بيانات نموذجية للتجارة الإلكترونية تحتوي على كتالوجات المنتجات ومراجعات العملاء مباشرةً من 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

4. تخزين مفتاح واجهة برمجة التطبيقات (API) الخاص بـ TypeSafe AI في Secret Manager

تتكامل ميزة "إدارة نقاط نهاية النماذج" في AlloyDB بشكلٍ أصلي مع Google Secret Manager لمصادقة طلبات البيانات من واجهات برمجة التطبيقات الخارجية بدون الكشف عن بيانات الاعتماد النصية في رمز قاعدة البيانات أو سجلّات الضبط.

1. إنشاء الرمز السرّي

في Cloud Shell، أنشئ سرًا جديدًا باسم typesafe-jev-api-key:

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

أضِف مفتاح واجهة برمجة التطبيقات TypeSafe AI كنسخة سرية:

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

2. منح إذن الوصول إلى وكيل خدمة AlloyDB

يستخدم AlloyDB وكيل خدمة المشروع لاسترداد الرموز السرية أثناء تنفيذ طلب البحث. ابحث عن رقم مشروعك وامنح دور "الوصول إلى البيانات السرية" (Secret Accessor):

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.

5- الاتصال بـ AlloyDB من خلال AlloyDB Studio وإعداد إضافات قواعد البيانات

للتفاعل مع قاعدة بيانات AlloyDB مباشرةً من المتصفّح بدون ضبط أدوات العميل المحلية أو قنوات الخادم الوكيل، استخدِم AlloyDB Studio في Google Cloud Console.

1. فتح AlloyDB Studio

  1. في Google Cloud Console، انتقِل إلى AlloyDB for PostgreSQL > المجموعات.
  2. انقر على المجموعة (my-alloydb-cluster).
  3. في قائمة التنقّل اليمنى، انقر على AlloyDB Studio.
  4. المصادقة على قاعدة البيانات:
    • قاعدة البيانات: postgres
    • المستخدم: postgres
    • كلمة المرور: أدخِل $PGPASSWORD التي تم إنشاؤها أثناء إنشاء المجموعة (مثلاً، شغِّل echo $PGPASSWORD في Cloud Shell لعرضها).
  5. انقر على مصادقة.

أنت الآن في محرِّر طلبات البحث التفاعلي في SQL ضمن AlloyDB Studio.

2. تفعيل إضافات قواعد البيانات وعلاماتها

في محرِّر طلبات البحث في 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';

انقر على تشغيل لتنفيذ طلب البحث.

3- تسجيل الرمز السرّي في AlloyDB MEM

أخبِر AlloyDB بمكان العثور على مفتاح واجهة برمجة التطبيقات (API) الخاص بـ TypeSafe AI:

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

6. إنشاء دوال تحويل SQL

تقبل واجهة برمجة التطبيقات System One من TypeSafe AI ملفات JSON المنظَّمة التي تتضمّن عناصر استدلالية مميّزة (noul للقيود المنطقية وchoice للتصنيف المتعدّد الفئات).

تستخدم ميزة "إدارة نقاط نهاية النماذج" في AlloyDB أربع دوال تحويل (إدخال عددي، وإخراج عددي، وإدخال مجمّع، وإخراج مجمّع) لربط توقيعات دوال ai.* العادية في PostgreSQL بتنسيق Jev REST API.

1. تحويل الإدخال القياسي

أضِف الدالة التالية لتحويل طلبات 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;
$$;

2. تحويل الناتج القياسي

أضِف الدالة لإلغاء حزمة استجابة JSON من Jev إلى نتيجة 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;
$$;

3- تحويل الإدخال المجمّع

يمكن لـ Jev تقييم عشرات الأسئلة في الوقت نفسه ضمن رحلة ذهاب وعودة واحدة لبروتوكول HTTP بدون تدهور في جودة المحتوى الذي يتم إنشاؤه.

أضِف تحويل الإدخال المجمّع لتحويل مصفوفات PostgreSQL prompts TEXT[] إلى أسئلة Jev q_1 .. q_N موازية:

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;
$$;

4. تحويل الناتج المجمّع

أضِف الدالة لاستخراج الإجابات بترتيب فهرس مصفوفة 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;
$$;

7. تسجيل نقطة نهاية النموذج المخصّص في AlloyDB

الآن، عليك ربط دوال التحويل وبيانات الاعتماد السرية ونقطة نهاية TypeSafe AI REST معًا في نموذج مسجَّل باسم jev-model.

1. تسجيل بطاقة "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'
);

2. التحقّق من التسجيل

يمكنك الاستعلام عن عرض سجلّ النماذج للتأكّد من أنّ 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)

8. تشغيل طلبات البحث الاختبارية على Jev

بعد تسجيل jev-model، يمكنك الآن تنفيذ العمليات الدلالية مباشرةً داخل طلبات البحث العادية في PostgreSQL.

1. اختبار الفلترة المنطقية العددية (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)

2. اختبار تحليل المشاعر العددية (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)

3- اختبار الفلترة المنطقية المجمّعة في مصفوفة

يمكنك تقييم عناصر متعددة في طلب واحد من خلال تمرير مصفوفة من الطلبات:

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)

4. اختبار طلبات البحث في الجدول باستخدام تجميع الصفائف

الآن، يمكنك الاستعلام عن جدول ecomm.products الذي تم تحميله سابقًا أثناء توفير موارد المجموعة، باستخدام ai.if على مجموعة من العناصر للتحقّق من المنتجات في الكتالوج التي تُعدّ ملابس للطقس البارد.

لتشغيل الفلترة الدلالية بمعدّل نقل بيانات عالٍ على بيانات الجدول (مثلاً، 50 صفًا لكل دفعة)، استخدِم دالة النافذة 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)

5- الاستعلام عن مراجعات العملاء للمنتجات لمعرفة آرائهم

يمكنك الآن تحليل مراجعات العملاء من جدول 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)

9. مكافأة: تسجيل المشاعر المستمر باستخدام درجة Jev

في حين أنّ دوال الذكاء الاصطناعي في AlloyDB، مثل ai.analyze_sentiment، تُرجع مجموعات فئوية (positive وnegative وneutral)، فإنّ دالة score الأساسية في TypeSafe AI تقيّم الفروق الدقيقة في قواعد تقييم منظَّمة وتُرجع تقييمًا مستمرًا مرجَّحًا حسب التوقعات من 0 إلى 100.

بما أنّ score يعرض بيانات وصفية رقمية بدلاً من تصنيف نصي، يمكنك تسجيل نقطة نهاية مخصّصة لنموذج generic (jev-systemone) واستدعائها باستخدام google_ml.predict_row.

1. تسجيل نقطة النهاية العامة

في 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'
);

2. إجراء تقييم متعدّد المهام (قيمة منطقية + نتيجة مستمرة)

يمكنك تقييم كل من فحص القيمة المنطقية للعيوب (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، ما يعكس بدقة أنّ تجربة العميل كانت سلبية في الغالب على الرغم من إقراره بأنّ القماش كان ناعمًا.

10. تَنظيم

لتجنُّب تحمُّل رسوم مستمرة مقابل الموارد التي تم إنشاؤها خلال هذا الدرس التطبيقي حول الترميز، عليك حذف عناصر قاعدة البيانات والبيانات السرية، وحذف مجموعة AlloyDB.

1. حذف موارد Secret Manager

في Cloud Shell، احذف البيانات السرية التي تم إنشاؤها لمفتاح واجهة برمجة التطبيقات (API) الخاص بـ TypeSafe AI:

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

2. حذف مثيل AlloyDB الأساسي والمجموعة

احذف المثيل الأساسي أولاً:

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

بعد اكتمال حذف المثيل، احذف المجموعة:

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

11. تهانينا

تهانينا! لقد نجحت في توفير مجموعة 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 الخارجية
  • كيفية تسجيل نقاط نهاية مخصّصة لنماذج لغوية كبيرة في AlloyDB باستخدام google_ml.create_model
  • كيفية تنفيذ طلبات بحث SQL دلالية قياسية ومجمّعة بمعدّل نقل بيانات عالٍ مباشرةً في PostgreSQL
  • كيفية تحليل مراجعات المنتجات من عملاء حقيقيين لمعرفة المشاعر تجاه فئات معيّنة
  • كيفية تسجيل نقطة نهاية نموذج عام وتقييم نتائج رضا العملاء المستمرة (0..100) من خلال google_ml.predict_row

الخطوات التالية

المستندات المرجعية