Adicionar um recurso de serviço de modelo Unity Gateway a um aplicativo Databricks

Importante

Esse recurso está em Visualização Pública.

Adicione serviços de modelos Unity Gateway como recursos do Databricks Apps para que seu app possa enviar requisições de inferência, incluindo chat, completions e embeddings, para modelos de IA governados no Unity Catalog. Os serviços de modelo do Unity Gateway incluem modelos fundamentais pay-per-token disponíveis em system.ai, assim como serviços de modelo que você cria.

Note

A atribuição de uso para serviços de modelos Unity Gateway é precisa apenas para Apps do Databricks padrão. Aplicativos que rodam em um ambiente de micro VM, como os aplicativos do Genie app builder, não reportam atribuição precisa de uso.

Veja Acompanhamento de Uso do Gateway Unity.

Requisitos de privilégio

Para acessar um serviço de modelo do Unity Gateway, o principal de serviço do aplicativo deve ter o privilégio USE CATALOG no catálogo pai, o privilégio USE SCHEMA no esquema pai e o privilégio EXECUTE no serviço de modelo. Quando você adiciona o recurso de serviço de modelo, o Azure Databricks automaticamente concede esses privilégios à entidade de serviço do aplicativo.

Para que essa concessão automática seja bem-sucedida, um dos seguintes deve ser verdadeiro para cada privilégio:

  • Para USE CATALOG: ou todos os usuários da conta têm o privilégio USE CATALOG no catálogo ou você tem o privilégio MANAGE no catálogo.
  • Para USE SCHEMA: Ou todos os usuários da conta possuem o privilégio USE SCHEMA no esquema, ou você possui o privilégio MANAGE no esquema.
  • Para EXECUTE: Ou todos os usuários da conta têm privilégio EXECUTE no serviço modelo, ou você tem o MANAGE privilégio no serviço modelo.

Consulte Referência de privilégios do Catálogo do Unity.

Adicionar um recurso de serviço do modelo Unity Gateway

Antes de adicionar um serviço modelo Unity Gateway como recurso, revise os pré-requisitos de recursos do app.

  1. Na seção Recursos do aplicativo, ao criar ou editar um aplicativo, clique em + Adicionar recurso>Modelo.
  2. No seletor de recursos, selecione um serviço de modelo da seção Unity Gateway. O seletor também lista endpoints de serviço personalizados sob uma seção de Endpoints de Serviço . Para conectar um desses endpoints, veja Adicionar um recurso de endpoint de disponibilização de modelo a um aplicativo Databricks. Para usar um modelo de base de pagamento por token, selecione um serviço de modelo no catálogo system.ai.
  3. Selecione o nível de permissão do aplicativo:
    • Pode executar: Concede ao principal de serviço do aplicativo o privilégio EXECUTE de enviar solicitações de inferência para o serviço de modelo. Este é o único nível de permissão disponível para um serviço de modelo.
  4. (Opcional) Especifique uma chave de recurso personalizada, que é como você referencia o serviço de modelo na configuração do seu app. A chave padrão é model.

Configurar com Pacotes de Recursos do Databricks

Se você definir seu aplicativo usando Pacotes de Automação Declarativa, adicione o serviço de modelo como um recurso uc_securable na configuração do seu pacote:

resources:
  apps:
    my_app:
      name: 'my-app'
      source_code_path: ./app
      resources:
        - name: 'model'
          uc_securable:
            securable_full_name: '<catalog>.<schema>.<model_service>'
            securable_type: 'MODEL_SERVICE'
            permission: 'EXECUTE'

Para informações sobre recursos de aplicativos em Pacotes de Automação Declarativa, veja app.resources.

Variáveis de ambiente

Ao implantar um aplicativo com um recurso de serviço de modelo do Unity Gateway, o Azure Databricks expõe o nome completo de três partes do Catálogo do Unity do serviço de modelo por meio de variáveis de ambiente que você pode referenciar usando o campo valueFrom.

Configuração de exemplo:

env:
  - name: MODEL_SERVICE_NAME
    valueFrom: model # Use your custom resource key if you set one

O campo valueFrom é resolvido para o nome completo de três partes do Unity Catalog do serviço de modelo (por exemplo, system.ai.databricks-dbrx-instruct). Use esse nome ao chamar o serviço de modelo pelo Azure Databricks SDK ou pela API REST do Unity Gateway.

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

Remover um recurso do serviço de modelo do Unity Gateway

Ao remover um recurso de serviço de modelo do Unity Gateway de um aplicativo, a entidade de serviço do aplicativo perde o privilégio EXECUTE no serviço de modelo. O serviço modelo em si permanece inalterado e continua disponível para outros usuários e aplicativos que possuem as permissões apropriadas.

Práticas recomendadas

Considere o seguinte ao trabalhar com recursos do serviço de modelo Unity Gateway:

  • EXECUTE é o único nível de permissão disponível. Ele concede ao aplicativo acesso para enviar requisições de inferência e não concede privilégios administrativos no serviço de modelo.
  • Para usar modelos de fundação pay-per-token sem configuração adicional, selecione um serviço de modelo do system.ai catálogo.
  • A variável de ambiente resolve para o nome completo do Catálogo Unity em três partes (catalog.schema.model_service). Use este valor ao chamar o serviço de modelo através do Azure Databricks SDK ou da API REST.
  • Gerencie erros de inferência e limites de taxa no código do seu app. O Unity Gateway impõe os limites de taxa e as proteções configuradas em cada serviço de modelo.
  • O seletor de recursos Model também lista os endpoints clássicos de serving de modelo, agrupados na seção Serving Endpoints. Serviços de modelo e endpoints de atendimento podem coexistir no mesmo app.
  • Última atualização em