다음을 통해 공유

Genie API를 사용하여 Genie를 애플리케이션에 통합

중요합니다

이 기능은 공개 미리보기 단계에 있습니다.

이 페이지에서는 Genie API를 사용하여 사용자 고유의 챗봇, 에이전트 또는 애플리케이션에서 Genie 기능을 사용하도록 설정하는 방법을 설명합니다.

개요

Genie API는 다음 두 가지 유형의 기능을 제공합니다.

  • 대화 API: 애플리케이션, 챗봇 및 AI 에이전트 프레임워크에서 자연어 데이터 쿼리를 사용하도록 설정합니다. 이러한 API는 사용자가 후속 질문을 하고 시간이 지남에 따라 데이터를 자연스럽게 탐색할 수 있는 상태 저장 대화를 지원합니다.
  • 관리 API: 작업 영역에서 Genie 공간을 프로그래밍 방식으로 만들고 구성하고 배포할 수 있습니다. CI/CD 파이프라인, 버전 제어 및 자동화된 공간 관리에 이러한 API를 사용합니다.

이 페이지에서는 대화 및 관리 API를 모두 설명합니다. 대화 API를 호출하기 전에 잘 큐레이팅된 Genie 공간을 준비합니다. 공간은 Genie가 질문을 해석하고 답변을 생성하는 데 사용하는 컨텍스트를 제공합니다. 공간이 불완전하거나 테스트되지 않은 경우에도 사용자는 올바른 API 통합을 통해 잘못된 결과를 받을 수 있습니다. 이 가이드에서는 Genie API와 효과적으로 작동하는 공간을 만드는 데 필요한 최소 설정에 대해 설명합니다.

필수 조건

Genie API를 사용하려면 다음이 있어야 합니다.

  • Databricks SQL 자격을 사용하여 Azure Databricks 작업 영역에 액세스합니다.
  • SQL Pro 또는 서버리스 SQL 웨어하우스에 대한 최소 CAN USE 권한

시작하기

Azure Databricks 인증 구성

브라우저에 액세스할 수 있는 사용자가 있는 프로덕션 사용 사례의 경우 사용자에 대해 OAuth(OAuth U2M)를 사용합니다. 브라우저 기반 인증이 불가능한 경우 서비스 주체를 사용하여 API로 인증합니다. OAuth 서비스 주체(OAuth M2M)를 참조하세요. 서비스 주체는 필요한 데이터 및 SQL 웨어하우스에 액세스할 수 있는 권한이 있어야 합니다.

세부 정보 수집

  • 작업 영역 인스턴스 이름: Databricks 작업 영역 URL에서 작업 영역 인스턴스 이름을 찾아 복사합니다. URL의 작업 영역 식별자에 대한 자세한 내용은 작업 영역 개체에 대한 식별자 가져오기를 참조하세요.

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

  • 웨어하우스 ID: 최소한 CAN USE 권한이 있는 SQL Warehouse의 ID가 필요합니다. 창고 ID를 찾으려면 다음 단계를 따르세요.

    1. 작업 영역 의 SQL Warehouse 로 이동합니다.
    2. 사용하려는 웨어하우스를 선택합니다.
    3. URL 또는 웨어하우스 세부 정보 페이지에서 웨어하우스 ID를 복사합니다.

    또는 목록 웨어하우스 엔드포인트GET /api/2.0/sql/warehouses 를 사용하여 액세스 권한이 있는 모든 SQL 웨어하우스 목록을 프로그래밍 방식으로 검색합니다. 응답에는 웨어하우스 ID가 포함됩니다.

지니 공간 만들기 또는 선택

