Creare e gestire fornitori modello esterni (servizi fornitori modello)

Registra un fornitore di modelli esterno come servizio di fornitore di modello, concedisci l'accesso, configura le funzionalità del Gateway AI di Unity ed eliminalo.

Requisiti

  • CREATE SERVICE nello schema in cui si crea il servizio del provider di modelli, oltre a USE CATALOG e USE SCHEMA per il catalogo e lo schema corrispondenti.
  • Le credenziali per il provider esterno da registrare, ad esempio una chiave API OpenAI o una coppia di chiavi di accesso AWS.
  • Per autenticare Azure OpenAI o Microsoft Foundry con una credenziale di servizio invece che con una chiave o un segreto, è necessaria una credenziale di servizio esistente e ACCESS su di essa. Vedi Autentica Azure OpenAI o Microsoft Foundry con una credenziale di servizio.

Crea un servizio modello di fornitore

I servizi del provider di modelli e i servizi del modello condividono un unico spazio dei nomi all'interno di uno schema di Unity Catalog. Non è possibile usare un nome per un servizio provider di modelli se un servizio modello nello schema lo usa già e viceversa.

Puoi creare un servizio di fornitore di modelli nell'interfaccia di Unity AI Gateway UI o in Catalog Explorer, oppure programmaticamente con l'API REST, gli SDK di Azure Databricks, la CLI di Azure Databricks o Terraform.

Interfaccia utente

  1. Eseguire una delle operazioni seguenti:
    • Nella barra laterale dello spazio di lavoro, clicca su AI Gateway, poi apri la scheda Fornitori e clicca su Fornitore.
    • In Esploratore catalogo, vai allo schema dove vuoi creare il servizio provider modello, clicca Crea>servizio, poi seleziona Servizio fornitore modello nella finestra di dialogo Crea un servizio .
  2. Immettere un nome per il servizio provider di modelli e selezionare il catalogo e lo schema in cui crearlo. Se si inizia da Esplora cataloghi, Esplora cataloghi precompila il catalogo e lo schema.
  3. Selezionare il tipo di provider e immettere i dettagli e le credenziali di connessione del provider.
  4. Clicca su Crea. Azure Databricks crittografa e archivia le credenziali. L'interfaccia utente non li visualizza dopo questo punto.

REST API

Invia POST a /api/2.1/unity-catalog/model-provider-services, passando parent e model_provider_service_id come parametri di query. Imposta provider_type ed esattamente un blocco del provider corrispondente; targets definisce l'elenco consentito dei modelli upstream raggiungibili e i segreti sono forniti in linea in testo semplice:

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

Passa lo schema padre e un nome della foglia, e fornisci la configurazione con --json. Imposta provider_type e esattamente un blocco provider corrispondente; targets permette di elencare i modelli a monte raggiungibili, e i segreti sono forniti in linea come testo in chiaro. Per installare la CLI, vedi Installa o aggiorna la CLI 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

Crea e gestisci un servizio di fornitore modello con il fornitore Databricks Terraform e la risorsa databricks_ai_gateway_model_provider_service . Tieni le chiavi reali fuori dal controllo del codice sorgente passando la chiave API tramite una variabile sensitive = true (impostala con -var o con una variabile di 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

Crea e gestisci un servizio di fornitore di modelli con l'SDK Databricks per 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 di sviluppo Go

Crea e gestisci un servizio di fornitore modello con l'SDK Databricks per 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

Crea e gestisci un servizio di fornitore di modelli con l'SDK Databricks per 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

Crea e gestisci un servizio di fornitore modello con l'SDK Databricks AI Gateway per 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' },
                },
              },
            },
          },
        },
      },
    },
  },
});

Per l'elenco completo dei fornitori e dei loro metodi di autenticazione, vedi Governare fornitori modello esterni (servizi fornitori modello).

Autentica Azure OpenAI o Microsoft Foundry con una credenziale di servizio

Puoi autenticare un provider Azure OpenAI o Microsoft Foundry con una credenziale di servizio invece di memorizzare una chiave API o il segreto client del service principal di Microsoft Entra ID. Una credenziale di servizio detiene un'identità Azure che Unity Catalog governa, quindi nessun segreto di lunga durata viene copiato nel servizio fornitore modello: Azure Databricks ottiene token di breve durata da quell'identità per autenticare ogni richiesta.

Crea il servizio fornitore modello come descritto in Crea un servizio fornitore modello. Seleziona Azure OpenAI o Microsoft Foundry come tipo di provider e inserisci i dettagli della connessione, incluso l'URL base dell'endpoint. Poi imposta il metodo Auth su Service credential e seleziona la credenziale invece di inserire una chiave API o un client secret. Una credenziale di servizio sostituisce solo il segreto, quindi l'URL base dell'endpoint è comunque necessario.

