Aracılığıyla paylaş

Genie'yi uygulamalarınızla tümleştirmek için Genie API'sini kullanma

Önemli

Bu özellik Genel Önizleme aşamasındadır.

Bu sayfada kendi sohbet botunuzda, aracınızda veya uygulamanızda Genie özelliklerini etkinleştirmek için Genie API'sinin nasıl kullanılacağı açıklanmaktadır.

Genel Bakış

Genie API iki tür özellik sağlar:

  • Konuşma API'leri: Uygulamalar, sohbet botları ve yapay zeka aracısı çerçevelerinde doğal dil veri sorgulamasını etkinleştirin. Bu API'ler, kullanıcıların zaman içinde takip soruları sorabileceği ve verileri doğal olarak keşfedebileceği durum bilgisine sahip konuşmaları destekler.
  • Yönetim API'leri: Çalışma alanları arasında Genie alanlarının program aracılığıyla oluşturulmasını, yapılandırılmasını ve dağıtılmasını etkinleştirin. CI/CD işlem hatları, sürüm denetimi ve otomatik alan yönetimi için bu API'leri kullanın.

Bu sayfada hem konuşma hem de yönetim API'leri açıklanmaktadır. Konuşma API'lerini çağırmadan önce iyi seçilmiş bir Genie alanı hazırlayın. Bu alan Genie'nin soruları yorumlamak ve yanıtlar oluşturmak için kullandığı bağlamı sağlar. Alan eksik veya test edilmemişse, kullanıcılar doğru API tümleştirmesiyle bile yanlış sonuçlar alabilir. Bu kılavuzda Genie API'siyle etkili bir şekilde çalışan bir alan oluşturmak için gereken minimum kurulum açıklanmaktadır.

Önkoşullar

Genie API'sini kullanmak için aşağıdakilere sahip olmanız gerekir:

  • Databricks SQL yetkilendirmesiyle Azure Databricks çalışma alanına erişim.
  • En azından SQL pro veya sunucusuz SQL ambarında CAN USE ayrıcalıkları.

Başlangıç Yapmak

Azure Databricks kimlik doğrulamayı yapılandırma

Tarayıcı erişimi olan bir kullanıcının mevcut olduğu üretim ortamlarında kullanıcılar için OAuth (OAuth U2M) kullanın. Tarayıcı tabanlı kimlik doğrulamasının mümkün olmadığı durumlarda, API ile kimlik doğrulaması yapmak için bir hizmet sorumlusu kullanın. Bkz Hizmet temsilcileri için OAuth (OAuth M2M). Hizmet sorumlularının gerekli verilere ve SQL ambarlarına erişme izinleri olmalıdır.

Ayrıntıları toplama

  • Çalışma alanı örneği adı: Databricks çalışma alanı URL'nizden çalışma alanı örneği adınızı bulun ve kopyalayın. URL'nizdeki çalışma alanı tanımlayıcıları hakkında ayrıntılı bilgi için bkz. Çalışma alanı nesneleri için tanımlayıcıları alma.

    Örnek: https://cust-success.cloud.databricks.com/

  • Ambar Kimliği: En azından CAN USE ayrıcalıklarına sahip olduğunuz bir SQL ambarının kimliğine ihtiyacınız vardır. Ambar kimliğinizi bulmak için:

    1. Çalışma alanınızdaki SQL Ambarları'na gidin.
    2. Kullanmak istediğiniz ambarı seçin.
    3. URL'den veya ambar ayrıntıları sayfasından ambar kimliğini kopyalayın.

    Alternatif olarak, erişim izinlerine sahip olduğunuz tüm SQL ambarlarının listesini program aracılığıyla almak için Liste ambarları uç noktasınıGET /api/2.0/sql/warehouses kullanın. Yanıt, ambar kimliğini içerir.

Genie alanı oluşturun veya seçin

