Receba descrições de imagens através de legendas visuais

Aviso: a partir de 24 de junho de 2025, as versões 1 e 2 do Imagen vão ser descontinuadas. Os modelos Imagen imagegeneration@002, imagegeneration@005 e imagegeneration@006 vão ser removidos a 24 de setembro de 2025 . Para mais informações sobre a migração para o Imagen 3, consulte o artigo Migre para o Imagen 3.

Nota: a API Gemini pode gerar descrições com base em várias entradas de imagens, enquanto o Imagen pode processar uma imagem em cada entrada.

As legendas visuais permitem-lhe gerar uma descrição relevante para uma imagem. Pode usar estas informações para várias finalidades:

• Obter metadados mais detalhados sobre imagens para armazenamento e pesquisa.
• Gerar legendas automáticas para suportar exemplos de utilização de acessibilidade.
• Receba descrições rápidas de produtos e recursos visuais.

Origem da imagem: Santhosh Kumar no Unsplash (recortada)

Legenda (formato curto): uma camisa azul com bolas brancas está pendurada num gancho

Idiomas suportados

As legendas visuais estão disponíveis nos seguintes idiomas:

• Inglês (en)
• Francês (fr)
• Alemão (de)
• Italiano (it)
• Espanhol (es)

Desempenho e limitações

Os seguintes limites aplicam-se quando usa este modelo:

Limites	Valor
Número máximo de pedidos de API (curtos) por minuto por projeto	500
Número máximo de tokens devolvidos na resposta (formato curto)	64 tokens
Número máximo de tokens aceites no pedido (apenas para formato curto de VQA)	80 tokens

As seguintes estimativas de latência do serviço aplicam-se quando usa este modelo. Estes valores destinam-se a ser ilustrativos e não são uma promessa de serviço:

Latência	Valor
Pedidos de API (formato curto)	1,5 segundos

Localizações

Uma localização é uma região que pode especificar num pedido para controlar onde os dados são armazenados em repouso. Para ver uma lista das regiões disponíveis, consulte o artigo IA generativa nas localizações da Vertex AI.

Filtragem de segurança da IA responsável

O modelo de legendagem de imagens e de resposta visual a perguntas (VQA) não suporta filtros de segurança configuráveis pelo utilizador. No entanto, a filtragem de segurança geral do Imagen ocorre nos seguintes dados:

• Introdução do utilizador
• Saída do modelo

Como resultado, a sua saída pode diferir da saída de amostra se o Imagen aplicar estes filtros de segurança. Considere os seguintes exemplos.

Entrada filtrada

Se a entrada for filtrada, a resposta é semelhante à seguinte:

{
  "error": {
    "code": 400,
    "message": "Media reasoning failed with the following error: The response is blocked, as it may violate our policies. If you believe this is an error, please send feedback to your account team. Error Code: 63429089, 72817394",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.DebugInfo",
        "detail": "[ORIGINAL ERROR] generic::invalid_argument: Media reasoning failed with the following error: The response is blocked, as it may violate our policies. If you believe this is an error, please send feedback to your account team. Error Code: 63429089, 72817394 [google.rpc.error_details_ext] { message: \"Media reasoning failed with the following error: The response is blocked, as it may violate our policies. If you believe this is an error, please send feedback to your account team. Error Code: 63429089, 72817394\" }"
      }
    ]
  }
}

Resultados filtrados

Se o número de respostas devolvidas for inferior à contagem de amostras especificada, significa que as respostas em falta são filtradas pela IA responsável. Por exemplo, o seguinte é uma resposta a um pedido com "sampleCount": 2, mas uma das respostas é filtrada:

{
  "predictions": [
    "cappuccino"
  ]
}

Se toda a saída for filtrada, a resposta é um objeto vazio semelhante ao seguinte:

{}

Obtenha legendas de imagens de formato curto

Use os seguintes exemplos para gerar legendas curtas para uma imagem.

REST

Para mais informações sobre os pedidos de modelos imagetext, consulte a imagetext referência da API de modelos.

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

• PROJECT_ID: o seu Google Cloud ID do projeto.
• LOCATION: a região do seu projeto. Por exemplo, us-central1, europe-west2 ou asia-northeast3. Para ver uma lista das regiões disponíveis, consulte Localizações da IA generativa na Vertex AI.
• B64_IMAGE: a imagem para gerar legendas. A imagem tem de ser especificada como uma string de bytes codificada em base64. Limite de tamanho: 10 MB.
• RESPONSE_COUNT: o número de legendas de imagens que quer gerar. Valores inteiros aceites: 1 a 3.
• LANGUAGE_CODE: um dos códigos de idioma suportados. Idiomas compatíveis:
  • Inglês (en)
  • Francês (fr)
  • Alemão (de)
  • Italiano (it)
  • Espanhol (es)

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/imagetext:predict

