É possível garantir que a saída gerada de um modelo sempre siga um esquema específico para receber respostas com formatação consistente. Por exemplo, você pode ter um esquema de dados estabelecido que é usado para outras tarefas. Se você seguir o mesmo esquema, é possível extrair dados diretamente da saída do modelo sem nenhum pós-processamento.
Para especificar a estrutura da saída de um modelo, defina um esquema de resposta, que funciona como modelo de respostas. Quando você envia um comando e inclui um esquema de resposta, a resposta do modelo sempre seguirá seu esquema.
Só é possível usar o Gemini 1.5 Pro para controlar as saídas geradas.
Exemplos de casos de uso
Um caso de uso para aplicar um esquema de resposta é garantir a resposta de um modelo que gera um JSON válido e está em conformidade com o esquema. As saídas do modelo generativas podem ter certo grau de variabilidade, portanto, incluir um esquema de resposta garante que você sempre recebem um JSON válido. Consequentemente, as tarefas downstream podem gerar uma entrada JSON válida das respostas geradas.
Outro exemplo é restringir a forma como um modelo pode responder. Por exemplo, é possível
fazer com que um modelo anote texto com rótulos definidos pelo usuário, não com rótulos
que o modelo produz. Essa restrição é útil quando você espera um conjunto específico de
rótulos como positive
ou negative
e não quer receber uma mistura de
outros rótulos que o modelo possa gerar, como good
, positive
, negative
ou bad
.
Considerações
As considerações a seguir trazem possíveis limitações se você planeja usar um esquema de resposta:
- É necessário usar a API para definir e utilizar um esquema de resposta. Não há console compatível.
- O tamanho do esquema de resposta é contabilizado no limite de tokens de entrada.
- Somente alguns formatos de saída são compatíveis, como
application/json
outext/x.enum
. Para mais informações, consulte o parâmetroresponseMimeType
na referência da API Gemini. A geração controlada oferece suporte aos seguintes campos do esquema, que são um subconjunto de campos compatíveis com a Vertex AI:
enum
items
maxItems
nullable
properties
required
Se você usa um campo sem suporte, a Vertex AI ainda pode lidar com sua solicitação, mas ignora o campo. Para conferir os detalhes de cada campo, consulte a Referência de esquema da Vertex AI.
Antes de começar
Defina um esquema de resposta para especificar a estrutura da saída de um modelo, os nomes dos campos e o tipo de dados esperado para cada campo. Use apenas os campos compatíveis conforme listado na seção Considerações. Todos os outros campos serão ignorados;
Para esquemas de amostra, consulte a seção Exemplos de esquemas e respostas de modelo.
Comportamento do modelo e esquema de resposta
Quando um modelo gera uma resposta, ele usa o nome do campo e o contexto do seu comando. Por isso, recomendamos que você use uma estrutura clara e sem nomes de campos ambíguos para que sua intent fique clara.
Por padrão, os campos são opcionais. Isso significa que o modelo pode preencher ou pular os campos. É possível definir campos conforme necessário para forçar o modelo a fornecer um valor. Se não houver contexto suficiente no comando de entrada associado, o modelo gera respostas principalmente com base nos dados em que foi treinado.
Se você não está vendo os resultados esperados, inclua mais contexto aos comandos de entrada ou revise seu esquema de resposta. Por exemplo, revise o modelo de resposta sem geração controlada para ver como o modelo responde. Depois, você pode atualizar o esquema de resposta que melhor se ajuste à saída do modelo.
Enviar um comando com um esquema de resposta
Por padrão, todos os campos são opcionais, o que significa que um modelo pode gerar uma resposta em um campo. Para forçar o modelo a sempre gerar uma resposta para um campo, defina o campo conforme necessário.
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.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- GENERATE_RESPONSE_METHOD: o tipo de resposta que você quer que o modelo gere.
Escolha um método que gere como você quer que a resposta do modelo seja retornada:
streamGenerateContent
: a resposta é transmitida conforme é gerada para reduzir a percepção de latência para o público humano.generateContent
: a resposta será retornada depois de ser totalmente gerada.
- LOCATION: a região para processar a solicitação.
- PROJECT_ID: o ID do projeto.
- MODEL_ID: o ID do modelo multimodal
que você quer usar. As opções são:
gemini-1.5-pro
- ROLE:
O papel em uma conversa associada ao conteúdo. É necessário especificar um papel mesmo em
casos de uso de turno único.
Os valores aceitáveis são os seguintes:
USER
: especifica o conteúdo que é enviado por você.
- TEXT: as instruções de texto a serem incluídas no comando.
- RESPONSE_MIME_TYPE: o tipo de formato do
texto candidato gerado. Para uma lista de valores aceitos, consulte o parâmetro
responseMimeType
na API Gemini. - RESPONSE_SCHEMA: esquema do modelo que deve ser seguido ao gerar respostas. Para mais informações, consulte a referência Esquema.
Método HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD
Corpo JSON da solicitação:
{ "contents": { "role": "ROLE", "parts": { "text": "TEXT" } }, "generation_config": { "responseMimeType": "RESPONSE_MIME_TYPE", "responseSchema": RESPONSE_SCHEMA, } }
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 a seguir:
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/MODEL_ID:GENERATE_RESPONSE_METHOD"
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/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content
Você receberá uma resposta JSON semelhante a seguinte.
Exemplo de comando curl
LOCATION="us-central1"
MODEL_ID="gemini-1.0-pro"
PROJECT_ID="test-project"
GENERATE_RESPONSE_METHOD="generateContent"
cat << EOF > request.json
{
"contents": {
"role": "user",
"parts": {
"text": "List a few popular cookie recipes."
}
},
"generation_config": {
"maxOutputTokens": 2048,
"responseMimeType": "application/json",
"responseSchema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recipe_name": {
"type": "string",
},
},
"required": ["recipe_name"],
},
}
}
}
EOF
curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:${GENERATE_RESPONSE_METHOD} -d \
-d `@request.json`
Exemplos de esquemas e respostas de modelo
As seções a seguir mostram uma variedade de exemplos de comandos e esquemas de respostas. Uma resposta de modelo de amostra também é incluída após cada exemplo de código.
- Resumir as análises de avaliações em uma lista aninhada
- Prever o clima para cada dia da semana em uma matriz
- Classificar um produto com um tipo enumerado bem definido
- Identificar objetos em imagens
- Responder com um único valor de tipo enumerado de texto simples
Resumir as análises das avaliações
O exemplo a seguir gera como saída uma matriz de objetos, na qual cada objeto tem duas propriedades: a classificação e o nome de um sabor de sorvete.
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.
Exemplo de resposta do modelo
candidates { content { role: "model" parts { text: "[\n [\n {\n \"rating\": 4\n },\n {\n \"flavor\": \"Strawberry Cheesecake\"\n },\n {\n \"rating\": 1\n },\n {\n \"flavor\": \"Mango Tango\"\n }\n ]\n] " } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.1139734759926796 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.10070161521434784 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: NEGLIGIBLE probability_score: 0.13695430755615234 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.12241825461387634 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.11676400154829025 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.05310790613293648 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.10521054267883301 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.08299414813518524 } } usage_metadata { prompt_token_count: 61 candidates_token_count: 66 total_token_count: 127 }
Estimar a previsão do tempo de cada dia da semana
O exemplo a seguir gera um objeto forecast
para cada dia
da semana que inclui uma matriz de propriedades, como a data
e os níveis de temperatura e umidade esperados. Algumas propriedades estão definidas como anuláveis.
Assim, o modelo pode retornar um valor nulo quando não tiver contexto suficiente para
gerar uma resposta significativa. Essa estratégia ajuda a reduzir alucinações.
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.
Exemplo de resposta do modelo
candidates { content { role: "model" parts { text: "{\"forecast\": [{\"Day\": \"Sunday\", \"Forecast\": \"sunny\", \"Humidity\": \"50%\", \"Temperature\": 77, \"Wind Speed\": 10}, {\"Day\": \"Monday\", \"Forecast\": \"partly cloudy\", \"Humidity\": null, \"Temperature\": 72, \"Wind Speed\": 15}, {\"Day\": \"Tuesday\", \"Forecast\": \"rain showers\", \"Humidity\": \"70%\", \"Temperature\": 64, \"Wind Speed\": null}, {\"Day\": \"Wednesday\", \"Forecast\": \"thunderstorms\", \"Humidity\": null, \"Temperature\": 68, \"Wind Speed\": null}, {\"Day\": \"Thursday\", \"Forecast\": \"cloudy\", \"Humidity\": \"60%\", \"Temperature\": 66, \"Wind Speed\": null}, {\"Day\": \"Friday\", \"Forecast\": \"partly cloudy\", \"Humidity\": null, \"Temperature\": 73, \"Wind Speed\": 12}, {\"Day\": \"Saturday\", \"Forecast\": \"sunny\", \"Humidity\": \"40%\", \"Temperature\": 80, \"Wind Speed\": 8}]}" } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.1037486344575882 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.09670579433441162 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: NEGLIGIBLE probability_score: 0.18126320838928223 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.10052486509084702 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.15960998833179474 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.09518112242221832 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.1388116478919983 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.10539454221725464 } } usage_metadata { prompt_token_count: 280 candidates_token_count: 249 total_token_count: 529 }
Classificar um produto
O exemplo a seguir inclui tipos enumerados em que o modelo precisa classificar o tipo e a condição de um objeto em uma lista de valores fornecidos.
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.
Exemplo de resposta do modelo
candidates { content { role: "model" parts { text: " [{\n \"item_category\": \"winter apparel\",\n \"subcategory\": \"coat\",\n \"to_discard\": 1\n }] " } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.08945459872484207 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.13753245770931244 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: NEGLIGIBLE probability_score: 0.19208428263664246 severity: HARM_SEVERITY_LOW severity_score: 0.23810701072216034 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.07585817575454712 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.04336579889059067 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.12667709589004517 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.07396338135004044 } } usage_metadata { prompt_token_count: 38 candidates_token_count: 33 total_token_count: 71 }
Identificar objetos em imagens
O exemplo a seguir identifica objetos de duas imagens que são armazenadas no Cloud Storage.
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.
Exemplo de resposta do modelo
candidates { content { role: "model" parts { text: "[\n [\n {\n \"object\": \"globe model\"\n },\n {\n \"object\": \"tablet computer\"\n },\n {\n \"object\": \"shopping cart\"\n },\n {\n \"object\": \"Eiffel Tower model\"\n },\n {\n \"object\": \"airplane model\"\n },\n {\n \"object\": \"coffee cup\"\n },\n {\n \"object\": \"computer keyboard\"\n },\n {\n \"object\": \"computer mouse\"\n },\n {\n \"object\": \"passport\"\n },\n {\n \"object\": \"sunglasses\"\n },\n {\n \"object\": \"US Dollar bills\"\n },\n {\n \"object\": \"notepad\"\n },\n {\n \"object\": \"pen\"\n }\n ],\n [\n {\n \"object\": \"watering can\"\n },\n {\n \"object\": \"oregano\"\n },\n {\n \"object\": \"flower pot\"\n },\n {\n \"object\": \"flower pot\"\n },\n {\n \"object\": \"gardening gloves\"\n },\n {\n \"object\": \"hand rake\"\n },\n {\n \"object\": \"hand trowel\"\n },\n {\n \"object\": \"grass\"\n }\n ]\n] " } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.1872812658548355 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.16357900202274323 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: LOW probability_score: 0.37920594215393066 severity: HARM_SEVERITY_LOW severity_score: 0.29320207238197327 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.14175598323345184 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.12074951827526093 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.12241825461387634 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.0955180674791336 } } usage_metadata { prompt_token_count: 525 candidates_token_count: 333 total_token_count: 858 }
Responder com um único valor de tipo enumerado de texto simples
O exemplo a seguir identifica o gênero de um filme com base na descrição dele. A saída é um valor de tipo enumerado de texto simples que o modelo seleciona de uma lista de valores definidos no esquema de resposta.
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.
Exemplo de resposta do modelo
candidates { content { role: "model" parts { text: "documentary" } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.051025390625 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.08056640625 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: NEGLIGIBLE probability_score: 0.1416015625 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.068359375 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.11572265625 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.0439453125 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.099609375 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.146484375 } avg_logprobs: -8.783838711678982e-05 } usage_metadata { prompt_token_count: 33 candidates_token_count: 2 total_token_count: 35 }