Skip to main content
Last updated on

Add a Unity Gateway model service resource to a Databricks app

Preview

This feature is in Public Preview.

Add Unity Gateway model services as Databricks Apps resources so your app can send inference requests, including chat, completions, and embeddings, to AI models governed in Unity Catalog. Unity Gateway model services include pay-per-token foundation models available under system.ai, as well as model services you create.

note

Usage attribution for Unity Gateway model services is accurate only for standard Databricks Apps. Apps that run in a micro VM environment, such as Genie app builder apps, do not report accurate usage attribution.

See Unity Gateway usage tracking.

Privilege requirements​

To access a Unity Gateway model service, the app's service principal must have the USE CATALOG privilege on the parent catalog, the USE SCHEMA privilege on the parent schema, and the EXECUTE privilege on the model service. When you add the model service resource, Databricks automatically grants these privileges to the app's service principal.

For this automatic granting to succeed, one of the following must be true for each privilege:

  • For USE CATALOG: Either all account users have the USE CATALOG privilege on the catalog, or you have the MANAGE privilege on the catalog.
  • For USE SCHEMA: Either all account users have the USE SCHEMA privilege on the schema, or you have the MANAGE privilege on the schema.
  • For EXECUTE: Either all account users have the EXECUTE privilege on the model service, or you have the MANAGE privilege on the model service.

See Unity Catalog privileges reference.

Add a Unity Gateway model service resource​

Before you add a Unity Gateway model service as a resource, review the app resource prerequisites.

  1. In the App resources section when you create or edit an app, click + Add resource > Model.
  2. In the resource picker, select a model service from the Unity Gateway section. The picker also lists custom serving endpoints under a Serving Endpoints section. To connect one of these endpoints, see Add a model serving endpoint resource to a Databricks app. To use a pay-per-token foundation model, select a model service from the system.ai catalog.
  3. Select the permission level for your app:
    • Can execute: Grants the app's service principal the EXECUTE privilege to send inference requests to the model service. This is the only permission level available for a model service.
  4. (Optional) Specify a custom resource key, which is how you reference the model service in your app configuration. The default key is model.

Configure with Databricks Asset Bundles​

If you define your app using Declarative Automation Bundles, add the model service as a uc_securable resource in your bundle configuration:

YAML
resources:
  apps:
    my_app:
      name: 'my-app'
      source_code_path: ./app
      resources:
        - name: 'model'
          uc_securable:
            securable_full_name: '<catalog>.<schema>.<model_service>'
            securable_type: 'MODEL_SERVICE'
            permission: 'EXECUTE'

For information about app resources in Declarative Automation Bundles, see app.resources.

Environment variables​

When you deploy an app with a Unity Gateway model service resource, Databricks exposes the model service's full three-part Unity Catalog name through environment variables that you can reference using the valueFrom field.

Example configuration:

YAML
env:
  - name: MODEL_SERVICE_NAME
    valueFrom: model # Use your custom resource key if you set one

The valueFrom field resolves to the full three-part Unity Catalog name of the model service (for example, system.ai.databricks-dbrx-instruct). Use this name when calling the model service through the Databricks SDK or the Unity Gateway REST API.

For more information, see Use environment variables to access resources.

Remove a Unity Gateway model service resource​

When you remove a Unity Gateway model service resource from an app, the app's service principal loses the EXECUTE privilege on the model service. The model service itself remains unchanged and continues to be available for other users and applications that have the appropriate permissions.

Best practices​

Consider the following when you work with Unity Gateway model service resources:

  • EXECUTE is the only available permission level. It grants the app access to send inference requests and does not grant administrative privileges on the model service.
  • To use pay-per-token foundation models without additional setup, select a model service from the system.ai catalog.
  • The environment variable resolves to the full three-part Unity Catalog name (catalog.schema.model_service). Use this value when calling the model service through the Databricks SDK or REST API.
  • Handle inference errors and rate limits in your app code. Unity Gateway enforces the rate limits and guardrails configured on each model service.
  • The Model resource picker also lists classic model serving endpoints, grouped under a Serving Endpoints section. Model services and serving endpoints can coexist in the same app.
On this page