Criar e gerenciar provedores com Serviços Modelo de Provedores

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

Requirements

  • CREATE SERVICE no esquema em que você cria o serviço do provedor de modelo, mais USE CATALOG e USE SCHEMA no catálogo e no esquema dele.
  • 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ê deve ter uma credencial de serviço existente e ACCESS nela. Veja: Autenticar Azure OpenAI ou Microsoft Foundry com credencial de serviço.

Para associar uma credencial de provedor a um segredo do Catálogo do Unity de propriedade do cliente em vez de armazenar o valor diretamente no código, você precisa ter um segredo do Catálogo do Unity existente e READ SECRET nele. Consulte Associar uma credencial de provedor a um segredo do Catálogo do Unity.

Crie um serviço de provedor de modelo

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.

Crie um serviço de provedor modelo na interface do Unity Gateway ou no Explorador de Catálogos. Para criar um programaticamente, use a API REST, os SDKs do Azure Databricks, a CLI Databricks, Terraform ou Pacotes de Automação Declarativa (DABs).

interface do usuário

  1. Realize um dos seguintes procedimentos:
    • Na barra lateral do espaço de trabalho, clique em Unity 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 }
      }
    }
  }
}

DABs (Beta)

Defina o serviço do provedor modelo em um pacote e implante-o com databricks bundle deploy. Mantenha chaves reais fora do controle de versão passando a chave API por uma variável bundle (defina-a com --var ou uma BUNDLE_VAR_provider_api_key variável de ambiente):

variables:
  provider_api_key:
    description: Provider API key.

resources:
  model_provider_services:
    my_provider:
      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",
						},
					},
				},
			},
		},
	})

Go Modular SDK

Crie e gerencie um serviço de provedor de modelo com o pacote Go SDK. Campos opcionais são ponteiros, então o exemplo usa um auxiliar de uma linha, func ptr[T any](v T) *T { return &v }.

