Criar e gerenciar provedores modelo externos (serviços de provedores modelo)

Registre um provedor de modelo externo como serviço de provedor modelo, conceda acesso a ele, configure recursos do Unity Gateway e delete-o.

Requirements

  • CREATE SERVICE no esquema em que você cria o serviço de provedor de modelo, além de USE CATALOG e USE SCHEMA em seu respectivo catálogo e esquema.
  • As credenciais do provedor externo que você deseja registrar (por exemplo, uma chave de API OpenAI ou um par de chaves de acesso AWS).
  • Para autenticar o Azure OpenAI ou o Microsoft Foundry com uma credencial de serviço em vez de uma chave ou segredo, você precisa de uma credencial de serviço existente e ACCESS nela. Veja: Autenticar Azure OpenAI ou Microsoft Foundry com credencial de serviço.

Crie um serviço modelo de provedor

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

Você pode criar um serviço de provedor de modelo na interface do Unity Gateway ou no Explorador de Catálogos, ou programaticamente com a API REST, os SDKs do Azure Databricks, a CLI do Azure Databricks ou o Terraform.

interface do usuário

  1. Realize um dos seguintes procedimentos:
    • Na barra lateral do workspace, clique em AI Gateway, depois abra a aba Providers e clique em Provider.
    • No Explorador de Catálogo, vá até o esquema onde deseja criar o serviço de provedor de modelo, clique em Criar>Serviço e selecione Serviço de Modelo no diálogo Criar um serviço .
  2. Insira um nome para o serviço do provedor de modelos e selecione o catálogo e o esquema no qual criá-lo. Se você começar no Catalog Explorer, o Catalog Explorer preenche automaticamente o catálogo e o esquema.
  3. Selecione o tipo de provedor e insira os detalhes e credenciais de conexão do provedor.
  4. Clique em Criar. Azure Databricks criptografa e armazena as credenciais. A interface do usuário não os exibe após esse ponto.

API REST

Envie um POST para /api/2.1/unity-catalog/model-provider-services, passando parent e model_provider_service_id como parâmetros de consulta. Defina provider_type e exatamente um bloco de provedor correspondente; targets permite listas dos modelos upstream acessíveis, e os segredos são fornecidos em linha como texto simples:

databricks api post \
  "/api/2.1/unity-catalog/model-provider-services?parent=schemas/main.default&model_provider_service_id=my_provider" \
  --json '{
  "comment": "Routes to a custom OpenAI-compatible provider",
  "config": {
    "provider_type": "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM",
    "targets": [
      { "model": "gpt-4o", "native_api_types": ["openai/v1/chat/completions"] }
    ],
    "custom": {
      "direct": {
        "base_url": "https://api.example.com/v1",
        "api_key": { "plaintext": "dummy-api-key" }
      }
    }
  }
}'

CLI

Passe o esquema pai e um nome de folha, e forneça a configuração com --json. Define provider_type e exatamente um bloco de provedor correspondente; targets permite listar os modelos upstream acessíveis, e os segredos são fornecidos em linha como texto simples. Para instalar a linha de código, veja Instalar ou atualizar a CLI do Databricks.

databricks ai-gateway create-model-provider-service schemas/main.default my_provider --json '{
  "comment": "Routes to a custom OpenAI-compatible provider",
  "config": {
    "provider_type": "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM",
    "targets": [
      { "model": "gpt-4o", "native_api_types": ["openai/v1/chat/completions"] }
    ],
    "custom": {
      "direct": {
        "base_url": "https://api.example.com/v1",
        "api_key": { "plaintext": "dummy-api-key" }
      }
    }
  }
}'

Terraform

Crie e gerencie um serviço de provedor modelo com o provedor Databricks Terraform e o recurso databricks_ai_gateway_model_provider_service . Mantenha chaves reais fora do controle de versão passando a chave API por uma sensitive = true variável (defina-a com -var ou uma TF_VAR_provider_api_key variável de ambiente):

variable "provider_api_key" {
  type      = string
  sensitive = true
}

resource "databricks_ai_gateway_model_provider_service" "example" {
  parent                    = "schemas/main.default"
  model_provider_service_id = "my_provider"
  comment                   = "Routes to a custom OpenAI-compatible provider"

  config = {
    provider_type = "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM"

    targets = [{
      model            = "gpt-4o"
      native_api_types = ["openai/v1/chat/completions"]
    }]

    custom = {
      direct = {
        base_url = "https://api.example.com/v1"
        api_key  = { plaintext = var.provider_api_key }
      }
    }
  }
}

Python SDK

Crie e gerencie um serviço de provedor de modelos com o SDK Databricks para Python:

from databricks.sdk.service import catalog as c

