Mengkueri model dengan OPEN Responses API

Artikel ini menjelaskan cara mengkueri model fondasi menggunakan OPEN Responses API dan menjelaskan perilaku khusus penyedia untuk memperhitungkan kapan Anda melakukannya.

Open Responses API adalah implementasi terbuka multi-penyedia dari format permintaan bergaya respons. Menggunakan kolom input alih-alih messages dan mengembalikan array output yang terstruktur. Kirim permintaan ke path /serving-endpoints/open-responses dengan nama endpoint penyajian model di kolom model pada isi permintaan.

Note

Untuk model OpenAI, gunakan OPENAI Responses API secara langsung. Jalur tersebut merupakan passthrough native dan mendukung seluruh parameter serta tool OpenAI Responses. Artikel ini membahas OPEN Responses API, yang berfungsi di seluruh penyedia tetapi mendukung set fitur yang berfokus.

Contoh kueri pencarian

Contoh berikut mengkueri titik akhir model fondasi dengan OPEN Responses API.

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

Respons berupa objek response dengan larik output. Untuk permintaan streaming (stream: true), responsnya adalah sebuah text/event-stream yang setiap event-nya merupakan bagian respons.

Perilaku khusus penyedia

Databricks menerjemahkan permintaan Respons Terbuka ke format asli setiap penyedia. Perilaku konsisten untuk sebagian besar permintaan, tetapi perbedaan khusus penyedia berikut berlaku.

Semua penyedia layanan

  • Percakapan tidak memiliki status. previous_response_id dan penyimpanan percakapan di sisi server tidak didukung. Kirim seluruh percakapan di kolom input pada setiap giliran.
  • Beberapa bidang khusus OpenAI diterima tetapi diabaikan pada penyedia non-OpenAI. Bidang seperti user, , safety_identifiermetadata, dan truncation dikembalikan dalam respons untuk portabilitas tetapi tidak mengubah perilaku penyedia.

Model yang dihosting di Databricks (sumber terbuka)

  • Dukungan fitur adalah per model. Pemanggilan fungsi, penalaran, output terstruktur, dan input gambar diaktifkan per model. Permintaan yang menggunakan fitur yang tidak didukung model mengembalikan kesalahan. Misalnya, model yang mendukung penalaran mungkin tidak mendukung input gambar.
  • Input gambar harus berupa URL atau URI data. Berikan gambar melalui image_url sebagai https URL atau data: URI. Referensi file (file_id) dan input dokumen (input_file) tidak didukung.

Model Claude Antropis

  • Suhu menggunakan skala 0–2. Claude menggunakan rentang bawaan 0–1, sehingga Databricks menskalakan ulang nilai tersebut dengan membaginya dua—temperature: 1.0 setara dengan 0.5.
  • Beralasan perjalanan pulang pergi secara bergantian. Untuk membiarkan model beralasan atas pemikiran sebelumnya dalam percakapan multi-giliran, kirim item yang dikembalikan reasoning —dengan item yang encrypted_content tidak berubah—kembali ke permintaan inputberikutnya . Lihat Model penalaran kueri.
  • Input gambar dan dokumen harus URI data base64. Berikan gambar melalui image_url sebagai URI base64 data: dan dokumen melalui file_data sebagai URI base64 data: . https URL dan file_id referensi tidak didukung.
  • Output terstruktur memiliki batasan. text.format berjenis json_schema didukung, tetapi json_object tidak didukung dan menghasilkan kesalahan. Output terstruktur tidak dapat dikombinasikan dengan streaming atau dengan penalaran, dan Anda tidak dapat menyematkan tool_choice ke alat tertentu saat menggunakannya. Lihat Output terstruktur di Azure Databricks.
  • Token penalaran disertakan dalam usage.output_tokens alih-alih dilaporkan secara terpisah.

Model Google Gemini

  • Suhu menggunakan skala 0–2. Gemini menggunakan kisaran asli 0–1, sehingga Databricks menskalakan ulang nilainya dengan membaginya menjadi dua—temperature: 1.0 berperilaku seperti 0.5.
  • Beralasan perjalanan pulang pergi secara bergantian. Untuk membiarkan model beralasan atas pemikiran sebelumnya dalam percakapan multi-giliran, kirim item yang dikembalikan reasoning —dengan item yang encrypted_content tidak berubah—kembali ke permintaan inputberikutnya . Lihat Model penalaran kueri.
  • Masukan gambar menerima baik https URL maupun URI data base64.
  • Token penalaran dilaporkan dalam usage.output_tokens_details.reasoning_tokens.

Important

Panggilan alat multi-putaran dengan Gemini mengharuskan mempertahankan encrypted_content. Gemini mengembalikan nilai encrypted_content pada setiap item function_call yang dihasilkannya. Saat Anda mengirim hasil alat kembali untuk giliran berikutnya, Anda harus menyertakan item asli function_call dengan bidangnya encrypted_content yang tidak berubah. Kerangka kerja agen yang merekonstruksi pemanggilan alat hanya dari name, arguments, dan call_id menghilangkan bidang ini, sehingga permintaan lanjutan ditolak.

Contoh berikut mempertahankan item function_call tersebut (beserta encrypted_content-nya) saat mengembalikan hasil alat:

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

Open Responses API mendukung alat bertipe function di berbagai penyedia. Untuk detail dan model yang didukung, lihat Panggilan fungsi di Azure Databricks. Untuk alat bawaan pencarian web, lihat Pencarian web di Azure Databricks.

Jenis alat bawaan dan kustom lainnya (misalnya custom, , apply_patch, image_generationdan mcp) hanya tersedia melalui OPENAI Responses API.

Model yang didukung

Open Responses API tersedia di berbagai model fondasi Databricks, termasuk Anthropic Claude, Google Gemini, dan model terbuka yang dihosting Databricks, dan dukungannya akan mencakup model-model baru ke depannya. Untuk daftar model yang tersedia saat ini, lihat Jenis model dasar.

Dukungan fitur, seperti pemanggilan fungsi, penalaran, output terstruktur, dan input gambar, tergantung pada model yang mendasar. Lihat Perilaku khusus penyedia.

Jenis input yang didukung

Dukungan input tergantung pada model dan penyedia. Input teks didukung oleh semua model. Untuk input gambar, lihat catatan per penyedia dalam perilaku khusus Penyedia serta persyaratan format dan ukuran dalam model Visi kueri. Untuk jenis input per model, lihat Model fondasi yang dihosting Databricks yang tersedia di API Model Foundation.

Sumber daya tambahan

  • Last updated on