modelProviderService, err := c.CreateModelProviderService(ctx,
	aigateway.CreateModelProviderServiceRequest{
		Parent:                 ptr("schemas/main.default"),
		ModelProviderServiceId: ptr("my_provider"),
		ModelProviderService: &aigateway.ModelProviderService{
			Comment: ptr("Routes to a custom OpenAI-compatible provider"),
			Config: &aigateway.ModelProviderServiceConfig{
				ProviderType: aigateway.ModelProviderServiceConfig_ExternalModelProviderType_ExternalModelProviderTypeCustom,
				Targets: []aigateway.ModelProviderServiceConfig_ModelTargetConfig{{
					Model:          ptr("gpt-4o"),
					NativeApiTypes: []string{"openai/v1/chat/completions"},
				}},
				Provider: &aigateway.ModelProviderServiceConfig_Provider_Custom{
					Custom: aigateway.ModelProviderServiceConfig_CustomProviderConfig{
						ProviderMode: &aigateway.ModelProviderServiceConfig_CustomProviderConfig_ProviderMode_Direct{
							Direct: aigateway.ModelProviderServiceConfig_CustomProviderDirectConfig{
								BaseUrl: ptr("https://api.example.com/v1"),
								AuthMode: &aigateway.ModelProviderServiceConfig_CustomProviderDirectConfig_AuthMode_ApiKey{
									ApiKey: aigateway.ModelProviderServiceConfig_ProviderSecret{
										Value: &aigateway.ModelProviderServiceConfig_ProviderSecret_Value_Plaintext{
											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 Modular SDK

Crie e gerencie um serviço de provedor de modelo com o pacote JavaScript SDK:

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 Provedores de modelos externos ao Databricks.

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

Proteja as credenciais de um provedor com um segredo do Unity Catalog

Em vez de armazenar uma credencial de prestador em linha, você pode apontar um serviço modelo para um segredo do Catálogo Unity pertencente ao cliente que detém o valor. O Azure Databricks lê o segredo no momento da execução da consulta usando as credenciais de acesso do proprietário do serviço do provedor de modelo e nunca copia o valor para o serviço do provedor de modelo, de modo que a rotação do segredo tenha efeito sem nenhuma alteração no serviço do provedor de modelo.

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

Crie o serviço de provedor modelo conforme descrito em Crie um serviço de provedor modelo. Selecione o tipo de provedor e insira seus detalhes de conexão. Para a credencial (como a chave API), mude o tipo de autenticação de Texto Simples para Secreto, depois selecione o catálogo, esquema e segredo que identificam seu segredo do Catálogo Unity.

Confirme os seguintes requisitos:

  • O proprietário do serviço de provedor de modelo tem READ SECRET no segredo do Catálogo do Unity. 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 ao segredo:

    GRANT READ SECRET ON SECRET <catalog>.<schema>.<secret> TO `<model-provider-service-owner>`;
    
  • O segredo do Catálogo Unity existe antes mesmo de você consultá-lo. Para criar e governar segredos do Catálogo Unity, veja Segredos no Catálogo Unity.

Chamadores que consultam o provedor precisam das mesmas permissões que para qualquer outro provedor. Eles não precisam de nenhum privilégio sobre o segredo do Unity Catalog, que é o que mantém o valor secreto fora do alcance deles.

Para fazer a rotação da credencial, atualize o valor do segredo do Unity Catalog, sem nenhuma alteração no serviço do provedor de modelos.

Se você deletar o segredo do Unity Catalog, as consultas falham. O serviço do provedor de modelo mantém a referência que agora está inválida para que você possa ver a dependência, e você pode restaurar o provedor atualizando-o para que faça referência a um segredo que ainda existe.

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

Use a assinatura Claude ou ChatGPT de cada interlocutor

Em vez de armazenar uma chave de API, um serviço de provedor de modelo pode permitir que cada chamador leve sua própria assinatura do Claude ou do ChatGPT para um agente de codificação. O serviço não armazena credencial. Cada solicitante faz login com sua própria assinatura, e os pedidos são cobrados com base nela.

Crie o serviço de provedor modelo conforme descrito em Criar um serviço de provedor modelo, depois selecione o tipo de provedor e o modo de autenticação:

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 de provedor de modelo no Explorador de Catálogos, ou vá até Unity 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

Conceda 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

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

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

DABs (Beta)

Adicione um bloco grants ao recurso de serviço do provedor de modelo no seu pacote e reimplante para conceder acesso.

variables:
  provider_api_key:
    description: Provider API key.

resources:
  model_provider_services:
    my_provider:
      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}
      grants:
        - principal: data-team
          privileges: [EXECUTE]

Python SDK

Conceda 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

Conceda EXECUTE com o SDK do 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

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

Configure um multiplicador de preço

Por padrão, o Azure Databricks estima os gastos com modelos externos com base nos preços de tabela publicados pelo provedor. Se o preço do seu fornecedor for diferente, configure um multiplicador de preço para refletir descontos ou margens. Por exemplo, 0.8 usa 80% do preço de listagem, enquanto 1.2 usa 120%.

  1. Crie um serviço de provedor modelo ou abra um serviço de provedor modelo existente no Explorador de Catálogos ou no Gateway Unity 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 do provedor de modelos. O gasto calculado em system.ai_gateway.external_model_spend reflete o multiplicador configurado. Mudanças se aplicam a requisições feitas após a entrada em vigor da configuração; requisições anteriores permanecem estimadas usando o preço de tabela ou o multiplicador previamente configurado.

Um multiplicador configurado exibe uma etiqueta de Preço Personalizado . Os preços ajustados têm um sublinhado pontilhado nas tabelas de preços. Passe o mouse sobre um preço ajustado para comparar o preço ajustado com o preço de tabela do provedor.

Configurar rotas de endpoint para um provedor personalizado

Rotas de endpoint são opcionais. Use-os quando um provedor personalizado hospeda modelos diferentes em caminhos diferentes no mesmo base_url. Um modelo pode suportar múltiplos tipos de API. Cada modelo possui uma rota de endpoint compartilhada pelos tipos de API suportados.

Para configurar uma rota, defina endpoint_route no destino para um caminho relativo, não uma URL completa. Unity Gateway adiciona a rota ao final de base_url, após qualquer caminho que base_url já contenha.

interface do usuário

  1. Abra o diálogo Criar serviço de provedor de modelo, conforme descrito em Criar um serviço de provedor de modelo, e selecione Personalizado na seção Provedor.
  2. Na seção Modelos, insira o nome de um modelo, selecione os tipos de API que esse modelo serve e insira um caminho relativo na rota Endpoint (opcional).
  3. Clique em Adicionar modelo. Repita para cada modelo.
  4. Clique em Criar.

API REST

A seguinte solicitação configura rotas separadas para um modelo de chat e um modelo de embedding:

databricks api post \
  "/api/2.1/unity-catalog/model-provider-services?parent=schemas/main.default&model_provider_service_id=my_provider" \
  --json '{
  "config": {
    "provider_type": "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM",
    "targets": [
      {
        "model": "chat-model",
        "native_api_types": ["openai/v1/chat/completions"],
        "endpoint_route": "serve/openai/chat"
      },
      {
        "model": "embedding-model",
        "native_api_types": ["openai/v1/embeddings"],
        "endpoint_route": "serve/openai/embed"
      }
    ],
    "custom": {
      "direct": {
        "base_url": "https://api.example.com/gateway",
        "api_key": { "plaintext": "placeholder-api-key" }
      }
    }
  }
}'

Com isso base_url, as requisições usam as seguintes URLs upstream:

  • chat-model: https://api.example.com/gateway/serve/openai/chat
  • embedding-model: https://api.example.com/gateway/serve/openai/embed

Se você omitir endpoint_route ou definir para uma string vazia, o Unity Gateway usa a base_url string inalterada.

native_api_types seleciona a tradução da API para cada modelo. Ele não seleciona nem altera a rota de upstream.

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.

DABs (Beta)

Edite comment (ou qualquer outro campo mutável) no recurso bundle e execute databricks bundle deploy. 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",
		},
	})

Go Modular SDK

mask, err := types.NewFieldMask[aigateway.ModelProviderService]("comment")
updated, err := c.UpdateModelProviderService(ctx,
	aigateway.UpdateModelProviderServiceRequest{
		ModelProviderService: &aigateway.ModelProviderService{
			Name:    ptr("model-provider-services/main.default.my_provider"),
			Comment: ptr("Updated: routes to a custom provider"),
		},
		UpdateMask: mask,
	})

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

DABs (Beta)

Remova o recurso do pacote e corra databricks bundle deploy para deletá-lo. databricks bundle destroy Também funciona, mas remove todos os recursos que o pacote gerencia, não só este.

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

Go Modular SDK

err := c.DeleteModelProviderService(ctx,
	aigateway.DeleteModelProviderServiceRequest{
		Name: ptr("model-provider-services/main.default.my_provider"),
	})

Java SDK

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

JS Modular SDK

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

Próximas Etapas