model_provider_service = w.ai_gateway.create_model_provider_service(
    parent="schemas/main.default",
    model_provider_service_id="my_provider",
    model_provider_service=c.ModelProviderService(
        comment="Routes to a custom OpenAI-compatible provider",
        config=c.ModelProviderServiceConfig(
            provider_type=(
                c.ModelProviderServiceConfigExternalModelProviderType
                .EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM
            ),
            targets=[
                c.ModelProviderServiceConfigModelTargetConfig(
                    model="gpt-4o",
                    native_api_types=["openai/v1/chat/completions"],
                )
            ],
            custom=c.ModelProviderServiceConfigCustomProviderConfig(
                direct=c.ModelProviderServiceConfigCustomProviderDirectConfig(
                    base_url="https://api.example.com/v1",
                    api_key=c.ModelProviderServiceConfigProviderSecret(
                        plaintext="dummy-api-key"
                    ),
                )
            ),
        ),
    ),
)

SDK do Go

Crie e gerencie um serviço de provedor modelo com o SDK Databricks para Go:

modelProviderService, err := w.AiGateway.CreateModelProviderService(ctx,
	catalog.CreateModelProviderServiceRequest{
		Parent:                 "schemas/main.default",
		ModelProviderServiceId: "my_provider",
		ModelProviderService: catalog.ModelProviderService{
			Comment: "Routes to a custom OpenAI-compatible provider",
			Config: &catalog.ModelProviderServiceConfig{
				ProviderType: catalog.ModelProviderServiceConfigExternalModelProviderTypeExternalModelProviderTypeCustom,
				Targets: []catalog.ModelProviderServiceConfigModelTargetConfig{{
					Model:          "gpt-4o",
					NativeApiTypes: []string{"openai/v1/chat/completions"},
				}},
				Custom: &catalog.ModelProviderServiceConfigCustomProviderConfig{
					Direct: &catalog.ModelProviderServiceConfigCustomProviderDirectConfig{
						BaseUrl: "https://api.example.com/v1",
						ApiKey: &catalog.ModelProviderServiceConfigProviderSecret{
							Plaintext: "dummy-api-key",
						},
					},
				},
			},
		},
	})

Java SDK

Crie e gerencie um serviço de provedor de modelo com o SDK Databricks para Java:

ModelProviderServiceConfig config =
    new ModelProviderServiceConfig()
        .setProviderType(
            ModelProviderServiceConfigExternalModelProviderType
                .EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM)
        .setTargets(
            Collections.singletonList(
                new ModelProviderServiceConfigModelTargetConfig()
                    .setModel("gpt-4o")
                    .setNativeApiTypes(
                        Collections.singletonList("openai/v1/chat/completions"))))
        .setCustom(
            new ModelProviderServiceConfigCustomProviderConfig()
                .setDirect(
                    new ModelProviderServiceConfigCustomProviderDirectConfig()
                        .setBaseUrl("https://api.example.com/v1")
                        .setApiKey(
                            new ModelProviderServiceConfigProviderSecret()
                                .setPlaintext("dummy-api-key"))));

ModelProviderService modelProviderService =
    w.aiGateway()
        .createModelProviderService(
            new CreateModelProviderServiceRequest()
                .setParent("schemas/main.default")
                .setModelProviderServiceId("my_provider")
                .setModelProviderService(
                    new ModelProviderService()
                        .setComment("Routes to a custom OpenAI-compatible provider")
                        .setConfig(config)));

JS SDK

Crie e gerencie um serviço de provedor modelo com o SDK Databricks AI Gateway para JavaScript:

import { ModelProviderServiceConfig_ExternalModelProviderType as ProviderType } from '@databricks/sdk-aigateway/v1';

const created = await client.createModelProviderService({
  parent: 'schemas/main.default',
  modelProviderServiceId: 'my_provider',
  modelProviderService: {
    comment: 'Routes to a custom OpenAI-compatible provider',
    config: {
      providerType: ProviderType.EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM,
      targets: [{ model: 'gpt-4o', nativeApiTypes: ['openai/v1/chat/completions'] }],
      provider: {
        $case: 'custom',
        custom: {
          providerMode: {
            $case: 'direct',
            direct: {
              baseUrl: 'https://api.example.com/v1',
              authMode: {
                $case: 'apiKey',
                apiKey: {
                  value: { $case: 'plaintext', plaintext: 'dummy-api-key' },
                },
              },
            },
          },
        },
      },
    },
  },
});

Para ver a lista completa de provedores e seus métodos de autenticação, consulte Governar provedores externos de modelos (serviços de provedores de modelos).

Autenticar Azure OpenAI ou Microsoft Foundry com uma credencial de serviço

