Pular para o conteúdo principal

Criar e gerenciar provedores com Serviços de Provedor de Modelos

Saiba como registrar um provedor como um serviço de provedor de modelo, conceder acesso a ele, configurar os recursos do Unity Gateway e excluí-lo.

Requisitos​

  • CREATE SERVICE no esquema onde você cria o serviço de provedor de modelo, além de USE CATALOG e USE SCHEMA em seu catálogo e esquema.
  • As credenciais para o provedor externo que você deseja registrar (por exemplo, uma key de API OpenAI ou um par de keys de acesso AWS).
  • Para autenticar o Google Gemini Enterprise com uma credencial de serviço em vez de uma API key, você deve ter uma credencial de serviço existente e ACCESS nela. Consulte Autenticar o Google Gemini Enterprise com uma credencial de serviço.

Para dar suporte a uma credencial de provedor com um segredo do Unity Catalog de propriedade do cliente em vez de armazenar o valor embutido, você deve ter um segredo existente do Unity Catalog e READ SECRET nele. Consulte Dar suporte a uma credencial de provedor com um segredo do Unity Catalog.

Criar um serviço de provedor de modelos​

Os serviços de provedor de modelos e os serviços de modelos compartilham um único namespace de nome em um esquema do Unity Catalog. Não é possível usar um nome para um serviço de provedor de modelos se um serviço de modelos no esquema já o usa, e vice-versa.

Create a model provider service in the Unity Gateway UI or Catalog Explorer. To create one programmatically, use the REST API, the Databricks SDKs, the Databricks CLI, Terraform, or Declarative Automation Bundles (DABs).

  1. Siga um destes procedimentos:

    • Na barra lateral do workspace, clique em AI Gateway , abra a tab Providers e clique em Provider .
    • No Catalog Explorer, vá para o esquema onde você deseja criar o serviço de provedor de modelos, clique em Create > Service e, em seguida, selecione Model provider service na caixa de diálogo Create a service .
  2. Insira um nome para o serviço de provedor de modelos e selecione o catálogo e o esquema para criá-lo. Se você começar do Catalog Explorer, o Catalog Explorer preencherá o catálogo e o esquema automaticamente.

  3. Selecione o tipo de provedor e insira os detalhes de conexão e as credenciais do provedor.

  4. Clique em Criar . A Databricks criptografa e armazena as credenciais. A IU não os exibe a partir deste ponto.

Para obter a lista completa de provedores e seus métodos de autenticação, consulte Provedores de modelo externos ao Databricks.

Autenticar o Google Gemini Enterprise com uma credencial de serviço​

Você pode autenticar um provedor Google Gemini Enterprise com uma credencial de serviço em vez de armazenar uma API key. Uma credencial de serviço contém uma conta de serviço do Google Cloud que o Unity Catalog gerencia, portanto, nenhuma chave de API de longa duração é copiada para o serviço do provedor de modelo: o Databricks obtém tokens de curta duração dessa conta de serviço para autenticar cada solicitação.

Crie o serviço de provedor de modelos conforme descrito em Criar um serviço de provedor de modelos. Selecione Google Gemini Enterprise como o tipo de provedor e insira seus detalhes de conexão, incluindo o ID do projeto GCP e a região. Em seguida, defina o Auth method como Serviço credential e selecione a credencial em vez de inserir uma chave de API. Uma credencial de serviço substitui apenas o segredo, portanto, o ID do projeto GCP e a região ainda são necessários.

