Eseguire query su un modello con l'API Open Responses

Questo articolo illustra come eseguire query sui modelli di base usando l'API Open Responses e descrive il comportamento specifico del provider da tenere in considerazione quando si esegue l'operazione.

L'API Open Responses è un'implementazione aperta e multi-provider del formato di richiesta in stile Responses. Usa un input campo anziché messages e restituisce una matrice strutturata output . Inviare richieste al percorso /serving-endpoints/open-responses con il nome dell'endpoint di serving del modello nel campo model del corpo della richiesta.

Esempi di query

L'esempio seguente esegue una query su un endpoint del modello di base con l'API Open Responses.

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

La risposta è un response oggetto con una output matrice. Per le richieste in streaming (stream: true), la risposta è una text/event-stream in cui ogni evento è un frammento di risposta.

Comportamento specifico del provider

Databricks converte la richiesta Open Responses nel formato nativo di ogni provider. Il comportamento è coerente per la maggior parte delle richieste, ma si applicano le differenze specifiche del provider seguenti.

Tutti i provider

• Le conversazioni sono senza stato. previous_response_id e l'archiviazione delle conversazioni sul lato server non sono supportate. Invia la conversazione completa nel campo input a ogni turno.
• Alcuni campi specifici di OpenAI vengono accettati ma ignorati nei provider non OpenAI. I campi, ad esempio user, safety_identifiermetadata, e truncation vengono restituiti nella risposta per la portabilità, ma non modificano il comportamento del provider.

Modelli ospitati da Databricks (open source)

• Il supporto delle funzionalità è per modello. Le chiamate di funzione, il ragionamento, l'output strutturato e l'input dell'immagine sono abilitati per ogni modello. Una richiesta che usa una funzionalità che il modello non supporta restituisce un errore. Ad esempio, un modello che supporta il ragionamento potrebbe non supportare l'input dell'immagine.
• L'input dell'immagine deve essere un URL o un URI dati. Fornisci immagini tramite image_url come un https URL o un data: URI. I riferimenti ai file () e gli input del documento (file_idinput_file) non sono supportati.

Modelli Anthropic Claude

• La temperatura usa una scala da 0 a 2. Claude usa un intervallo nativo da 0 a 1, quindi Databricks ridimensiona il valore dimezzandolo,temperature: 1.0 si comporta come 0.5.
• Il ragionamento fa andata e ritorno tra i turni. Per consentire al modello di ragionare sul proprio ragionamento precedente in una conversazione multi-turno, rinvia gli elementi reasoning restituiti, con i relativi encrypted_content invariati, nella input della richiesta successiva. Vedere Modelli di ragionamento delle query.
• Gli input di immagini e documenti devono essere URI di dati Base64. Fornire immagini tramite image_url come URI base64 data: e documenti tramite file_data come URI base64 data:. https Gli URL e file_id i riferimenti non sono supportati.
• L'output strutturato ha vincoli. text.format di tipo json_schema è supportato, ma json_object non è e restituisce un errore. L'output strutturato non può essere combinato né con lo streaming né con il ragionamento, e non è possibile vincolare tool_choice a uno strumento specifico quando lo si utilizza. Consulta Output strutturati in Azure Databricks.
• I token di ragionamento vengono inclusi in usage.output_tokens anziché segnalati separatamente.

Modelli Google Gemini

• La temperatura usa una scala da 0 a 2. Gemini usa un intervallo nativo da 0 a 1, quindi Databricks ridimensiona il valore dimezzandolo,temperature: 1.0 si comporta come 0.5.
• Il ragionamento passa da un turno all'altro. Per consentire al modello di ragionare sul proprio ragionamento precedente in una conversazione su più turni, invia gli elementi reasoning restituiti, con i encrypted_content invariati, nella input della richiesta successiva. Vedere Modelli di ragionamento delle query.
• L'input immagine accetta sia URL che httpsURI di dati base64.
• I token di reasoning sono riportati in usage.output_tokens_details.reasoning_tokens.

Nell'esempio seguente viene mantenuto l'elemento function_call (con il relativo encrypted_content) quando si restituisce il risultato dello strumento:

{
  "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}"
    }
  ]
}

Tools

L'API Open Responses supporta strumenti di tipo function tra i provider. Per informazioni dettagliate e i modelli supportati, vedere Chiamata di funzioni su Azure Databricks. Per lo strumento predefinito di ricerca Web, vedere Ricerca Web in Azure Databricks.

Altri tipi di strumenti predefiniti e personalizzati (ad esempio custom, , apply_patchimage_generatione mcp) sono disponibili solo tramite l'API Risposte OpenAI.

Modelli supportati

L'API Open Responses è disponibile nei modelli di base di Databricks, tra cui Anthropic Claude, Google Gemini e Modelli aperti ospitati in Databricks e il supporto si estende ai nuovi modelli in futuro. Per l'elenco corrente dei modelli disponibili, vedere Tipi di modelli di base.

Il supporto delle funzionalità, ad esempio la chiamata di funzioni, il ragionamento, l'output strutturato e l'input dell'immagine, dipendono dal modello sottostante. Vedere Comportamento specifico del provider.

Tipi di input supportati

Il supporto dell'input dipende dal modello e dal provider. L'input di testo è supportato da tutti i modelli. Per l'input di immagini, consulta le note specifiche per provider in Comportamento specifico del provider e i requisiti di formato e dimensioni in Interrogare i modelli di visione. Per i tipi di input per modello, vedere Modelli di base ospitati in Databricks disponibili nelle API del modello di base.

Risorse aggiuntive

• Interrogare con l'API Responses di OpenAI
• Interrogare un modello di chat
• Chiamata di funzione in Azure Databricks
• Ricerca sul Web in Azure Databricks
• Output strutturati in Azure Databricks
• API di modelli fondamentali di Databricks