Gunakan Genie API untuk mengintegrasikan Genie ke dalam aplikasi Anda

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

Gambaran Umum

Genie API menyediakan dua jenis kemampuan:

  • API Percakapan: Mengaktifkan kueri data bahasa alami dalam aplikasi, chatbot, dan kerangka kerja agen AI. API ini mendukung percakapan stateful di mana pengguna dapat mengajukan pertanyaan tindak lanjut dan menjelajahi data secara alami dari waktu ke waktu.
  • API Manajemen: Aktifkan pembuatan, konfigurasi, dan penyebaran Ruang Genie terprogram di seluruh ruang kerja. Gunakan API ini untuk alur CI/CD, kontrol versi, dan manajemen ruang otomatis.

Halaman ini menjelaskan API percakapan dan manajemen. Sebelum memanggil API percakapan, siapkan Genie Space yang dikurasi dengan baik. Ruang menyediakan konteks yang digunakan Genie untuk menafsirkan pertanyaan dan menghasilkan jawaban. Jika ruang tidak lengkap atau belum diuji, pengguna mungkin masih menerima hasil yang salah bahkan dengan integrasi API yang benar. Panduan ini menjelaskan pengaturan minimum yang diperlukan untuk membuat ruang yang berfungsi secara efektif dengan API Genie.

Contoh di halaman ini menggunakan REST API secara langsung. Anda juga dapat memanggil API ini menggunakan SDK Azure Databricks. Lihat SDK Databricks.

Prasyarat

Untuk menggunakan API 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.

Memulai Langkah Pertama

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, gunakan 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.

Mengumpulkan detail

  • Nama instans workspace: Temukan dan salin nama instans workspace Anda dari URL workspace Databricks Anda. Untuk detail tentang pengidentifikasi ruang kerja di URL Anda, lihat Mendapatkan pengidentifikasi untuk objek ruang kerja.

    Contoh: https://cust-success.cloud.databricks.com/

  • ID Gudang: Anda memerlukan ID gudang SQL yang Anda memiliki setidaknya izin untuk menggunakan. Untuk menemukan ID gudang Anda:

    1. Buka Gudang SQL di ruang kerja Anda.
    2. Pilih gudang yang ingin Anda gunakan.
    3. Salin ID gudang dari URL atau halaman detail gudang.

    Atau, gunakan endpoint Daftar gudangGET /api/2.0/sql/warehouses untuk mengambil dengan cara terprogram daftar semua gudang SQL yang Anda memiliki izin untuk mengaksesnya. Tanggapannya menyertakan ID gudang.

Membuat atau memilih Genie Space

Genie Space yang terstruktur dengan baik memiliki karakteristik berikut:

  • Menggunakan data yang dianotasi dengan baik: Genie bergantung pada metadata tabel dan komentar kolom. Verifikasi bahwa sumber data Unity Catalog Anda memiliki komentar yang jelas dan deskriptif.
  • Apakah pengguna diuji: Uji ruang Anda dengan mengajukan pertanyaan yang Anda harapkan dari pengguna akhir. Gunakan pengujian untuk membuat dan memperbaiki contoh kueri SQL.
  • Mencakup konteks khusus perusahaan: Tambahkan instruksi, contoh SQL, dan fungsi. Lihat Menambahkan contoh dan instruksi SQL. Bertujuan untuk setidaknya lima contoh kueri SQL yang diuji.
  • Menggunakan tolok ukur untuk menguji akurasi: Tambahkan setidaknya lima pertanyaan tolok ukur berdasarkan pertanyaan pengguna yang diantisipasi. Lihat Menggunakan tolok ukur di Genie Space.

Untuk informasi selengkapnya tentang membuat ruang, lihat Menyiapkan dan Mengelola Genie Space dan Mengkurasi Genie Space yang Efektif.

Anda dapat membuat Genie Space baru atau menggunakan yang sudah ada:

Membuat spasi baru

Buat Genie Space secara terprogram menggunakan Create Genie Space API. Contoh berikut menunjukkan ruang terstruktur dengan baik yang mengikuti praktik terbaik. Ganti placeholder dengan nilai Anda