Confirme os seguintes requisitos:

  • O proprietário do serviço de provedor de modelos tem ACCESS na credencial de serviço. Como o Databricks verifica novamente o acesso do proprietário ao atender a solicitações, o proprietário deve mantê-lo enquanto o provedor estiver em uso. A revogação interrompe as queries para todos, até mesmo para os chamadores que possuem EXECUTE no provedor. Para conceder ao proprietário acesso à credencial:

    SQL
    GRANT ACCESS ON SERVICE CREDENTIAL <service-credential-name> TO `<model-provider-service-owner>`;
  • O propósito da credencial é serviço , não armazenamento.

  • A credencial está disponível nos workspaces de onde as solicitações se originam. Suas associações de workspace ainda se aplicam, portanto, uma solicitação de um workspace ao qual a credencial não está associada falhará lá, embora o serviço de provedor de modelo em si seja acessível a partir de qualquer workspace que compartilhe a metastore.

  • A service account do Google Cloud da credencial de serviço está autorizada a chamar os modelos do Gemini que você planeja query. Para criar uma credencial de serviço, consulte Create service credentials.

Os chamadores que fazem query no provedor precisam das mesmas concessões que para qualquer outro provedor. Eles não precisam de nenhum privilégio na credencial de serviço, o que mantém a própria credencial fora do alcance deles.

O serviço de provedor de modelo rastreia uma credencial por seu identificador interno, portanto, você pode renomear uma credencial sem falha na query.

Se você excluir uma credencial, as queries falharão e não haverá aviso de que um serviço de provedor de modelos faz referência a ela. Confirme se não há referências a esta credencial antes de excluí-la.

Não é possível alternar um serviço de provedor de modelo existente entre a autenticação por credencial de serviço e a autenticação por chave de API. Crie um novo serviço de provedor de modelo.

Enviar uma chave de API de provedor personalizada em um cabeçalho​

Um provedor personalizado envia sua API key como um token do portador por default. Quando seu Endpoint espera a key em um cabeçalho específico, use a autenticação de cabeçalho de key de API e nomeie o cabeçalho você mesmo. O Databricks então envia a chave em cada solicitação de saída como <header name>: <header value>.

Crie o serviço de provedor de modelos conforme descrito em Criar um serviço de provedor de modelos. Selecione Custom como o tipo de provedor, defina Auth method como API key header e forneça o Header name que seu endpoint espera (como X-API-Key ou Ocp-Apim-Subscription-Key) junto com o Header value .

Os dois métodos são mutuamente exclusivos: um provedor personalizado usa um token do portador ou um cabeçalho nomeado, não ambos. A autenticação de cabeçalho aceita exatamente um cabeçalho.

O nome do cabeçalho deve ser um nome de cabeçalho HTTP válido: letras, dígitos e os caracteres !#$%&'*+-.^_`|~, até 255 caracteres. Qualquer outro caractere é rejeitado, incluindo espaços, dois-pontos, barras e quebras de linha.

Dar suporte a uma credencial de provedor com um segredo do Unity Catalog​

Em vez de armazenar a credencial de um provedor embutida, você pode apontar um serviço de provedor de modelo para um Unity Catalog secret de propriedade do cliente que contenha o valor. O Databricks lê o segredo no momento da query com o acesso do proprietário do serviço de provedor de modelo e nunca copia o valor para o serviço de provedor de modelo, de modo que a rotação do segredo entra em vigor sem nenhuma alteração no serviço de provedor de modelo.

Isso funciona para qualquer provedor cuja credencial seja um único valor embutido: OpenAI, Azure OpenAI, Anthropic, Amazon Bedrock, Microsoft Foundry, Google Gemini Enterprise e Personalizado.

Create the model provider serviço as described in Create a model provider serviço. Select the provider type and enter its connection details. For the credential (such as the API key ), change the authentication type from Plaintext to Secret , then select the catalog, schema, and secret that identify your Unity Catalog secret.

Confirme os seguintes requisitos:

  • O proprietário do serviço de provedor de modelo tem READ SECRET no segredo do Unity Catalog. Como o Databricks verifica novamente o acesso do proprietário ao atender a solicitações, o proprietário deve mantê-lo enquanto o provedor estiver em uso. A revogação interrompe as queries para todos, até mesmo para os chamadores que possuem EXECUTE no provedor. Para conceder ao proprietário acesso ao segredo:

    SQL
    GRANT READ SECRET ON SECRET <catalog>.<schema>.<secret> TO `<model-provider-service-owner>`;
  • O segredo do Unity Catalog existe antes de você fazer referência a ele. Para criar e governar segredos do Unity Catalog, consulte Secrets in Unity Catalog.

