Criar e gerir fornecedores modelo externos (serviços de prestadores modelo)

Registar um fornecedor de modelos externo como serviço de fornecedor de modelo, conceder acesso a ele, configurar funcionalidades do Unity AI Gateway e eliminá-lo.

Requirements

  • CREATE SERVICE no esquema onde cria o serviço do fornecedor do modelo, mais USE CATALOG e USE SCHEMA no respetivo catálogo e esquema.
  • As credenciais do fornecedor externo que pretende registar (por exemplo, uma chave 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, precisa de uma credencial de serviço existente e ACCESS nela. Veja Autenticar Azure OpenAI ou Microsoft Foundry com credencial de serviço.

Criar um serviço modelo de prestador

Os serviços do fornecedor de modelos e os serviços de modelo partilham um único namespace dentro de um esquema do Catálogo Unity. Não podes usar um nome para um serviço de prestador modelo se um serviço modelo no esquema já o usar, e vice-versa.

Pode criar um serviço de fornecedor de modelos na interface do Unity AI Gateway ou no Catalog Explorer, ou programaticamente com a API REST, os SDKs do Azure Databricks, a CLI do Azure Databricks ou o Terraform.

IU

  1. Proceda de uma das seguintes formas:
    • Na barra lateral do espaço de trabalho, clique em AI Gateway, depois, abra o separador Fornecedores e clique em Fornecedor.
    • No Explorador de Catálogo, vá ao esquema onde quer criar o serviço de fornecedor de modelo, clique em Criar>Serviço e depois selecione Serviço de Modelo de Fornecedor na janela de diálogo Criar um serviço .
  2. Introduza um nome para o serviço de fornecedor de modelos e selecione o catálogo e o esquema onde o pretende criar. Se começares pelo Explorador de Catálogos, o Explorador de Catálogos prepreenche o catálogo e o esquema.
  3. Selecione o tipo de prestador e insira os dados e credenciais da ligação do fornecedor.
  4. Clique em Criar. Azure Databricks encripta e armazena as credenciais. A interface deixa de os mostrar a partir deste 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. definir provider_type e exatamente um bloco de fornecedor correspondente; targets permite listar os modelos a montante 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 da folha, e forneça a configuração com --json. Defina provider_type e exatamente um bloco de prestador correspondente; targets define uma lista de permissões dos modelos de origem acessíveis, e os segredos são fornecidos inline em texto simples. Para instalar a linha de código, consulte Instalar ou atualizar a CLI de 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 gere um serviço de fornecedor de modelos com o fornecedor Databricks Terraform e o recurso databricks_ai_gateway_model_provider_service . Mantenha as chaves reais fora do controlo de código-fonte ao passar a chave da API através de uma variável sensitive = true (defina-a com -var ou uma variável de ambiente TF_VAR_provider_api_key):

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

Criar e gerir um serviço de fornecedor 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"
                    ),
                )
            ),
        ),
    ),
)

Kit de Desenvolvimento de Software Go

Crie e gere um serviço de fornecedor 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",
						},
					},
				},
			},
		},
	})

SDK de Java

Crie e gere um serviço de fornecedor de modelos 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 gere um serviço de fornecedor 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 consultar a lista completa de fornecedores e os respetivos métodos de autenticação, consulte Gerir fornecedores externos de modelos (serviços de fornecedores de modelos).

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

Pode autenticar um fornecedor do Azure OpenAI ou do Microsoft Foundry com uma credencial de serviço, em vez de armazenar uma chave de API ou um segredo do cliente de uma entidade de serviço do Microsoft Entra ID. Uma credencial de serviço detém uma identidade Azure que o Unity Catalog governa, pelo que nenhum segredo duradouro é copiado para o serviço do fornecedor modelo: o Azure Databricks obtém tokens de curta duração dessa identidade para autenticar cada pedido.

Crie o serviço modelo de prestador conforme descrito em Criar um serviço modelo de prestador. Selecione Azure OpenAI ou Microsoft Foundry como tipo de fornecedor e introduza os detalhes da sua ligação, incluindo a URL base do endpoint. Depois, defina o método Auth como credencial de serviço e selecione a credencial em vez de introduzir uma chave API ou o segredo do cliente. Uma credencial de serviço substitui apenas o segredo, pelo que a URL base do endpoint continua a ser necessária.

