المصادقة باستخدام التشغيل السريع لبروتوكول OAuth

تتيح لك PaLM API ضبط النماذج استنادًا إلى بياناتك الخاصة. وبما أنّها بياناتك و نماذجك المحسّنة، يجب أن تكون عناصر التحكّم في الوصول أكثر صرامة من مفاتيح واجهة برمجة التطبيقات.

يستخدم دليل البدء السريع هذا نهج مصادقة مبسطًا ومناسبًا لبيئة الاختبار. بالنسبة إلى بيئة الإنتاج، تعرَّف على المصادقة والتفويض قبل اختيار بيانات اعتماد الوصول الملائمة لتطبيقك.

الأهداف

  • إعداد مشروعك على السحابة الإلكترونية لاستخدام بروتوكول OAuth
  • إعداد application-default-credentials
  • إدارة بيانات الاعتماد في برنامجك بدلاً من استخدام gcloud auth

المتطلبات الأساسية

لتنفيذ هذه الخطوات السريعة، ستحتاج إلى ما يلي:

إعداد مشروعك على السحابة الإلكترونية

لإكمال هذه الخطوة السريعة، عليك أولاً إعداد مشروعك على السحابة الإلكترونية.

1. تفعيل واجهة برمجة التطبيقات

قبل استخدام واجهات برمجة تطبيقات Google، عليك تفعيلها في مشروع على Google Cloud.

بعد ذلك، عليك ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth للمشروع وإضافة نفسك كمستخدم اختباري. إذا سبق لك إكمال هذه الخطوة لمشروعك على Cloud، يمكنك الانتقال إلى القسم التالي.

  1. في وحدة تحكّم Google Cloud، انتقِل إلى القائمة > واجهات برمجة التطبيقات والخدمات > OAuth شاشة الموافقة.

    الانتقال إلى شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

  2. اختَر نوع المستخدم خارجي لتطبيقك، ثم انقر على إنشاء.

  3. املأ نموذج تسجيل التطبيق (يمكنك ترك معظم الحقول فارغة)، ثم انقر على حفظ ومتابعة.

  4. في الوقت الحالي، يمكنك تخطّي إضافة النطاقات والنقر على حفظ ومتابعة. في المستقبل، عند إنشاء تطبيق لاستخدامه خارج مؤسستك على Google Workspace، يجب إضافة نطاقات التفويض التي يتطلبها تطبيقك والتحقّق منها.

  5. إضافة مستخدمين تجريبيين:

    1. ضمن مستخدمو الاختبار، انقر على إضافة مستخدمين.
    2. أدخِل عنوان بريدك الإلكتروني وأي مستخدمين آخرين معتمَدين للاختبار، ثم انقر على حفظ ومتابعة.

  6. راجِع ملخّص تسجيل تطبيقك. لإجراء تغييرات، انقر على تعديل. إذا كانت تسجيل التطبيق على ما يرام، انقر على العودة إلى لوحة البيانات.

3- تفويض بيانات الاعتماد لتطبيق سطح المكتب

لمصادقة المستخدم النهائي والوصول إلى بياناته في تطبيقك، عليك إنشاء معرّف عميل واحد أو أكثر من معرّفات OAuth 2.0. يُستخدَم معرّف العميل لتحديد تطبيق واحد في خوادم OAuth في Google. إذا كان تطبيقك يعمل على منصات متعددة، يجب إنشاء معرّف عميل منفصل لكل منصة.

  1. في وحدة تحكّم Google Cloud، انتقِل إلى القائمة > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.

    الانتقال إلى "بيانات الاعتماد"

  2. انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.

  3. انقر على نوع التطبيق > تطبيق كمبيوتر مكتبي.

  4. في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. ولا يظهر هذا الاسم إلا في Google Cloud Console.

  5. انقر على إنشاء. تظهر شاشة "تم إنشاء عميل OAuth"، وتعرض معرّف العميل وسر العميل الجديدَين.

  6. انقر على موافق. تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن معرّفات عملاء OAuth 2.0.

  7. انقر على زر التنزيل لحفظ ملف JSON. سيتم حفظه باسم client_secret_<identifier>.json، ويمكنك إعادة تسميته باسم client_secret.json ونقله إلى دليل العمل.

إعداد "بيانات الاعتماد التلقائية للتطبيق"

لتحويل ملف client_secret.json إلى بيانات اعتماد قابلة للاستخدام، عليك تمرير موقعه الجغرافي إلى الوسيطة --client-id-file في الأمر gcloud auth application-default login.

gcloud auth application-default login \
    --client-id-file=client_secret.json \
    --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/generative-language.tuning'

يؤدي الإعداد المبسّط للمشروع في هذا الدليل التعليمي إلى ظهور مربّع الحوار "لم تُثبِت Google صحة هذا التطبيق.". هذا أمر طبيعي، يُرجى اختيار "متابعة".

يؤدي ذلك إلى وضع الرمز المميّز الناتج في موقع معروف حتى يمكن لـgcloud أو مكتبات العملاء الوصول إليه.

gcloud auth application-default login 

    --no-browser
    --client-id-file=client_secret.json 

    --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/generative-language.tuning'