POST /api/2.0/genie/spaces
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>
{
  "description": "Space for analyzing sales performance and trends",
  "parent_path": "/Workspace/Users/<username>",
  "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g7\",\"question\":[\"Show top 10 customers by revenue\"]},{\"id\":\"c3d4e5f6g7h8\",\"question\":[\"Compare sales by region for Q1 vs Q2\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}",
  "title": "Sales Analytics Space",
  "warehouse_id": "<warehouse-id>"
}

Response:
{
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "title": "Sales Analytics Space",
  "description": "Space for analyzing sales performance and trends",
  "warehouse_id": "<warehouse-id>",
  "serialized_space": "{\n  \"version\": 1,\n  \"config\": {\n    \"sample_questions\": [\n      {\n        \"id\": \"a1b2c3d4e5f600000000000000000000\",\n        \"question\": [\n          \"What were total sales last month?\"\n        ]\n      },\n      {\n        \"id\": \"b2c3d4e5f6g700000000000000000000\",\n        \"question\": [\n          \"Show top 10 customers by revenue\"\n        ]\n      },\n      {\n        \"id\": \"c3d4e5f6g7h800000000000000000000\",\n        \"question\": [\n          \"Compare sales by region for Q1 vs Q2\"\n        ]\n      }\n    ]\n  },\n  \"data_sources\": {\n    \"tables\": [\n      {\n        \"identifier\": \"sales.analytics.orders\",\n        \"description\": [\n          \"Transactional order data including order date, amount, and customer information\"\n        ],\n        \"column_configs\": [\n          {\n            \"column_name\": \"order_date\",\n            \"get_example_values\": true\n          },\n          {\n            \"column_name\": \"status\",\n            \"get_example_values\": true,\n            \"build_value_dictionary\": true\n          },\n          {\n            \"column_name\": \"region\",\n            \"get_example_values\": true,\n            \"build_value_dictionary\": true\n          }\n        ]\n      },\n      {\n        \"identifier\": \"sales.analytics.customers\"\n      },\n      {\n        \"identifier\": \"sales.analytics.products\"\n      }\n    ]\n  },\n  \"instructions\": {\n    \"text_instructions\": [\n      {\n        \"id\": \"01f0b37c378e1c91\",\n        \"content\": [\n          \"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"\n        ]\n      }\n    ],\n    \"example_question_sqls\": [\n      {\n        \"id\": \"01f0821116d912db\",\n        \"question\": [\n          \"Show top 10 customers by revenue\"\n        ],\n        \"sql\": [\n          \"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\n          \"FROM sales.analytics.orders o\\n\",\n          \"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\n          \"GROUP BY customer_name\\n\",\n          \"ORDER BY total_revenue DESC\\n\",\n          \"LIMIT 10\"\n        ]\n      },\n      {\n        \"id\": \"01f099751a3a1df3\",\n        \"question\": [\n          \"What were total sales last month\"\n        ],\n        \"sql\": [\n          \"SELECT SUM(order_amount) as total_sales\\n\",\n          \"FROM sales.analytics.orders\\n\",\n          \"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\n          \"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"\n        ]\n      }\n    ],\n    \"join_specs\": [\n      {\n        \"id\": \"01f0c0b4e8151\",\n        \"left\": {\n          \"identifier\": \"sales.analytics.orders\",\n          \"alias\": \"orders\"\n        },\n        \"right\": {\n          \"identifier\": \"sales.analytics.customers\",\n          \"alias\": \"customers\"\n        },\n        \"sql\": [\n          \"orders.customer_id = customers.customer_id\"\n        ]\n      }\n    ],\n    \"sql_snippets\": {\n      \"filters\": [\n        {\n          \"id\": \"01f09972e66d1\",\n          \"sql\": [\"orders.order_amount > 1000\"],\n          \"display_name\": \"high value orders\",\n          \"synonyms\": [\"large orders\", \"big purchases\"]\n        }\n      ],\n      \"expressions\": [\n        {\n          \"id\": \"01f09974563a1\",\n          \"alias\": \"order_year\",\n          \"sql\": [\"YEAR(orders.order_date)\"],\n          \"display_name\": \"year\"\n        }\n      ],\n      \"measures\": [\n        {\n          \"id\": \"01f09972611f1\",\n          \"alias\": \"total_revenue\",\n          \"sql\": [\"SUM(orders.order_amount)\"],\n          \"display_name\": \"total revenue\",\n          \"synonyms\": [\"revenue\", \"total sales\"]\n        }\n      ]\n    }\n  }\n}\n"
}

