Creëer en beheer externe modelproviders (model provider services)

Registreer een externe modelprovider als modelproviderservice, verleen er toegang toe, configureer Unity Gateway-functies en verwijder het.

Requirements

• CREATE SERVICE op het schema waarin u de modelprovider-service maakt, plus USE CATALOG en USE SCHEMA op de catalogus en het schema ervan.
• De referenties voor de externe provider die u wilt registreren (bijvoorbeeld een OpenAI-API-sleutel of een AWS-toegangssleutelpaar).
• Om Azure OpenAI of Microsoft Foundry te authenticeren met een servicecredential in plaats van een sleutel of geheim, heb je een bestaand servicecredential nodig en ACCESS erop staan. Zie Azure OpenAI en Microsoft Foundry authentiseren met een servicecredential.

Creëer een modelprovider service

Modelproviderservices en modelservices delen één naamruimte binnen een Unity Catalog-schema. U kunt geen naam gebruiken voor een modelproviderservice als een modelservice in het schema dit al gebruikt en omgekeerd.

Je kunt een modelproviderdienst maken in de Unity Gateway UI of in Catalog Explorer, of programmatisch met de REST API, de Azure Databricks SDK's, de Azure Databricks CLI of Terraform.

UI (Gebruikersinterface)

1. Ga op een van de volgende manieren te werk:
   • Klik in de zijbalk van de werkruimte op AI Gateway, open vervolgens het tabblad Providers en klik op Provider.
   • Ga in Catalog Explorer naar het schema waar je de model provider service wilt aanmaken, klik op Create>Service en selecteer vervolgens Model provider service in het menu 'Create a service '.
2. Voer een naam in voor de modelproviderservice en selecteer de catalogus en het schema waarin u deze wilt maken. Als u begint met Catalog Explorer, vult Catalog Explorer de catalogus en het schema vooraf in.
3. Selecteer het providertype en voer de verbindingsgegevens en referenties van de provider in.
4. Klik op Create. Azure Databricks versleutelt en slaat de referenties op. De gebruikersinterface geeft deze na dit punt niet weer.

REST API

Stuur een POST naar /api/2.1/unity-catalog/model-provider-services, waarbij model_provider_service_id en parent als queryparameters worden doorgegeven. Stel provider_type en precies één overeenkomend providerblok in; targets staat de bereikbare upstream-modellen toe, en geheimen worden inline in platte tekst opgegeven:

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

Geef het bovenliggende schema en een leaf-naam door, en specificeer de configuratie met --json. Stel provider_type en precies één overeenkomend providerblok in; targets beperkt de bereikbare upstream-modellen tot de toegestane, en geheimen worden inline in platte tekst opgegeven. Om de CLI te installeren, zie Installeren of bijwerken de Databricks CLI.

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

Creëer en beheer een modelproviderdienst met de Databricks Terraform-provider en de databricks_ai_gateway_model_provider_service resource. Houd echte sleutels buiten de broncode door de API-sleutel door een variabele sensitive = true te laten lopen (stel deze in met -var of een TF_VAR_provider_api_key omgevingsvariabele):

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

Creëer en beheer een model provider-service met de Databricks SDK voor 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 Softwareontwikkelingskit

Creëer en beheer een model provider-dienst met de Databricks SDK voor 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

Creëer en beheer een model provider-dienst met de Databricks SDK voor 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

Creëer en beheer een model provider-dienst met de Databricks AI Gateway SDK voor 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' },
                },
              },
            },
          },
        },
      },
    },
  },
});

Raadpleeg voor de volledige lijst van providers en hun authenticatiemethoden Externe modelproviders beheren (services van modelproviders).

Authenticeer Azure OpenAI of Microsoft Foundry met een servicecredential

Je kunt een Azure OpenAI- of Microsoft Foundry-provider authenticeren met een servicecredential in plaats van een API-sleutel of een Microsoft Entra ID service principal client secret op te slaan. Een servicecredential bevat een Azure-identiteit die door Unity Catalog wordt beheerd, dus geen langlevend geheim wordt gekopieerd in de model provider-service: Azure Databricks verkrijgt kortstondige tokens van die identiteit om elk verzoek te authenticeren.

Creëer de model provider service zoals beschreven in Create a model provider service. Selecteer Azure OpenAI of Microsoft Foundry als providertype en voer de verbindingsgegevens in, inclusief de endpointbasis-URL. Stel vervolgens de Auth-methode in op Service-credential en selecteer de credential in plaats van een API-sleutel of clientgeheim in te voeren. Een servicecredential vervangt alleen het geheim, dus de endpointbasis-URL is nog steeds vereist.

Bevestig de volgende vereisten:

• De eigenaar van de modelprovider service heeft ACCESS op de servicecredential. Omdat Azure Databricks de toegang van de eigenaar opnieuw controleert bij het verzenden van verzoeken, moet de eigenaar deze behouden zolang de provider in gebruik is. Het intrekken ervan stopt query’s voor iedereen, zelfs voor aanroepers die over EXECUTE op de provider beschikken. Om de eigenaar toegang te geven tot het inloggegevens:

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

• Het doel van het inlogboek is dienst, niet opslag.

• Het inloggegevens is beschikbaar in de werkruimtes waar verzoeken vandaan komen. De werkruimtebindingen blijven van toepassing, dus een verzoek vanuit een werkruimte waaraan de referentie niet is gebonden, mislukt daar, ook al is de service van de modelprovider zelf bereikbaar vanuit elke werkruimte die dezelfde metastore deelt.

