Esta página mostra como formatar solicitações de API para o Gemini no Google Distributed Cloud (GDC) isolado por ar usando os detalhes do corpo da solicitação do endpoint Chat Completions da OpenAI. Ao seguir esse formato, você pode integrar facilmente os recursos avançados do Gemini aos seus aplicativos usando a estrutura da API do OpenAI.
A família de modelos do Gemini inclui modelos que funcionam com solicitações de comando multimodais. O termo multimodal indica que é possível usar mais de uma modalidade ou tipo de entrada em um comando. Para mais informações, consulte Criar comandos.
Para mais informações sobre as descrições genéricas dos tipos, métodos e campos gerados para a biblioteca gRPC, consulte a referência do gRPC do Gemini.
Antes de começar
Antes de formatar suas solicitações de API, verifique se você atende aos seguintes pré-requisitos:
- Saiba mais sobre os recursos do Gemini no GDC.
- Comece a usar os requisitos mínimos do projeto para fazer solicitações de API para o Gemini.
- Identifique o ID do endpoint do modelo do Gemini que você quer usar nas suas solicitações. Ao selecionar um modelo específico, você pode usar os recursos exclusivos dele para suas tarefas. Consulte os modelos do Gemini disponíveis no GDC.
- Entender como elaborar comandos com cuidado para receber as respostas esperadas do Gemini. Teste diferentes estilos e formatos de comandos para otimizar a saída. Para mais informações, consulte Introdução aos comandos.
- Conheça os vários parâmetros disponíveis no endpoint OpenAI Chat Completions
para controlar o comportamento do Gemini. Ajuste parâmetros como
temperature,max_completion_tokensetop_ppara controlar a criatividade, o comprimento e a diversidade do texto gerado. Para mais informações, consulte Testar parâmetros.
Sintaxe da solicitação
Os exemplos a seguir contêm a sintaxe que você precisa usar nas solicitações de API para gerar uma resposta do modelo:
Python
import openai
client = openai.OpenAI()
model_response = client.chat.completions.create(
model = "MODEL_ID",
messages = [
{
...
}
]
...
)
print(model_response)
curl
curl \
-X POST "https://ENDPOINT:443/v1/projects/PROJECT/locations/PROJECT/chat/completions" \
-H "Content-Type: application/json; charset=utf-8" \
-H "Authorization: Bearer $(gdcloud auth print-identity-token)" \
-d '{
"model_id": "MODEL_ID",
"messages" = [
{
...
}
]
...
}'
Parâmetros da API
Esta seção contém uma lista dos parâmetros mais importantes que podem ser definidos no corpo da solicitação das suas solicitações de API para o Gemini no GDC e no corpo da resposta que o modelo precisa retornar. Para conferir a referência completa da API do endpoint "Chat Completions" da OpenAI, acesse https://platform.openai.com/docs/api-reference/chat.
Corpo da solicitação
{
"messages" = [
{
"role": string,
"content": [
{
"type": "image_url",
"image_url": {
"url": string
}
},
{
"type": "input_audio",
"input_audio": {
"data": string,
"format": string
}
},
{
"type": "audio_url",
"audio_url": {
"url": string
}
},
{
"type": "input_video",
"input_video": {
"data": string,
"format": string
}
},
{
"type": "video_url",
"video_url": {
"url": string
}
},
{
"type": "input_document",
"input_document": {
"data": string,
"format": string
}
},
{
"type": "document_url",
"document_url": {
"url": string
}
}
]
}
],
"temperature": number,
"max_completion_tokens": integer,
"top_p": number,
"n": integer,
"stop": string,
"user": string
}
A tabela a seguir descreve os principais campos e as descrições no corpo da solicitação para o endpoint OpenAI Chat Completions quando usado com o Gemini:
| Parâmetros | ||
|---|---|---|
| Nome do campo | Descrição | |
|
Obrigatório: O modelo do Gemini a ser usado. Para mais informações, consulte os modelos do Gemini disponíveis. |
|
|
Obrigatório: Uma lista de mensagens que compõem a conversa atual com o modelo. Cada mensagem tem um Diferentes tipos de mensagens (modalidades) são aceitos, como texto, imagens, áudio, vídeos e documentos. |
|
|
Obrigatório: A função do autor da mensagem, que pode ser uma das seguintes:
|
|
|
Obrigatório: O conteúdo da mensagem do sistema, do usuário ou do assistente. O valor é uma única instância para consultas de turno único. Para consultas com várias interações, |
|
|
Opcional: A aleatoriedade do texto gerado. Valores mais baixos (mais próximos de O valor padrão é |
|
|
Opcional: O número máximo de tokens a serem gerados na resposta, incluindo tokens de saída visíveis e de raciocínio. |
|
|
Opcional: A probabilidade de amostragem de núcleo. Valores mais altos (mais próximos de O valor padrão é |
|
|
Opcional: O número de conclusões a serem geradas para cada comando. O valor padrão é |
|
|
Opcional: Uma lista de strings que, quando encontradas, interrompem o processo de geração de texto. O valor padrão é |
|
|
Opcional: Um identificador exclusivo do usuário final. Com ele, é possível acompanhar padrões de uso e personalizar respostas. |
|
content
Esse campo é o tipo de dados estruturados de base que contém o conteúdo de várias partes de uma mensagem.
Se a entrada for um comando de texto, o valor desse campo será uma string. No entanto, para comandos multimodais, esse campo consiste em uma matriz que contém duas propriedades principais em cada objeto: type e INPUT. A propriedade type indica o tipo de conteúdo da entrada multimodal, enquanto a propriedade INPUT contém o elemento de entrada, representado como dados codificados em base64 ou um URL de um bucket de armazenamento do GDC.
A tabela a seguir descreve os principais campos content e as descrições deles para comandos multimodais:
| Nome do campo | Descrição | |
|---|---|---|
|
Obrigatório: O tipo de conteúdo para comandos multimodais. Os valores aceitáveis são os seguintes:
|
|
|
Obrigatório: A entrada de conteúdo para comandos multimodais. O nome do campo precisa ser igual ao valor especificado no campo Portanto, o nome do campo é um dos seguintes:
Cada campo de entrada tem um |
|
|
Opcional: Se o conteúdo de entrada for fornecido como um URL, o caminho para o arquivo em um bucket de armazenamento do GDC. No caso de imagens, esse campo pode conter dados codificados em base64 em vez de um URL. |
|
|
Opcional: Se o conteúdo de entrada for fornecido como dados codificados em base64, os dados binários serão convertidos em uma string de caracteres. No caso de imagens, os dados codificados em base64 são fornecidos no campo |
|
|
Opcional: Se o conteúdo de entrada for fornecido no campo Dependendo dos dados de entrada, diferentes formatos são aceitos. Para mais informações, consulte tipos MIME para imagens, áudio, vídeos e documentos. |
|
Corpo da resposta
{
"id": string,
"object": string,
"created": integer,
"model": string,
"choices": [
{
"index": integer,
"message": {
"role": string,
"content": string,
"refusal": null
},
"logprobs": null,
"finish_reason": string
}
],
"usage": {
"completion_tokens": integer,
"prompt_tokens": integer,
"total_tokens": integer
},
"system_fingerprint": string
}
A tabela a seguir descreve os principais campos e as descrições deles no corpo da resposta retornada pelo modelo com base na entrada fornecida:
| Nome do campo | Descrição | |
|---|---|---|
|
Um identificador exclusivo do texto gerado. |
|
|
O tipo de objeto, que é sempre |
|
|
O carimbo de data/hora em segundos de quando o texto é gerado. |
|
|
O modelo usado para gerar o texto. |
|
|
Uma lista de opções de geração de texto. Esse campo pode conter várias opções se |
|
|
O índice da opção na lista de opções. |
|
|
Uma mensagem de geração de texto criada pelo modelo. Esse campo contém as seguintes propriedades:
|
|
|
Informações de probabilidade de registro para a escolha. |
|
|
O motivo pelo qual o modelo parou de gerar tokens. O valor é um dos seguintes:
|
|
|
Estatísticas de uso da solicitação. |
|
|
Número de tokens no texto gerado. |
|
|
Número de tokens no comando. |
|
|
Número total de tokens no comando e no texto gerado. |
|
|
A configuração de back-end que o modelo usa para ser executado. |
|
Exemplos
Esta seção contém um exemplo do corpo da solicitação e da resposta de geração de texto que o modelo precisa retornar.
Exemplo de solicitação
O exemplo a seguir mostra os detalhes de um corpo de solicitação que envia um comando ao Gemini para gerar texto. O exemplo contém controles de temperatura e de número máximo de tokens. Para detalhes da implementação, consulte Enviar um comando de texto ou Enviar um comando multimodal.
{
"messages": [
{
"role": "system",
"content": "You are a helpful and informative assistant."
},
{
"role": "user",
"content": "What is the capital of France?"
}
],
"temperature": 0.7,
"max_completion_tokens": 100
}
Exemplo de resposta
O exemplo a seguir mostra os detalhes de uma resposta de geração de texto retornada pelo modelo:
{
"id": "",
"object": "",
"created": 0,
"model": "",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The capital of France is Paris.\n",
"refusal": null
},
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"completion_tokens": 7,
"prompt_tokens": 8,
"total_tokens": 15
},
"system_fingerprint": ""
}