İyi yapılandırılmış bir Genie alanı aşağıdaki özelliklere sahiptir:

  • İyi açıklamalı veriler kullanır: Genie, tablo meta verilerine ve sütun açıklamalarına dayanır. Unity Kataloğu veri kaynaklarınızın açık ve açıklayıcı açıklamaları olduğunu doğrulayın.
  • Kullanıcı test edildi mi: Son kullanıcılardan beklediğiniz soruları sorarak alanınızı test edin. Örnek SQL sorguları oluşturmak ve iyileştirmek için test yapın.
  • Şirkete özgü bağlamı içerir: Yönergeler, örneğin SQL ve işlevler ekleyin. Bkz . SQL örnekleri ve yönergeleri ekleme. Test edilmiş en az beş örnek SQL sorgusu hedefleyin.
  • Doğruluğu test etmek için karşılaştırmaları kullanır: Beklenen kullanıcı sorularına göre en az beş karşılaştırma sorusu ekleyin. Bkz. Genie alanında karşılaştırmaları kullanma.

Alan oluşturma hakkında daha fazla bilgi için bkz. AI/BI Genie alanını ayarlama ve yönetme ve Etkili bir Genie alanı oluşturma.

Yeni bir Genie alanı oluşturabilir veya mevcut bir alanı kullanabilirsiniz:

Yeni alan oluşturma

Genie space API'sini kullanarak program aracılığıyla genie alanı oluşturun. Aşağıdaki örnekte en iyi yöntemleri izleyen iyi yapılandırılmış bir alan gösterilmektedir. Yer tutucuları değerlerinizle değiştirin:

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

Var olan bir alanı kullanma

Zaten bir Genie alanınız varsa, Genie boşluklarını listele API'sini kullanarak alan kimliğini bulabilirsiniz. Ayrıca Genie space Settings (Genie space Settings ) sekmesinden boşluk kimliğini bulabilir ve kopyalayabilirsiniz.

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

API yanıtındaki space_id öğesini sonraki API çağrılarında kullanın.

serialized_space alanını anlama

Alanı serialized_space , Genie alanınız için yapılandırmayı ve veri kaynaklarını tanımlayan bir JSON dizesidir. API isteğinde, bu JSON bir dize olarak escape edilmelidir. Alanı aşağıdakileri içerir:

  • sürüm: Geriye dönük uyumluluk için şema sürüm numarası. Aşağıdaki örnekte gösterildiği gibi kullanın 2 .
  • yapılandırma: Aşağıdakiler dahil olmak üzere alan yapılandırması:
    • sample_questions: Kullanıcılara yol gösterecek örnek sorular. Her soru bir kimlik (32 karakterlik onaltılık dize) ve soru (dize dizisi) gerektirir.
  • data_sources: Alan için kullanılabilir veri kaynakları:
    • tablolar: Tanımlayıcı (üç düzeyli ad alanı), isteğe bağlı açıklama ve isteğe bağlı column_configs içeren tablo nesneleri dizisi.
    • metric_views: Ölçüm görünümü nesnelerinin dizisi (tablolarla aynı yapı).
  • yönergeler: Alan için yapılandırılmış yönergeler:
    • text_instructions: LLM için üst düzey yönergeler.
    • example_question_sqls: İsteğe bağlı olarak parametreler ve usage_guidance ile SQL yanıtları içeren örnek sorular.
    • sql_functions: Alana sağlanan SQL işlevlerine başvurular.
    • join_specs: Tablolar arasında önceden tanımlanmış birleştirme ilişkileri.
    • sql_snippets: Yeniden kullanılabilir filtreler, ifadeler ve ölçüler.
  • benchmarks: Her birinin bir gerçek SQL yanıtıyla alan/ortam kalitesini değerlendirmeye yönelik sorular.

Alan oluşturma örneğinden serialized_space alanının kaçış karakterleri kaldırılmış sürümü şöyle görünür:

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

Alanınızı oluştururken bu JSON yapısını oluşturun ve API isteği için bu yapıyı dize haline getirin. Şema ayrıntılarının tamamı için Genie space API'sini oluşturma başvurusuna bakın.

