Bagikan melalui

Gunakan API Percakapan Genie untuk mengintegrasikan Genie ke dalam aplikasi Anda

Penting

Fitur ini ada di Pratinjau Publik.

Halaman ini menjelaskan cara menggunakan API Percakapan Genie untuk mengaktifkan kemampuan Genie di chatbot, agen, atau aplikasi Anda sendiri.

Gambaran Umum

GENie Conversation API memungkinkan pengembang untuk mengintegrasikan kueri data bahasa alami ke dalam aplikasi, chatbot, dan kerangka kerja agen AI. Ini mendukung percakapan bernuansa, memungkinkan pengguna untuk mengajukan pertanyaan lanjutan dan menjelajahi data dengan lebih alami seiring waktu. Dengan menggunakan GENie API, Anda dapat mengintegrasikan kueri bahasa alami ke dalam alat dan alur kerja Anda, membuat data lebih mudah diakses di seluruh organisasi.

Sebelum menggunakan API, Anda harus menyiapkan ruang Genie yang dikurasi dengan baik. Spasi menentukan konteks yang digunakan Genie untuk menafsirkan pertanyaan dan mengembalikan hasil. Jika ruang tidak lengkap atau belum diutes, pengguna mungkin menerima tingkat jawaban yang salah yang tinggi, bahkan jika integrasi API itu sendiri berhasil. Panduan ini menguraikan penyiapan minimum yang diperlukan untuk membuat ruang yang berfungsi secara efektif dengan GENie API.

Prasyarat

Untuk menggunakan API percakapan Genie, Anda harus memiliki:

  • Akses ke ruang kerja Azure Databricks dengan hak Databricks SQL.
  • Setidaknya DAPAT MENGGUNAKAN hak istimewa pada gudang SQL pro atau SQL tanpa server.
  • Pemahaman tentang referensi Databricks REST API.

Langkah 1: Membuat dan menguji ruang Genie

Siapkan ruang Genie yang dengan andal menjawab pertanyaan pengguna dengan tingkat akurasi tinggi.

Nota

Bahkan jika Anda berencana untuk mengkueri ruang Genie menggunakan API, Anda harus menyiapkan dan memperbaiki ruang menggunakan antarmuka pengguna Azure Databricks.

Gunakan sumber daya berikut untuk membantu Anda mengonfigurasi dan mengkurasi ruang Genie Anda.

  1. Siapkan ruang Genie: Pelajari cara membuat ruang Genie menggunakan antarmuka pengguna Azure Databricks. Artikel ini mencakup panduan langkah demi langkah untuk menggunakan alat UI untuk membuat ruang Genie yang berfungsi.
  2. Tinjau praktik-praktik terbaik: Pelajari praktik-praktik terbaik untuk membuat ruang Genie baru. Artikel ini menawarkan rekomendasi tentang cara memulai penciptaan ruang Genie baru dan cara memperhalus lalu mengulang pengembangan ruang melalui pengujian dan umpan balik.
  3. Atur tolok ukur: Siapkan pertanyaan pengujian tolok ukur yang dapat Anda jalankan untuk mengukur akurasi respons Genie.

Ruang Genie yang terstruktur dengan baik memiliki karakteristik berikut:

  • Menggunakan data yang dianotasi dengan baik: Genie mengandalkan metadata tabel dan komentar kolom untuk menghasilkan respons. Sumber data Unity Catalog untuk ruang Genie Anda harus menyertakan komentar yang jelas dan deskriptif.
  • Apakah pengguna sudah diuji: Anda harus menjadi pengguna pertama ruang milik Anda. Uji ruang Anda dengan mengajukan pertanyaan yang Anda harapkan dari pengguna akhir. Gunakan pengujian Anda untuk membuat dan menyempurnakan contoh kueri SQL.
  • Termasuk konteks khusus perusahaan: Anda perlu menyertakan konteks untuk mengajarkan Genie tentang data dan jargon perusahaan Anda. Lihat Menambahkan contoh dan instruksi untuk mempelajari cara menambahkan instruksi, contoh SQL, dan fungsi untuk memproses pertanyaan umum. Bertujuan untuk menyertakan setidaknya 5 contoh kueri SQL yang telah menjalani pengujian dan penyempurnaan.
  • Menggunakan tolok ukur untuk menguji akurasi: Tambahkan setidaknya 5 pertanyaan tolok ukur berdasarkan pertanyaan yang Anda antisipasi dari pengguna akhir. Jalankan pengujian tolok ukur untuk memverifikasi bahwa Genie menjawab pertanyaan tersebut secara akurat.