بعد ضبط بيانات اعتماد Application Default Credentials (ADC)، لا تحتاج مكتبات العميل بأغلب اللغات إلى مساعدة تذكر للعثور عليها.

تجعيد

إنّ أسرع طريقة لاختبار عمل هذا الإجراء هي استخدامه للوصول إلى واجهة برمجة التطبيقات rest باستخدام curl:

access_token=$(gcloud auth application-default print-access-token)
project_id=<MY PROJECT ID>
curl -X GET https://generativelanguage.googleapis.com/v1beta3/models \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer ${access_token}" \
    -H "x-goog-user-project: ${project_id}" | grep '"name"'
"name": "models/chat-bison-001",
"name": "models/text-bison-001",
"name": "models/embedding-gecko-001",

Python

في Python، من المفترض أن تعثر مكتبات العملاء على هذه الإعدادات تلقائيًا:

pip install google-generativeai

يمكن أن يكون النصّ البرمجي الأدنى لاختباره على النحو التالي:

import google.generativeai as genai

print('Available base models:', [m.name for m in genai.list_models()])
print('My tuned models:', [m.name for m in genai.list_tuned_models()])

الناتج المتوقع يكون على النحو التالي:

Available base models: ['models/chat-bison-001', 'models/text-bison-001', 'models/embedding-gecko-001']
My tuned models: []

Node.js

لاستخدام بيانات الاعتماد هذه مع مكتبة عملاء Node.js، اضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS.

export GOOGLE_APPLICATION_CREDENTIALS='<PATH_TO>/application_default_credentials.json'

ثبِّت مكتبة البرامج:

npm install @google-ai/generativelanguage

أنشئ نصًا برمجيًا بسيطًا:

const { ModelServiceClient } =
  require("@google-ai/generativelanguage").v1beta3;

const MODEL_NAME = "models/text-bison-001";

const client = new ModelServiceClient({});

client
  .listModels({})
  .then((result) => {
    result = result[0]
    for (let i = 0; i < result.length; i++) {
      console.log(result[i].name);
    }
  });

من المفترض أن يكون الناتج على النحو التالي:

models/chat-bison-001
models/text-bison-001
models/embedding-gecko-001

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

إذا كان هذا الإجراء ناجحًا، يعني ذلك أنّك جاهز لمحاولة ضبط نموذج بنفسك. جرِّب بدء ضبط الإعدادات.

إدارة بيانات الاعتماد بنفسك [Python]

في العديد من الحالات، لن يتوفّر لك الأمر gcloud لإنشاء رمز تمييز الدخول من رقم تعريف العميل (client_secret.json). توفّر Google مكتبات بالعديد من اللغات للسماح لك بإدارة هذه العملية في تطبيقك. يوضّح هذا القسم العملية بلغة Python. تتوفّر أمثلة مماثلة لهذا النوع من الإجراءات بلغات أخرى في مستندات واجهة برمجة التطبيقات Drive API.

1. تثبيت المكتبات اللازمة

ثبِّت مكتبة برامج Google لنظام التشغيل Python ومكتبة برامج PaLM.

pip install --upgrade -q google-api-python-client google-auth-httplib2 google-auth-oauthlib

pip install google-generativeai

2. كتابة مدير بيانات الاعتماد

في دليل العمل، أنشئ ملفًا باسم load_creds.py. ابدأ باستخدام الرمز البرمجي التالي لتحويل client_secret.json إلى رمز مميّز يمكن استخدامه مع genai.configure:

import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/generative-language.tuning']

def load_creds():
    """Converts `oauth-client-id.json` to a credential object.

    This function caches the generated tokens to minimize the use of the
    consent screen.
    """
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                'oauth-client-id.json', SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run
        with open('token.json', 'w') as token:
            token.write(creds.to_json())
    return creds

لتقليل عدد المرات التي عليك فيها النقر على شاشات التفويض، يمكنك تخزين ملف token.json مؤقتًا في ذاكرة التخزين المؤقت، ويمكنك إعادة استخدامه لاحقًا، أو إعادة تحميله إذا انتهت صلاحيته.

3- كتابة برنامجك

أنشئ الآن script.py:

import pprint
import google.generativeai as genai
from load_creds import load_creds

creds = load_creds()

genai.configure(credentials=creds)

print()
print('Available base models:', [m.name for m in genai.list_tuned_models()])
print('My tuned models:', [m.name for m in genai.list_tuned_models()])

4. تشغيل البرنامج

في دليل العمل، شغِّل العيّنة:

python script.py

في المرة الأولى التي تُشغِّل فيها النص البرمجي، سيفتح نافذة متصفّح ويطلب منك تفويض الوصول.

  1. إذا لم تكن مسجِّلاً الدخول إلى حسابك على Google، سيُطلب منك تسجيل الدخول. إذا كنت مسجّلاً الدخول إلى حسابات متعدّدة، احرص على اختيار الحساب الذي أعددته كـ "حساب اختباري" عند ضبط إعدادات مشروعك.

  2. يتم تخزين معلومات التفويض في نظام الملفات، لذا لن يُطلب منك منح التفويض في المرة القادمة التي تدخِل فيها رمزًا نموذجيًا.

تم إعداد المصادقة بنجاح.