serialized_space için doğrulama kuralları

JSON aşağıdaki serialized_space doğrulama kurallarına uymalıdır. Geçerli olmayan JSON, alan oluşturma veya güncelleştirme sırasında reddedilir.

Sürüm

  • Sürüm alanı: Gerekli. Yeni alanlar için kullanın 2 . Sürüm numarası geriye dönük uyumluluk için var.

Kimlik biçimi

Tüm Kimlik alanları 32 karakterlik küçük harf onaltılık dizeler (kısa çizgi içermeyen UUID biçimi) olmalıdır.

  • Geçerli: a1b2c3d4e5f60000000000000000000a
  • Geçerli değil: a1b2c3d4e5f6 (çok kısa), A1B2C3D4E5F60000000000000000000A (büyük harf), a1b2c3d4-e5f6-0000-0000-00000000000a (kısa çizgi içeriyor)

Kimlikler şunlar için gereklidir:

  • 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 (karşılaştırmalar dahilse)

Sıralama gereksinimleri

Kimlik veya tanımlayıcı içeren koleksiyonlar önceden sıralanmalıdır. Sistem, dizilerin zaten sıralandığını doğrular ve sıralanmamış girişleri reddeder.

Collection Sıralama tuşu
data_sources.tables identifier (alfabetik olarak)
data_sources.metric_views identifier (alfabetik olarak)
data_sources.tables[].column_configs column_name (alfabetik olarak)
data_sources.metric_views[].column_configs column_name (alfabetik olarak)
config.sample_questions id (alfabetik olarak)
instructions.text_instructions id (alfabetik olarak)
instructions.example_question_sqls id (alfabetik olarak)
instructions.sql_functions (id, identifier) küme (alfabetik olarak)
instructions.join_specs id (alfabetik olarak)
instructions.sql_snippets.filters id (alfabetik olarak)
instructions.sql_snippets.expressions id (alfabetik olarak)
instructions.sql_snippets.measures id (alfabetik olarak)
benchmarks.questions id (alfabetik olarak)

Benzersizlik kısıtlamaları

  • Soru Kimlikleri: config.sample_questions ve benchmarks.questions içindeki tüm kimlikler, her iki koleksiyon genelinde benzersiz olmalıdır.
  • Yönerge Kimlikleri: text_instructions, example_question_sqls, sql_functions, join_specs ve tüm sql_snippets türleri boyunca kimlikler benzersiz olmalıdır.
  • Sütun yapılandırmaları: (table_identifier, column_name) kombinasyonu alan içinde benzersiz olmalıdır.

Boyut ve uzunluk sınırları

  • Dize uzunluğu: Tek tek dize öğeleri 25.000 karakterle sınırlıdır.
  • Dizi boyutu: Yinelenen alanlar 10.000 öğeyle sınırlıdır.
  • Metin yönergeleri: Boşluk başına en fazla 1 metin yönergesi kullanılmasına izin verilir.
  • Tablolar ve ölçüm görünümleri: Çalışma alanına özgü sınırlara tabidir.
  • SQL içeriği: ve sql alanlarındaki join_specs.sql sorgu metni uzunluk sınırlarına tabidir.

Diğer gereksinimler

  • Tablo tanımlayıcıları: Üç düzeyli ad alanı biçimi (catalog.schema.table) kullanılmalıdır.
  • Karşılaştırma yanıtları: Her karşılaştırma sorusunun biçimi SQL olarak ayarlanmış tam olarak bir yanıtı olmalıdır.
  • SQL kod parçacıkları: Filtre, ifade ve ölçü SQL alanları boş olmamalıdır.

Konuşma API'sini kullanma

Genie alanını yapılandırdıktan sonra, soru sormak, sonuçları almak ve bağlamla çok aşamalı konuşmaları sürdürmek için konuşma API'sinin uç noktalarını kullanın.

