Adicionar um recurso de espaço do Genie a um aplicativo do Databricks

Adicione espaços Genie de IA/BI como recursos do Databricks Apps para habilitar a consulta de linguagem natural em seus aplicativos. Os espaços do Genie fornecem uma interface de conversa para exploração de dados, permitindo que os usuários façam perguntas comerciais em inglês sem formatação e recebam insights baseados em SQL de seus conjuntos de dados coletados.

Quando você adiciona um espaço do Genie como um recurso, seu aplicativo pode:

• Converter consultas de linguagem natural de usuários em SQL
• Acessar o contexto de negócios pré-configurado e os metadados
• Usar consultas de exemplo e definições de dados com curadoria
• Gerar respostas com base nos conjuntos de dados da sua organização

Adicionar um recurso de espaço do Genie

Antes de adicionar um espaço do Genie como um recurso, examine os pré-requisitos do recurso de aplicativo.

1. Ao criar ou editar um aplicativo, navegue até a etapa Configurar.
2. Na seção Recursos do aplicativo, clique em + Adicionar recurso.
3. Selecione o espaço do Genie como o tipo de recurso.
4. Escolha um espaço do Genie na lista de espaços disponíveis em seu workspace.
5. Selecione o nível de permissão do aplicativo:
   • Pode exibir: Concede ao aplicativo permissão para ler a configuração e os metadados de espaço do Genie.
   • Pode executar: Concede ao aplicativo permissão para enviar consultas ao espaço do Genie e receber respostas.
   • Pode editar: Concede permissão ao aplicativo para modificar a configuração de espaço do Genie.
   • Pode gerenciar: Concede ao aplicativo acesso administrativo completo ao espaço do Genie.
6. (Opcional) Especifique uma chave de recurso personalizada, que é como você faz referência ao espaço do Genie na configuração do aplicativo. A chave padrão é genie-space.

Quando você adiciona um recurso de espaço do Genie:

• O Azure Databricks concede à entidade de serviço do aplicativo as permissões especificadas no espaço do Genie selecionado.
• O aplicativo pode enviar consultas de linguagem natural para o espaço e receber respostas estruturadas com consultas e resultados do SQL.
• O aplicativo acessa o contexto comercial coletado do espaço, incluindo metadados, consultas de exemplo e definições de dados.
• O acesso tem como escopo apenas o espaço selecionado. Seu aplicativo não pode acessar outros espaços do Genie, a menos que você os adicione como recursos separados.

Variáveis de ambiente

Quando você implanta um aplicativo com um recurso de espaço do Genie, o Azure Databricks expõe a ID de espaço por meio de variáveis de ambiente que você pode referenciar usando o valueFrom campo em sua app.yaml configuração.

Configuração de exemplo:

env:
  - name: GENIE_SPACE_ID
    valueFrom: genie-space # Use your custom resource key if different

Usando a ID de espaço em seu aplicativo:

import os
from databricks.sdk import WorkspaceClient

# Access the Genie space using the injected environment variable
space_id = os.getenv("GENIE_SPACE_ID")

# Initialize the workspace client
w = WorkspaceClient()

# Start a conversation with a natural language query
response = w.genie.start_conversation_and_wait(
    space_id=space_id,
    content="What were our top-selling products last quarter?"
)

# Process the response (responses contain attachments with text, queries, and so on)
for attachment in response.attachments:
    print(f"Genie response: {attachment.text.content}")

# Continue the conversation with additional questions
follow_up = w.genie.create_message_and_wait(
    space_id=space_id,
    conversation_id=response.conversation_id,
    content="Can you break that down by product category?"
)

Para obter mais informações, consulte Como acessar variáveis de ambiente dos recursos.

Remover um recurso de espaço do Genie

Quando você remove um recurso de espaço do Genie de um aplicativo, a entidade de serviço do aplicativo perde o acesso ao espaço. O próprio espaço do Genie permanece inalterado e continua disponível para outros usuários e aplicativos que têm permissões apropriadas.

Combinar espaços do Genie com outros recursos de aplicativo

Combine espaços do Genie com outros recursos do Databricks Apps para criar aplicativos de dados mais sofisticados. Os padrões comuns de integração incluem:

Painel de análise de linguagem natural

Use os seguintes recursos juntos para executar análises interativas:

• Espaço do gênio: Converte perguntas do usuário em consultas SQL
• SQL Warehouse: Executa as consultas e retorna resultados para visualização
• Segredos: Armazena chaves de API para ferramentas de visualização externas

Configuração de exemplo:

env:
  - name: GENIE_SPACE_ID
    valueFrom: genie-space
  - name: SQL_WAREHOUSE_ID
    valueFrom: sql-warehouse
  - name: EXTERNAL_API_KEY
    valueFrom: viz-secret

Business Intelligence aprimorado por IA

Use os seguintes recursos para se integrar aos modelos de IA:

• Espaço do gênio: Gera a consulta inicial e o contexto de dados
• Ponto de extremidade de serviço de modelo: Retorna resumos e recomendações gerados por IA
• SQL Warehouse: Executa consultas analíticas complexas

Permissões da entidade de serviço

Conceda à entidade de serviço do aplicativo as seguintes permissões ao integrar com outros recursos do aplicativo:

• CAN RUN no espaço do Genie
• CAN USE no SQL Warehouse (se estiver usando um separado do espaço do Genie)
• CAN QUERY em pontos de extremidade de serviço de modelo
• USE CATALOG e USE SCHEMA em objetos relevantes do Catálogo do Unity
• SELECT em tabelas que o aplicativo consulta diretamente

Práticas recomendadas

Siga estas práticas recomendadas ao trabalhar com recursos espaciais do Genie:

• Conceda permissões mínimas. Forneça apenas acesso aos espaços específicos do Genie que seu aplicativo precisa para funcionar.
• Verifique se o espaço do Genie contém conjuntos de dados bem coletados e metadados para melhorar a qualidade das respostas de consulta de linguagem natural.
• Teste as consultas do aplicativo no espaço do Genie para validar se ele pode gerar resultados precisos para perguntas esperadas do usuário.
• Monitore o desempenho da consulta e ajuste os padrões de interação do aplicativo com o espaço do Genie para otimizar os tempos de resposta.
• Implemente o tratamento de erros para casos em que o espaço do Genie não possa interpretar ou responder a consultas de usuário efetivamente.