Como usar as bibliotecas da OpenAI com a plataforma de agentes do Gemini Enterprise

A API Chat Completions funciona como um endpoint compatível com a OpenAI, projetado para facilitar a interface com o Gemini na Gemini Enterprise Agent Platform usando as bibliotecas da OpenAI para Python e REST. Se você já estiver usando as bibliotecas da OpenAI, poderá usar essa API como uma maneira de baixo custo de alternar entre chamar modelos da OpenAI e modelos hospedados na Agent Platform para comparar resultados, custos e escalonabilidade, sem mudar o código atual. Se você ainda não usa as bibliotecas da OpenAI, recomendamos que você use o SDK de IA Generativa do Google. Para migrar o código do SDK da OpenAI para usar o SDK de IA Generativa do Google, consulte Migrar do SDK da OpenAI para o SDK de IA Generativa do Google.

Modelos compatíveis

A API Chat Completions oferece suporte a modelos do Gemini e a alguns modelos autoimplantados do Model Garden.

Modelos do Gemini

Os modelos a seguir oferecem suporte à API Chat Completions:

Clique para expandir os modelos compatíveis

Modelos autoimplantados do Model Garden

A interface de geração de texto Hugging Face (HF TGI) e os contêineres vLLM pré-criados do Model Garden do Agent Platform têm suporte à API Chat Completions. No entanto, nem todos os modelos implantados nesses contêineres são compatíveis com a API Chat Completions. A tabela a seguir inclui os modelos com suporte mais conhecidos por contêiner:

HF TGI

vLLM

Parâmetros aceitos

Para modelos do Google, a API Chat Completions é compatível com as seguintes APIs parâmetros. Para ver uma descrição de cada parâmetro, consulte a documentação da OpenAI sobre Como criar conclusões de chat. A compatibilidade com parâmetros para modelos de terceiros varia de acordo com o modelo. Para saber quais parâmetros são aceitos, consulte a documentação do modelo.

messages
  • System message
  • User message: os tipos text e image_url são aceitos. O tipo image_url oferece suporte a imagens armazenadas em um URI do Cloud Storage ou uma codificação Base64 no formato "data:<MIME-TYPE>;base64,<BASE64-ENCODED-BYTES>". Para saber como criar um bucket do Cloud Storage e fazer upload de um arquivo nele, consulte Descubra o armazenamento de objetos.
  • Assistant message
  • Tool message
  • Function message: o uso deste campo foi descontinuado, mas tem suporte para compatibilidade com versões anteriores.
model
detail Para modelos mais antigos que o Gemini 3, o campo detail precisa ser consistente em todas as mensagens e conteúdos (é no nível da solicitação). Para o Gemini 3 e versões mais recentes, isso corresponde a um `media_resolution` no nível da parte. Para mais informações, consulte Resolução de mídia.
max_completion_tokens Alias para max_tokens.
modalities Oferece suporte a audio, image e text.
max_tokens
n
frequency_penalty
presence_penalty
reasoning_effort Configura quanto tempo e quantos tokens são usados em uma resposta.
  • low: 1024
  • medium: 8192
  • high: 24576
Como nenhum pensamento está incluído na resposta, apenas um de reasoning_effort ou extra_body.google.thinking_config pode ser especificado.
response_format
  • json_object: interpretado como transmissão de "application/json" para a API Gemini.
  • json_schema. Esquemas totalmente recursivos não são aceitos. additional_properties é aceito.
  • text: interpretado como transmissão de "texto/simples" para a API Gemini.
  • Qualquer outro tipo MIME é passado no estado em que se encontra para o modelo, como passar "application/json" diretamente.
seed Corresponde a GenerationConfig.seed.
stop
stream
temperature
top_p
tools
  • type
  • function
    • name
    • description
    • parameters: especifique parâmetros usando a Especificação OpenAPI. Ela é diferente do campo de parâmetros da OpenAI, que é descrito como um objeto de esquema JSON. Para saber mais sobre as diferenças de palavras-chave entre os esquemas OpenAPI e JSON, consulte o Guia da OpenAPI.
tool_choice
  • none
  • auto
  • required: corresponde ao modo ANY no FunctionCallingConfig.
  • validated: Corresponde ao modo VALIDATED no FunctionCallingConfig. Isso é específico do Google.
web_search_options Corresponde à ferramenta GoogleSearch. Nenhuma subopção é aceita.
function_call Este campo está descontinuado, mas tem suporte para compatibilidade com versões anteriores.
functions Este campo está obsoleto, mas tem suporte para compatibilidade com versões anteriores.