Konuşma başlatma

Konuşma başlatma uç noktasıPOST /api/2.0/genie/spaces/{space_id}/start-conversation Genie alanınızda yeni bir konuşma başlatır.

Yer tutucuları Databricks örneğinle, Genie alan kimliğiyle ve kimlik doğrulama belirteciyle değiştirin. başarılı bir yanıt örneği isteği izler. İzleme soruları için bu konuşmaya yeniden erişmek için kullanabileceğiniz ayrıntıları içerir.

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
  }
}

Oluşturulan SQL'i alma

İletinin oluşturma durumunu denetlemek ve oluşturulan SQL'i Genie'den çekmek için yoklamadaki yanıtta conversation_id ve message_id kullanın. tam istek ve yanıt ayrıntıları için bkz GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} .

Uyarı

Yalnızca POST istekler dakika başına sorgu aktarım hızı sınırına doğru sayılır. GET sonuçları yoklamada kullanılan istekler bu sınıra tabi değildir.

Değerlerinizi aşağıdaki istekle değiştirin:

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

Aşağıdaki örnek yanıt ileti ayrıntılarını bildirir:

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
}

status alanı COMPLETED olduğunda yanıt attachments dizisine doldurulur.

Sorgu sonuçlarını alma

Dizi attachments Genie'nin yanıtını içerir. Oluşturulan metin yanıtını (text ), varsa sorgu deyimini ()query ve ilişkili sorgu sonuçlarını (attachment_id almak için kullanabileceğiniz bir tanımlayıcıyı içerir. Oluşturulan sorgu sonuçlarını almak için aşağıdaki örnekte yer tutucuları değiştirin:

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

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

takip soruları sorun

Yanıt aldıktan sonra, konuşmayı conversation_id kullanarak sürdürün. Önceki iletilerden gelen bağlam korunur ve izleme yanıtlarında kullanılır. İstek ve yanıt ayrıntılarının tamamı için bkz 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?",
}

Alan ve konuşma verilerini geri alma

Genie API,mevcut alanlardan ve konuşmalardan yapılandırma ve geçmiş verileri almak için ek uç noktalar sağlar.

Alan yapılandırmasını alma

Get Genie Space API'sini kullanarak alan bilgilerini alırken, parametresini serialized_space olarak ayarlayarak alanı yanıta include_serialized_spacetrueekleyebilirsiniz. alanı serialized_space , yönergeler, karşılaştırmalar, birleştirmeler ve diğer yapılandırma ayrıntıları dahil olmak üzere Genie alanının serileştirilmiş dize gösterimini içerir.

Genie alanlarını çalışma alanları arasında yükseltmek veya alan yapılandırmalarının yedeklerini oluşturmak için Genie Space API'sini Oluşturma ve Genie Space API'sini Güncelleştirme ile bu serileştirilmiş gösterimi kullanın.

Örnek GET istek:

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>",
  "created_timestamp": 1719769718,
  "last_updated_timestamp": 1719769718,
  "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\"]}]}}}"
}

Eski konuşma yazışmalarına başvurma

Kullanıcıların eski konuşma yazışmalarına başvurmasına izin vermek için Konuşma iletilerini listele uç noktasınıGET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages kullanarak belirli bir konuşma yazışmasından tüm iletileri alın.

Analiz için konuşma verilerini alma

Alan yöneticileri, bir alanın tüm kullanıcıları tarafından analiz için istenen tüm önceki iletileri program aracılığıyla alabilir. Bu verileri almak için:

  1. GET /api/2.0/genie/spaces/{space_id}/conversations Mevcut tüm konuşma iş parçacıklarını bir alana almak için uç noktayı kullanın.
  2. Döndürülen her konuşma kimliği için uç noktayı kullanarak GET /api/2.0/genie/spaces/{space_id}/conversations bu konuşmaya ilişkin iletilerin listesini alın.

En iyi yöntemler ve sınırlar

