Pular para o conteúdo principal
Última atualização em

Consultar um modelo com a API Open Responses

Este artigo explica como consultar modelos básicos usando a API Open Responses e descreve o comportamento específico do provedor a ser considerado ao fazê-lo.

A API Open Responses é uma implementação aberta e multiprovedor do formato de solicitação no estilo de respostas. Ele usa um campo input em vez de messages e retorna um array output estruturado. Envie solicitações para o caminho /serving-endpoints/open-responses com o nome do endpoint de servindo modelo no campo model do corpo da solicitação.

nota

Para modelos OpenAI, use a API de Respostas OpenAI diretamente. Esse caminho é uma passagem nativa e oferece suporte a todo o conjunto de parâmetros e ferramentas das Respostas OpenAI. Este artigo abrange a API de Respostas Abertas, que funciona em vários provedores, mas oferece suporte a um conjunto de recursos focado.

Exemplos de consulta​

O exemplo a seguir consulta um endpoint de modelo de base com a API Open Responses.

Bash
curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "databricks-claude-sonnet-4-5",
    "input": [
      {
        "role": "user",
        "content": "What is a mixture of experts model?"
      }
    ],
    "max_output_tokens": 256
  }' \
  https://<workspace_host>.databricks.com/serving-endpoints/open-responses

A resposta é um objeto response com um array output. Para solicitações de transmissão (stream: true), a resposta é um text/event-stream onde cada evento é um fragmento de resposta.

Comportamento específico do provedor​

O Databricks traduz a solicitação de Respostas Abertas para o formato nativo de cada provedor. O comportamento é consistente para a maioria das solicitações, mas se aplicam as seguintes diferenças específicas do provedor.

Todos os provedores​

  • As conversas são sem estado. previous_response_id e o armazenamento de conversas no lado do servidor não são compatíveis. Envie a conversa completa no campo input a cada turno.
  • Alguns campos específicos da OpenAI são aceitos, mas ignorados em provedores que não são da OpenAI. Campos como user, safety_identifier, metadata e truncation são retornados na resposta para portabilidade, mas não alteram o comportamento do provedor.

Modelos hospedados pelo Databricks (código aberto)​

  • O suporte a recursos é por modelo. Chamada de função, raciocínio, saída estruturada e entrada de imagem são habilitados por modelo. Uma solicitação que usa um recurso que o modelo não suporta retorna um erro. Por exemplo, um modelo que suporta raciocínio pode não suportar entrada de imagem.
  • A entrada de imagem deve ser uma URL ou URI de dados. Forneça imagens através de image_url como uma URL https ou um URI data:. Referências de arquivo (file_id) e entradas de documento (input_file) não são suportadas.

Modelos Anthropic Claude​

  • A temperatura usa uma escala de 0–2. Claude usa um intervalo nativo de 0–1, então Databricks reajusta a escala do valor pela metade —temperature: 1.0 se comporta como 0.5.
  • Idas e vindas de raciocínio entre turnos. Para permitir que o modelo raciocine sobre seu pensamento anterior em uma conversa em vários turnos, envie os itens reasoning retornados—com seus encrypted_content inalterados—de volta na input da próxima solicitação. Consulte Modelos de raciocínio de consulta.
  • As entradas de imagem e documento devem ser URIs de dados base64. Forneça imagens através de image_url como um URI data: base64 e documentos através de file_data como um URI data: base64. URLs https e referências file_id não são suportadas.
  • A saída estruturada tem restrições. text.format do tipo json_schema é suportado, mas json_object não é e retorna um erro. A saída estruturada não pode ser combinada com transmissão ou com raciocínio, e você não pode pin tool_choice a uma ferramenta específica ao usá-la. Consulte Saídas estruturadas no Databricks.
  • Os tokens de raciocínio estão incluídos em usage.output_tokens, em vez de serem relatados separadamente.

Modelos Google Gemini​

  • A temperatura usa uma escala de 0–2. Gemini usa um intervalo nativo de 0–1, então o Databricks reescala o valor pela metade—temperature: 1.0 se comporta como 0.5.
  • Idas e vindas de raciocínio entre turnos. Para permitir que o modelo raciocine sobre seu pensamento anterior em uma conversa em vários turnos, envie os itens reasoning retornados—com seus encrypted_content inalterados—de volta na input da próxima solicitação. Consulte Modelos de raciocínio de consulta.
  • A entrada de imagem aceita tanto https URLs quanto URIs de dados base64.
  • Tokens de raciocínio são relatados em usage.output_tokens_details.reasoning_tokens.
importante

Chamadas de ferramenta em várias etapas com Gemini exigem a preservação de encrypted_content. O Gemini retorna um valor encrypted_content em cada item function_call que ele produz. Ao enviar o resultado da ferramenta de volta para o próximo turno, você deve incluir o item function_call original com seu campo encrypted_content inalterado. Os frameworks de agente que reconstroem chamadas de ferramenta apenas de name, arguments e call_id descartam este campo, o que faz com que a solicitação de acompanhamento seja rejeitada.

O exemplo a seguir preserva o item function_call (com seu encrypted_content) ao retornar o resultado da ferramenta:

JSON
{
  "model": "databricks-gemini-2-5-pro",
  "input": [
    { "role": "user", "content": "What's the weather in San Francisco?" },
    {
      "type": "function_call",
      "call_id": "call_abc123",
      "name": "get_weather",
      "arguments": "{\"city\": \"San Francisco\"}",
      "encrypted_content": "<opaque-provider-signature>"
    },
    {
      "type": "function_call_output",
      "call_id": "call_abc123",
      "output": "{\"temp_f\": 64}"
    }
  ]
}

Ferramentas​

A API de Respostas Abertas suporta ferramentas do tipo functionem todos os provedores. Para obter detalhes e os modelos compatíveis, consulte Chamada de função no Databricks. Para a ferramenta integrada de pesquisa na web, consulte Pesquisa na Web no Databricks.

Outros tipos de ferramentas integradas e personalizadas (por exemplo, custom, apply_patch, image_generation e mcp) estão disponíveis apenas por meio da API OpenAI Responses.

Modelos compatíveis​

A API Open Responses está disponível em todos os modelos de base do Databricks, incluindo Anthropic Claude, Google Gemini e modelos abertos hospedados pelo Databricks, e o suporte se estende a novos modelos daqui para frente. Para a lista atual de modelos disponíveis, consulte Tipos de modelo de base.

O suporte a recursos, como chamada de função, raciocínio, saída estruturada e entrada de imagem, depende do modelo subjacente. Consulte Comportamento específico do provedor.

Tipos de entrada compatíveis​

O suporte à entrada depende do modelo e do provedor. A entrada de texto é compatível com todos os modelos. Para entrada de imagem, consulte as observações por provedor em Comportamento específico do provedor e os requisitos de formato e tamanho em Consultar modelos de visão. Para tipos de entrada por modelo, consulte modelos básicos hospedados no Databricks disponíveis nas APIs do Foundation Model.

Recursos adicionais​

Nesta página