Se você passar algum parâmetro não suportado, ele será ignorado.

Parâmetros de entrada multimodais

A API Chat Completions oferece suporte a entradas multimodais selecionadas.

input_audio
  • data: qualquer URI ou formato de blob válido. Oferecemos suporte a todos os tipos de blob, incluindo imagem, áudio e vídeo. Tudo o que é compatível com GenerateContent também é compatível (HTTP, Cloud Storage etc.).
  • format: a OpenAI oferece suporte a wav (audio/wav) e mp3 (audio/mp3). Usando o Gemini, todos os tipos MIME válidos são aceitos.
image_url
  • data: como input_audio, qualquer URI ou formato de blob válido é aceito.
    Observe que image_url como um URL terá como padrão o tipo MIME image/* e image_url como dados de blob pode ser usado como qualquer entrada multimodal.
  • detail: Semelhante a resolução de mídia, isso determina o número máximo de tokens por imagem para a solicitação. Observe que, embora o campo da OpenAI seja por imagem, o Gemini aplica o mesmo detalhe em toda a solicitação, e a transmissão de vários tipos de detalhes em uma solicitação vai gerar um erro.

Em geral, o parâmetro data pode ser um URI ou uma combinação de tipo MIME e bytes codificados em Base64 no formato "data:<MIME-TYPE>;base64,<BASE64-ENCODED-BYTES>". Para uma lista completa de tipos MIME, consulte GenerateContent. Para mais informações sobre a codificação Base64 da OpenAI, consulte a documentação.

Para uso, consulte nossos exemplos de entrada multimodal.

Parâmetros específicos do Gemini

Há vários recursos com suporte do Gemini que não estão disponíveis em modelos da OpenAI. Esses recursos ainda podem ser transmitidos como parâmetros, mas precisam estar contidos em um extra_content ou extra_body, caso contrário, serão ignorados.

Recursos extra_body

Inclua um campo google para conter todos os recursos extra_body específicos do Gemini.

{
  ...,
  "extra_body": {
     "google": {
       ...,
       // Add extra_body features here.
     }
   }
}
safety_settings Corresponde ao Gemini SafetySetting.
cached_content Corresponde ao campo generateContent.cached_content do Gemini.
thinking_config Corresponde ao Gemini GenerationConfig.ThinkingConfig.
thought_tag_marker Usado para separar os pensamentos de um modelo das respostas para modelos com o recurso de Raciocínio disponível.
Se não for especificado, nenhuma tag será retornada nos pensamentos do modelo. Se presente, as consultas subsequentes vão remover as tags de pensamento e marcar os pensamentos adequadamente para o contexto. Isso ajuda a preservar o contexto adequado para consultas subsequentes.
stream_function_call_arguments Transmite argumentos de chamada de função de volta como segmentos de JSON. Para mais informações, consulte Argumentos de chamada de função de streaming.
tools Especifique ferramentas semelhantes a `GenerateContent`. Para mais informações, consulte Tool.
media_resolution Especifique uma resolução de mídia no nível da solicitação semelhante a `GenerateContent`. Para mais informações, consulte MediaResolution.

Recursos extra_content

extra_content permite especificar conteúdo específico do Gemini que não deve ser ignorado.

Inclua um campo google para conter todos os recursos extra_content específicos do Gemini.

{
  ...,
  "extra_content": {
     "google": {
       ...,
       // Add extra_content features here.
     }
   }
}
thought Esse campo marca explicitamente se um campo é um pensamento e tem precedência sobre thought_tag_marker. Ele ajuda a distinguir entre diferentes etapas em um processo de pensamento, especialmente em cenários de uso de ferramentas em que as etapas intermediárias etapas podem ser confundidas com respostas finais. Ao marcar partes específicas da entrada como pensamentos, você pode orientar o modelo a tratá-las como raciocínio interno em vez de respostas voltadas ao usuário.
thought_signature Um campo de bytes que fornece uma assinatura de pensamento para validar os pensamentos retornados pelo modelo. Esse campo é diferente de thought, que é um campo booleano. Para mais informações, consulte Assinaturas de pensamento.
parts Específico para uma mensagem de ferramenta para transmitir partes de resposta de função multimodal de volta ao modelo. Para mais informações, consulte FunctionResponsePart e Resposta de função multimodal.

A seguir