Muitos modelos abertos na Gemini Enterprise Agent Platform oferecem modelos totalmente gerenciados e sem servidor como APIs usando a API Chat Completions da Gemini Enterprise Agent Platform. Para esses modelos, não é necessário provisionar nem gerenciar a infraestrutura.
É possível transmitir as respostas para reduzir a percepção de latência do usuário final. Uma resposta transmitida usa eventos enviados pelo servidor (SSE) para transmitir a resposta de forma incremental.
Nesta página, mostramos como fazer chamadas de streaming e não streaming para modelos abertos que oferecem suporte à API Chat Completions da OpenAI. Para considerações específicas do Llama, consulte Solicitar previsões do Llama.
Antes de começar
Para usar modelos abertos com a Gemini Enterprise Agent Platform, siga as
etapas abaixo. A API Agent Platform
(aiplatform.googleapis.com) e a API Cloud Commerce Consumer
Procurement (cloudcommerceconsumerprocurement.googleapis.com)
precisam estar ativadas para usar modelos abertos na Gemini Enterprise Agent Platform. Se você já tiver um projeto com essas APIs ativadas, use-o em vez de criar um novo.
- Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Gemini Enterprise Agent Platform and Cloud Commerce Consumer Procurement APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Gemini Enterprise Agent Platform and Cloud Commerce Consumer Procurement APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.- Acesse o card do modelo que você quer usar no Model Garden e clique em Ativar para ativar o modelo no seu projeto.
Funções exigidas
Para receber as permissões necessárias para ativar e usar modelos abertos, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:
- Usuário da Agent Platform (
roles/aiplatform.user) - Gerente de direito de compra do consumidor (
roles/consumerprocurement.entitlementManager)
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.
Para mais informações sobre como conceder permissões e configurar políticas da organização para modelos abertos, consulte Conceder acesso de usuário a modelos abertos.
Fazer uma chamada de streaming para um modelo aberto
O exemplo a seguir faz uma chamada de streaming para um modelo aberto:
Python
Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.
Para autenticar na plataforma de agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar este exemplo, defina a variável de ambiente OPENAI_BASE_URL.
Para mais informações, consulte Autenticação e credenciais.
from openai import OpenAI client = OpenAI() stream = client.chat.completions.create( model="MODEL", messages=[{"role": "ROLE", "content": "CONTENT"}], max_tokens=MAX_OUTPUT_TOKENS, stream=True, ) for chunk in stream: print(chunk.choices[0].delta.content or "", end="")
- MODEL: o nome do modelo que você quer usar,
por exemplo,
openai/gpt-oss-120b-maas. - ROLE: o papel associado a uma mensagem. É possível especificar
userouassistant. A primeira mensagem precisa usar o papeluser. Os modelos funcionam com voltas alternadas deusereassistant. Se a mensagem final usar o papelassistant, o conteúdo da resposta continuará imediatamente a partir do conteúdo dessa mensagem. É possível usar isso para restringir parte da resposta do modelo. - CONTENT: o conteúdo, como texto, da mensagem
userouassistant. - MAX_OUTPUT_TOKENS:
número máximo de tokens que podem ser gerados na resposta. Um token tem cerca de quatro caracteres. 100 tokens correspondem a cerca de 60 a 80 palavras.
Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas potencialmente mais longas.
REST
Depois de configurar o ambiente, use REST para testar um comando de texto. O exemplo a seguir envia uma solicitação ao endpoint do modelo de editor.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud.
- MODEL: o nome do modelo que você quer usar,
por exemplo,
openai/gpt-oss-120b-maas. - ROLE: o papel associado a uma mensagem. É possível especificar
userouassistant. A primeira mensagem precisa usar o papeluser. Os modelos funcionam com voltas alternadas deusereassistant. Se a mensagem final usar o papelassistant, o conteúdo da resposta continuará imediatamente a partir do conteúdo dessa mensagem. É possível usar isso para restringir parte da resposta do modelo. - CONTENT: o conteúdo, como texto, da mensagem
userouassistant. - MAX_OUTPUT_TOKENS:
número máximo de tokens que podem ser gerados na resposta. Um token tem cerca de quatro caracteres. 100 tokens correspondem a cerca de 60 a 80 palavras.
Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas potencialmente mais longas.
- STREAM: um booleano que especifica se a resposta será transmitida ou não. Transmita sua resposta para reduzir a percepção de latência do uso final. Defina como
truepara transmitir a resposta efalsepara retornar a resposta de uma só vez.
Método HTTP e URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions
Corpo JSON da solicitação:
{
"model": "MODEL",
"messages": [
{
"role": "ROLE",
"content": "CONTENT"
}
],
"max_tokens": MAX_OUTPUT_TOKENS,
"stream": true
}
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions" | Select-Object -Expand Content
Você receberá uma resposta JSON semelhante a seguinte.
Fazer uma chamada sem streaming para um modelo aberto
O exemplo a seguir faz uma chamada sem streaming para um modelo aberto:
Python
Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.
Para autenticar na plataforma de agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar este exemplo, defina a variável de ambiente OPENAI_BASE_URL.
Para mais informações, consulte Autenticação e credenciais.
from openai import OpenAI client = OpenAI() completion = client.chat.completions.create( model="MODEL", messages=[{"role": "ROLE", "content": "CONTENT"}], max_tokens=MAX_OUTPUT_TOKENS, stream=False, ) print(completion.choices[0].message)
- MODEL: o nome do modelo que você quer usar,
por exemplo,
openai/gpt-oss-120b-maas. - ROLE: o papel associado a uma mensagem. É possível especificar
userouassistant. A primeira mensagem precisa usar o papeluser. Os modelos funcionam com voltas alternadas deusereassistant. Se a mensagem final usar o papelassistant, o conteúdo da resposta continuará imediatamente a partir do conteúdo dessa mensagem. É possível usar isso para restringir parte da resposta do modelo. - CONTENT: o conteúdo, como texto, da mensagem
userouassistant. - MAX_OUTPUT_TOKENS:
número máximo de tokens que podem ser gerados na resposta. Um token tem cerca de quatro caracteres. 100 tokens correspondem a cerca de 60 a 80 palavras.
Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas potencialmente mais longas.
REST
Depois de configurar o ambiente, use REST para testar um comando de texto. O exemplo a seguir envia uma solicitação ao endpoint do modelo de editor.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto do Google Cloud.
- MODEL: o nome do modelo que você quer usar,
por exemplo,
openai/gpt-oss-120b-maas. - ROLE: o papel associado a uma mensagem. É possível especificar
userouassistant. A primeira mensagem precisa usar o papeluser. Os modelos funcionam com voltas alternadas deusereassistant. Se a mensagem final usar o papelassistant, o conteúdo da resposta continuará imediatamente a partir do conteúdo dessa mensagem. É possível usar isso para restringir parte da resposta do modelo. - CONTENT: o conteúdo, como texto, da mensagem
userouassistant. - MAX_OUTPUT_TOKENS:
número máximo de tokens que podem ser gerados na resposta. Um token tem cerca de quatro caracteres. 100 tokens correspondem a cerca de 60 a 80 palavras.
Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas potencialmente mais longas.
- STREAM: um booleano que especifica se a resposta será transmitida ou não. Transmita sua resposta para reduzir a percepção de latência do uso final. Defina como
truepara transmitir a resposta efalsepara retornar a resposta de uma só vez.
Método HTTP e URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions
Corpo JSON da solicitação:
{
"model": "MODEL",
"messages": [
{
"role": "ROLE",
"content": "CONTENT"
}
],
"max_tokens": MAX_OUTPUT_TOKENS,
"stream": false
}
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions" | Select-Object -Expand Content
Você receberá uma resposta JSON semelhante a seguinte.
Endpoints regionais e globais
Para endpoints regionais, as solicitações são atendidas na região especificada. Nos casos em que você tem requisitos de residência de dados ou se um modelo não é compatível com o endpoint global, use os endpoints regionais.
Quando você usa o endpoint global, o Google pode processar e atender às suas solicitações em qualquer região compatível com o modelo que você está usando. Isso pode resultar em maior latência em alguns casos. O endpoint global ajuda a melhorar a disponibilidade geral e a reduzir erros.
Não há diferença de preço com os endpoints regionais quando você usa o endpoint global. No entanto, as cotas de endpoints globais e os recursos de modelos compatíveis podem ser diferentes dos endpoints regionais. Para mais informações, consulte a página relacionada ao modelo de terceiros.
Especifique o endpoint global
Para usar o endpoint global, defina a região como global.
Por exemplo, o URL de solicitação de um comando curl usa o seguinte formato:
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi
Para o SDK da Agent Platform, um endpoint regional é o padrão. Defina a
região como GLOBAL para usar o endpoint global.
Restringir o uso de endpoints de API globais
Para ajudar a aplicar o uso de endpoints regionais, utilize a
restrição de política da organização constraints/gcp.restrictEndpointUsage para
bloquear solicitações ao endpoint de API global. Para mais informações, consulte
Restringir o uso de endpoints.
A seguir
- Saiba como usar a chamada de função.
- Saiba mais sobre a saída estruturada.
- Saiba mais sobre predições em lote.