É possível autenticar um provedor do OpenAI do Azure ou do Microsoft Foundry com uma credencial de serviço, em vez de armazenar uma chave de API ou um segredo do cliente da entidade de serviço do Microsoft Entra ID. Uma credencial de serviço possui uma identidade Azure que o Unity Catalog governa, então nenhum segredo duradouro é copiado no serviço do provedor modelo: o Azure Databricks obtém tokens de curta duração dessa identidade para autenticar cada solicitação.

Crie o serviço de provedor modelo conforme descrito em Crie um serviço de provedor modelo. Selecione Azure OpenAI ou Microsoft Foundry como tipo de provedor e insira seus detalhes de conexão, incluindo a URL base do endpoint. Depois, defina o método de Auth como credencial de serviço e selecione a credencial em vez de inserir uma chave de API ou segredo do cliente. Uma credencial de serviço substitui apenas o segredo, então a URL base do endpoint ainda é necessária.

Confirme os seguintes requisitos:

  • O proprietário do serviço do provedor de modelo tem ACCESS na credencial de serviço. Como o Azure Databricks verifica novamente o acesso do proprietário ao atender solicitações, o proprietário deve mantê-lo enquanto o provedor estiver em uso. Revogá-lo interrompe consultas para todos, até mesmo para os chamadores que mantêm EXECUTE no provedor. Para conceder ao proprietário acesso à credencial:

    GRANT ACCESS ON SERVICE CREDENTIAL <service-credential-name> TO `<model-provider-service-owner>`;

  • O objetivo da credencial é o serviço, não o armazenamento.

  • A credencial está disponível nos espaços de trabalho de onde vêm as solicitações. Seus vínculos de workspace ainda se aplicam, portanto uma solicitação proveniente de um workspace ao qual a credencial não está vinculada falhará nesse ambiente, embora o próprio serviço do provedor de modelo possa ser acessado de qualquer workspace que compartilhe o metastore.

  • A identidade do Azure da credencial de serviço está autorizada a acessar as implantações do OpenAI do Azure ou do Microsoft Foundry que você pretende consultar. Para criar uma credencial de serviço, consulte Criar credenciais de serviço.

Chamadores que consultam o provedor precisam das mesmas permissões que para qualquer outro provedor. Eles não precisam de nenhum privilégio sobre a credencial de serviço, que é o que mantém a credencial fora do alcance deles.

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

Se você excluir uma credencial, as consultas falham e não há aviso de que um serviço modelo de provedor faz referência a ela. Confirme que não há referências a essa credencial antes de excluí-la.

Não é possível alternar um serviço de provedor modelo existente entre credencial de serviço e chave de API ou autenticação de segredo de cliente. Crie um novo modelo de serviço de provedor em vez disso.

Envie uma chave de API personalizada de provedor em um cabeçalho

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

Crie o serviço de provedor modelo conforme descrito em Crie um serviço de provedor modelo. Selecione Personalizado como tipo de provedor, depois defina o método Auth como cabeçalho da chave API e forneça o nome do Cabeçalho que seu endpoint espera (como X-API-Key ou Ocp-Apim-Subscription-Key) junto com o valor do Cabeçalho.

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

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

Conceda acesso a um serviço modelo de provedor

Por padrão, apenas o proprietário do serviço do provedor modelo pode consultá-lo. Para permitir que outros consultem um serviço de provedor de modelos, conceda-lhes EXECUTE sobre ele, além de USE CATALOG e USE SCHEMA sobre seu catálogo e esquema. Se o serviço provedor do modelo registrar dados em uma tabela de inferência, conceda SELECT na tabela para permitir que leiam as requisições e respostas registradas.

interface do usuário

  1. Abra o serviço do provedor modelo no Explorador de Catálogos, ou vá até AI Gateway e selecione o serviço.
  2. Acesse a guia Permissões.
  3. Selecione Conceder.
  4. Selecione os usuários, grupos ou entidades de serviço aos quais dar acesso.
  5. Selecione o privilégio EXECUTE .
  6. Selecione Conceder.

API REST

databricks api patch \
  "/api/2.1/unity-catalog/permissions/model_provider_service/main.default.my_provider" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["EXECUTE"] }
    ]
  }'

CLI

Grant EXECUTE com a CLI do Databricks. Para instalar a linha de código, veja Instalar ou atualizar a CLI do Databricks.

databricks grants update model_provider_service main.default.my_provider \
  --json '{"changes": [{"principal": "data-team", "add": ["EXECUTE"]}]}'

Terraform

Concessão EXECUTE com o provedor Databricks Terraform e o databricks_grant recurso:

resource "databricks_grant" "example" {
  model_provider_service = "main.default.my_provider"
  principal              = "data-team"
  privileges             = ["EXECUTE"]
}

Python SDK

Grant EXECUTE com o SDK Databricks para Python:

from databricks.sdk.service import catalog as c

