Criar e gerenciar provedores de modelos externos (serviços de provedor de modelos)

Faça o registro de um provedor de modelo externo como um serviço de provedor de modelo, conceda acesso a ele, configure os recursos do Unity Gateway e exclua-o.

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ê precisa de uma credencial de serviço existente e ACCESS nela. Consulte Autenticar o Google Gemini Enterprise com uma credencial de serviço.

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.

Você pode criar um serviço de provedor de modelo na interface do usuário do Unity Gateway ou no Catalog Explorer, ou programaticamente com a API REST, os SDKs do Databricks, a CLI do Databricks ou o Terraform.

UI

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.

REST API

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

Bash

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. Defina provider_type e exatamente um bloco de provedor correspondente; targets coloca na lista de permissões os modelos upstream acessíveis, e os segredos são fornecidos em linha como texto simples. Para instalar a CLI, consulte Instalar ou atualizar a CLI do Databricks.

Bash

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 de modelo com o provedor Databricks Terraform e o recurso databricks_ai_gateway_model_provider_service. Mantenha as keys reais fora do controle de código-fonte passando a API key por meio de uma variável sensitive = true (defina-a com -var ou uma variável de ambiente TF_VAR_provider_api_key):

Hcl

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 modelo com o SDK do Databricks para Python:

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"
                    ),
                )
            ),
        ),
    ),
)

Go SDK

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

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 do Databricks para Java:

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 de modelo com o SDK do Databricks AI Gateway para JavaScript:

TypeScript

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 obter a lista completa de provedores e seus métodos de autenticação, consulte Governar provedores de modelos externos (serviços de provedor de modelos).

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 modelo tem ACCESS na credencial de serviço. Como o 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á-la 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.

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.

UI

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 .

REST API

Bash

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

CLI

Conceda EXECUTE com a CLI do Databricks. Para instalar a CLI, consulte Instalar ou atualizar a CLI do Databricks.

Bash

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

Terraform

Conceda EXECUTE com o provedor Databricks Terraform e o recurso databricks_grant:

Hcl

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

Python SDK

Conceda EXECUTE com o SDK do Databricks para Python:

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])],
)

Go SDK

Conceda EXECUTE com o Databricks SDK para Go:

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

Conceda EXECUTE com o SDK do Databricks para Java:

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 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:

• Registro de inferência. Registrar solicitações e respostas em uma tabela do Unity Catalog. Consulte Logs solicitações e respostas em tabelas de inferência.
• Limites de taxa. Limite as queries por minuto para gerenciar a capacidade e o custo. Consulte Aplicar limites de taxa a serviços de modelo e MCP.
• Políticas de serviço. Governe o conteúdo de cada interação, como bloquear conteúdo inseguro ou editar dados confidenciais, anexando uma política de serviço. Consulte Políticas de serviço para securables de AI e Criar e anexar uma política de serviço.

Atualizar um serviço de provedor de modelos

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

UI

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.

REST API

Bash

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

Bash

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 recurso databricks_ai_gateway_model_provider_service e reaplique. As alterações são aplicadas no local.

Python SDK

Python

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"
    ),
)

Go SDK

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

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

TypeScript

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 de provedor de modelos

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

UI

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

REST API

Bash

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

CLI

Bash

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 reaplique.

Python SDK

Python

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

Go SDK

Go

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

Java SDK

Java

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

JS SDK

TypeScript

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

Próximos os passos

• query provedores de modelos externos (serviços de provedor de modelos)
• Descubra e governe o acesso a provedores de modelos externos (serviços de provedor de modelos)
• Controlar provedores de modelos externos (serviços de provedor de modelos)