Adicionar um recurso do Genie Space a um aplicativo do Databricks

Adicione o Genie Spaces como recurso dos Aplicativos Databricks para habilitar a consulta em linguagem natural nos seus aplicativos. O Genie Spaces fornece 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 Genie Space 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
• Utilize consultas de exemplo e definições de dados curadas
• Gerar respostas com base nos conjuntos de dados da sua organização

Adicionar um recurso do Genie Space

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

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

Quando você adiciona um recurso do Genie Space:

• Azure Databricks concede ao service principal do seu aplicativo as permissões especificadas no Genie Space selecionado.
• O aplicativo pode enviar consultas em linguagem natural para o ambiente e receber respostas estruturadas com consultas SQL e resultados.
• O aplicativo acessa o contexto comercial curado do espaço, incluindo metadados, consultas amostrais e definições de dados.
• O acesso é restrito apenas ao espaço selecionado. Seu aplicativo não pode acessar outros Genie Spaces, a menos que você os adicione como recursos separados.

Variáveis de ambiente

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

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 do Genie Space

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

Combinar o Genie Spaces com outros recursos de aplicativo

Combine o Genie Spaces 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 do principal de serviço

Conceda ao principal de serviço do aplicativo as seguintes permissões ao integrar-se a outros recursos do aplicativo:

• CAN RUN no Espaço do Gênio
• CAN USE no SQL Warehouse (se estiver usando um separado do Genie Space)
• CAN QUERY em endpoints de serviço de modelagem
• USE CATALOG e USE SCHEMA em objetos relevantes do Catálogo Unity
• SELECT em tabelas que o aplicativo consulta diretamente

Práticas recomendadas

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

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