• De Azure-identiteit van het service-credential is geautoriseerd om de Azure OpenAI- of Microsoft Foundry-implementaties aan te roepen die je wilt opvragen. Zie Servicereferenties maken om een servicereferentie te creëren.

Aanroepers die de provider bevragen, hebben dezelfde machtigingen nodig als voor elke andere provider. Ze hebben geen privileges nodig op het service-credential, wat het credential zelf buiten hun bereik houdt.

De model provider-dienst volgt een credential op basis van de interne identificatie, zodat je een credential kunt hernoemen zonder queryfout.

Als je een credential verwijdert, falen queries en is er geen waarschuwing dat een modelprovider service ernaar verwijst. Controleer of er geen verwijzingen naar dit inlogement zijn voordat je het verwijdert.

Je kunt een bestaande service van een modelprovider niet omschakelen van authenticatie met servicereferentie naar authenticatie met een API-sleutel of client secret. Maak in plaats daarvan een nieuw model provider-dienst.

Stuur een aangepaste provider-API-sleutel in een header

Een aangepaste provider stuurt standaard zijn API-sleutel als een bearer-token. Wanneer je endpoint de sleutel in een specifieke header verwacht, gebruik dan API-sleutelheaderauthenticatie en geef de header zelf een naam. Azure Databricks stuurt vervolgens de sleutel bij elk uitgaande verzoek als <header name>: <header value>.

Creëer de model provider service zoals beschreven in Create a model provider service. Selecteer Aangepast als providertype, stel vervolgens de Auth-methode in op de API-sleutelheader en geef de headernaam die je endpoint verwacht (zoals X-API-Key of Ocp-Apim-Subscription-Key) samen met de headerwaarde.

De twee methoden sluiten elkaar uit: een aangepaste provider gebruikt ofwel een bearer token of een benoemde header, niet beide. Headerauthenticatie vereist precies één header.

De naam van de header moet een geldige HTTP-headernaam zijn: letters, cijfers en de tekens !#$%&'*+-.^_`|~, tot 255 tekens. Elk ander teken wordt geweigerd, inclusief spaties, dubbele punten, schuine strepen en regelafbrekingen.

Verleen toegang tot een dienst van een modelaanbieder

Standaard kan alleen de eigenaar van de modelproviderservice deze bevragen. Om anderen query's te laten uitvoeren op een service van een modelprovider, verleent u hun EXECUTE erop, plus USE CATALOG en USE SCHEMA op de catalogus en het schema. Als de service van de modelprovider gegevens logt in een inferentietabel, verleent u SELECT op de tabel zodat de provider de gelogde aanvragen en antwoorden kan lezen.

UI (Gebruikersinterface)

1. Open de model provider-dienst in Catalog Explorer, of ga naar AI Gateway en selecteer de service.
2. Ga naar het tabblad Machtigingen .
3. Klik op Toestaan.
4. Selecteer de gebruikers, groepen of service-principals om toegang te verlenen.
5. Selecteer de execute-bevoegdheid .
6. Klik op Toestaan.

REST API

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 met de Databricks CLI. Om de CLI te installeren, zie Installeren of bijwerken de Databricks CLI.

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

Terraform

Geef een subsidie EXECUTE met de Databricks Terraform-provider en de databricks_grant bron:

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

Python SDK

Toegang verlenen EXECUTE met de Databricks SDK voor 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 Softwareontwikkelingskit

Grant EXECUTE met de Databricks SDK voor 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 met de Databricks SDK voor 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)))));

Voor meer informatie over het verlenen en ontdekken van toegang, zie Ontdek en beheer toegang tot externe modelproviders (modelproviderservices).

Functies configureren

Omdat een modelprovider dienst via Unity Gateway routeert, pas dezelfde governance- en observabiliteitsfuncties toe die je gebruikt voor ander Unity Gateway-verkeer:

• Logboekregistratie van inferentie. Logboekaanvragen en antwoorden op een Unity Catalog-tabel. Zie Logverzoeken en antwoorden op inferentietabellen.
• Frequentielimieten. Beperk het aantal query's per minuut om capaciteit en kosten te beheren. Zie Tarieflimieten toepassen op model- en MCP-services.
• Servicebeleid. Reguleer de inhoud van elke interactie, zoals het blokkeren van onveilige inhoud of het censureren van gevoelige gegevens, door een servicebeleid toe te voegen. Zie Servicebeleid voor AI-beveiliging eneen servicebeleid maken en koppelen.

Werk een model providerdienst bij

Je moet eigenaar zijn of MANAGE hebben. Het type zorgverlener is onveranderlijk.

UI (Gebruikersinterface)

Bewerk de configuratie van de modelprovider-service vanuit de Unity Gateway UI of Catalog Explorer. Wijzigingen worden direct toegepast.

REST API

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

Bewerk comment (of een ander veranderbaar veld) op de databricks_ai_gateway_model_provider_service bron en breng opnieuw aan. Wijzigingen worden direct toegepast.

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

Go Softwareontwikkelingskit

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

Een modelproviderservice verwijderen

Je moet eigenaar zijn of MANAGE hebben.

UI (Gebruikersinterface)

Open de model providerservice in de Unity Gateway UI of Catalog Explorer en selecteer Verwijderen in het kebabmenu.

REST API

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

Voer terraform destroyuit, of verwijder het resource block en breng het opnieuw toe.

Python SDK

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

Go Softwareontwikkelingskit

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

Volgende stappen 

• Zoeken in externe modelaanbieders (services voor modelaanbieders)
• Ontdek en beheer toegang tot externe modelproviders (modelproviderservices)
• Beheer externe modelaanbieders (services van modelaanbieders)