אימות באמצעות מדריך למתחילים של OAuth

PaLM API מאפשר לכם לכוונן מודלים על סמך הנתונים שלכם. מכיוון שמדובר בנתונים שלכם ובמודלים שהותאמו, צריך אמצעי בקרת גישה מחמירים יותר מאשר מפתחות API.

במדריך למתחילים הזה נעשה שימוש בגישה פשוטה לאימות שמתאימה לסביבת בדיקה. בסביבת ייצור, כדאי לקרוא על אימות והרשאה לפני בחירת פרטי הכניסה המתאימים לאפליקציה.

מטרות

  • הגדרת פרויקט בענן ל-OAuth
  • הגדרת application-default-credentials
  • ניהול פרטי הכניסה בתוכנית במקום להשתמש ב-gcloud auth

דרישות מוקדמות

כדי להריץ את המדריך למתחילים הזה, צריך:

הגדרת הפרויקט בענן

כדי להשלים את המדריך למתחילים הזה, קודם צריך להגדיר את פרויקט הענן.

1. הפעלת ה-API

לפני שמשתמשים ב-Google APIs, צריך להפעיל אותם בפרויקט ב-Google Cloud.

  • במסוף Google Cloud, מפעילים את Google Generative Language API.

    להפעלת ה-API

בשלב הבא מגדירים את מסך ההסכמה של OAuth בפרויקט ומוסיפים את עצמכם כמשתמשי בדיקה. אם כבר השלמתם את השלב הזה בפרויקט ב-Cloud, תוכלו לדלג לקטע הבא.

  1. במסוף Google Cloud, עוברים אל תפריט > APIs & Services > OAuth screen consent.

    כניסה למסך ההסכמה של OAuth

  2. בוחרים את סוג המשתמש חיצוני לאפליקציה ולוחצים על Create.

  3. ממלאים את טופס הרישום של האפליקציה (אפשר להשאיר את רוב השדות ריקים) ולוחצים על שמירה והמשך.

  4. בשלב הזה, אפשר לדלג על הוספת היקפי הרשאה וללחוץ על Save and Continue (שמירה והמשך). בעתיד, כשיוצרים אפליקציה לשימוש מחוץ לארגון ב-Google Workspace, צריך להוסיף ולאמת את היקפי ההרשאה הנדרשים לאפליקציה.

  5. מוסיפים משתמשי בדיקה:

    1. בקטע משתמשי בדיקה, לוחצים על הוספת משתמשים.
    2. מזינים את כתובת האימייל שלכם ואת כתובות האימייל של משתמשי הבדיקה המורשים האחרים, ולוחצים על Save and Continue (שמירה והמשך).
  6. בודקים את סיכום רישום האפליקציה. כדי לבצע שינויים, לוחצים על עריכה. אם הרשמת האפליקציה נראית תקינה, לוחצים על Back to Dashboard (חזרה למרכז הבקרה).

3. מתן הרשאה לפרטי כניסה לאפליקציה למחשב

כדי לבצע אימות כמשתמש קצה ולגשת לנתוני המשתמשים באפליקציה, צריך ליצור מזהה לקוח אחד או יותר ב-OAuth 2.0. מזהה לקוח משמש לזיהוי אפליקציה אחת בשרתי OAuth של Google. אם האפליקציה פועלת בכמה פלטפורמות, צריך ליצור מזהה לקוח נפרד לכל פלטפורמה.

  1. נכנסים למסוף Google Cloud, לוחצים על תפריט > APIs & Services > Credentials.

    לדף Credentials

  2. לוחצים על Create Credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth).

  3. לוחצים על Application type (סוג האפליקציה) > Desktop app (אפליקציה למחשב).

  4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.

  5. לוחצים על יצירה. מופיע המסך של לקוח OAuth שנוצר, שבו מוצגים מזהה הלקוח החדש וסוד הלקוח.

  6. לוחצים על אישור. פרטי הכניסה החדשים שיצרתם יופיעו בקטע מזהי לקוח של OAuth 2.0.

  7. לוחצים על לחצן ההורדה כדי לשמור את קובץ ה-JSON. הוא יישמר בתור client_secret_<identifier>.json, ותצטרכו לשנות את השם שלו ל-client_secret.json ולהעביר אותו לספריית העבודה.

הגדרת Application Default Credentials

כדי להמיר את הקובץ 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 hasn't verified this app". זוהי תופעה רגילה. בוחרים באפשרות 'המשך'.

כך האסימון שנוצר ממוקם במיקום ידוע, כך שאפשר לגשת אליו באמצעות 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), ספריות הלקוח ברוב השפות לא זקוקות לעזרה רבה או בכלל כדי למצוא אותם.

Curl

הדרך המהירה ביותר לבדוק אם זה עובד היא להשתמש בו כדי לגשת ל-API ה-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. פרטי ההרשאה מאוחסנים במערכת הקבצים, כך שבפעם הבאה שתפעילו את הקוד לדוגמה, לא תתבקשו להעניק הרשאה.

הגדרתם את האימות.