Gunakan ruang yang ada

Jika Anda sudah memiliki Genie Space, Anda dapat menemukan ID ruang menggunakan List Genie Spaces API. Anda juga dapat menemukan dan menyalin ID ruang dari tab Pengaturan Ruang Genie.

GET /api/2.0/genie/spaces
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

Response:
{
  "spaces": [
    {
      "description": "Space for analyzing sales performance and trends",
      "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g7\",\"question\":[\"Show top 10 customers by revenue\"]},{\"id\":\"c3d4e5f6g7h8\",\"question\":[\"Compare sales by region for Q1 vs Q2\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}",
      "space_id": "3c409c00b54a44c79f79da06b82460e2",
      "title": "Sales Analytics Space",
      "warehouse_id": "<warehouse-id>",
    },
    {
      "description": "Space for marketing campaign analysis",
      "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"Show total revenue by state\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.gold.orders\"}]}}",
      "space_id": "7f8e9d0c1b2a3456789abcdef0123456",
      "title": "Marketing Analytics Space",
      "warehouse_id": "<warehouse-id>",
    }
  ]
}

Gunakan space_id dari respons pada panggilan API berikut.

Memahami bidang serialized_space

Bidang serialized_space adalah string JSON yang menentukan konfigurasi dan sumber data untuk Genie Space Anda. Dalam permintaan API, JSON ini harus diloloskan sebagai string. Bidang berisi:

  • versi: Nomor versi skema untuk kompatibilitas ke belakang. Gunakan 2 seperti yang ditunjukkan pada contoh di bawah ini.
  • konfigurasi: Pengaturan ruang termasuk:
    • sample_questions: Contoh pertanyaan untuk memandu pengguna. Setiap pertanyaan memerlukan id (string heksa 32 karakter) dan pertanyaan (array string).
  • data_sources: Sumber data yang tersedia untuk ruang:
    • tabel: Array objek tabel dengan pengidentifikasi (namespace tiga tingkat), deskripsi opsional, dan column_configs opsional.
    • metric_views: Array objek tampilan metrik (struktur yang sama dengan tabel).
  • instruksi: Instruksi terstruktur untuk ruang:
    • text_instructions: Panduan tingkat tinggi untuk LLM.
    • example_question_sqls: Contoh pertanyaan dengan jawaban SQL, secara opsional dengan parameter dan usage_guidance.
    • sql_functions: Referensi ke fungsi SQL yang tersedia untuk ruang.
    • join_specs: Hubungan gabungan yang telah ditentukan sebelumnya antar tabel. Bidang sql memerlukan tepat dua elemen: kondisi gabungan menggunakan referensi alias dalam tanda kutip backtick dan anotasi jenis hubungan, misalnya "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". Lihat Format spesifikasi gabungan.
    • sql_snippets: filters, ekspresi, dan ukuran yang dapat digunakan kembali.
  • tolok ukur: Pertanyaan untuk mengevaluasi kualitas ruang, masing-masing dengan jawaban SQL kebenaran dasar.

Versi bidang yang serialized_space tidak diescaped dari contoh buat ruang terlihat seperti:

{
  "version": 2,
  "config": {
    "sample_questions": [
      {
        "id": "a1b2c3d4e5f60000000000000000000a",
        "question": ["What were total sales last month?"]
      },
      {
        "id": "b2c3d4e5f6a70000000000000000000b",
        "question": ["Show top 10 customers by revenue"]
      }
    ]
  },
  "data_sources": {
    "tables": [
      {
        "identifier": "sales.analytics.customers",
        "description": ["Customer master data including contact information and account details"],
        "column_configs": [
          {
            "column_name": "customer_id",
            "description": ["Unique identifier for each customer"],
            "synonyms": ["cust_id", "account_id"]
          },
          {
            "column_name": "customer_name",
            "enable_entity_matching": true
          },
          {
            "column_name": "internal_notes",
            "exclude": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.orders",
        "description": ["Transactional order data including order date, amount, and customer information"],
        "column_configs": [
          {
            "column_name": "order_date",
            "enable_format_assistance": true
          },
          {
            "column_name": "region",
            "enable_format_assistance": true,
            "enable_entity_matching": true
          },
          {
            "column_name": "status",
            "enable_format_assistance": true,
            "enable_entity_matching": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.products"
      }
    ],
    "metric_views": [
      {
        "identifier": "sales.analytics.revenue_metrics",
        "description": ["Pre-aggregated revenue metrics by region and time period"],
        "column_configs": [
          {
            "column_name": "period",
            "description": ["Time period for the metric (monthly, quarterly, yearly)"],
            "enable_format_assistance": true
          }
        ]
      }
    ]
  },
  "instructions": {
    "text_instructions": [
      {
        "id": "01f0b37c378e1c9100000000000000a1",
        "content": [
          "When calculating revenue, sum the order_amount column. ",
          "When asked about 'last month', use the previous calendar month. ",
          "Round all monetary values to 2 decimal places."
        ]
      }
    ],
    "example_question_sqls": [
      {
        "id": "01f0821116d912db00000000000000b1",
        "question": ["Show top 10 customers by revenue"],
        "sql": [
          "SELECT customer_name, SUM(order_amount) as total_revenue\n",
          "FROM sales.analytics.orders o\n",
          "JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\n",
          "GROUP BY customer_name\n",
          "ORDER BY total_revenue DESC\n",
          "LIMIT 10"
        ]
      },
      {
        "id": "01f099751a3a1df300000000000000b2",
        "question": ["What were total sales last month"],
        "sql": [
          "SELECT SUM(order_amount) as total_sales\n",
          "FROM sales.analytics.orders\n",
          "WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\n",
          "AND order_date < DATE_TRUNC('month', CURRENT_DATE)"
        ]
      },
      {
        "id": "01f099751a3a1df300000000000000b3",
        "question": ["Show sales for a specific region"],
        "sql": [
          "SELECT SUM(order_amount) as total_sales\n",
          "FROM sales.analytics.orders\n",
          "WHERE region = :region_name"
        ],
        "parameters": [
          {
            "name": "region_name",
            "type_hint": "STRING",
            "description": ["The region to filter by (e.g., 'North America', 'Europe')"],
            "default_value": {
              "values": ["North America"]
            }
          }
        ],
        "usage_guidance": ["Use this example when the user asks about sales filtered by a specific geographic region"]
      }
    ],
    "sql_functions": [
      {
        "id": "01f0c0b4e815100000000000000000f1",
        "identifier": "sales.analytics.fiscal_quarter"
      }
    ],
    "join_specs": [
      {
        "id": "01f0c0b4e815100000000000000000c1",
        "left": {
          "identifier": "sales.analytics.orders",
          "alias": "orders"
        },
        "right": {
          "identifier": "sales.analytics.customers",
          "alias": "customers"
        },
        "sql": ["`orders`.`customer_id` = `customers`.`customer_id`", "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--"],
        "comment": ["Join orders to customers on customer_id"],
        "instruction": ["Use this join when you need customer details for order analysis"]
      }
    ],
    "sql_snippets": {
      "filters": [
        {
          "id": "01f09972e66d100000000000000000d1",
          "sql": ["orders.order_amount > 1000"],
          "display_name": "high value orders",
          "synonyms": ["large orders", "big purchases"],
          "comment": ["Filters to orders over $1000"],
          "instruction": ["Use when the user asks about high-value or large orders"]
        }
      ],
      "expressions": [
        {
          "id": "01f09974563a100000000000000000e1",
          "alias": "order_year",
          "sql": ["YEAR(orders.order_date)"],
          "display_name": "year",
          "synonyms": ["fiscal year", "calendar year"],
          "comment": ["Extracts the year from order date"],
          "instruction": ["Use for year-over-year analysis"]
        }
      ],
      "measures": [
        {
          "id": "01f09972611f100000000000000000f1",
          "alias": "total_revenue",
          "sql": ["SUM(orders.order_amount)"],
          "display_name": "total revenue",
          "synonyms": ["revenue", "total sales"],
          "comment": ["Sum of all order amounts"],
          "instruction": ["Use this measure for revenue calculations"]
        }
      ]
    }
  },
  "benchmarks": {
    "questions": [
      {
        "id": "01f0d0b4e815100000000000000000g1",
        "question": ["What is the average order value?"],
        "answer": [
          {
            "format": "SQL",
            "content": ["SELECT AVG(order_amount) as avg_order_value\n", "FROM sales.analytics.orders"]
          }
        ]
      }
    ]
  }
}

Saat membangun ruang Anda, buat struktur JSON ini kemudian konversi menjadi string untuk permintaan API. Untuk detail skema lengkap, lihat referensi Buat API Ruang Genie.

Aturan validasi untuk serialized_space

serialized_space JSON harus sesuai dengan aturan validasi berikut. JSON yang tidak valid ditolak selama pembuatan atau pembaruan ruang.

Versi

  • Bidang versi: Diperlukan. Gunakan 2 untuk spasi baru. Nomor versi ada untuk kemampuan kompatibilitas ke belakang.

Format ID

Semua bidang ID harus berupa string heksadesimal huruf kecil 32 karakter (format UUID tanpa tanda hubung).

  • Valid: a1b2c3d4e5f60000000000000000000a
  • Tidak valid: a1b2c3d4e5f6 (terlalu pendek), A1B2C3D4E5F60000000000000000000A (huruf besar), a1b2c3d4-e5f6-0000-0000-00000000000a (berisi tanda hubung)

ID diperlukan untuk:

  • config.sample_questions[].id
  • instructions.text_instructions[].id
  • instructions.example_question_sqls[].id
  • instructions.join_specs[].id
  • instructions.sql_snippets.filters[].id
  • instructions.sql_snippets.expressions[].id
  • instructions.sql_snippets.measures[].id
  • benchmarks.questions[].id (jika tolok ukur disertakan)

Anda dapat menggunakan perintah berikut untuk menghasilkan ID yang valid:

python3 -c "import random,datetime;t=int((datetime.datetime.now()-datetime.datetime(1582,10,15)).total_seconds()*1e7);print(f'{(t&0xFFFFFFFFFFFF0000)|(1<<12)|((t&0xFFFF)>>4):016x}{random.getrandbits(62)|0x8000000000000000:016x}')"

Ini menghasilkan UUID yang diurutkan waktu. ID yang dihasilkan secara berurutan akan terurut secara alfabet sesuai urutan pembuatannya, yang memenuhi persyaratan pengurutan secara otomatis.

Persyaratan pengurutan

Koleksi yang berisi ID atau pengidentifikasi harus diurutkan sebelumnya. Sistem memvalidasi bahwa array sudah diurutkan dan menolak input yang tidak diurutkan.

Collection Urutkan kunci
data_sources.tables identifier (menurut abjad)
data_sources.metric_views identifier (menurut abjad)
data_sources.tables[].column_configs column_name (menurut abjad)
data_sources.metric_views[].column_configs column_name (menurut abjad)
config.sample_questions id (menurut abjad)
instructions.text_instructions id (menurut abjad)
instructions.example_question_sqls id (menurut abjad)
instructions.sql_functions (id, identifier) tuple (menurut abjad)
instructions.join_specs id (menurut abjad)
instructions.sql_snippets.filters id (menurut abjad)
instructions.sql_snippets.expressions id (menurut abjad)
instructions.sql_snippets.measures id (menurut abjad)
benchmarks.questions id (menurut abjad)

Batasan keunikan

  • ID Pertanyaan: Semua ID dalam config.sample_questions dan benchmarks.questions harus unik di kedua koleksi tersebut.
  • ID instruksi: Semua ID di seluruh text_instructions, example_question_sqls, sql_functions, join_specs, dan semua jenis sql_snippets harus unik.
  • Konfigurasi kolom: Kombinasi (table_identifier, column_name) harus unik dalam spasi.

Batas ukuran dan panjang

  • Panjang string: Elemen string individual dibatasi hingga 25.000 karakter.
  • Ukuran array: Bidang berulang dibatasi hingga 10.000 item.
  • Instruksi teks: Paling banyak 1 instruksi teks diizinkan per spasi.
  • Tabel dan tampilan metrik: Tunduk pada batas khusus ruang kerja.
  • Konten SQL: Teks kueri di bidang sql dan join_specs.sql tunduk pada batas panjang.

Format spesifikasi gabungan

Bidang sql di setiap spesifikasi gabungan harus berisi dua elemen:

  1. Kondisi gabungan, menggunakan referensi alias yang dikutip backtick:

    "`orders`.`customer_id` = `customers`.`customer_id`"

  2. Anotasi jenis hubungan dalam format berikut:

    "--rt=FROM_RELATIONSHIP_TYPE_<CARDINALITY>--"

    Nilai kardinalitas yang valid:

    • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
    • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
    • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
    • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

Menghilangkan anotasi jenis hubungan menyebabkan API menolak permintaan dengan kesalahan penguraian. Untuk gabungan multi-kolom, buat spesifikasi gabungan terpisah untuk setiap hubungan.

Persyaratan lain

  • Pengidentifikasi tabel: Harus menggunakan format namespace tiga tingkat (catalog.schema.table).
  • Jawaban tolok ukur: Setiap pertanyaan tolok ukur harus memiliki satu jawaban dengan format yang diatur ke SQL.
  • Cuplikan SQL: Filter, ekspresi, dan pengukuran kolom SQL tidak boleh kosong.

Menggunakan API percakapan

Setelah Anda mengonfigurasi Genie Space, gunakan endpoint API percakapan untuk mengajukan pertanyaan, mengambil data, dan memelihara percakapan multi-giliran dengan konteks.

Memulai percakapan

Titik POST /api/2.0/genie/spaces/{space_id}/start-conversation memulai percakapan baru di Genie Space 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
  }
}

Mengambil 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 pertimbangan 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.

Untuk menentukan apakah respons dihasilkan menggunakan aset tepercaya, periksa attachments bidang dalam respons untuk query.parameters objek. Kehadirannya menunjukkan jawaban berasal dari aset tepercaya.

Untuk mengakses jejak penalaran Genie, periksa bidang attachments untuk objek query_attachments dengan jenis GenieQueryAttachments. Ketika ada, ini berisi penalaran langkah demi langkah yang digunakan Genie untuk menghasilkan respons. Untuk detail bidang lengkap, lihat referensi API untuk Get message.

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.

Nota

API Percakapan Genie mengembalikan hasil kueri tabular sebagai data terstruktur. Ini tidak mengembalikan bagan atau visualisasi yang dirender. Untuk menampilkan bagan, ambil hasil kueri dari attachment_id dan render di aplikasi Anda menggunakan pustaka bagan pilihan Anda. Bidang query dalam lampiran berisi SQL yang dihasilkan Genie, yang juga dapat Anda jalankan langsung terhadap gudang Anda untuk mengambil hasil visualisasi.

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.

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?",
}

Menambahkan komentar ke pesan

Anda dapat menambahkan komentar teks ke pesan dan mencantumkan komentar yang ada menggunakan titik akhir API komentar pesan.

Untuk menambahkan komentar ke pesan, gunakan endpoint POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments:

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments
HOST= <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>
{
  "comment": "<your comment text>"
}

Untuk mencantumkan komentar yang ada pada pesan, gunakan titik akhir Daftar komentar pesan.

Mengambil data percakapan dan ruang penyimpanan

GENie API menyediakan titik akhir tambahan untuk mengambil konfigurasi dan data historis dari ruang dan percakapan yang ada.

Mengambil konfigurasi ruang

Saat mengambil informasi ruang menggunakan Get Genie Space API, Anda dapat menyertakan serialized_space bidang dalam respons dengan mengatur include_serialized_space parameter ke true. Bidang serialized_space berisi representasi string berseri dari Genie Space, termasuk instruksi, tolok ukur, gabungan, dan detail konfigurasi lainnya.

Gunakan representasi berseri ini dengan Create Genie Space API dan Update Genie Space API untuk mempromosikan Ruang Genie di seluruh ruang kerja atau membuat cadangan konfigurasi ruang.

Contoh GET permintaan:

GET /api/2.0/genie/spaces/{space_id}?include_serialized_space=true
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

Response:
{
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "title": "Sales Analytics Space",
  "description": "Space for analyzing sales performance and trends",
  "warehouse_id": "<warehouse-id>",
  "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f600000000000000000000\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g700000000000000000000\",\"question\":[\"Show top 10 customers by revenue\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}"
}

Rujuk topik diskusi sebelumnya

Untuk memungkinkan pengguna merujuk ke utas percakapan lama, gunakan endpoint List conversation messagesGET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages untuk mengambil semua pesan dari utas percakapan tertentu.

Mengambil data percakapan untuk analisis

Manajer ruang dapat mengambil pesan-pesan sebelumnya secara programatis dari semua pengguna dalam ruang untuk analisis. Untuk mengambil data ini:

  1. Gunakan endpoint GET /api/2.0/genie/spaces/{space_id}/conversations untuk mendapatkan semua utas percakapan yang ada dalam ruang.
  2. Untuk setiap ID percakapan yang dikembalikan, gunakan GET /api/2.0/genie/spaces/{space_id}/conversations endpoint untuk memperoleh daftar pesan untuk percakapan tersebut.

Praktik dan batasan terbaik

Praktik terbaik untuk menggunakan API Genie

Untuk mempertahankan performa dan keandalan saat menggunakan API Genie:

  • Terapkan logika coba lagi dengan backoff eksponensial: API tidak otomatis mencoba kembali permintaan yang gagal, jadi tambahkan pengaturan antrian dan backoff eksponensial Anda sendiri. Ini membantu aplikasi Anda menangani kegagalan sementara, menghindari permintaan berulang yang tidak perlu, dan tetap berada dalam batas throughput saat berkembang.
  • Respons API log: Terapkan pengelogan komprehensif permintaan dan respons API untuk membantu penelusuran kesalahan, memantau pola penggunaan, dan melacak biaya.
  • Polling untuk pembaruan status setiap 1 hingga 5 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 untuk polling: Tingkatkan penundaan antar polling hingga maksimum satu menit. Ini mengurangi permintaan yang tidak perlu untuk kueri yang berjalan lama sambil tetap memungkinkan latensi rendah untuk kueri yang cepat.
  • Memulai 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: Untuk mengelola percakapan lama dan tetap berada di bawah batas 10.000 percakapan:
    1. Gunakan titik akses GET /api/2.0/genie/spaces/{space_id}/conversations untuk melihat semua utas percakapan yang ada dalam ruang.
    2. Identifikasi percakapan yang tidak lagi diperlukan, seperti percakapan yang lebih lama atau percakapan pengujian.
    3. DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} Gunakan titik akhir untuk menghapus percakapan secara terprogram.
  • Ketahui batas hasil kueri: API Genie mengembalikan maksimum 5.000 baris per hasil kueri. Jika analisis data Anda memerlukan lebih banyak baris, pertimbangkan untuk menyempurnakan pertanyaan Anda untuk fokus pada subset data tertentu atau menggunakan filter untuk mempersempit hasilnya.

Pertimbangan throughput

Tarif throughput untuk tingkat gratis API percakapan Genie adalah upaya terbaik dan bergantung pada kapasitas sistem. Untuk mengurangi penyalahgunaan dan mencegah penyalahgunaan selama periode penggunaan puncak, sistem memproses permintaan berdasarkan kapasitas yang tersedia. Dalam kondisi lalu lintas normal atau rendah, API mendukung permintaan hingga lima pertanyaan per menit per ruang kerja. Jika Anda mencari dukungan throughput yang lebih tinggi, hubungi tim akun Databricks Anda.

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 Genie Space. Lihat Acara Genie Space.

  • Last updated on