잘 구성된 지니 공간에는 다음과 같은 특징이 있습니다.

  • 주석이 잘 추가된 데이터를 사용합니다 . Genie는 테이블 메타데이터 및 열 주석을 사용합니다. Unity 카탈로그 데이터 원본에 명확하고 설명적인 주석이 있는지 확인합니다.
  • 사용자 테스트 여부 확인: 최종 사용자가 할 것으로 기대되는 질문을 통해 환경을 테스트하세요. 테스트를 사용하여 예제 SQL 쿼리를 만들고 구체화합니다.
  • 회사별 컨텍스트를 포함합니다. 지침, 예제 SQL 및 함수를 추가합니다. SQL 예제 및 지침 추가를 참조하세요. 테스트된 예제 SQL 쿼리를 5개 이상 목표로 합니다.
  • 벤치마크를 사용하여 정확도를 테스트합니다. 예상 사용자 질문에 따라 5개 이상의 벤치마크 질문을 추가합니다. 지니 공간에서 벤치마크 사용을 참조하세요.

공간을 만드는 방법에 대한 자세한 내용은 AI/BI 지니 공간 설정 및 관리 및 효과적인 지니 공간 큐레이팅을 참조하세요.

새 Genie 공간을 만들거나 기존 공간을 사용할 수 있습니다.

새 공간 만들기

Genie 공간 만들기 API를 사용하여 프로그래밍 방식으로 Genie 공간을 만듭니다. 다음 예제에서는 모범 사례를 따르는 잘 구성된 공간을 보여 줍니다. 자리 표시자를 값으로 바꿉다.

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

기존 공간 사용

지니 공간이 이미 있는 경우 목록 지니 공간 API를 사용하여 공간 ID를 찾을 수 있습니다. 지니 공간 설정 탭에서 공간 ID를 찾아 복사할 수도 있습니다.

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

space_id 후속 API 호출에서 응답에서 사용합니다.

serialized_space 필드를 이해하기

serialized_space 필드는 Genie 공간에 대한 구성 및 데이터 원본을 정의하는 JSON 문자열입니다. API 요청에서 이 JSON은 문자열로 이스케이프되어야 합니다. 필드에는 다음이 포함됩니다.

  • 버전: 스키마 버전(현재 1)

  • 구성: 다음을 포함한 공간 구성:

    • sample_questions: 사용자를 안내하는 예제 질문입니다. 각 질문에는 다음이 필요합니다.

      • id: 질문에 대한 고유 식별자입니다. 고유한 문자열(예: 짧은 영숫자 문자열 또는 UUID)을 생성할 수 있습니다. 시스템은 이러한 식별자를 32자 식별자로 정규화합니다.
      • 질문: 질문 텍스트가 포함된 배열입니다.

      일반적인 사용 사례를 나타내는 5개 이상의 다양한 질문을 포함합니다.

  • data_sources: 다음을 포함하여 공간에서 사용할 수 있는 데이터 원본:

    • tables: 3개 수준 네임스페이스 형식(catalog.schema.table)의 테이블 개체 배열입니다. 각 테이블에는 다음이 포함될 수 있습니다.

      • identifier: 필수입니다. 전체 테이블 이름입니다.
      • description: 선택 사항입니다. 테이블에 대한 설명 텍스트가 포함된 배열입니다.
      • column_configs: 선택 사항입니다. 열 구성 개체로 구성된 배열:
        • column_name: 열 이름입니다.
        • get_example_values: 부울. 이 열의 예제 값을 샘플링할지 여부입니다.
        • build_value_dictionary: 부울 값 (Boolean). 범주 열에 대한 값 사전을 작성할지 여부입니다.

  • 지침: 선택 사항입니다. 다음을 포함한 공간에 대한 구조적 지침:

    • text_instructions: 공간에 대한 텍스트 지침입니다.
    • example_question_sqls: 예제 SQL 쿼리 개체의 배열입니다.
    • join_specs: 테이블 간의 조인 관계를 정의하는 배열입니다.
    • sql_snippets: 필터, 식 및 측정값을 포함하는 개체입니다.

공간 만들기 예제의 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"]
        }
      ]
    }
  }
}