Os chamadores que fazem query ao provedor precisam das mesmas permissões que para qualquer outro provedor. Eles não precisam de nenhum privilégio no segredo do Unity Catalog, o que impede que o valor do segredo fique ao alcance deles.

Para rotacionar a credencial, atualize o valor do segredo do Unity Catalog, sem alterar o serviço de provedor de modelo.

Se você excluir o secret do Unity Catalog, as queries falharão. O serviço de provedor de modelo mantém a referência agora quebrada para que você possa ver a dependência, e você pode restaurar o provedor atualizando-o para referenciar um secret que ainda existe.

Excluir um serviço de provedor de modelo nunca exclui o segredo do Unity Catalog ao qual ele faz referência.

Conceder acesso a um serviço de provedor de modelos​

Por default, apenas o proprietário do service de provedor de modelo pode fazer query dele. Para permitir que outros façam query de um serviço de provedor de modelo, conceda a eles EXECUTE nele, além de USE CATALOG e USE SCHEMA em seu catálogo e esquema. Se o serviço de provedor de modelo fizer Logs em uma tabela de inferência, conceda SELECT na tabela para permitir que eles leiam as solicitações e respostas registradas.

  1. Abra o serviço de provedor de modelo no Catalog Explorer ou vá para AI Gateway e selecione o serviço.
  2. Vá para a tab Permissões.
  3. Clique em Conceder .
  4. Selecione os usuários, grupos ou Service Principal aos quais deseja conceder acesso.
  5. Selecione o privilégio EXECUTE .
  6. Clique em Conceder .

Para saber mais sobre como conceder e descobrir acesso, consulte Descubra e governe o acesso a provedores de modelos externos (serviços de provedor de modelo).

Configurar recursos​

Como um serviço de provedor de modelo é roteado pelo Unity Gateway, aplique os mesmos recursos de governança e observabilidade que você usa para outros tráfegos do Unity Gateway:

Configurar um multiplicador de preço​

Por default, o Databricks estima o gasto com modelos externos usando os preços de lista publicados pelo provedor. Se os preços do seu provedor forem diferentes, configure um multiplicador de preço para refletir descontos ou margens. Por exemplo, 0.8 usa 80% do preço de lista, enquanto 1.2 usa 120%.

  1. Crie um serviço de provedor de modelo ou abra um serviço de provedor de modelo existente no Catalog Explorer ou no AI Gateway e clique em Editar .
  2. Expanda Opções avançadas .
  3. Insira um multiplicador de preço .
  4. Clique em Criar ou Salvar .

Campo multiplicador de preço em Opções avançadas na caixa de diálogo Criar serviço de provedor de modelo

O multiplicador se aplica a todos os modelos disponíveis por meio do serviço de provedor de modelos. O gasto computado em system.ai_gateway.external_model_spend reflete o multiplicador configurado. As alterações se aplicam às solicitações feitas após a configuração entrar em vigor; as solicitações anteriores continuam sendo estimadas usando o preço de tabela ou o multiplicador configurado anteriormente.

Um multiplicador configurado exibe uma tag de Custom preços . Preços ajustados têm um sublinhado pontilhado nas tabelas de preços. Passe o cursor sobre um preço ajustado para comparar o preço ajustado com o preço de lista do provedor.

Atualizar um serviço de provedor de modelos​

O senhor deve ser um proprietário ou ter MANAGE. O tipo de provedor é imutável.

Edite a configuração do serviço de provedor de modelo na interface do Unity Gateway ou no Explorador de Catálogos. As alterações são aplicadas no local.

Excluir um serviço de provedor de modelos​

Você deve ser um proprietário ou ter MANAGE.

Abra o serviço de provedor de modelo na IU do Unity Gateway ou no Catalog Explorer e selecione Excluir no menu kebab.

Próximos os passos​