Confirme os seguintes requisitos:

  • O proprietário do serviço do fornecedor do modelo tem ACCESS na credencial do serviço. Como o Azure Databricks verifica novamente o acesso do proprietário ao atender pedidos, o proprietário deve mantê-lo enquanto o fornecedor estiver em uso. Revogá-lo impede consultas para todos, até para os autores das chamadas que tenham EXECUTE no fornecedor. 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 os pedidos. Os seus vínculos ao espaço de trabalho continuam a aplicar-se, pelo que um pedido proveniente de um espaço de trabalho ao qual a credencial não está associada falha nesse espaço, embora o próprio serviço do fornecedor de modelos seja acessível a partir de qualquer espaço de trabalho que partilhe o metastore.

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

Os que consultam o prestador necessitam das mesmas subvenções que para qualquer outro prestador. Eles não precisam de ter qualquer privilégio sobre a credencial de serviço, o que mantém a própria credencial fora do alcance deles.

O serviço do fornecedor do modelo identifica uma credencial pelo seu identificador interno, o que lhe permite renomear uma credencial sem que a consulta falhe.

Se apagar uma credencial, as consultas falham e não há qualquer aviso de que um serviço modelo de fornecedor a refere. Confirme que não há referências a esta credencial antes de a apagar.

Não se pode alternar um serviço de fornecedor modelo existente entre credencial de serviço e autenticação por chave API ou segredo do cliente. Crie um novo modelo de serviço de prestação em vez disso.

Envie uma chave API personalizada de fornecedor num cabeçalho

Um fornecedor personalizado envia a sua chave API como token portador por defeito. Quando o seu endpoint espera que a chave esteja num cabeçalho específico, use a autenticação do cabeçalho da chave API e nomeie o cabeçalho você mesmo. O Azure Databricks envia então a chave em cada pedido de saída como <header name>: <header value>.

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

Os dois métodos são mutuamente exclusivos: um fornecedor personalizado utiliza um token portador ou um cabeçalho nomeado, não ambos. A autenticação por cabeçalho requer 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 carácter não é aceite, incluindo espaços, dois-pontos, barras e quebras de linha.

Conceder acesso a um serviço modelo de prestador

Por predefinição, apenas o proprietário do serviço do fornecedor do modelo pode consultá-lo. Para permitir que outros consultem um serviço de fornecedor de modelos, concede-lhes EXECUTE sobre esse serviço, bem como USE CATALOG e USE SCHEMA sobre o respetivo catálogo e esquema. Se o serviço do fornecedor do modelo registar uma tabela de inferência, conceda SELECT à tabela que lhes permita ler os pedidos e respostas registados.

IU

  1. Abra o serviço de fornecedor modelo no Explorador de Catálogos, ou vá ao AI Gateway e selecione o serviço.
  2. Vá para a guia Permissões .
  3. Clique em Conceder.
  4. Selecione os utilizadores, grupos ou identidades de serviço a quem pretende conceder acesso.
  5. Selecione o privilégio EXECUTE.
  6. Clique em 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 linha de comando do Databricks. Para instalar a linha de código, consulte Instalar ou atualizar a CLI de Databricks.

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

Terraform

Subvenção EXECUTE com o fornecedor 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

Subvenção 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])],
)

Kit de Desenvolvimento de Software Go

Grant EXECUTE com o SDK 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},
	}},
})

SDK de Java

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, consulte Descobrir e regular o acesso a fornecedores modelo externos (serviços modelo de fornecedores).

Configurar recursos

Uma vez que um serviço de fornecedor de modelos é encaminhado através do Unity AI Gateway, aplique as mesmas funcionalidades de governação e observabilidade que utiliza para outro tráfego do Unity AI Gateway:

Atualizar um serviço modelo de fornecedor

Deve ser proprietário ou ter MANAGE. O tipo de fornecedor é imutável.

IU

Editar a configuração do serviço do fornecedor de modelos a partir da interface do Unity AI Gateway ou do Explorador de Catálogos. As alterações aplicam-se 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

Edita comment (ou qualquer outro campo mutável) no databricks_ai_gateway_model_provider_service recurso e volta a aplicar. As alterações aplicam-se 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"
    ),
)

Kit de Desenvolvimento de Software 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",
		},
	})

SDK de Java

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'),
});

Eliminar um serviço de prestador modelo

Deve ser proprietário ou ter MANAGE.

IU

Abra o serviço do fornecedor de modelos na interface do Unity AI Gateway ou no Explorador de Catálogos e selecione Delete 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

Executa terraform destroy, ou remove o bloco de recurso e volta a aplicar.

Python SDK

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

Kit de Desenvolvimento de Software Go

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

SDK de Java

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',
});

Passos seguintes

  • Last updated on