Chamar APIs do MaaS para modelos abertos

Muitos modelos abertos na Vertex AI oferecem modelos totalmente gerenciados e sem servidor como APIs usando a API Chat Completions da Vertex AI. Para esses modelos, não é necessário provisionar nem gerenciar 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 OpenAI Chat Completions. Para considerações específicas do Llama, consulte Solicitar previsões do Llama.

Antes de começar

Para usar modelos abertos com a Vertex AI, faça o etapas a seguir. A API Vertex AI (aiplatform.googleapis.com) precisa estar ativada para usar a Vertex AI. Se você já tiver um projeto existente com a API do Vertex AI ativada, poderá usar esse projeto em vez de criar um novo.

  1. 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.

  2. 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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

  5. 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

  6. Verify that billing is enabled for your Google Cloud project.

  7. 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

    8.
  8. Acesse o card do modelo que você quer usar no Model Garden e clique em Ativar para habilitar o uso no seu projeto.

    Acessar o Model Garden

    9. 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 esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

    Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

    Antes de executar esta amostra, 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, deepseek-ai/deepseek-v3.1-maas.
    • ROLE: o papel associado a uma mensagem. É possível especificar user ou assistant. A primeira mensagem precisa usar o papel user. Os modelos funcionam com voltas alternadas de user e assistant. Se a mensagem final usar o papel assistant, 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 user ou assistant.
    • 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 configurou seu ambiente use REST para testar uma solicitação de texto. O exemplo a seguir envia uma solicitação ao publisher endpoint do modelo.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • LOCATION: uma região compatível com modelos abertos.
    • MODEL: o nome do modelo que você quer usar, por exemplo, deepseek-ai/deepseek-v2.
    • ROLE: o papel associado a uma mensagem. É possível especificar user ou assistant. A primeira mensagem precisa usar o papel user. Os modelos funcionam com voltas alternadas de user e assistant. Se a mensagem final usar o papel assistant, 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 user ou assistant.
    • 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 true para transmitir a resposta e false para retornar 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 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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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 esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

    Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

    Antes de executar esta amostra, 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, deepseek-ai/deepseek-v3.1-maas.
    • ROLE: o papel associado a uma mensagem. É possível especificar user ou assistant. A primeira mensagem precisa usar o papel user. Os modelos funcionam com voltas alternadas de user e assistant. Se a mensagem final usar o papel assistant, 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 user ou assistant.
    • 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 configurou seu ambiente use REST para testar uma solicitação de texto. O exemplo a seguir envia uma solicitação ao publisher endpoint do modelo.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • LOCATION: uma região compatível com modelos abertos.
    • MODEL: o nome do modelo que você quer usar, por exemplo, deepseek-ai/deepseek-v2.
    • ROLE: o papel associado a uma mensagem. É possível especificar user ou assistant. A primeira mensagem precisa usar o papel user. Os modelos funcionam com voltas alternadas de user e assistant. Se a mensagem final usar o papel assistant, 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 user ou assistant.
    • 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 true para transmitir a resposta e false para retornar 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 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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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. Em casos em que você tem requisitos de residência de dados ou se um modelo não oferece suporte ao endpoint global, use os endpoints regionais.

    Ao usar o endpoint global, o Google pode processar e atender 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 reduzir erros.

    Não há diferença de preço com os endpoints regionais ao usar o endpoint global. No entanto, as cotas de endpoint global e os recursos do modelo compatível podem ser diferentes dos endpoints regionais. Para mais informações, consulte a página do modelo de terceiros relacionada.

    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 Vertex AI, 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 na aplicação do uso de endpoints regionais, utilize a restrição de política da organização constraints/gcp.restrictEndpointUsage para bloquear solicitações ao endpoint da API global. Para mais informações, consulte Restringir o uso de endpoints.

    A seguir