Ketika Anda puas dengan respons di ruang Genie Anda dan telah mengujinya dengan pertanyaan representatif, Anda dapat mulai mengintegrasikannya dengan aplikasi Anda.

Langkah 2: Mengonfigurasi autentikasi Azure Databricks

Untuk kasus penggunaan produksi di mana pengguna dengan akses ke browser ada, gunakan OAuth untuk pengguna (OAuth U2M). Dalam situasi di mana autentikasi berbasis browser tidak dimungkinkan, Anda dapat menggunakan perwakilan layanan untuk mengautentikasi dengan API. Lihat OAuth untuk perwakilan layanan (OAuth M2M). Perwakilan layanan harus memiliki izin untuk mengakses data dan gudang SQL yang diperlukan.

Langkah 3: Kumpulkan detail

Gunakan URL ruang Genie untuk menemukan nama instans ruang kerja Anda dan ID ruang Genie. Contoh berikut menunjukkan cara menemukan komponen ini di URL. Untuk detail tentang pengidentifikasi ruang kerja di URL Anda, lihat Mendapatkan pengidentifikasi untuk objek ruang kerja.

https://<databricks-instance>/genie/rooms/<space-id>

Salin <databricks-instance> dan <space-id> untuk ruang Genie Anda.

Daftar ruang Genie

Alih-alih menemukan space-id di URL, Anda dapat menggunakan endpoint List Genie spacesGET /api/2.0/genie/spaces untuk mengambil secara terprogram daftar semua ruang Genie di ruang kerja yang dapat diakses pengguna. Array yang dikembalikan mencantumkan deskripsi, ID ruang, dan judul dari setiap ruang Genie.

Langkah 4: Memulai percakapan

Titik akhir Mulai percakapanPOST /api/2.0/genie/spaces/{space_id}/start-conversation memulai percakapan baru di ruang Genie Anda.

Ganti tempat penampung dengan instans Databricks, ID ruang Genie, dan token autentikasi Anda. Contoh respons yang berhasil diberikan setelah permintaan. Ini termasuk detail yang dapat Anda gunakan untuk mengakses percakapan ini lagi untuk pertanyaan tindak lanjut.

POST /api/2.0/genie/spaces/{space_id}/start-conversation

HOST= <DATABRICKS_INSTANCE>
Authorization: <your_authentication_token>
{
    "content": "<your question>",
}


Response:

{
  "conversation": {
    "created_timestamp": 1719769718,
    "id": "6a64adad2e664ee58de08488f986af3e",
    "last_updated_timestamp": 1719769718,
    "space_id": "3c409c00b54a44c79f79da06b82460e2",
    "title": "Give me top sales for last month",
    "user_id": 12345
  },
  "message": {
    "attachments": null,
    "content": "Give me top sales for last month",
    "conversation_id": "6a64adad2e664ee58de08488f986af3e",
    "created_timestamp": 1719769718,
    "error": null,
    "id": "e1ef34712a29169db030324fd0e1df5f",
    "last_updated_timestamp": 1719769718,
    "query_result": null,
    "space_id": "3c409c00b54a44c79f79da06b82460e2",
    "status": "IN_PROGRESS",
    "user_id": 12345
  }
}

Langkah 5: Ambil SQL yang dihasilkan

Gunakan conversation_id dan message_id dalam respons polling untuk memeriksa status pembuatan pesan dan mengambil SQL yang dihasilkan dari Genie. Lihat GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} untuk detail permintaan dan respons lengkap.

Nota

Hanya POST permintaan yang dihitung terhadap batas throughput kueri per menit. GET permintaan yang digunakan untuk hasil polling tidak tunduk pada batas ini.