Verificare i requisiti seguenti:

  • Il proprietario del servizio fornitore modello ha ACCESS sulla credenziale del servizio. Poiché Azure Databricks ricontrolla l'accesso del proprietario quando gestisce le richieste, il proprietario deve conservarlo finché il provider è in uso. La revoca interrompe le query per tutti, anche per i chiamanti che mantengono un EXECUTE sul provider. Per concedere al proprietario l'accesso alla credenziale:

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

  • Lo scopo della credenziale è il servizio, non lo stoccaggio.

  • La credenziale è disponibile negli spazi di lavoro da cui provengono le richieste. I suoi binding di spazio di lavoro si applicano ancora, quindi una richiesta da parte di uno spazio di lavoro a cui la credenziale non è destinata fallisce lì, anche se il servizio di fornitore modello è raggiungibile da qualsiasi spazio di lavoro che condivida il metastore.

  • L'identità Azure della credenziale di servizio è autorizzata a richiamare le distribuzioni di Azure OpenAI o Microsoft Foundry che prevedi di interrogare. Per creare credenziali del servizio, vedere Creare credenziali del servizio.

I chiamanti che interrogano il fornitore hanno bisogno delle stesse sovvenzioni di qualsiasi altro fornitore. Non hanno bisogno di alcun privilegio sulla credenzia, ed è proprio questo che la tiene fuori dalla loro portata.

Il servizio di fornitore modello traccia una credenziale tramite il suo identificatore interno, così puoi rinominarla senza fallimento della querit.

Se elimini una credenziale, le query non vengono eseguite e non viene visualizzato alcun avviso che indichi che un servizio del provider di modelli fa riferimento ad essa. Conferma che non ci siano riferimenti a questa credenziali prima di cancellarla.

Non puoi cambiare un servizio di fornitore modello esistente tra credenziale di servizio e chiave API o autenticazione segreta client. Crea invece un nuovo modello di servizio fornitore.

Invia una chiave API personalizzata del provider nell'intestazione

Un provider personalizzato invia la propria chiave API come token portatore di default. Quando il tuo endpoint prevede che la chiave venga passata in uno specifico header, usa l'autenticazione tramite header API key e specifica tu stesso il nome dell'header. Azure Databricks invia quindi la chiave su ogni richiesta in uscita come <header name>: <header value>.

Crea il servizio fornitore modello come descritto in Crea un servizio fornitore modello. Seleziona Personalizzato come tipo di fornitore, poi imposta il metodo Auth su API key header e fornisci il nome Header che il tuo endpoint si aspetta (come X-API-Key o Ocp-Apim-Subscription-Key) insieme al valore Header.

I due metodi sono mutuamente esclusivi: un provider personalizzato utilizza o un token portatore o un'intestazione nominata, non entrambi. L'autenticazione dell'intestazione richiede esattamente un'intestazione.

Il nome dell'intestazione deve essere un nome valido per l'intestazione HTTP: lettere, cifre e i caratteri !#$%&'*+-.^_`|~, fino a 255 caratteri. Qualsiasi altro carattere viene rifiutato, inclusi spazi, due punti, barre e interruzioni di riga.

Concedere l'accesso a un servizio di fornitore modello

Per impostazione predefinita, solo il proprietario del servizio del fornitore modello può interrogarla. Per consentire ad altri di interrogare un servizio provider del modello, concedi loro EXECUTE su di esso, oltre a USE CATALOG e USE SCHEMA sul relativo catalogo e schema. Se il servizio provider di modelli accede a una tabella di inferenza, concedere SELECT alla tabella per consentire loro di leggere le richieste e le risposte registrate.

Interfaccia utente

  1. Apri il servizio del fornitore modello in Catalog Explorer, oppure vai su AI Gateway e seleziona il servizio.
  2. Passare alla scheda Autorizzazioni .
  3. Fare clic su "Concedi".
  4. Selezionare gli utenti, i gruppi o le entità servizio a cui concedere l'accesso.
  5. Selezionare il privilegio EXECUTE .
  6. Fare clic su "Concedi".

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"] }
    ]
  }'

Per maggiori informazioni sulla concessione e la scoperta dell'accesso, vedi Scopri e regoli l'accesso a fornitori modello esterni (servizi fornitori modello).

Configurare le funzionalità

Poiché un servizio del provider del modello passa attraverso Unity AI Gateway, applica le stesse funzionalità di governance e osservabilità che utilizzi per il resto del traffico di Unity AI Gateway:

Aggiorna un servizio di fornitore modello

Devi essere proprietario o avere MANAGE. Il tipo di fornitore è immutabile.

Interfaccia utente

Modifica la configurazione del servizio del provider del modello dall'interfaccia utente di Unity AI Gateway o da Catalog Explorer. Le modifiche vengono applicate direttamente.

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

Modifica comment (o qualsiasi altro campo mutabile) sulla databricks_ai_gateway_model_provider_service risorsa e riapplica. Le modifiche vengono applicate direttamente.

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 di sviluppo Go

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

Java SDK

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

JS SDK

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

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

Eliminare un servizio provider di modelli

Devi essere proprietario o avere MANAGE.

Interfaccia utente

Apri il servizio di fornitore modello nell'interfaccia utente Unity AI Gateway o nell'Esplora cataloghi e seleziona Elimina dal menu kebab.

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

Esegui terraform destroy, oppure rimuovi il blocco risorsa e riapplica.

PYTHON SDK

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

SDK di sviluppo Go

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

Java SDK

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

JS SDK

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

Passaggi successivi

  • Last updated on