w.grants.update(
    securable_type="model_provider_service",
    full_name="main.default.my_provider",
    changes=[c.PermissionsChange(principal="data-team", add=[c.Privilege.EXECUTE])],
)

SDK do Go

Conceder EXECUTE com o SDK da Databricks para Go:

_, err := w.Grants.Update(ctx, catalog.UpdatePermissions{
	SecurableType: "model_provider_service",
	FullName:      "main.default.my_provider",
	Changes: []catalog.PermissionsChange{{
		Principal: "data-team",
		Add:       []catalog.Privilege{catalog.PrivilegeExecute},
	}},
})

Java SDK

Grant EXECUTE com o SDK Databricks para Java:

w.grants().update(
    new UpdatePermissions()
        .setSecurableType("model_provider_service")
        .setFullName("main.default.my_provider")
        .setChanges(Arrays.asList(
            new PermissionsChange().setPrincipal("data-team").setAdd(Arrays.asList(Privilege.EXECUTE)))));

Para mais informações sobre conceder e descobrir acesso, veja Descobrir e regular o acesso a provedores modelo externos (serviços de provedores modelo).

Configurar recursos

Como um provedor modelo faz roteamentos de serviço através do Unity Gateway, aplica as mesmas funcionalidades de governança e observabilidade que você usa para outros tráfegos do Unity Gateway:

Atualize um serviço modelo de provedor

Você deve ser proprietário ou ter MANAGE. O tipo de prestador é imutável.

interface do usuário

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

API REST

databricks api patch \
  "/api/2.1/unity-catalog/model-provider-services/main.default.my_provider?update_mask=comment" \
  --json '{"comment": "Updated: routes to a custom provider"}'

CLI

databricks ai-gateway update-model-provider-service model-provider-services/main.default.my_provider comment \
  --json '{"comment": "Updated: routes to a custom provider"}'

Terraform

Edite comment (ou qualquer outro campo mutável) no databricks_ai_gateway_model_provider_service recurso e reaplique. As alterações são aplicadas no local.

Python SDK

from databricks.sdk.service import catalog as c
from google.protobuf.field_mask_pb2 import FieldMask

updated = w.ai_gateway.update_model_provider_service(
    name="model-provider-services/main.default.my_provider",
    update_mask=FieldMask(paths=["comment"]),
    model_provider_service=c.ModelProviderService(
        comment="Updated: routes to a custom provider"
    ),
)

SDK do Go

updated, err := w.AiGateway.UpdateModelProviderService(ctx,
	catalog.UpdateModelProviderServiceRequest{
		Name:       "model-provider-services/main.default.my_provider",
		UpdateMask: *fieldmask.New([]string{"comment"}),
		ModelProviderService: catalog.ModelProviderService{
			Comment: "Updated: routes to a custom provider",
		},
	})

Java SDK

ModelProviderService updated =
    w.aiGateway()
        .updateModelProviderService(
            new UpdateModelProviderServiceRequest()
                .setName("model-provider-services/main.default.my_provider")
                .setUpdateMask(FieldMask.newBuilder().addPaths("comment").build())
                .setModelProviderService(
                    new ModelProviderService()
                        .setComment("Updated: routes to a custom provider")));

JS SDK

import { modelProviderServiceFieldMask } from '@databricks/sdk-aigateway/v1';

const updated = await client.updateModelProviderService({
  modelProviderService: {
    name: 'model-provider-services/main.default.my_provider',
    comment: 'Updated: routes to a custom provider',
  },
  updateMask: modelProviderServiceFieldMask('comment'),
});

Excluir um serviço do provedor de modelos

Você deve ser proprietário ou ter MANAGE.

interface do usuário

Abra o serviço de provedor de modelo na interface do Unity Gateway ou no Explorador de Catálogo e selecione Excluir no menu kebab.

API REST

databricks api delete "/api/2.1/unity-catalog/model-provider-services/main.default.my_provider"

CLI

databricks ai-gateway delete-model-provider-service model-provider-services/main.default.my_provider

Terraform

Execute terraform destroy, ou remova o bloco de recurso e aplique novamente.

Python SDK

w.ai_gateway.delete_model_provider_service(
    name="model-provider-services/main.default.my_provider"
)

SDK do Go

err := w.AiGateway.DeleteModelProviderService(ctx,
	catalog.DeleteModelProviderServiceRequest{
		Name: "model-provider-services/main.default.my_provider",
	})

Java SDK

w.aiGateway()
    .deleteModelProviderService(
        new DeleteModelProviderServiceRequest()
            .setName("model-provider-services/main.default.my_provider"));

JS SDK

await client.deleteModelProviderService({
  name: 'model-provider-services/main.default.my_provider',
});

Próximas Etapas 

  • Last updated on