Ganti nilai Anda ke dalam permintaan berikut:

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}
HOST= <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

Contoh respons berikut melaporkan detail pesan:

Response:

{
  "attachments": null,
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": null,
  "id": "e1ef34712a29169db030324fd0e1df5f",
  "last_updated_timestamp": 1719769718,
  "query_result": null,
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "IN_PROGRESS",
  "user_id": 12345
}

Ketika bidang status adalah COMPLETED, respons dimasukkan ke dalam array attachments.

Langkah 6: Mengambil hasil kueri

Array attachments berisi respons Genie. Ini termasuk respons teks yang dihasilkan (text), pernyataan kueri jika ada (query), dan pengidentifikasi yang bisa Anda gunakan untuk mendapatkan hasil kueri terkait (attachment_id). Ganti placeholder dalam contoh berikut untuk mengambil hasil kueri yang telah dihasilkan.

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/query-result/{attachment_id}
Authorization: Bearer <your_authentication_token>

Lihat GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-result.

Langkah 7: Ajukan pertanyaan tindak lanjut

Setelah Anda menerima respons, gunakan conversation_id untuk melanjutkan percakapan. Konteks dari pesan sebelumnya dipertahankan dan digunakan dalam respons tindak lanjut. Untuk detail permintaan dan respons lengkap, lihat POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages.

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages
HOST= <DATABRICKS_INSTANCE>
Authorization: <your_authentication_token>
{
  "content": "Which of these customers opened and forwarded the email?",
}

Praktik terbaik untuk menggunakan API Percakapan

Untuk mempertahankan performa dan keandalan saat menggunakan API Percakapan Genie:

  • Terapkan proses antrean dan backoff permintaan: API tidak mengelola pengulangan permintaan. Gunakan sistem antrean Anda sendiri dan terapkan mundur bertahap untuk menghindari melebihi batas throughput.
  • Polling untuk pembaruan status setiap 5 hingga 10 detik: Lanjutkan polling hingga status pesan konklusif, seperti COMPLETED, , FAILEDatau CANCELLED, diterima. Batasi polling hingga 10 menit untuk sebagian besar pertanyaan. Jika tidak ada respons konklusif setelah 10 menit, hentikan polling dan kembalikan kesalahan batas waktu atau instruksikan pengguna untuk memeriksa status kueri secara manual nanti.
  • Gunakan backoff eksponensial setelah 2 menit: Jika tidak ada respons yang diterima dalam waktu 2 menit, terapkan backoff eksponensial untuk meningkatkan keandalan.
  • Mulai percakapan baru untuk setiap sesi: Hindari menggunakan kembali utas percakapan di seluruh sesi, karena ini dapat mengurangi akurasi karena penggunaan kembali konteks yang tidak diinginkan.
  • Pertahankan batas percakapan: Gunakan titik akhir Hapus percakapan untuk menghapus percakapan secara terprogram saat spasi mendekati batas 10.000 percakapan.

Memantau ruang

Setelah aplikasi disiapkan, Anda dapat memantau pertanyaan dan respons di UI Databricks.

Dorong pengguna untuk menguji ruang sehingga Anda mempelajari tentang jenis pertanyaan yang kemungkinan akan mereka tanyakan dan respons yang mereka terima. Berikan panduan kepada pengguna untuk membantu mereka mulai menguji ruang. Gunakan tab Pemantauan untuk melihat pertanyaan dan respons. Lihat Memantau ruang.

Anda juga dapat menggunakan log audit untuk memantau aktivitas di ruang Genie. Lihat acara AI/BI Genie .

Batas throughput

Selama periode Pratinjau Umum, tingkat throughput untuk API Percakapan adalah upaya terbaik dan bergantung pada kapasitas sistem. Dalam kondisi lalu lintas normal atau rendah, permintaan dibatasi hingga 5 kueri per menit per ruang kerja. Selama periode penggunaan puncak, throughput aktual dapat lebih rendah karena permintaan diproses berdasarkan kapasitas yang tersedia.