Genie API'sini kullanmaya yönelik en iyi yöntemler

Genie API'sini kullanırken performansı ve güvenilirliği korumak için:

  • Üstel geri alma ile yeniden deneme mantığını uygulayın: API sizin için başarısız istekleri yeniden denemez, bu nedenle kendi kuyruğa alma ve üstel geri alma işleminizi ekleyin. Bu, uygulamanızın geçici hataları işlemesini, gereksiz yineleme isteklerinden kaçınmasını ve büyüdükçe aktarım hızı sınırları içinde kalmasına yardımcı olur.
  • API yanıtlarını günlüğe kaydet: Hata ayıklama, kullanım örüntülerini izleme ve maliyetleri takip etme konularında yardımcı olmak için API istek ve yanıtlarını kapsamlı bir şekilde kayıt altına alın.
  • Durum güncelleştirmelerini her 1-5 saniyede bir yoklama:COMPLETED, FAILED, veya CANCELLED gibi kesin bir ileti durumu alınana kadar yoklama işlemine devam edin. Çoğu sorgu için yoklamayı 10 dakika ile sınırlayın. 10 dakika sonra kesin yanıt yoksa yoklamayı durdurun ve zaman aşımı hatası döndürin veya kullanıcıdan sorgu durumunu daha sonra el ile denetlemesini iste.
  • Yoklama için üstel geri alma kullanın: Yoklamalar arasındaki gecikmeyi en fazla bir dakikaya kadar artırın. Bu, uzun süre çalışan sorgular için gereksiz istekleri azaltırken hızlı sorgular için düşük gecikme süresi sağlar.
  • Her oturum için yeni bir konuşma başlatın: İstenmeyen bağlamın yeniden kullanılması nedeniyle doğruluğu azaltabildiğinden konuşma iş parçacıklarını oturumlar arasında yeniden kullanmaktan kaçının.
  • Konuşma sınırlarını koruyun: Eski konuşmaları yönetmek ve 10.000 konuşma sınırının altında kalmak için:
    1. GET /api/2.0/genie/spaces/{space_id}/conversations Var olan tüm konuşma iş parçacıklarını bir alanda görmek için uç noktayı kullanın.
    2. Eski konuşmalar veya test konuşmaları gibi artık gerekli olmayan konuşmaları belirleyin.
    3. Konuşmaları DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} program aracılığıyla kaldırmak için uç noktayı kullanın.
  • Sorgu sonucu sınırına dikkat edin: Genie API,sorgu sonucu başına en fazla 5.000 satır döndürür. Veri analiziniz daha fazla satır gerektiriyorsa, belirli bir veri alt kümesine odaklanmak için sorunuzu iyileştirmeyi veya sonuçları daraltmak için filtreleri kullanmayı göz önünde bulundurun.

Aktarım hızı sınırı

Genel Önizleme döneminde Genie API ücretsiz katmanı için aktarım hızı en iyi çabayı gösterir ve sistem kapasitesine bağlıdır. Normal veya düşük trafik koşulları altında API, istekleri çalışma alanı başına dakikada 5 sorguyla sınırlar. Yoğun kullanım dönemlerinde sistem, istekleri kullanılabilir kapasiteye göre işler ve bu da daha düşük aktarım hızına neden olabilir.

Alanı gözlemle

Uygulamanız ayarlandıktan sonra Databricks kullanıcı arabiriminde soruları ve yanıtları izleyebilirsiniz.

Kullanıcılara, sorma olasılığı olan soru türleri ve aldıkları yanıtlar hakkında bilgi edinmek için alanı test etmelerini teşvik edin. Kullanıcılara alanı test etmeye başlamalarına yardımcı olacak yönergeler sağlayın. Soruları ve yanıtları görüntülemek için İzleme sekmesini kullanın. Bkz Monitor the space.

Genie alanında etkinliği izlemek için denetim günlüklerini de kullanabilirsiniz. AI/BI Genie olaylarına bkz..

  • Last updated on