Como usar as bibliotecas da OpenAI com a Vertex AI

Este documento mostra como usar a API Chat Completions compatível com a OpenAI para interagir com os modelos da Vertex AI. Neste documento, discutimos os seguintes tópicos:

A API Chat Completions é um endpoint compatível com a OpenAI que permite usar as bibliotecas Python e REST da OpenAI para interagir com o Gemini na Vertex AI. Se você já usa as bibliotecas OpenAI, essa API oferece uma maneira de alternar entre modelos OpenAI e modelos hospedados da Vertex AI para comparar resultados, custos e escalonabilidade com mudanças mínimas no código atual. Se você não usa as bibliotecas OpenAI, recomendamos usar o SDK da 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

A API Chat Completions é compatível com os seguintes modelos do Gemini:

Modelos autoimplantados do Model Garden

Os contêineres Hugging Face Text Generation Interface (HF TGI) e vLLM pré-criado do Model Garden da Vertex AI são compatíveis com a 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. A opção detail não é compatível.
  • Assistant message
  • Tool message
  • Function message: o uso deste campo foi descontinuado, mas tem suporte para compatibilidade com versões anteriores.
model
max_completion_tokens Alias de max_tokens.
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 não há pensamentos incluídos 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 compatíveis. additional_properties é compatível.
  • 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 é compatível.
function_call Este campo está obsoleto, 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 multimodal

A API Chat Completions oferece suporte a algumas entradas multimodais.

input_audio
  • data: Qualquer URI ou formato de blob válido. Aceitamos todos os tipos de blob, incluindo imagem, áudio e vídeo. Qualquer coisa compatível com GenerateContent (HTTP, Cloud Storage etc.).
  • format: A OpenAI é compatível com wav (audio/wav) e mp3 (audio/mp3). Com o Gemini, todos os tipos MIME válidos são aceitos.
image_url
  • data: Assim como input_audio, qualquer URI ou formato blob válido é compatível.
    Observe que image_url como um URL vai usar por padrão o tipo MIME image/* e image_url como dados de blob pode ser usado como qualquer entrada multimodal.
  • detail: Semelhante à resolução de mídia, esse parâmetro determina o número máximo de tokens por imagem para a solicitação. O campo da OpenAI é por imagem, mas o Gemini aplica o mesmo nível de detalhe em toda a solicitação. Se você transmitir vários tipos de detalhes em uma solicitação, vai ocorrer 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 ver uma lista completa de tipos MIME, consulte GenerateContent. Para mais informações sobre a codificação base64 da OpenAI, consulte a documentação deles.

Para saber como usar, consulte nossos exemplos de entrada multimodal.

Parâmetros específicos do Gemini

Para usar recursos compatíveis com o Gemini, mas não com os modelos da OpenAI, transmita-os como parâmetros em um campo extra_content ou extra_body. Se você transmitir esses recursos fora desses campos, eles serão ignorados.

extra_body recursos

Para usar recursos específicos do Gemini extra_body, inclua-os em um campo google.

{
  ...,
  "extra_body": {
     "google": {
       ...,
       // Add extra_body features here.
     }
   }
}
safety_settings Isso corresponde ao SafetySetting do Gemini.
cached_content Isso corresponde ao GenerateContentRequest.cached_content do Gemini.
thinking_config Isso corresponde ao GenerationConfig.ThinkingConfig do Gemini.
thought_tag_marker Usado para separar os pensamentos de um modelo das respostas dele para modelos com o recurso "Pensando" disponível.
Se não for especificado, nenhuma tag será retornada em torno dos pensamentos do modelo. Se estiverem presentes, 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.

extra_part recursos

O campo extra_part permite especificar outras configurações para cada Part. Para usar recursos específicos do Gemini extra_part, inclua-os em um campo google.

{
  ...,
  "extra_part": {
     "google": {
       ...,
       // Add extra_part features here.
     }
   }
}
extra_content Um campo para adicionar conteúdo específico do Gemini que não deve ser ignorado.
thought Isso marca explicitamente se um campo é um pensamento e tem precedência sobre thought_tag_marker. Deve ser usado para especificar se uma chamada de função faz parte de um pensamento ou não.

A seguir