Snowflake

Deploy Kumo Relational NIM as a Snowpark Container Services (SPCS) service. This recipe copies a published NIM image to a Snowflake image repository and runs one model on one GPU per service instance. The service exposes the NIM HTTP API for classification and regression.

Replace each <...> placeholder with a value for your environment. Run SQL statements with a Snowflake role that has the required privileges. Run the Bash commands in the same terminal so that the image variables remain available.

Before you start

• A Snowflake account with SPCS available and a GPU compute pool compatible with the selected NIM profile. Use SHOW COMPUTE POOL INSTANCE FAMILIES to check the available instance families and their resource capacity.
• A database and schema where you can create an image repository and service. The service owner needs USAGE on the compute pool and READ on the image repository. A public endpoint also requires BIND SERVICE ENDPOINT on the account. See CREATE SERVICE for privileges, including access to the parent database and schema.
• A Bash shell, Docker, and a configured Snowflake CLI connection.
• Access to the selected release of the Kumo Relational NIM image. Follow NGC’s authentication instructions for your account.

1. Create Snowflake resources

Use an existing GPU compute pool or create one using an available GPU instance family compatible with the model profile:

SHOW COMPUTE POOL INSTANCE FAMILIES;
CREATE COMPUTE POOL <compute_pool>
  MIN_NODES = 1
  MAX_NODES = 1
  INSTANCE_FAMILY = <gpu_instance_family>
  AUTO_RESUME = TRUE;

Create an image repository in an existing database and schema:

CREATE IMAGE REPOSITORY IF NOT EXISTS <database>.<schema>.<repository>;
SHOW IMAGE REPOSITORIES IN SCHEMA <database>.<schema>;

Copy repository_url from the output. It has the form <registry-host>/<database>/<schema>/<repository>. See Snowflake’s image repository guide for repository privileges and URL details.

2. Pull the NIM image from NVIDIA

Set NIM_VERSION to a published Kumo Relational image tag. If the image requires NGC authentication, log in with an NGC API key that can access it:

read -r -s -p 'NGC API key: ' NGC_API_KEY
printf '\n'
printf '%s' "$NGC_API_KEY" | docker login nvcr.io \
  --username '$oauthtoken' --password-stdin
unset NGC_API_KEY
NIM_VERSION='<published-tag>'
NVIDIA_IMAGE="nvcr.io/nim/nvidia/kumo-relational:${NIM_VERSION}"
docker pull "$NVIDIA_IMAGE"

Use an image architecture compatible with the selected Snowflake compute pool. The packaged NIM contains its model artifacts, so it does not need to download the model at service startup. See the Kumo Relational NIM catalog for release details.

3. Push the image to Snowflake

Log Docker in to the Snowflake image registry using your configured CLI connection. Set SNOWFLAKE_REPOSITORY_URL to the repository_url from step 1, without a trailing slash:

snow spcs image-registry login --connection <connection_name>
SNOWFLAKE_REPOSITORY_URL='<repository_url>'
SNOWFLAKE_IMAGE="${SNOWFLAKE_REPOSITORY_URL}/kumo-relational:${NIM_VERSION}"
docker tag "$NVIDIA_IMAGE" "$SNOWFLAKE_IMAGE"
docker push "$SNOWFLAKE_IMAGE"

Confirm that the image is available and record its tag and digest:

SHOW IMAGES IN IMAGE REPOSITORY <database>.<schema>.<repository>;

The Snowflake CLI registry login reference describes connection options and authentication requirements.

4. Start the service

Create a service with one instance using the inline specification below. Replace <nim_version> with the tag you pushed in step 3. SQL does not substitute the Bash variables from the previous steps. The image path begins with / and omits the registry hostname.

CREATE SERVICE <database>.<schema>.<service>
  IN COMPUTE POOL <compute_pool>
  FROM SPECIFICATION $$
spec:
  containers:
    - name: nim
      image: /<database>/<schema>/<repository>/kumo-relational:<nim_version>
      mountSessionToken: false
      env:
        NIM_HTTP_API_PORT: "8000"
      resources:
        requests:
          cpu: 4
          memory: 24Gi
          nvidia.com/gpu: 1
        limits:
          nvidia.com/gpu: 1
      readinessProbe:
        port: 8000
        path: /v1/health/ready
  endpoints:
    - name: inference
      port: 8000
      protocol: HTTP
      public: true
  $$
  MIN_INSTANCES = 1
  MAX_INSTANCES = 1
  AUTO_RESUME = TRUE;

The CPU and memory requests are starting values. Verify the selected model profile’s requirements and the compute pool’s available resources.

This specification exposes a public endpoint. For clients connecting only from SPCS, set public: false to keep the endpoint private. A private endpoint does not require the account privilege for binding a public service endpoint.

Check the service and its endpoint while the container starts:

SELECT SYSTEM$GET_SERVICE_STATUS('<database>.<schema>.<service>');
SHOW SERVICE CONTAINERS IN SERVICE <database>.<schema>.<service>;
SHOW ENDPOINTS IN SERVICE <database>.<schema>.<service>;

Wait until the NIM container is ready. The readiness probe calls /v1/health/ready, which becomes ready after the model loads. If startup fails, review the container status and the Snowflake service monitoring guidance before retrying.

5. Access the NIM endpoint

From a Snowflake notebook using Container Runtime

For a notebook running on an SPCS compute pool, use the service’s internal DNS name and port. Obtain dns_name from DESCRIBE SERVICE and the port from SHOW ENDPOINTS:

DESCRIBE SERVICE <database>.<schema>.<service>;
SHOW ENDPOINTS IN SERVICE <database>.<schema>.<service>;

In a notebook Python cell with requests installed, verify readiness and list the available models. Replace <service_dns_name> with the returned DNS name. The example service uses port 8000:

import requests
nim_endpoint = "http://<service_dns_name>:8000"
response = requests.get(f"{nim_endpoint}/v1/health/ready", timeout=30)
response.raise_for_status()
response = requests.get(f"{nim_endpoint}/v1/models", timeout=30)
response.raise_for_status()
response.json()

This route uses internal networking without a public ingress URL or token. Services with the same owner role can access each other’s endpoints. When the owner roles differ, the client service’s owner role needs the destination service role. See Snowflake’s service-to-service access rules. If access is denied, confirm the notebook’s Container Runtime identity and its grants. Warehouse Runtime notebooks use different networking; this internal DNS example applies to Container Runtime.

6. Manage the service

When the service is no longer needed, suspend it:

ALTER SERVICE <database>.<schema>.<service> SUSPEND;

Resume it when needed:

ALTER SERVICE <database>.<schema>.<service> RESUME;

NIM sessions reside in process memory and must be recreated after a restart or suspension. Keep one service instance for session-based requests unless your deployment provides routing that keeps each session on its originating instance. Suspending the service does not suspend other services or delete the compute pool and image repository. Review the compute pool’s suspension settings when the deployment is no longer in use.