Esta página foi traduzida pela API Cloud Translation.

Chame APIs MaaS para modelos abertos

Muitos modelos abertos no Vertex AI oferecem modelos totalmente geridos e sem servidor como APIs através da API Chat Completions do Vertex AI. Para estes modelos, não é necessário aprovisionar nem gerir a infraestrutura.

Pode transmitir as suas respostas para reduzir a perceção de latência do utilizador final. Uma resposta em stream usa eventos enviados pelo servidor (SSE) para transmitir a resposta de forma incremental.

Esta página mostra como fazer chamadas de streaming e não streaming para abrir modelos que suportam a API OpenAI Chat Completions. Para considerações específicas do Llama, consulte o artigo Peça previsões do Llama.

Antes de começar

Para usar modelos abertos com a Vertex AI, tem de seguir os passos abaixo. A API Vertex AI (aiplatform.googleapis.com) tem de estar ativada para usar a Vertex AI. Se já tiver um projeto com a API Vertex AI ativada, pode usá-lo em vez de criar um novo projeto.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Aceda ao cartão do modelo do Model Garden para o modelo que quer usar e, de seguida, clique em Ativar para ativar o modelo para utilização no seu projeto.
Aceda ao Model Garden

Faça uma chamada de streaming para um modelo aberto

O exemplo seguinte faz uma chamada de streaming para um modelo aberto:

Python

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Python Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

Antes de executar este exemplo, certifique-se de que define a variável de ambiente OPENAI_BASE_URL. Para mais informações, consulte o artigo 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 quer usar, por exemplo, deepseek-ai/deepseek-v3.1-maas.
ROLE: a função associada a uma mensagem. Pode especificar um user ou um assistant. A primeira mensagem tem de usar a função user. Os modelos funcionam com turnos alternados de user e assistant. Se a mensagem final usar a função assistant, o conteúdo da resposta continua imediatamente a partir do conteúdo dessa mensagem. Pode usar isto para restringir parte da resposta do modelo.
CONTENT: O conteúdo, como o texto, da mensagem user ou assistant.
MAX_OUTPUT_TOKENS: Número máximo de tokens que podem ser gerados na resposta. Um token tem aproximadamente quatro carateres. 100 tokens correspondem a aproximadamente 60 a 80 palavras.
Especifique um valor inferior para respostas mais curtas e um valor superior para respostas potencialmente mais longas.

REST

Depois de configurar o seu ambiente, pode usar a API REST para testar um comando de texto. O exemplo seguinte envia um pedido para o ponto final do modelo do publicador.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

LOCATION: Uma região que suporta modelos abertos.
MODEL: o nome do modelo que quer usar, por exemplo, deepseek-ai/deepseek-v2.
ROLE: a função associada a uma mensagem. Pode especificar um user ou um assistant. A primeira mensagem tem de usar a função user. Os modelos funcionam com turnos alternados de user e assistant. Se a mensagem final usar a função assistant, o conteúdo da resposta continua imediatamente a partir do conteúdo dessa mensagem. Pode usar isto para restringir parte da resposta do modelo.
CONTENT: O conteúdo, como o texto, da mensagem user ou assistant.
MAX_OUTPUT_TOKENS: Número máximo de tokens que podem ser gerados na resposta. Um token tem aproximadamente quatro carateres. 100 tokens correspondem a aproximadamente 60 a 80 palavras.
Especifique um valor inferior para respostas mais curtas e um valor superior para respostas potencialmente mais longas.
STREAM: um valor booleano que especifica se a resposta é transmitida ou não. Transmita a sua resposta para reduzir a perceção de latência do utilizador final. Defina como true para fazer streaming da resposta e false para devolver a resposta de uma só vez.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

Corpo JSON do pedido:

{
  "model": "MODEL",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_OUTPUT_TOKENS,
  "stream": true
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

PowerShell

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte.

Resposta

data: {
  "choices": [
    {
      "delta": {
        "content": "CONTENT",
        "role": "assistant"
      },
      "index": 0,
      "logprobs": null
    }
  ],
  "created": 1234567890,
  "id": "2025-06-11|10:00:00.292195-07|9.7.144.202|-123456789",
  "model": "MODEL",
  "object": "chat.completion.chunk",
  "system_fingerprint": ""
}

data: {
  "choices": [
    {
      "delta": {
        "content": "CONTENT",
        "role": "assistant"
      },
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null
    }
  ],
  "created": 1234567890,
  "id": "2025-06-11|10:00:00.292195-07|9.7.144.202|-123456789",
  "model": "MODEL",
  "object": "chat.completion.chunk",
  "system_fingerprint": "",
  "usage": {
    "completion_tokens": 131,
    "prompt_tokens": 14,
    "total_tokens": 145
  }
}

data: [DONE]

Faça uma chamada sem streaming a um modelo aberto

O exemplo seguinte faz uma chamada não de streaming a um modelo aberto:

Python

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

Antes de executar este exemplo, certifique-se de que define a variável de ambiente OPENAI_BASE_URL. Para mais informações, consulte o artigo 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 quer usar, por exemplo, deepseek-ai/deepseek-v3.1-maas.
ROLE: a função associada a uma mensagem. Pode especificar um user ou um assistant. A primeira mensagem tem de usar a função user. Os modelos funcionam com turnos alternados de user e assistant. Se a mensagem final usar a função assistant, o conteúdo da resposta continua imediatamente a partir do conteúdo dessa mensagem. Pode usar isto para restringir parte da resposta do modelo.
CONTENT: O conteúdo, como o texto, da mensagem user ou assistant.
MAX_OUTPUT_TOKENS: Número máximo de tokens que podem ser gerados na resposta. Um token tem aproximadamente quatro carateres. 100 tokens correspondem a aproximadamente 60 a 80 palavras.
Especifique um valor inferior para respostas mais curtas e um valor superior para respostas potencialmente mais longas.

REST

Depois de configurar o seu ambiente, pode usar a API REST para testar um comando de texto. O exemplo seguinte envia um pedido para o ponto final do modelo do publicador.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

LOCATION: Uma região que suporta modelos abertos.
MODEL: o nome do modelo que quer usar, por exemplo, deepseek-ai/deepseek-v2.
ROLE: a função associada a uma mensagem. Pode especificar um user ou um assistant. A primeira mensagem tem de usar a função user. Os modelos funcionam com turnos alternados de user e assistant. Se a mensagem final usar a função assistant, o conteúdo da resposta continua imediatamente a partir do conteúdo dessa mensagem. Pode usar isto para restringir parte da resposta do modelo.
CONTENT: O conteúdo, como o texto, da mensagem user ou assistant.
MAX_OUTPUT_TOKENS: Número máximo de tokens que podem ser gerados na resposta. Um token tem aproximadamente quatro carateres. 100 tokens correspondem a aproximadamente 60 a 80 palavras.
Especifique um valor inferior para respostas mais curtas e um valor superior para respostas potencialmente mais longas.
STREAM: um valor booleano que especifica se a resposta é transmitida ou não. Transmita a sua resposta para reduzir a perceção de latência do utilizador final. Defina como true para fazer streaming da resposta e false para devolver a resposta de uma só vez.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

Corpo JSON do pedido:

{
  "model": "MODEL",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_OUTPUT_TOKENS,
  "stream": false
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

PowerShell

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte.

Resposta

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "CONTENT",
        "role": "assistant"
      }
    }
  ],
  "created": 1234567890,
  "id": "2025-06-11|10:00:00.292195-07|9.7.144.202|-123456789",
  "model": "MODEL",
  "object": "chat.completion",
  "system_fingerprint": "",
  "usage": {
    "completion_tokens": 367,
    "prompt_tokens": 14,
    "total_tokens": 381
  }
}

Pontos finais regionais e globais

Para pontos finais regionais, os pedidos são processados a partir da região especificada. Nos casos em que tem requisitos de residência de dados ou se um modelo não suportar o ponto final global, use os pontos finais regionais.

Quando usa o ponto final global, a Google pode processar e responder aos seus pedidos a partir de qualquer região suportada pelo modelo que está a usar. Isto pode resultar numa latência mais elevada em alguns casos. O ponto final global ajuda a melhorar a disponibilidade geral e a reduzir os erros.

Não existe diferença de preço com os pontos finais regionais quando usa o ponto final global. No entanto, as quotas de pontos finais globais e as capacidades do modelo suportadas podem diferir dos pontos finais regionais. Para mais informações, consulte a página do modelo de terceiros relacionado.

Especifique o ponto final global

Para usar o ponto final global, defina a região como global.

Por exemplo, o URL de pedido de um comando curl usa o seguinte formato: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi

Para o SDK Vertex AI, um ponto final regional é a predefinição. Defina a região para GLOBAL para usar o ponto final global.

Restrinja a utilização do ponto final da API global

Para ajudar a aplicar a utilização de pontos finais regionais, use a restrição da política da organização constraints/gcp.restrictEndpointUsage para bloquear pedidos ao ponto final da API global. Para mais informações, consulte o artigo Restringir a utilização de pontos finais.

O que se segue?

Saiba como usar a chamada de funções.
Saiba mais sobre a saída estruturada.
Saiba mais sobre as previsões em lote.

Chame APIs MaaS para modelos abertos Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Faça uma chamada de streaming para um modelo aberto

Python

REST

curl

PowerShell

Resposta

Faça uma chamada sem streaming a um modelo aberto

Python

REST

curl

PowerShell

Resposta

Pontos finais regionais e globais

Especifique o ponto final global

Restrinja a utilização do ponto final da API global

O que se segue?

Chame APIs MaaS para modelos abertos