공간을 구성할 때 이 JSON 구조를 생성한 후 API 요청을 위해 문자열로 이스케이프 처리합니다. 전체 스키마 세부 정보는 Genie 공간 만들기 API 참조를 참조하세요.

대화 API 사용

Genie 공간을 구성한 후 대화 API 엔드포인트를 사용하여 질문을 하고, 결과를 검색하고, 컨텍스트를 사용하여 다중 턴 대화를 유지 관리합니다.

대화 시작

대화 시작 엔드포인트POST /api/2.0/genie/spaces/{space_id}/start-conversation는 지니 공간에서 새 대화를 시작합니다.

자리 표시자를 Databricks 인스턴스, Genie 공간 ID 및 인증 토큰으로 바꿉니다. 성공적인 응답의 예는 요청을 따릅니다. 여기에는 후속 질문에 대해 이 대화에 다시 액세스하는 데 사용할 수 있는 세부 정보가 포함되어 있습니다.

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

생성된 SQL 검색

응답에서 conversation_id 및 message_id를 사용하여 메시지의 생성 상태를 확인하고 Genie에서 생성된 SQL을 검색합니다. 전체 요청 및 응답 세부 정보는 참조하세요 GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} .

비고

요청만 POST 분당 쿼리 처리량 제한에 포함됩니다. GET 결과를 폴링하는 데 사용되는 요청은 이 제한의 적용을 받지 않습니다.

값을 다음 요청으로 대체합니다.

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

다음 예제 응답은 메시지 세부 정보를 보고합니다.

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 필드가 COMPLETED일 때, 응답은 attachments 배열에 채워집니다.

쿼리 결과 검색

배열에는 attachments Genie의 응답이 포함됩니다. 여기에는 생성된 텍스트 응답(), 쿼리 문(text있는 경우), 연결된 쿼리 결과(queryattachment_id)를 가져오는 데 사용할 수 있는 식별자가 포함됩니다. 다음 예제의 자리 표시자를 바꿔 생성된 쿼리 결과를 검색합니다.

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

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-result을(를) 참조하세요.

후속 질문하기

응답을 받은 후 대화를 계속하려면 사용합니다 conversation_id . 이전 메시지의 컨텍스트는 유지되며 후속 응답에 사용됩니다. 전체 요청 및 응답 세부 정보는 다음을 참조하세요 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?",
}

공간 및 대화 데이터 검색

Genie API는 기존 공간 및 대화에서 구성 및 기록 데이터를 검색하기 위한 추가 엔드포인트를 제공합니다.

공간 구성 검색

Get Genie Space API를 사용하여 공간 정보를 검색할 때, 매개 변수를 serialized_space로 설정하여 include_serialized_space 필드를 true 응답에 포함할 수 있습니다. 필드에는 serialized_space 지침, 벤치마크, 조인 및 기타 구성 세부 정보를 포함하여 Genie 공간의 직렬화된 문자열 표현이 포함됩니다.

Genie Space API 만들기 및 Genie Space API 업데이트와 함께 직렬화된 표현을 사용하여 작업 영역에서 지니 공간을 승격하거나 공간 구성의 백업을 만듭니다.

요청 예제 GET :

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

이전 대화 스레드 참조

사용자가 이전 대화 스레드를 참조할 수 있도록 하려면 대화 메시지 목록 엔드포인트GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages 를 사용하여 특정 대화 스레드에서 모든 메시지를 검색합니다.

분석을 위한 대화 데이터 검색

공간 관리자는 분석을 위해 공간의 모든 사용자에게 요청된 모든 이전 메시지를 프로그래밍 방식으로 검색할 수 있습니다. 이 데이터를 검색하려면 다음을 수행합니다.

  1. 엔드포인트를 GET /api/2.0/genie/spaces/{space_id}/conversations 사용하여 공간에 있는 모든 기존 대화 스레드를 가져옵니다.
  2. 반환된 각 대화 ID에 대해 엔드포인트를 GET /api/2.0/genie/spaces/{space_id}/conversations 사용하여 해당 대화의 메시지 목록을 검색합니다.

