Guia de início rápido do OAuth

A API PaLM permite ajustar modelos com base em dados próprios. Como são seus dados e seus modelos ajustados, isso requer controles de acesso mais rigorosos do que as APIs-Keys.

Neste guia de início rápido, usamos uma abordagem de autenticação simplificada que é apropriada para um ambiente de teste. Para um ambiente de produção, saiba mais sobre autenticação e autorização antes de escolher as credenciais de acesso adequadas para seu app.

Objetivos

  • Configurar seu projeto na nuvem para OAuth
  • Configurar o application-default-credentials
  • Gerencie as credenciais no seu programa em vez de usar gcloud auth

Pré-requisitos

Para executar este guia de início rápido, você precisa de:

Configurar seu projeto na nuvem

Para concluir este guia de início rápido, primeiro você precisa configurar seu projeto do Cloud.

1. Ativar a API

Antes de usar as APIs do Google, elas precisam ser ativadas em um projeto do Google Cloud.

  • No console do Google Cloud, ative a API Google Generative Language.

    Ativar a API

Em seguida, configure a tela de permissão OAuth do projeto e adicione-se como usuário de teste. Se você já concluiu essa etapa no projeto do Cloud, pule para a próxima seção.

  1. No Console do Google Cloud, acesse Menu > APIs e serviços > Tela de consentimento do OAuth.

    Acessar a tela de permissão OAuth

  2. Selecione o tipo de usuário Externo para o app e clique em Criar.

  3. Preencha o formulário de registro do app (é possível deixar a maioria dos campos em branco) e clique em Salvar e continuar.

  4. Por enquanto, é possível pular a adição de escopos e clicar em Salvar e continuar. No futuro, ao criar um app para uso fora da sua organização do Google Workspace, você precisará adicionar e verificar os escopos de autorização exigidos pelo app.

  5. Adicionar usuários de teste:

    1. Em Usuários de teste, clique em Adicionar usuários.
    2. Insira seu endereço de e-mail e outros usuários de teste autorizados, e clique em Salvar e continuar.
  6. Analise o resumo de registro do seu app. Para fazer mudanças, clique em Editar. Se o registro do app parecer correto, clique em Voltar ao painel.

3. Autorizar credenciais de um aplicativo para computador

Para fazer a autenticação como usuário final e acessar os dados do usuário no app, crie um ou mais IDs do cliente OAuth 2.0. Um ID do cliente é usado para identificar um único app nos servidores OAuth do Google. Se o app for executado em várias plataformas, você precisará criar um ID do cliente separado para cada uma delas.

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Acessar "Credenciais"

  2. Clique em Criar credenciais > ID do cliente OAuth.

  3. Clique em Tipo de aplicativo > App para computador.

  4. No campo Nome, digite um nome para a credencial. Esse nome só é mostrado no console do Google Cloud.

  5. Clique em Criar. A tela do cliente OAuth criado é exibida, mostrando o novo ID e a chave secreta do cliente.

  6. Clique em OK. A credencial recém-criada é exibida em IDs do cliente OAuth 2.0.

  7. Clique no botão de download para salvar o arquivo JSON. Ele será salvo como client_secret_<identifier>.json, renomeado como client_secret.json e movido para o diretório de trabalho.

Configurar o Application Default Credentials

Para converter o arquivo client_secret.json em credenciais utilizáveis, transmita o local do argumento --client-id-file do comando 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'

A configuração simplificada do projeto neste tutorial aciona a caixa de diálogo "O Google não verificou este app". Isso é normal. Escolha "continuar".

Isso coloca o token resultante em um local conhecido para que possa ser acessado pelo gcloud ou pelas bibliotecas de cliente.

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'

Depois de definir as credenciais padrão do aplicativo (ACD, na sigla em inglês), as bibliotecas de cliente, na maioria das linguagens, vão precisar de pouca ou nenhuma ajuda para encontrá-las.

Curl

A maneira mais rápida de testar se isso está funcionando é usá-lo para acessar a API REST usando 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

Em Python, as bibliotecas de cliente devem encontrá-las automaticamente:

pip install google-generativeai

Um script mínimo para testá-lo pode ser:

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()])

A resposta esperada é:

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

Node.js

Para usar essas credenciais com a biblioteca de cliente Node.js, defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

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

Instale a biblioteca de cliente:

npm install @google-ai/generativelanguage

Crie um script mínimo:

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);
    }
  });

A saída vai ser:

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

Próximas etapas

Se isso estiver funcionando, você pode tentar ajustar um modelo por conta própria. Consulte Começar a fazer os ajustes.

Gerenciar credenciais por conta própria [Python]

Em muitos casos, você não tem o comando gcloud disponível para criar o token de acesso a partir do ID do cliente (client_secret.json). O Google oferece bibliotecas em muitas linguagens para que você gerencie esse processo no seu app. Esta seção demonstra o processo em Python. Há exemplos equivalentes desse tipo de procedimento, para outras linguagens, disponíveis na documentação da API do Drive.

1. Instalar as bibliotecas necessárias

Instale a biblioteca de cliente do Google para Python e a biblioteca de cliente do PaLM.

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

pip install google-generativeai

2. Gravar o gerenciador de credenciais

No diretório de trabalho, crie um arquivo chamado load_creds.py. Comece com o código a seguir para converter o client_secret.json em um token que pode ser usado com o 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

Para minimizar o número de vezes que você precisa clicar nas telas de autorização se armazenar em cache um arquivo token.json que possa ser reutilizado mais tarde, ou atualizar se ele expirar.

3. Criar seu programa

Agora crie o 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. Executar o programa

No diretório de trabalho, execute o exemplo:

python script.py

Quando o script é executado pela primeira vez, ele abre uma janela do navegador e solicita que você autorize o acesso.

  1. Se você ainda não tiver feito login na sua Conta do Google, será necessário fazer login. Se você tiver feito login em várias contas, selecione a conta definida como "Conta de teste" ao configurar o projeto.

  2. As informações de autorização são armazenadas no sistema de arquivos. Portanto, na próxima vez que você executar o exemplo de código, a autorização não será solicitada.

A autenticação foi configurada.