Corpo JSON do pedido:

{
  "instances": [
    {
      "image": {
          "bytesBase64Encoded": "B64_IMAGE"
      }
    }
  ],
  "parameters": {
    "sampleCount": RESPONSE_COUNT,
    "language": "LANGUAGE_CODE"
  }
}

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/publishers/google/models/imagetext:predict"

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/publishers/google/models/imagetext:predict" | Select-Object -Expand Content

As seguintes respostas de exemplo destinam-se a um pedido com "sampleCount": 2. A resposta devolve duas strings de previsão.

Inglês (en):

{
  "predictions": [
    "a yellow mug with a sheep on it sits next to a slice of cake",
    "a cup of coffee with a heart shaped latte art next to a slice of cake"
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID",
  "model": "projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID",
  "modelDisplayName": "MODEL_DISPLAYNAME",
  "modelVersionId": "1"
}

Espanhol (es):

{
  "predictions": [
    "una taza de café junto a un plato de pastel de chocolate",
    "una taza de café con una forma de corazón en la espuma"
  ]
}

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.

Neste exemplo, usa o método load_from_file para referenciar um ficheiro local como a base Image para obter uma legenda. Depois de especificar a imagem base, usa o método get_captions no ImageTextModel e imprime o resultado.

import vertexai
from vertexai.preview.vision_models import Image, ImageTextModel

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# input_file = "input-image.png"

vertexai.init(project=PROJECT_ID, location="us-central1")

model = ImageTextModel.from_pretrained("imagetext@001")
source_img = Image.load_from_file(location=input_file)

captions = model.get_captions(
    image=source_img,
    # Optional parameters
    language="en",
    number_of_results=2,
)

print(captions)
# Example response:
# ['a cat with green eyes looks up at the sky']

Node.js

Antes de experimentar este exemplo, siga as Node.jsinstruçõ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 Node.js 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.

Neste exemplo, chama o método predict num PredictionServiceClient. O serviço devolve legendas para a imagem fornecida.

/**
 * TODO(developer): Update these variables before running the sample.
 */
const projectId = process.env.CAIP_PROJECT_ID;
const location = 'us-central1';
const inputFile = 'resources/cat.png';

const aiplatform = require('@google-cloud/aiplatform');

// Imports the Google Cloud Prediction Service Client library
const {PredictionServiceClient} = aiplatform.v1;

// Import the helper module for converting arbitrary protobuf.Value objects
const {helpers} = aiplatform;

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: `${location}-aiplatform.googleapis.com`,
};

// Instantiates a client
const predictionServiceClient = new PredictionServiceClient(clientOptions);

async function getShortFormImageCaptions() {
  const fs = require('fs');
  // Configure the parent resource
  const endpoint = `projects/${projectId}/locations/${location}/publishers/google/models/imagetext@001`;

  const imageFile = fs.readFileSync(inputFile);
  // Convert the image data to a Buffer and base64 encode it.
  const encodedImage = Buffer.from(imageFile).toString('base64');

  const instance = {
    image: {
      bytesBase64Encoded: encodedImage,
    },
  };
  const instanceValue = helpers.toValue(instance);
  const instances = [instanceValue];

  const parameter = {
    // Optional parameters
    language: 'en',
    sampleCount: 2,
  };
  const parameters = helpers.toValue(parameter);

  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);
  const predictions = response.predictions;
  if (predictions.length === 0) {
    console.log(
      'No captions were generated. Check the request parameters and image.'
    );
  } else {
    predictions.forEach(prediction => {
      console.log(prediction.stringValue);
    });
  }
}
await getShortFormImageCaptions();

Use parâmetros para a geração de legendas de imagens

Quando recebe legendas de imagens, existem vários parâmetros que pode definir consoante o seu exemplo de utilização.

Número de resultados

Use o parâmetro de número de resultados para limitar a quantidade de legendas devolvidas para cada pedido que enviar. Para mais informações, consulte a imagetext referência da API do modelo (legendas de imagens).

Número aleatório

Um número que adiciona a um pedido para tornar as descrições geradas determinísticas. Adicionar um número de semente ao seu pedido é uma forma de garantir que recebe a mesma previsão (descrições) todas as vezes. No entanto, as legendas das imagens não são necessariamente devolvidas pela mesma ordem. Para mais informações, consulte a imagetext referência da API do modelo (legendas de imagens).

O que se segue?

Leia artigos sobre o Imagen e outros produtos de IA generativa na Vertex AI:

• Um guia do programador para começar a usar o Imagen 3 na Vertex AI
• Novos modelos e ferramentas de multimédia generativa, criados com e para criadores
• Novidades no Gemini: Gems personalizados e geração de imagens melhorada com o Imagen 3
• Google DeepMind: Imagen 3 – O nosso modelo de conversão de texto em imagem de mais alta qualidade