모범 사례 및 제한

Genie API 사용에 대한 모범 사례

Genie API를 사용할 때 성능 및 안정성을 유지하려면 다음을 수행합니다.

  • 지수 백오프를 사용하여 재시도 논리를 구현 합니다. API는 실패한 요청을 다시 시도하지 않으므로 고유한 큐 및 지수 백오프를 추가합니다. 이렇게 하면 애플리케이션이 일시적인 오류를 처리하고 불필요한 반복 요청을 방지하며 증가하는 처리량 제한 내에서 유지됩니다.
  • 로그 API 응답: 디버깅, 사용 패턴 모니터링 및 비용 추적에 도움이 되는 API 요청 및 응답의 포괄적인 로깅을 구현합니다.
  • 1~5초마다 상태 업데이트를 폴링합니다. 와 같은 COMPLETEDFAILEDCANCELLED결정적인 메시지 상태가 수신될 때까지 폴링을 계속합니다. 대부분의 쿼리에 대해 폴링을 10분으로 제한합니다. 10분 후에 결정적인 응답이 없는 경우 폴링을 중지하고 시간 제한 오류를 반환하거나 나중에 쿼리 상태를 수동으로 확인하라는 메시지를 사용자에게 표시합니다.
  • 폴링에 지수 백오프를 사용합니다 . 설문 조사 사이의 지연 시간을 최대 1분까지 늘입니다. 이렇게 하면 장기 실행 쿼리에 대한 불필요한 요청이 줄어들지만 빠른 쿼리에 대한 대기 시간이 짧습니다.
  • 각 세션에 대해 새 대화를 시작 합니다. 의도하지 않은 컨텍스트 재사용으로 인해 정확도가 낮아질 수 있으므로 세션 간에 대화 스레드를 다시 사용하지 마세요.
  • 대화 제한 유지 관리: 이전 대화를 관리하고 대화 제한 10,000개 미만으로 유지하려면 다음을 수행합니다.
    1. 엔드포인트를 GET /api/2.0/genie/spaces/{space_id}/conversations 사용하여 공간에 있는 모든 기존 대화 스레드를 볼 수 있습니다.
    2. 이전 대화 또는 테스트 대화와 같이 더 이상 필요하지 않은 대화를 식별합니다.
    3. 엔드포인트를 DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} 사용하여 프로그래밍 방식으로 대화를 제거합니다.
  • 쿼리 결과 제한에 유의하세요. Genie API는 쿼리 결과당 최대 5,000개의 행을 반환합니다. 데이터 분석에 더 많은 행이 필요한 경우 특정 데이터 하위 집합에 집중하도록 질문을 구체화하거나 필터를 사용하여 결과를 좁히는 것이 좋습니다.

처리량 제한

공개 미리 보기 기간 동안 Genie API 무료 계층의 처리량 속도는 최상의 작업이며 시스템 용량에 따라 달라집니다. 일반 또는 트래픽이 낮은 조건에서 API는 요청을 작업 영역당 분당 5개의 쿼리로 제한합니다. 사용량이 가장 많은 기간 동안 시스템은 사용 가능한 용량에 따라 요청을 처리하므로 처리량이 낮아질 수 있습니다.

공간 모니터링

애플리케이션이 설정되면 Databricks UI에서 질문과 응답을 모니터링할 수 있습니다.

사용자가 질문할 가능성이 있는 질문 유형과 받는 응답에 대해 배울 수 있도록 공간을 테스트하도록 권장합니다. 사용자에게 공간 테스트를 시작하는 데 도움이 되는 지침을 제공합니다. 모니터링 탭을 사용하여 질문과 응답을 볼 수 있습니다. 공간을 모니터링하기를 참조하세요.

감사 로그를 사용하여 지니 공간에서 활동을 모니터링할 수도 있습니다. AI/BI Genie 이벤트를 참조하세요.

  • Last updated on